Hi François, pin...@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 <carsten.domi...@gmail.com> 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