From mboxrd@z Thu Jan 1 00:00:00 1970 From: Bastien Subject: Re: The reportmode report does not count the running clock Date: Wed, 04 Jan 2012 02:37:41 +0100 Message-ID: <878vlont7e.fsf@altern.org> References: <87liqhrt6r.fsf@iro.umontreal.ca> <87pqfsituv.fsf@norang.ca> <87r508d00p.fsf@iro.umontreal.ca> <87hb14ij4h.fsf@norang.ca> <3CF43367-3C9C-4509-8383-90A26C016D2A@gmail.com> <87mxa4u6oe.fsf@iro.umontreal.ca> Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit Return-path: Received: from eggs.gnu.org ([140.186.70.92]:50414) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RiFmQ-0003wl-Gi for emacs-orgmode@gnu.org; Tue, 03 Jan 2012 20:36:39 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RiFmP-0001pb-38 for emacs-orgmode@gnu.org; Tue, 03 Jan 2012 20:36:38 -0500 Received: from mail-ww0-f41.google.com ([74.125.82.41]:43062) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RiFmO-0001pU-R0 for emacs-orgmode@gnu.org; Tue, 03 Jan 2012 20:36:37 -0500 Received: by wgbdt12 with SMTP id dt12so25297969wgb.0 for ; Tue, 03 Jan 2012 17:36:35 -0800 (PST) In-Reply-To: <87mxa4u6oe.fsf@iro.umontreal.ca> (=?iso-8859-1?Q?=22Fran=E7o?= =?iso-8859-1?Q?is?= Pinard"'s message of "Tue, 03 Jan 2012 10:50:09 -0500") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: =?iso-8859-1?Q?Fran=E7ois?= Pinard Cc: Bernt Hansen , emacs-orgmode@gnu.org, Carsten Dominik Hi François, pinard@iro.umontreal.ca (François Pinard) writes: > Hello, everybody. Let me wish you all that the Year Started Well, and > will continue that way all along! Thanks! > Carsten Dominik writes: > >> Note that there is a million variables which are not referred to >> in the manual - simply too many to mention them all. > > A million? You *always* exaggerate! :-) Well, I counted more than 1070 variables... describing 5 of them per page would take 214 pages. Not something I'd like to read :) >> It might be useful to mentions this one, otherwise I would urge >> restraint. A good way to find unknown variables is described here: >> http://orgmode.org/worg/org-tutorials/org-customize.html > > The manual should be reference, and should mention all variables. A > textual search in the manual should yield anything worth finding. Emacs is The All-Mighty Self-Documenting Editor ;) Wrt documentation, Emacs is its own reference, by letting you access everything with C-h v org-*. The manual is a secondary reference: one that contains the most useful things to know about Org to use it efficiently. It should cover 100% of the core feature, and most of the rest -- but there is a trade-off in this last area. Between readability and completeness. > However nicely and carefully the customization has been organized, one > should ideally not have to guess and retry customize branches in hope of > finding something, or peruse the sources, after having tried the manual. > > Do not misread me, I'm not at all saying that there is something wrong > with the customization, or the availability of the sources! :-) Another point: there is a lot to do to improve the current docstrings and the manual. This is a matter of 1) pulling from git, 2) modifying the file, 3) run `C-x v =' in the buffer, 4) send the patch. :) > Maybe an appendix to the manual could be mechanically generated out of > all customization information, with some Makefile/Emacs machinery for > keeping it up-to-date? Easier said than done, I know... But I would > like at least to throw the idea in the field. This crossed my mind recently. See this file: http://lumiere.ens.fr/~guerry/u/org.org which presents all functions/options/variables from some org*el files. The code to produce this is here: http://lumiere.ens.fr/~guerry/u/org-lto.el This is broken in many respect -- no cleanup is done on the docstring, and there is nearly no formatting. Also, it does not export well (see http://lumiere.ens.fr/~guerry/u/org.html) If you're interested in improving this, please go ahead, I'd be interested in getting something working along these lines. Best regards, -- Bastien