Re: Hook Function Examples

From: Carsten Dominik <carsten.dominik@gmail.com>
To: Mark Elston <m_elston@comcast.net>
Cc: org-mode emacs-orgmode <emacs-orgmode@gnu.org>
Subject: Re: Hook Function Examples
Date: Thu, 28 Jan 2010 19:22:06 +0100	[thread overview]
Message-ID: <4820660C-AA77-4796-9EA8-2F0EE2F86AC2@gmail.com> (raw)
In-Reply-To: <4B5D3861.400@comcast.net>

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