Re: Boost Documentation [was Iterator Adaptors]

From: williamkempf_at_[hidden]
Date: 2001-03-09 18:11:11

--- In boost_at_y..., Beman Dawes <bdawes_at_a...> wrote:
> At 04:34 PM 3/9/2001 +0000, Moore, Paul wrote:
> 
>  >PS Is there any way of getting the Boost documentation packaged 
up into
>  >something printable for offline use? HTML is all very well, but 
it's not
>  >really on to try to print each page manually. Maybe it's time to 
consider
>  >some form of documentation guidelines...
> 
> One hack (not just for Boost, but any HTML) if you have a copy of 
Adobe 
> Acrobat is to first print to the PDF Writer, then print the 
resulting .pdf 
> file.  Looks better that most browser's print output.
> 
> Long term, we are going to need something better that just HTML 
pages.  Of 
> course, we will still need the HTML pages, but also ways to print, 
special 
> formats, etc.
> 
> Think about ISO standardization, for example.  First there is the 
proposal, 
> then the actual Technical Report wording.  With the current 
standard, that 
> wording then had to be hand converted to troff.  It was a wonder it 
only 
> took ten years to produce the standard.
> 
> We (both Boost members and Library Working Group members) are going 
to want 
> something a lot smoother or we will all go crazy.  I've personally 
sworn 
> off troff for life.
> 
> Matt, are you reading this?  What's your take on XML?  (Matt 
Austern chairs 
> the C++ committee's LWG, and just converted the library issues list 
to 
> XML.)

DocBook was created just for this (http://www.oasis-
open.org/docbook/).  It's a standard DTD for both SGM and XML 
designed for complete text mark up for publication of printed 
documentation.  It's original intent was for documentation on 
computer hardware and software, making it ideal for use by Boost, but 
it's by no means limited to this.  There are numerous utilities 
available to translate DocBook files to HTML or other computer 
formats (roff, man pages, texinfo, DSSSL, XSL, LaTeX, etc.).

I've not personally used this, but I've looked at it and can tell you 
that there'd be a definate learning curve (it's much more complex 
than HTML, though it's just another markup format).  Most 
contributers will have no idea how to use DocBook and so will have to 
face this learning curve, while HTML is pretty much known by 
everyone.  However, if you really want a flexible and fairly easy to 
use method of generating numerous types of documentation, printed and 
online, DocBook would probably be the best choice.

Bill Kempf