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"?
> * 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.
> * 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.
> > - We place the top-level DocBook sources in boost/doc_src
>
> That seems OK, too.
>
> 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'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.
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).
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.
Doug
-------------------------------------------------------
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
