From mboxrd@z Thu Jan 1 00:00:00 1970 From: Carsten Dominik Subject: Re: Documentation updates for hooks and function variables Date: Sat, 20 Jun 2009 19:01:42 +0200 Message-ID: <37D38AB8-169F-4F30-981C-C1372AD4127D@gmail.com> References: <51b0095d0906200419i65ca67a0t4e6a6d54db6a1a02@mail.gmail.com> Mime-Version: 1.0 (Apple Message framework v935.3) Content-Type: text/plain; charset=US-ASCII; format=flowed Content-Transfer-Encoding: 7bit Return-path: Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MI3wv-0007eq-AM for emacs-orgmode@gnu.org; Sat, 20 Jun 2009 13:01:53 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MI3wq-0007Yz-Lw for emacs-orgmode@gnu.org; Sat, 20 Jun 2009 13:01:52 -0400 Received: from [199.232.76.173] (port=59035 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MI3wq-0007Yq-Hf for emacs-orgmode@gnu.org; Sat, 20 Jun 2009 13:01:48 -0400 Received: from mx20.gnu.org ([199.232.41.8]:29834) by monty-python.gnu.org with esmtps (TLS-1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MI3wp-0006IM-R7 for emacs-orgmode@gnu.org; Sat, 20 Jun 2009 13:01:48 -0400 Received: from mail-ew0-f220.google.com ([209.85.219.220]) by mx20.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1MI3wp-0007zY-15 for emacs-orgmode@gnu.org; Sat, 20 Jun 2009 13:01:47 -0400 Received: by ewy20 with SMTP id 20so277929ewy.42 for ; Sat, 20 Jun 2009 10:01:45 -0700 (PDT) In-Reply-To: <51b0095d0906200419i65ca67a0t4e6a6d54db6a1a02@mail.gmail.com> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-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: Nicolas Girard Cc: emacs-orgmode@gnu.org 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