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 _______________________________________________ Gardeners mailing list [email protected] http://www.lispniks.com/mailman/listinfo/gardeners
