Aloha Joe, Joe Riel <j...@san.rr.com> writes: > > No offense, but the help pages on the code blocks could really use > improvement.
Glad to have your help. The documentation is a community effort. > For example, > > Exporting code blocks > --------------------- > Nowhere does this section explain *how* you can export a code block, > nor are there any links to pages that are helpful. As a minimum it > should include the relevant commands and the key bindings for > exporting code blocks. Where are they? Typically, one doesn't export a code block by itself. Instead, one exports a document that includes one or more code blocks. How to export a document is covered in Chapter 12, Exporting. > Evaluating code blocks > ---------------------- > The second paragraph states that only 'emacs-lisp' is enabled by > default. Suppose I want to use something other than 'emacs-lisp', > *how* do I enable that? The parenthetical comment states that the > Languages section lists the supoported languages but doesn't mention > that the explanation of enabling other languages is there. Better > to not leave the reader hanging. How about this: > > "By default, the evaluation facility is only enabled for Lisp code > blocks specified as ‘emacs-lisp’. See _Languages_ for instructions on > enabling other languages and for a list of supported languages. See > _Structure of code blocks_ for information on the syntax used to > define a code block." I think this is an improvement. IMHO it is almost always a good thing to get rid of parenthetical statements. Would you like to submit a patch for org.texi? You'll find instructions here: http://orgmode.org/worg/org-contribute.html#orgheadline1 Another problem is the outdated list of supported languages in Section 14.7, Languages. Perhaps this could be replaced by a pointer to the more complete list maintained on Worg? Should this section distinguish the various levels of "support", e.g. core, contrib, and packages? All the best, Tom -- Thomas S. Dye http://www.tsdye.com
