* Documentation updates for hooks and function variables
@ 2009-06-20 11:19 Nicolas Girard
2009-06-20 11:27 ` Nicolas Girard
2009-06-20 17:01 ` Carsten Dominik
0 siblings, 2 replies; 3+ messages in thread
From: Nicolas Girard @ 2009-06-20 11:19 UTC (permalink / raw
To: emacs-orgmode
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
}
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Documentation updates for hooks and function variables
2009-06-20 11:19 Documentation updates for hooks and function variables Nicolas Girard
@ 2009-06-20 11:27 ` Nicolas Girard
2009-06-20 17:01 ` Carsten Dominik
1 sibling, 0 replies; 3+ messages in thread
From: Nicolas Girard @ 2009-06-20 11:27 UTC (permalink / raw
To: emacs-orgmode
[-- Attachment #1.1: Type: text/plain, Size: 226 bytes --]
2009/6/20 Nicolas Girard
> The hooks and function variables are currently not documented in the manual
>
${format}_visit_section 1 Function variables
should be replaced with
${format}_visit_section 1 "Function variables"
[-- Attachment #1.2: Type: text/html, Size: 451 bytes --]
[-- Attachment #2: Type: text/plain, Size: 204 bytes --]
_______________________________________________
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
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Documentation updates for hooks and function variables
2009-06-20 11:19 Documentation updates for hooks and function variables Nicolas Girard
2009-06-20 11:27 ` Nicolas Girard
@ 2009-06-20 17:01 ` Carsten Dominik
1 sibling, 0 replies; 3+ messages in thread
From: Carsten Dominik @ 2009-06-20 17:01 UTC (permalink / raw
To: Nicolas Girard; +Cc: emacs-orgmode
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
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2009-06-20 17:01 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2009-06-20 11:19 Documentation updates for hooks and function variables Nicolas Girard
2009-06-20 11:27 ` Nicolas Girard
2009-06-20 17:01 ` Carsten Dominik
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.