RE: [boost] Re: Reference documentation: one approach

From: Jeff Garland (jeff_at_[hidden])
Date: 2002-11-01 17:26:01

> It looks like it will be either DocBook or LaTeX, but we won't know until we 
> have prototypes each and can make an informed decision. We don't want to make 
> the wrong choice here, because it will require a significant amount of effort 
> for developers to change to a new documentation style (we _don't_ want to do 
> it twice).
>
> FWIW, the LaTeX prototype would have to be pretty amazing to get my vote.

I agree.  I think it is difficult for LaTeX to compete here on the following 
grounds:
1) XML is less of a learning curve for those already using HTML
2) Web browsers are building (or have) direct support for XML and XSL which
   eliminates the browsing tool issue.
3) Lots of projects are using XML so programmers are more likely to know 
   about it and the tools
4) There are a plethora of books on XML

So, I guess I hate to see people spend time prototyping it b/c I don't 
think I would be inclined to support the LaTeX option even if it is better
technically.  

> I've been using DocBook as the target of the my own prototype and have found 
> it to work very well. DocBook is a good intermediate format, because it is 
> easy to parse, generate, and transform. 

I've looked over what you checked in the sandbox briefly.  Having only
briefly skimmed the DocBook documentation it seems like most of your 
element types are custom.  What, if anything, are the issues associated 
with this in your view?  The only thing I can think is that standard
docbook style sheets will need to be modified.  

Jeff