On Jun 20, 2009, at 1:19 PM, Nicolas Girard wrote:
Hi, The hooks and function variables are currently not documented in the manual ; instead, the reader is redirected to a Worg page [1] which is outdated. [1] http://orgmode.org/worg/org-configs/org-hooks.php My proposal is that such documentation takes place in the manual (possibly also in Worg) and is kept up-to-date. The following shell (perhaps bash-specific) code allows to do so. It only consists in helper functions. These functions need emacsclient to be running. Assuming the path to org-mode source is "path", generate_doc org "$path" outputs the documentation in org format, and generate_doc texi "$path" outputs the documentation in texinfo format. Of course, this is just a usage suggestion. Feel free to adapt this code the way you like.
Hi Nicolas, thank you very much. I do have already a script in place that does update the hooks section on Worg. Not daily from git snapshots, but whenever I make a new release, I try to remember to update this list. The program I use is UTILITIES/listhooks.pl We used to have the list of hooks in the manual, but it has become so long that this is no longer appropriate, just like we do not document all 400 or so variables in the manual. People still print the manual, and an online list seems to be right to me. If you think the Worg list should be updated more often, feel free to do so! - Carsten
Cheers, Nicolas --------------------- function search_vars_in_elisp_matching () { local path="$1" local expr="${2:--}" find "${path}" -type f -name *.el|xargs grep "defvar\|defcustom"|grep -- "${expr}"|cut -d\( -f2|cut -d\ -f2|cut -d\) -f1|sort|uniq } function source_file_for_var() { local path="$1" local symbol="${2}" find "${path}" -type f -name *.el|xargs grep "defvar\|defcustom"|grep "${symbol}"|cut -d\: -f1|xargs basename } function emacs_msg() { local msg="$1" emacsclient -eval "(message ${msg})"|sed -e 's/^"//' -e 's/"$//' } function get_docstring () { local symbol="$1" local nodoc="No documentation string." emacs_msg "(if (functionp '${symbol}) (or (documentation '${symbol}) \"${nodoc}\") (or (documentation-property '${symbol} 'variable-documentation) \"${nodoc}\") )" } function org_visit_section(){ local level="$1" local name="$2" local stars=$(printf "%${level}s" ' '|tr ' ' '*') echo "${stars} ${name}" } function org_visit_symbol (){ local symbol="$1" local sourcefile="$2" org_visit_section 2 "=${symbol}=" echo -e "Defined in /${sourcefile}/ #+begin_example $(get_docstring ${symbol}) #+end_example " } function texi_visit_section(){ local level="$1" local name="$2" local cmd="" case "${level}" in 1) cmd="@section";; 2) cmd="@subsection";; 3) cmd="@subsubsection";; esac echo -e "${cmd} ${name}\n" } function texi_visit_symbol (){ local symbol="$1" local sourcefile="$2" texi_visit_section 2 "@code{${symbol}}" echo -e "Defined in @code{${sourcefile}} $(get_docstring ${symbol}) " } function generate_doc (){ local format="$1" local path="$2" ${format}_visit_section 1 "Hooks" search_vars_in_elisp_matching "${path}" -hook | head -2 | while read symbol; do ${format}_visit_symbol $symbol $(source_file_for_var . $symbol) done ${format}_visit_section 1 Function variables search_vars_in_elisp_matching "${path}" -function | head -2 | while read symbol; do ${format}_visit_symbol $symbol $(source_file_for_var . $symbol) done } _______________________________________________ Emacs-orgmode mailing list Remember: use `Reply All' to send replies to the list. Emacs-orgmode@gnu.org http://lists.gnu.org/mailman/listinfo/emacs-orgmode
_______________________________________________ Emacs-orgmode mailing list Remember: use `Reply All' to send replies to the list. Emacs-orgmode@gnu.org http://lists.gnu.org/mailman/listinfo/emacs-orgmode