Re: Documentation updates for hooks and function variables

From: Carsten Dominik <carsten.dominik@gmail.com>
To: Nicolas Girard <nicolas.girard@nerim.net>
Cc: emacs-orgmode@gnu.org
Subject: Re: Documentation updates for hooks and function variables
Date: Sat, 20 Jun 2009 19:01:42 +0200	[thread overview]
Message-ID: <37D38AB8-169F-4F30-981C-C1372AD4127D@gmail.com> (raw)
In-Reply-To: <51b0095d0906200419i65ca67a0t4e6a6d54db6a1a02@mail.gmail.com>

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