[Orgmode] Documentation updates for hooks and function variables

[Nicolas Girard]

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.

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
}