Hook Function Examples

Hook Function Examples

[Mark Elston]

I am trying to make use of some of the hooks for exporting and haven't
found any docs about what they take or how to make use of them (elisp
is *not* my native language).

In particular, I am trying to figure out how to use the following
to see if any of them are going to help me:

  org-export-preprocess-hook
  org-export-preprocess-after-tree-selection-hook
  org-export-preprocess-final-hook

Any examples of a hook function for these would help a lot.  In
particular, what are the parameters, is the point "looking at"
anything in particular, etc.

Mark

Re: Hook Function Examples

[Nick Dokos]

Mark Elston <m_elston@comcast.net> wrote:

> I am trying to make use of some of the hooks for exporting and haven't
> found any docs about what they take or how to make use of them (elisp
> is *not* my native language).
> 

The Emacs Lisp Reference manual has a section (23.1: Hooks) on hooks,
but I'm not sure how helpful it will be to you. The most important note
is that "normal" hook variables are, by convention, named
<foo>-hook. "normal" means that the functions that are added to the hook
take no arguments and return no useful values.

> In particular, I am trying to figure out how to use the following
> to see if any of them are going to help me:
> 
>  org-export-preprocess-hook
>  org-export-preprocess-after-tree-selection-hook
>  org-export-preprocess-final-hook
> 
> Any examples of a hook function for these would help a lot.  In
> particular, what are the parameters, is the point "looking at"
> anything in particular, etc.
> 

Use the source, Luke! (erm... Mark!)

 C-h v org-export-preprocess-hook <RET>

gives me:

 (org-export-blocks-preprocess)

so we have here an example of a hook function!

 C-h f org-export-blocks-preprocess <RET>

gives you the function's doc string, including a link to where it is
defined, and clicking on the link will take you to the function: no
params (it is a "normal" hook after all), and I think you can make no
assumptions about the context. In particular, the above function wraps
everything in a save-excursion, goes to the beginning of the buffer and
searches for interesting things, doing something on each interesting
thing it finds.

The other two hooks are nil in my case, but I think similar things
would apply there too.

HTH,
Nick

Re: Hook Function Examples

[Mark Elston]

On 1/24/2010 9:24 PM, Nick Dokos wrote:
> Mark Elston<m_elston@comcast.net>  wrote:
>
>> I am trying to make use of some of the hooks for exporting and haven't
>> found any docs about what they take or how to make use of them (elisp
>> is *not* my native language).
>>
>
> The Emacs Lisp Reference manual has a section (23.1: Hooks) on hooks,
> but I'm not sure how helpful it will be to you. The most important note
> is that "normal" hook variables are, by convention, named
> <foo>-hook. "normal" means that the functions that are added to the hook
> take no arguments and return no useful values.
>
>> In particular, I am trying to figure out how to use the following
>> to see if any of them are going to help me:
>>
>>   org-export-preprocess-hook
>>   org-export-preprocess-after-tree-selection-hook
>>   org-export-preprocess-final-hook
>>
>> Any examples of a hook function for these would help a lot.  In
>> particular, what are the parameters, is the point "looking at"
>> anything in particular, etc.
>>
>
> Use the source, Luke! (erm... Mark!)
>
>   C-h v org-export-preprocess-hook<RET>
>
> gives me:
>
>   (org-export-blocks-preprocess)
>

Thanks, Nick.  I had checked a few hooks (but not that one) and
couldn't find any that had any functions assigned.

> so we have here an example of a hook function!
>
>   C-h f org-export-blocks-preprocess<RET>
>
> gives you the function's doc string, including a link to where it is
> defined, and clicking on the link will take you to the function: no
> params (it is a "normal" hook after all), and I think you can make no
> assumptions about the context. In particular, the above function wraps
> everything in a save-excursion, goes to the beginning of the buffer and
> searches for interesting things, doing something on each interesting
> thing it finds.

OK.  From what I read I am assuming that a buffer is created with some
already-processed (though not completely) org data as its initial
content.  Then, at some point, these hook functions are called on this
new buffer.  I assume this is the case since you wouldn't want to go
modifying the original buffer - though this is not stated anywhere that
I can find.

Some hook functions apparently *do* take parameters (e.g.
org-cycle-hook, etc) and I wasn't sure about the ones that didn't
mention any.

I was just trying to find my way and didn't have a map of what was
where.  Even the org-export-blocks-preprocess()  function is a little
difficult to wade through for someone not really familiar with elisp.
I think I have pieced it together, though.  This may give me what I need
to do what I want (remove some specific kinds of headers when creating
certain LaTeX files).

