[Gardeners] texinfo/documentation

[Tim Cross]

JC Helary writes:
 > > native, Lisp-programmable documentation generation system. A starting
 > > point might be my own Markup library:
 > >
 > >    <http://www.gigamonkeys.com/lisp/markup/>
 > 
 > I like that :) But I was thinking that it would be better for the  
 > future (including localisation, form/structure/content separation  
 > etc) to include a few notions like:
 > 
 > 1) structure:
 > -what is block level formating
 > -what is inline level formating
 > 
 > in a very generic form like what OD does:
 > 
 > <text:p> and <text:span> are the core of textual items there. The  
 > rest is attributes like:
 > <text:p style:name="style1">
 > 
 >  From there you can also implement style sheet which allows for  
 > different output types (and css could be a very good option for your  
 > markup I suppose)
 > 
 > To make that look like your markup I suppose you could have stuff like:
 > 
 > (Where \p is for paragraph and \i is for inline and :snb is for style  
 > number)
 > 
 > \p{Some paragraph with no specific style info maybe defaulting to ":s0"
 > 	\i:s1{into which a ":s1" styled segment would appear}
 > 	then we go back to the \p default formating.}
 > \p:s2{Here we start with a formatted paragraph
 > 	\i:s0{with what could be a revert to default \p values}
 > 	and back to \p:s2 stuff.}
 > 
 > 2) contents specification:
 > -what is localizable contents
 > 
 > see Internationalization Tag Set (ITS) at:
 > http://www.w3.org/TR/its/
 > 
 > I suppose a transfer of the ITS tags could look like that:
 > (With l: for localizable)
 > 
 > @l:s1 (a declaration that makes all :s1 sections localizable)
 > \p{Some paragraph with no specific style info maybe defaulting to ":s0"
 > 	\i:s1{into which a ":s1" styled segment would appear} (so here this  
 > section would be localizable)
 > 	then we go back to the \p default formating.}
 > \p:s2:l{Here we start with a formatted paragraph (to affect only  
 > the :s2 part)
 > 	\i:s0{with what could be a revert to default \p values}
 > 	and back to \p:s2 stuff.} (here also l: would be applied)
 > 
 > This kind of stuff could easily be exported to xliff with only  
 > relevant l10nable contents.
 > 
 > This is vastly beyond what I suppose you had in mind and that may not  
 > be relevant at all too...
 > 

I have to say I'm not convinced that defining a new markup language is
a good idea. My issue with this is that the markup language is only
part of the equation. Possibly of more importance is a suitable
authoring environment. Developers in the main view documentation as
one of the less enjoyable aspects of development. A way of taking out
some of the pain is through an authoring environment which makes the
process less painful. However, if we define a new markup language, its
unlikely there will be many authoring environments which would
adequately support working with that markup. While this is not a big
issue with lisp doc strings, documentation automatically generated
from doc strings, while useful, is rarely sufficient, especially for
novice users. On the other-hand, if we stick with an already existing
standard, its more likely individuals can find the authoring
environment which suits them. Therefore, my preferred project
orientation would be towards a lisp program/library which is able to
process existing markup languages, such as docbook and possibly
through the use of other existing libraries, like cl-pdf, generate
output in various formats. 

Tim