From mboxrd@z Thu Jan  1 00:00:00 1970
From: Nicolas Girard <nicolas.girard@nerim.net>
Subject: Documentation updates for hooks and function variables
Date: Sat, 20 Jun 2009 13:19:36 +0200
Message-ID: <51b0095d0906200419i65ca67a0t4e6a6d54db6a1a02@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Return-path: <emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org>
Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43)
	id 1MHybi-0001hk-Pm
	for emacs-orgmode@gnu.org; Sat, 20 Jun 2009 07:19:38 -0400
Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43)
	id 1MHybi-0001fr-5I
	for emacs-orgmode@gnu.org; Sat, 20 Jun 2009 07:19:38 -0400
Received: from [199.232.76.173] (port=60407 helo=monty-python.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.43) id 1MHybh-0001fT-NG
	for emacs-orgmode@gnu.org; Sat, 20 Jun 2009 07:19:37 -0400
Received: from fg-out-1718.google.com ([72.14.220.155]:39430)
	by monty-python.gnu.org with esmtp (Exim 4.60)
	(envelope-from <girard.nicolas@gmail.com>) id 1MHybh-0004Cf-4m
	for emacs-orgmode@gnu.org; Sat, 20 Jun 2009 07:19:37 -0400
Received: by fg-out-1718.google.com with SMTP id l27so222549fgb.7
	for <emacs-orgmode@gnu.org>; Sat, 20 Jun 2009 04:19:36 -0700 (PDT)
List-Id: "General discussions about Org-mode." <emacs-orgmode.gnu.org>
List-Unsubscribe: <http://lists.gnu.org/mailman/listinfo/emacs-orgmode>,
	<mailto:emacs-orgmode-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/pipermail/emacs-orgmode>
List-Post: <mailto:emacs-orgmode@gnu.org>
List-Help: <mailto:emacs-orgmode-request@gnu.org?subject=help>
List-Subscribe: <http://lists.gnu.org/mailman/listinfo/emacs-orgmode>,
	<mailto:emacs-orgmode-request@gnu.org?subject=subscribe>
Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org
Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org
To: emacs-orgmode@gnu.org

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
}