Are my assumptions above correct, then?

Mark

Re: Hook Function Examples

[Nick Dokos]

Mark Elston <m_elston@comcast.net> wrote:

> 
> OK.  From what I read I am assuming that a buffer is created with some
> already-processed (though not completely) org data as its initial
> content.  Then, at some point, these hook functions are called on this
> new buffer.  I assume this is the case since you wouldn't want to go
> modifying the original buffer - though this is not stated anywhere that
> I can find.
> 
> Some hook functions apparently *do* take parameters (e.g.
> org-cycle-hook, etc) and I wasn't sure about the ones that didn't
> mention any.
> 

Yes - it is (in the terminology of the Elisp Ref manual) an "abnormal"
hook and should not be called ``org-cycle-hook'', but the convention is not
enforced.

> I was just trying to find my way and didn't have a map of what was
> where.  Even the org-export-blocks-preprocess()  function is a little
> difficult to wade through for someone not really familiar with elisp.
> I think I have pieced it together, though.  This may give me what I need
> to do what I want (remove some specific kinds of headers when creating
> certain LaTeX files).
> 
> Are my assumptions above correct, then?
> 

I think so.

Nick

Re: Hook Function Examples

[Carsten Dominik]

On Jan 25, 2010, at 7:21 AM, Mark Elston wrote:

> On 1/24/2010 9:24 PM, Nick Dokos wrote:
>> Mark Elston<m_elston@comcast.net>  wrote:
>>
>>> I am trying to make use of some of the hooks for exporting and  
>>> haven't
>>> found any docs about what they take or how to make use of them  
>>> (elisp
>>> is *not* my native language).
>>>
>>
>> The Emacs Lisp Reference manual has a section (23.1: Hooks) on hooks,
>> but I'm not sure how helpful it will be to you. The most important  
>> note
>> is that "normal" hook variables are, by convention, named
>> <foo>-hook. "normal" means that the functions that are added to the  
>> hook
>> take no arguments and return no useful values.
>>
>>> In particular, I am trying to figure out how to use the following
>>> to see if any of them are going to help me:
>>>
>>>  org-export-preprocess-hook
>>>  org-export-preprocess-after-tree-selection-hook
>>>  org-export-preprocess-final-hook
>>>
>>> Any examples of a hook function for these would help a lot.  In
>>> particular, what are the parameters, is the point "looking at"
>>> anything in particular, etc.
>>>
>>
>> Use the source, Luke! (erm... Mark!)
>>
>>  C-h v org-export-preprocess-hook<RET>
>>
>> gives me:
>>
>>  (org-export-blocks-preprocess)
>>
>
> Thanks, Nick.  I had checked a few hooks (but not that one) and
> couldn't find any that had any functions assigned.
>
>> so we have here an example of a hook function!
>>
>>  C-h f org-export-blocks-preprocess<RET>
>>
>> gives you the function's doc string, including a link to where it is
>> defined, and clicking on the link will take you to the function: no
>> params (it is a "normal" hook after all), and I think you can make no
>> assumptions about the context. In particular, the above function  
>> wraps
>> everything in a save-excursion, goes to the beginning of the buffer  
>> and
>> searches for interesting things, doing something on each interesting
>> thing it finds.
>
> OK.  From what I read I am assuming that a buffer is created with some
> already-processed (though not completely) org data as its initial
> content.  Then, at some point, these hook functions are called on this
> new buffer.  I assume this is the case since you wouldn't want to go
> modifying the original buffer - though this is not stated anywhere  
> that
> I can find.

That is correct, the "preprocess" hooks are called in a temporary  
buffer,
they can be used to modify that buffer in any way you like without
affecting the original buffer.

>
> Some hook functions apparently *do* take parameters (e.g.
> org-cycle-hook, etc) and I wasn't sure about the ones that didn't
> mention any.

Yes, the only way to find out is to look at the docstring.
If that says nothing about arguments and return values, you can assume
the they do not expect arguments and do not return anything useful,
respectively.

>
> I was just trying to find my way and didn't have a map of what was
> where.  Even the org-export-blocks-preprocess()  function is a little
> difficult to wade through for someone not really familiar with elisp.
> I think I have pieced it together, though.  This may give me what I  
> need
> to do what I want (remove some specific kinds of headers when creating
> certain LaTeX files).
>
> Are my assumptions above correct, then?
>
> Mark
>
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

- Carsten