emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Orgmode] Documentation updates for hooks and function variables


From: Carsten Dominik
Subject: Re: [Orgmode] Documentation updates for hooks and function variables
Date: Sat, 20 Jun 2009 19:01:42 +0200


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.
address@hidden
http://lists.gnu.org/mailman/listinfo/emacs-orgmode





reply via email to

[Prev in Thread] Current Thread [Next in Thread]