[boost] Re: [Boost-docs] Integrating BoostBook documentation withHTMLdocumentation
On Monday 20 January 2003 01:44 pm, Beman Dawes wrote: > I guess I'm still unsure how the generated HTML docs are going to be > integrated with the rest of the web site and CVS. > > My understanding was that the docs in formats other than HTML would go on a > separate web site, but that the source and HTML would be on the regular > site. I assumed that also meant they would be in the regular CVS. > > --Beman I'm going to assume that library documentation for a particular release is not changed after the release. This is the way we do things now---www.boost.org has the library documentation for 1.29.0. When we release 1.30.0, it will have the 1.30.0 documentation and won't change until we release another version. So here is the suggestion: The documentation source (BoostBook format) will be in CVS. Whatever the stable documentation from the last release is, it will be on the regular site (www.boost.org). On another site (currently www.cs.rpi.edu), there will be a nightly script that keeps an up-to-date CVS tree and regenerates documentation in various formats (including HTML) from CVS. The main page at www.boost.org would look something like this: http://www.cs.rpi.edu/~gregod/boost/index.htm Instead of a single "Documentation" link, we have a link to the documentaiton for the most recently released Boost version, which will be to a local copy of the documentation (e.g., doc/html/libraries.html or libs/libraries.htm). The documentation is static---it may have been generated for the release, but it won't change after that. The second link, "CVS", will always go to www.cs.rpi.edu/~gregod/boost/doc/html/libraries.html (or wherever the nightly documentation generation puts the result). If a user is using Boost from CVS and wants a local copy of the HTML documentation, they should download boost-doc-html.tar.gz and extract it in the same place they checkout Boost CVS. Then the first link under documentation (for the current version) will reference the documentation they download. Doug ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
[boost] Re: [Boost-docs] Integrating BoostBook documentation withHTMLdocumentation
At 09:48 PM 1/19/2003, Douglas Gregor wrote: >> -- Footer should have a "revised" date. I like the horizon rule, too. > >A "generated" date would be easy; a "revised" date isn't so easy, because >it's not trivial to figure out when something used in the list changed. For this page it probably isn't a problem, but for regular doc pages I personally like to know the revision date. >> Have you check to verify there won't be any CVS "churn" once this becomes >> something that is checked into CVS? (Unless, of course, there is a real >> change on the page.) > >I'm not expecting this page to go into CVS, but to be autogenerated nightly >along with the rest of the documentation. I guess I'm still unsure how the generated HTML docs are going to be integrated with the rest of the web site and CVS. My understanding was that the docs in formats other than HTML would go on a separate web site, but that the source and HTML would be on the regular site. I assumed that also meant they would be in the regular CVS. --Beman ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
[boost] Re: [Boost-docs] Integrating BoostBook documentation withHTMLdocumentation
On Sunday 19 January 2003 08:25 pm, Beman Dawes wrote: > I'd like to see a bit more refinement first, and understand how the > maintenance works. > > Let's take the last first. What does a developer do to add a new library? If the library documentation is in the BoostBook format, just make sure the Boost documentation includes the BoostBook source (e.g., by adding an appropriate xi:include element to boost.xml). If the library documentation is in HTML, the developer needs to add a library description to the file boost-sandbox/libs/documentation/examples/boost.xml. A library description looks like this: John Maddock Howard Hinnant Empty member optimization I think the above is relatively self-explanatory. The library category names are in the same file (boost.xml), and are each defined like this: String and text processing > As far as refinement goes: > > * Why the bloat of breaking libraries.html up into multiple files? For me, > at least, this reduces the quality of the browsing experience. That's mostly an issue with the way I'm using DocBook. Will fix. > * The navigation header and footer need more work, IMO: > > -- Some color and general site navigation help. If you don't like the >usual Boost intermediate level page header (see the current >libraries.htm), design another one. But the page needs something >to give it a bit of life, identification with Boost, navigation >back to home, etc. Will do. Sprucing up the headers has been on the task list for a while, but nobody has yet to take on the challenge :) > -- Footer should have a "revised" date. I like the horizon rule, too. A "generated" date would be easy; a "revised" date isn't so easy, because it's not trivial to figure out when something used in the list changed. > -- Personally, I dislike "prev" and "next" links in general, and >particularly those that give no indication of what they are linking >to. Hovering the cursor to see the link URL helps a bit, but only a >little. The footer is much better than the header in this regard, because it actually gives names. > * Have you tried single spacing the alpha and by category lists? The old > single spacing seems a tiny bit easier to scan, although that is obviously > very subjective. Done. I think it does look better. > * The formatting of the HTML isn't very human reader friendly. Would it be > possible to do a bit of formatting? I'm not sure. XSLT does have an "indent" property when transforming to another XML document, but AFAIK it's not considered safe to use when spacing is important. And spacing _is_ important, especially within the reference documentation. > Have you check to verify there won't be any CVS "churn" once this becomes > something that is checked into CVS? (Unless, of course, there is a real > change on the page.) I'm not expecting this page to go into CVS, but to be autogenerated nightly along with the rest of the documentation. Doug ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
[boost] Re: [Boost-docs] Integrating BoostBook documentation withHTMLdocumentation
At 02:30 PM 1/19/2003, Douglas Gregor wrote: >The alphabetized/categorized list of libraries generated from the BoostBook >documentation now includes all libraries that have (only) HTML >documentation, so it is now possible to replace boost/libs/libraries.htm >with the generated doc/html/libraries.html. Here is the HTML: > > http://www.cs.rpi.edu/~gregod/boost/doc/html/libraries.html > >I have a script that regenerates the all of the current documentation >formats >(HTML, PDF, man pages, XSL formatting objects, and DocBook---see the link >above) that will be run nightly following updates of the Boost and Boost >Sandbox CVS repositories, so the current CVS documentation will be >available from the above URL. I'd like to make a "CVS" link to this URL >under the "Documentation" header on the Boost main page. Objections? I'd like to see a bit more refinement first, and understand how the maintenance works. Let's take the last first. What does a developer do to add a new library? As far as refinement goes: * Why the bloat of breaking libraries.html up into multiple files? For me, at least, this reduces the quality of the browsing experience. * If for some reason it is really desirable to split the one file into two, the second one should have a meaningful name. ch01s02.html gives you no clue as to what "next" is linking too. * The navigation header and footer need more work, IMO: -- Some color and general site navigation help. If you don't like the usual Boost intermediate level page header (see the current libraries.htm), design another one. But the page needs something to give it a bit of life, identification with Boost, navigation back to home, etc. -- Footer should have a "revised" date. I like the horizon rule, too. -- Personally, I dislike "prev" and "next" links in general, and particularly those that give no indication of what they are linking to. Hovering the cursor to see the link URL helps a bit, but only a little. * Have you tried single spacing the alpha and by category lists? The old single spacing seems a tiny bit easier to scan, although that is obviously very subjective. * The formatting of the HTML isn't very human reader friendly. Would it be possible to do a bit of formatting? Have you check to verify there won't be any CVS "churn" once this becomes something that is checked into CVS? (Unless, of course, there is a real change on the page.) The content looks good, but I think a bit more work on the presentation is needed. --Beman ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
