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
* 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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.