[Bese-devel] request for comments: qbook

[Marco Baringer]

i'll just respond to everyone here instead of sending out 3 seperate
emails.

1) i set the width of the text to 40em as opposed to 600px. with my
   default font-size this is slightly wider than before, hopefully
   this will adapt better to people's font-sizes. (should it be even
   wider? i don't want to fill up the entire browser window (i find
   that hard to read) but maybe that's what most people prefer?)

2) the horizontal scroll bars in the code listings are my fault. i
   tend to work with 130 columns, so my code will, occasinaly arive at
   column 100 or 110. this is a good enough reason to reformat my
   code.

3) my intention with qbook is not to replace user manuals, howtos or
   conceptual overviews, i'd like to avoid falling into that javadoc
   trap.

   however as far as describing what the classes, methods, variables
   etc. are, describing how these work and work together i'm of the
   opinion that putting this information in comments close to the code
   itself is helpfull. i'm not trying to say that it produces the best
   possible documenatation, but i've found that it's much easier for
   me to edit/update a doc string than it is to open a latex file.

4) i like latex's pdf output, but latex2html is a big huge mess. i
   _love_ info, but texinfo produces crappy html (if at least it was
   customizable....) and i've _never_ been able to get it to work with
   my tex setup. finally i think it's important that the html output
   (which is the first thing most people see) be well done. the only
   solution that i'd be happy with is generating html, latex and
   texinfo from the same source, which is exactly what i plan on
   doing.

   until i get around to writing a latex backend for qbook (it's
   shouldn't take more than a hour) i'd appreciate feedback on the
   print style sheet.

5) thanks for the comments.

6) qbook no longer generates a single html file but splits the output
   according to the level 1 headers. this required moving the demos
   around a bit:

   http://www.common-lisp.net/project/bese/docs/qbook/index.html
   http://www.common-lisp.net/project/bese/docs/fiveam/index.html

-- 
-Marco
Ring the bells that still can ring.
Forget the perfect offering.
There is a crack in everything.
That's how the light gets in.
	-Leonard Cohen