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

Subject: Re: [Boost-docs] [ping]questions about boost documentation
From: John Maddock (john_at_[hidden])
Date: 2007-08-20 17:34:28

Robert Ramey wrote:
> 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?

Not sure, but actually I think the IDB folks are moving somewhat in the 
direction you suggest: things that should be centralised (style sheets icons 
etc) are, while library specific docs live under libs/name/doc/html.

I suspect that Matias has been busy, given that he's been awfully quiet 
lately, but will no doubt reply in time.

That's the way that the sandbox is organised at present anyway, and as I 
said in a previous reply to your message, some of us are already using this 
structure.

John.

> 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
>
>
>
> _______________________________________________
> Boost-docs mailing list
> Boost-docs_at_[hidden]
> http://lists.boost.org/mailman/listinfo.cgi/boost-docs