[Boost-docs] [ping]questions about boost documentation

Subject: [Boost-docs] [ping]questions about boost documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2007-08-20 16:50:37

I'm disappointed that no one who is actually doing this work
responded to this post. If there is some reason that my
concerns/suggestions aren't a good idea, I would be
interested in knowing about it. The whole documentation
initiative has progressed with almost no review or testing or
as far as I can see input from developers who
need/use the system. The fact that a couple of
libraries have addressed these concerns in an ad-hoc
way suggests that I'm not alone in this.

Why are things being done they way are rather
than the way I've suggested. Is there a real reason
or were no alternatives originally considered?

Robert Ramey

Robert Ramey wrote:
> In the beginning ....
> It was pretty simple. Each library had a directory,
> In each library there was a directory named "docs".
> and in that subdirectory there was a bunch of linked html files.
> Now in the improved system - I don't know what there is.
> Sometimes I get bumped over to www.boost.org/...
> I find a directory in the boost_root/doc/html .. and ...
> When I look at a quickbook document chapter - very
> nice looking - but it starts out with chapter 24 or something.
> What's up with that?
> And generating local documentation for your system - like you
> need if you want to have it available if you're not near a wi-fi
> connections is a fragil process that takes a huge amount of time.
> And the recommended way to do it doesn't permit one to do it
> for just one or the other library - or test the process on just one
> library.
> Note that I've only spent some time looking at this.
> Wouldn't it be much, much easier to organize things in
> the following way?
> boost_root
> libs
> serialization
> build...
> src...
> test...
> example...
> performance ...
> doc
> html
> files written by hand or generated by boost book
> pdf
> files made by ? some method or by boost book
> boost book
> Jamfile.v2
> files made by hand or by quickbook
> quickbook
> Jamfile.v2
> quickbook files
> boost entry webpage
> boost document navigator - frame with links to all library
> documentation.
> This would permit building and maintainence of library documentation
> to be independent of that for other libraries. It doesn't conflict
> with the way
> things were "In the beggining". It would make it much easier
> to convert to a new, "improved" system on a library by library basis.
> It would permit users to a subset of the documentation if they
> desired. It provides a fallback if the boost documentation build is
> improved
> beyond functionality. It permits various distribution options - with
> and without pre-built html, pdf. or with build directories
> It would permit one to use the system to generate documentation for
> his non-boost projects. I would be easy to convert to this system.
> Robert Ramey

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:40 UTC