[Bese-devel] request for comments: qbook

[rm at fabula.de]

Hi everyone,


On Thu, Mar 10, 2005 at 10:14:24PM -0500, Eugene Tyurin wrote:
> 
> Marco,
> 
> Have you seen the documentation tool that comes with the OSE library?
> 
> http://ose.sourceforge.net/browse.php?group=tools-manual&entry=cinfo.htm
> 
> I think it has a nice document structure list that you may want to add 
> to the canned set of formats (Dumpleton calls it "= tags").  Also, I am 
> not sure that HTML is such a hot primary output format - horizontal 
> scroll bars inside code sections definitely have to go.  

Let me jump in here: this seems to be a tendency lately to focus on
html-formated documentation. While i sometimes find it rather convenient
to look up references online i _really_ prefer to read the old fashioned
way - i.e. hardcopy with coffee and chair :-/
I think one of the results of this change in documentation is the temptation
of what commonly is called "auto"-documentation, documentation created from
comments and the actual code (sometimes by means of introspection, see Albert).
More and more i find myself exposed to documentation that is little more than
a pretty-printed version of the header files ... ,-)


> Call me 
> old-fashioned but what about texinfo or latex?  Both can be then 
> converted to HTML, PDF, or almost any other format/medium.

Yes, i'd go for one of these as well. I think currently there are three source
formats worth considering: 

 - latex:   + Very nice hardcopy output
            + Can be customized for the project (LISP specific makrup etc.)
	    - Harder to learn (well, ....)

 - texinfo: + Very easy to write
            + Good support for LISP-specific markup (macro vs. function etc.)
	    - Hard to customize hardcopy output (try to change the fonts ...)

 - DocBook: + Format du jour
            + xml (can be transformed to a lot of other formats)
	    - xml (sexpr would be so much nicer)
	    - _very_ ALGOL-centric
	    - "deep" document structure (lots of tags, markup down to the individual
	      function parameter [but rather ALGOL-centric]).
            - Very few LISP tools to process XML :-(
           
 
 Currently i'd go for LaTeX or texinfo - i'd be reluctant to learn yet another documentation
 tool (SBCL uses texinfo, OpenMCL uses DocBook ...)


 cheers Ralf Mattes

> 
> --ET.
> 
> _______________________________________________
> bese-devel mailing list
> bese-devel at common-lisp.net
> http://common-lisp.net/cgi-bin/mailman/listinfo/bese-devel