Re: [Boost-docs] Re: [boost] Location of generated documentation in Boost tree?

[Beman Dawes]

At 06:08 PM 1/2/2003, Douglas Gregor wrote:

>On Monday 30 December 2002 03:40 pm, Beman Dawes wrote:
>> * Those who access docs directly via the web site.
>>
>> The need here is to continue to have well-integrated HTML available.
>
>What do you mean by "well-integrated"?

An exact mirror of the web-site, ready to browse with any reasonable web browser.

Another way of looking at it is that HTML has special status because it provides the on-line web documentation, and we can't do anything to break the web site.

>> * Those downloading and using Boost distributions.
>>
>> A particular concern is the size of the distribution. Also, many people
>may
>> just plain not want docs in formats they don't use.
>
>This is an important concern: at the moment, the PDF is ~230k and the HTML
>is
>~430k. And that's with only Function, Signals, and Ref documented.

The PDF doesn't bother me because that will live somewhere separately.

Is that HTML size a concern? Let's see - the current docs for those functions adds up to about 132k. What has happened to cause that increase in size?

>
>> * Those involved in maintenance activities, including automated scans of
>> the directory tree.
>>
>> These folks (or programs) need to be able to mechanically associate every
>> file with a particular library. The bigger Boost gets, the more this
>> becomes a necessity. Any library related files not part of the library's
>> boost-root/libs/lib-name hierarchy are maintenance problems.
>
>The suggestion to put all library documentation in
>libs/<library-name>/doc_src
>should cover this.
>
>> * CVS, and those downloading and using the daily CVS tarball.
>>
>> We can't change CVS, so we have to deal with its oddities. CVS is great
>for
>> source files, but with generated files CVS can have serious space/size
>> problems. IIUC, binary files are a particular problem because they are
>kept
>> in full, rather than diff, form, and rapidly increase CVS space (and
>> therefore tarball) requirements.
>
>AFAIK, all the formats we've discussed thus far are text formats.
>
>> We need a way with generated files to tell CVS, "yes, do keep this file,
>> but only the current version; don't keep history." Is there a way to do
>> that?
>
>Well, with the "cvs admin" command option '-o' one can erase specific
>revisions, but I'm not sure it's a great solution. We'd need a script that
>runs through the 'doc/' subdirectory, gets the current version number of
>each
>file, then executes:
> cvs admin -o ::<revnum> >filename>
>
>... and we can't undo a "cvs admin" command :)
>
>> >some conventions. I suggest:
>> > - We create a directory boost/doc that will contain generated Boost
>> >documentation. This directory will have subdirectories for each
>> >documentation
>> >format (e.g., doc/html, doc/man, doc/pdf).
>>
>> Would these further be broken down by library? If not, how to avoid name
>> clashes?
>
>No, they would not be broken down by library. The documentation for all
>libraries is built together, with one XSLT pass so that cross-referencing
>can
>be performed. All of the filenames for the generated documentation are
>generated by the DocBook->HMTL conversion, so there will be no collisions.
>
>> > - We create forwarding pages libs/<library-name>/index.html and
>> >libs/<library-name>/doc/index.html that reference the generated
>> >documentation.
>>
>> I'm undecided where the generated html should go, but for the other
>formats
>> my initial feeling is that they shouldn't be in CVS, but rather should be
>> available as separate downloads.
>
>The best solution here is probably to generate them on a nightly basis and
>make them available in some public place. I'll volunteer for that, of
>course.

Yes, I think keeping the bulk of the generated material on a separate web site is best. That way no one pays for storage space or download time unless they use it.

We can probably set that up as a separate SourceForge project so that no one person has to worry about the administration.

>> How have others handled similar situations?
>>
>> --Beman
>
>I dug through a few software packages I have around. I found that most
>packages that generated multiple documentation formats from a single source
>(be it LaTeX, texinfo, DocBook, or whatever) only distributed the original
>sources and not any generated documentation. Documentation for the user was
>generated during the build process.

I've seen that too, mostly in UNIX-oriented packages. I've also had a lot of build failures in such systems, mostly because my non-UNIX machine never seems to have all the right tools available.

I think having the generated docs available in a separate place will be much more user friendly.

>I'm going to refine my original proposal a bit, because I'm convinced now
>that
>we should not have any generated documentation in the CVS tree. I now
>propose
>to:
>
>- Place the C++XML/DocBook sources for each library in
>libs/<library-name>/doc_src
>
>- Place the top-level DocBook sources in boost/doc
>
>- Create nightly tarballs of generated documentation in a few formats that
>should be extracted in the same place as the Boost tarballs, and will place
>their contents in "boost/doc/<format>". When we release a new version of
>Boost, create documentation tarballs for that release. The HTML version of
>the documentation will be publicly available for users of Boost CVS.

That sounds better.

>The biggest problem now is the need to integrate Boost DocBook documentation
>
>with HTML documentation. I see two ways:
> 1) Update libs/libraries.htm to reference both the generated and the
>existing HTML pages. The names of the generated HTML pages might change as
>the DocBook input changes, so this would be an ongoing task that I don't
>(yet?) know how to automate.
>
> 2) Modify the existing XSLT stylesheet that generates the alphabetical and
>
>categorized lists to support HTML documentation along with the DocBook
>documentation. This means that an equivalent to libs/libraries.htm will be
>autogenerated from the DocBook sources and will include libraries whose
>documentation is either DocBook or is HTML.
>
>I think (2) is far better, because I can generate (nightly) all of the
>formats
>from the DocBook document, and link to the HTML documentation of libraries
>that don't have DocBook documentation. I would then suggest that the
>"Documentation" link on the Boost site be changed to contain links to the
>1.29.0 documentation (in the local directory tree) and to the CVS
>documentation (somewhere off in autogenerated land).

I don't have enough knowledge yet to comment. I guess it is time to look at samples. Where should I look?

>The only problem with (2) that I foresee is that it is, to some degree,
>forcing the unreviewed documentation system on users and developers,
>especially when it comes time to roll another release.

There would be a lot of advantages to a scheme that can roll out gradually, so that developers only have to deal with the DocBook approach if and when they want to. In fact a big-bang roll out is so much tougher than a darwinian roll out that gradual roll out is pretty close to a requirement.

Thanks for working on this stuff!

--Beman




-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
_______________________________________________
Boost-docs mailing list
[EMAIL PROTECTED]
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs