emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed

From: Nicolas Girard <nicolas.girard@nerim.net>
To: emacs-orgmode@gnu.org
Subject: Documentation updates for hooks and function variables
Date: Sat, 20 Jun 2009 13:19:36 +0200	[thread overview]
Message-ID: <51b0095d0906200419i65ca67a0t4e6a6d54db6a1a02@mail.gmail.com> (raw)

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
}

next             reply	other threads:[~2009-06-20 11:19 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2009-06-20 11:19 Nicolas Girard [this message]
2009-06-20 11:27 ` Documentation updates for hooks and function variables Nicolas Girard
2009-06-20 17:01 ` Carsten Dominik

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=51b0095d0906200419i65ca67a0t4e6a6d54db6a1a02@mail.gmail.com \
    --to=nicolas.girard@nerim.net \
    --cc=emacs-orgmode@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).