Re: [boost] Any, Function, and Signals documentation
At 11:08 AM 2/19/2003, Douglas Gregor wrote: >On Wednesday 19 February 2003 10:46 am, William E. Kempf wrote: >> Beman Dawes said: >> > I'd like to hold off as many changes as possible until after the >> > release. I don't have time to think clearly about the problems >> > involved, and I'd like to actually try out some of the software too. >> > The final day or two before a branch-for-release isn't a good time for >> > this important discussion. >> >> Sorry, I do agree strongly with this and didn't mean to imply we should >> rush moving the tools in before this release. But since some of the >> documentation for this release will be (it seems) generated >documentation, >> I think we should move the tools in very shortly after release. > >Here's a short-term compromise: After the branch, I'll add the generated >documentation into the right places on the release branch. Except for the >directory structure, nothing will look different from before. > >We'll talk about the rest after the release. Sounds good. Thanks. --Beman ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
On Wednesday 19 February 2003 10:46 am, William E. Kempf wrote: > Beman Dawes said: > > I'd like to hold off as many changes as possible until after the > > release. I don't have time to think clearly about the problems > > involved, and I'd like to actually try out some of the software too. > > The final day or two before a branch-for-release isn't a good time for > > this important discussion. > > Sorry, I do agree strongly with this and didn't mean to imply we should > rush moving the tools in before this release. But since some of the > documentation for this release will be (it seems) generated documentation, > I think we should move the tools in very shortly after release. Here's a short-term compromise: After the branch, I'll add the generated documentation into the right places on the release branch. Except for the directory structure, nothing will look different from before. We'll talk about the rest after the release. Doug ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
On Tuesday 18 February 2003 08:46 pm, Darryl Green wrote: > It may be easier to use a platform dependent (or user selectable) xslt > tool rather than try to build/install a cross platform one? Anyone who > has a recent enough IE installed on Windows has XSLT installed - why not > use it. Absolutely. Eventually, I hope to have Boost Jam support for XSL transformation, with support for multiple XSL transformation tools like we have support for multiple C++ compilers. > I've been using XSLT on windows and linux. On windows I'm just using > MS's msxml. This seems to be pretty solid these days - nothing to build > - just install it... To do a command line xslt transformation you can > use a little (28k exe) utility that uses the msxml dll. The utility > (msxsl) can be downloadded from: > > http://msdn.microsoft.com/downloads/default.asp?URL=/code/sample.asp?url > =/msdn-files/027/001/485/msdncompositedoc.xml Thanks for the link. Do Microsoft also have a small utility for XInclude processing? Doug ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
Beman Dawes said: > At 11:56 AM 2/18/2003, William E. Kempf wrote: > > >Well, I'm in favor of that, since we're moving at least some of the > documentation to Boost.Book with this release (or so I gathered). So > what's the group opinion on this one? > > I'd like to hold off as many changes as possible until after the > release. I don't have time to think clearly about the problems > involved, and I'd like to actually try out some of the software too. > The final day or two before a branch-for-release isn't a good time for > this important discussion. Sorry, I do agree strongly with this and didn't mean to imply we should rush moving the tools in before this release. But since some of the documentation for this release will be (it seems) generated documentation, I think we should move the tools in very shortly after release. -- William E. Kempf ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
At 11:56 AM 2/18/2003, William E. Kempf wrote: >Well, I'm in favor of that, since we're moving at least some of the >documentation to Boost.Book with this release (or so I gathered). So >what's the group opinion on this one? I'd like to hold off as many changes as possible until after the release. I don't have time to think clearly about the problems involved, and I'd like to actually try out some of the software too. The final day or two before a branch-for-release isn't a good time for this important discussion. --Beman ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
RE: [boost] Any, Function, and Signals documentation
> -Original Message- > From: William E. Kempf [mailto:[EMAIL PROTECTED]] > This a minor difference here, though. The bjam executable boot straps > fairly easily on most platforms. XSLT processors aren't quite as > convenient. At least that was my experience that last time I tried to do > DocBook stuff on a Windows box (with out Cygwin). Things may have > improved in this regard, and if not, I'm sure we can improve things > ourselves, but I'm nervous that we're not ready for this yet. It may be easier to use a platform dependent (or user selectable) xslt tool rather than try to build/install a cross platform one? Anyone who has a recent enough IE installed on Windows has XSLT installed - why not use it. If you actually want a full docbook authoring environment, things are a little ;-) more complex - but just building the docs shouldn't be too hard? I've been using XSLT on windows and linux. On windows I'm just using MS's msxml. This seems to be pretty solid these days - nothing to build - just install it... To do a command line xslt transformation you can use a little (28k exe) utility that uses the msxml dll. The utility (msxsl) can be downloadded from: http://msdn.microsoft.com/downloads/default.asp?URL=/code/sample.asp?url =/msdn-files/027/001/485/msdncompositedoc.xml regards Darryl Green. ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
On Tue, 18 Feb 2003, William E. Kempf wrote: > > If there are no complains, I would _love_ to move BoostBook out of the > > sandbox and into its (presumably) permanent place in Boost CVS. > > Well, I'm in favor of that, since we're moving at least some of the > documentation to Boost.Book with this release (or so I gathered). So > what's the group opinion on this one? > > -- > William E. Kempf For reference, here is the directory structure I'm proposing: - BoostBook XML documentation for each library will go into libs//doc (wherever the HTML documentation was located) - BoostBook tools go into tools/doc. Specifically: + BoostBook DTD will be in tools/doc/dtd/ + BoostBook XSL will be in tools/doc/xsl/ + BoostBook docs will be in tools/doc/doc + BoostBook makefiles/Jamfiles/etc will be in tools/doc/build - Generated documentation goes into doc/ + doc/html, doc/man, and doc/pdf contain generated documentation in HTML, Man pages, and PDF, respectively - Top-level documentation (e.g., library categories, descriptions of libraries with static documentation) goes into doc/src Doug ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
Douglas Paul Gregor said: > On Tue, 18 Feb 2003, William E. Kempf wrote: >> Douglas Gregor said: >> A reasonable concern. But if we keep only release versions of >> generated documentation in CVS, I don't think it will be too severe. >> Intermediate doc changes would either have to be accessed directly >> from the web or generated locally from CVS. Seems a fair compromise >> to this issue to me. > > I'm okay with this. What are other's thoughts on this compromise? >> > It's my hope that developers will adopt BoostBook for their own >> documentation. Then any time they want to be sure their local copy >> of the documentation is up-to-date they just regenerate the format >> they want locally. It's really not much different from rebuilding, >> e.g., libboost_regex with Boost Jam. >> >> Actually, today it's much different. There's no Jam files for >> producing the documentation, and several tools are required to run the >> makefiles that not all developers will have on hand. In the future I >> expect we'll be able to simplify the process, but you have to admit >> we're not there yet. > > My intended analogy was with Boost.Build. To use Boost.Build, you need > to compile and install another program (Boost Jam), and perform a build > step to get updated binaries. BoostBook will be the same way: compile > and install another program (XSLT processor) and perform a build step to > get updated documentation. (Granted, Boost Jam comes with the Boost > distribution, but an XSLT processor should not; on the other hand, you > need Jam if you want to use Regex, Thread, Signals, or Date-Time, but > generally nobody is required to rebuild documentation). This a minor difference here, though. The bjam executable boot straps fairly easily on most platforms. XSLT processors aren't quite as convenient. At least that was my experience that last time I tried to do DocBook stuff on a Windows box (with out Cygwin). Things may have improved in this regard, and if not, I'm sure we can improve things ourselves, but I'm nervous that we're not ready for this yet. >> The only issue lies in the transition period when not all >> documentation has been converted to Boost.Book and some of the >> "static" documentation needs to link into a library that's been >> converted. > > ... and I don't know how to do that, yet. Which is the single biggest concern with the migration to Boost.Book. Here's where I see the real catch-22, and I'm not sure how to deal with it. >> I think there's several of us interested who will be working on this >> when time permits. But honestly, having it in the sandbox is at least >> a little inconvenient... and to me it makes little sense if some >> released documentation is going to depend on it. > > If there are no complains, I would _love_ to move BoostBook out of the > sandbox and into its (presumably) permanent place in Boost CVS. Well, I'm in favor of that, since we're moving at least some of the documentation to Boost.Book with this release (or so I gathered). So what's the group opinion on this one? -- William E. Kempf ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
On Mon, 17 Feb 2003, Beman Dawes wrote: > At 06:24 PM 2/17/2003, Douglas Gregor wrote: > >Well, you'll have the doc source on your machine, and can generate > whatever > >format you want. > > Where is this documented? How long does it take? It there a way to only > regenerate the files that change, or does the entire Boost docs have to be > generated? Documented here: http://www.cs.rpi.edu/~gregod/boost/doc/html/boostbook.html See the "Getting started" section. Unfortunately, if you don't have a *nix box or Cywin, don't bother. The Makefile is the easiest way to do things, because we don't yet have Jam support. > I'd like to give it a try, but need pointers to docs. I don't even have an > XML editor at the moment, let alone any of the other tools. At a minimum, you'll need an XSLT processor. The aforementioned documentation has links & binaries for my preferred processor, which is also available via Cygwin and on many Unix platforms. > >> Seems like a step backward. We have a simple model now. Click on CVS > >> "update" (or equivalent in your favorite client) and you get the latest > >> version of all files. CVS is the only tool needed. > > > >Sure, but we also have documentation that's inconsistent across > libraries, > >not indexable, and unavailable in any format other than HTML. Our current > >simple model is simple for simple uses, but doesn't extend to any more > >advanced cases. > > A system that is too cumbersome to use isn't really more advanced, it is > just a mess. We need to make the new system as easy to use as the old one > or only the masochists will use it. Working on it :) Doug ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
On Tue, 18 Feb 2003, William E. Kempf wrote: > Douglas Gregor said: > > You probably caught me messing with the scripts (and therefore > > regenerating the documentation in-place). > > Long term, this wouldn't be satisfactory. The scripts should be generated > in a seperate location to minimize the amount of time in which the online > distribution is impacted. Of course. > >> Having the docs locally on my own machine is just a lot more > >> satisfactory. Cheaper, too (my Internet access is metered service.) > > > > Well, you'll have the doc source on your machine, and can generate > > whatever format you want. > > Not everyone will have the tools needed for generating docs. So I don't > think this is satisfactory either. Well, it's one of several options. If you need up-to-date documentation, you can either generate it, view it online, or download an archive. If older documentation is acceptable, it'll be in the distribution (and, if there is agreement on your next suggestion, in CVS). > A reasonable concern. But if we keep only release versions of generated > documentation in CVS, I don't think it will be too severe. Intermediate > doc changes would either have to be accessed directly from the web or > generated locally from CVS. Seems a fair compromise to this issue to me. I'm okay with this. > > It's my hope that developers will adopt BoostBook for their own > > documentation. Then any time they want to be sure their local copy of > > the documentation is up-to-date they just regenerate the format they > > want locally. It's really not much different from rebuilding, e.g., > > libboost_regex with Boost Jam. > > Actually, today it's much different. There's no Jam files for producing > the documentation, and several tools are required to run the makefiles > that not all developers will have on hand. In the future I expect we'll > be able to simplify the process, but you have to admit we're not there > yet. My intended analogy was with Boost.Build. To use Boost.Build, you need to compile and install another program (Boost Jam), and perform a build step to get updated binaries. BoostBook will be the same way: compile and install another program (XSLT processor) and perform a build step to get updated documentation. (Granted, Boost Jam comes with the Boost distribution, but an XSLT processor should not; on the other hand, you need Jam if you want to use Regex, Thread, Signals, or Date-Time, but generally nobody is required to rebuild documentation). > The only issue lies in the transition period when not all documentation > has been converted to Boost.Book and some of the "static" documentation > needs to link into a library that's been converted. ... and I don't know how to do that, yet. > I think there's several of us interested who will be working on this when > time permits. But honestly, having it in the sandbox is at least a little > inconvenient... and to me it makes little sense if some released > documentation is going to depend on it. If there are no complains, I would _love_ to move BoostBook out of the sandbox and into its (presumably) permanent place in Boost CVS. Doug ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
Douglas Gregor said: > On Monday 17 February 2003 04:49 pm, Beman Dawes wrote: >> At 02:00 PM 2/17/2003, Douglas Gregor wrote: >> >They're always available here, regenerated nightly in HTML, DocBook, >> FO, PDF, and man pages: >> > http://www.cs.rpi.edu/~gregod/boost/doc/html/libraries.html >> >> That really isn't very satisfactory. In the last hour for example, >> pages on that web site have only been available sporadically. One >> minute access is OK, the next minute the site or page can't be found. >> No problems with other popular web sites. > > You probably caught me messing with the scripts (and therefore > regenerating the documentation in-place). Long term, this wouldn't be satisfactory. The scripts should be generated in a seperate location to minimize the amount of time in which the online distribution is impacted. >> Having the docs locally on my own machine is just a lot more >> satisfactory. Cheaper, too (my Internet access is metered service.) > > Well, you'll have the doc source on your machine, and can generate > whatever format you want. Not everyone will have the tools needed for generating docs. So I don't think this is satisfactory either. >> >We don't want to stick all of the generated HTML into CVS (too big). >> >> If it is too big for the regular CVS, isn't it too big for the >> distribution too? How big is big? > > The documentation isn't big (~650k, much smaller compressed). However, > generated documentation tends to change a lot even with minor changes to > the input, so unless someone has a good way to tell CVS "don't track > any history for this file" then the CVS repository will get huge with > the histories of these generated files. A reasonable concern. But if we keep only release versions of generated documentation in CVS, I don't think it will be too severe. Intermediate doc changes would either have to be accessed directly from the web or generated locally from CVS. Seems a fair compromise to this issue to me. >> >Documentation changes will show up the next morning at the >> aforementioned >> > >> >site. I'd like to add a link to this generated documentation on the >> main page (so it is obvious that both the current release >> documentation and >> >> the >> >> >current CVS documentation are available on-line). >> >> Seems like a step backward. We have a simple model now. Click on CVS >> "update" (or equivalent in your favorite client) and you get the >> latest version of all files. CVS is the only tool needed. > > Sure, but we also have documentation that's inconsistent across > libraries, not indexable, and unavailable in any format other than > HTML. Our current simple model is simple for simple uses, but doesn't > extend to any more advanced cases. But we have to meet all the needs, both simple and complex. So I think some sort of compromise is needed here. >> It really isn't practical for many Boost developers to download a >> whole tarball and unpack it every time they want to be sure their >> Boost tree is up to date. Unpacking doesn't do things like getting rid >> of obsolete files either. Need a way to just download the changed >> files - and that sounds like CVS to me. > > It's my hope that developers will adopt BoostBook for their own > documentation. Then any time they want to be sure their local copy of > the documentation is up-to-date they just regenerate the format they > want locally. It's really not much different from rebuilding, e.g., > libboost_regex with Boost Jam. Actually, today it's much different. There's no Jam files for producing the documentation, and several tools are required to run the makefiles that not all developers will have on hand. In the future I expect we'll be able to simplify the process, but you have to admit we're not there yet. >> So I think we need to figure out a way for generated docs to work in >> the context of CVS. Or am I just being too picky? > > If I can stabilize the filenames a bit, it _might_ be plausible to use > CVS along with the "cvs admin -o" command, which can erase completely > certain revisions of a file. It would be possible for a little grim > reaper script to come by and erase all but the most recent version of > each file on a nightly basis, after checking in the new version. Sounds > tenuous to me... That's why I think the release snapshot compromise is better. This will still have issues with differing file names, but will put a minimal impact on the CVS repository. >> >They will only break if the links try to link inside the >> documentation files, >> >e.g., to a specific anchor. Links that go directly to the library's >> entry >> > >> >point (index.html) will find the meta-refresh index.html that >> redirects >> >> to >> >> >the generated documentation. I've checked with inspect: nothing >> broke. >> >> Well, but that's because there are only three libraries being >> generated now. Some lib's docs do a lot more linking to other boost >> docs. >> >> -
Re: [boost] Any, Function, and Signals documentation
At 06:24 PM 2/17/2003, Douglas Gregor wrote: >On Monday 17 February 2003 04:49 pm, Beman Dawes wrote: >> Having the docs locally on my own machine is just a lot more >> satisfactory. Cheaper, too (my Internet access is metered service.) > >Well, you'll have the doc source on your machine, and can generate whatever >format you want. Where is this documented? How long does it take? It there a way to only regenerate the files that change, or does the entire Boost docs have to be generated? I'd like to give it a try, but need pointers to docs. I don't even have an XML editor at the moment, let alone any of the other tools. >The documentation isn't big (~650k, much smaller compressed). However, >generated documentation tends to change a lot even with minor changes >to the input, so unless someone has a good way to tell CVS "don't track >any history for this file" then the CVS repository will get huge with >the histories of these generated files. Understood. So we need to come up with some other smooth way of updating the documentation HTML files on developers machines to match the CVS state. >> Seems like a step backward. We have a simple model now. Click on CVS >> "update" (or equivalent in your favorite client) and you get the latest >> version of all files. CVS is the only tool needed. > >Sure, but we also have documentation that's inconsistent across libraries, >not indexable, and unavailable in any format other than HTML. Our current >simple model is simple for simple uses, but doesn't extend to any more >advanced cases. A system that is too cumbersome to use isn't really more advanced, it is just a mess. We need to make the new system as easy to use as the old one or only the masochists will use it. >Using generated documentation has some up-front costs: you'll need to get >an XSLT processor, and maybe some stylesheets (if you don't want them >downloaded on demand), and probably run a simple configuration command >(now a shell script; will be in Jam eventually). I don't mind some added costs as long as the system is easy to use. --Beman ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
On Monday 17 February 2003 04:49 pm, Beman Dawes wrote: > At 02:00 PM 2/17/2003, Douglas Gregor wrote: > >They're always available here, regenerated nightly in HTML, DocBook, FO, > >PDF, and man pages: > > http://www.cs.rpi.edu/~gregod/boost/doc/html/libraries.html > > That really isn't very satisfactory. In the last hour for example, pages on > that web site have only been available sporadically. One minute access is > OK, the next minute the site or page can't be found. No problems with other > popular web sites. You probably caught me messing with the scripts (and therefore regenerating the documentation in-place). > Having the docs locally on my own machine is just a lot more satisfactory. > Cheaper, too (my Internet access is metered service.) Well, you'll have the doc source on your machine, and can generate whatever format you want. > >We don't want to stick all of the generated HTML into CVS (too big). > > If it is too big for the regular CVS, isn't it too big for the distribution > too? How big is big? The documentation isn't big (~650k, much smaller compressed). However, generated documentation tends to change a lot even with minor changes to the input, so unless someone has a good way to tell CVS "don't track any history for this file" then the CVS repository will get huge with the histories of these generated files. > >Documentation changes will show up the next morning at the aforementioned > > > >site. I'd like to add a link to this generated documentation on the main > >page (so it is obvious that both the current release documentation and > > the > > >current CVS documentation are available on-line). > > Seems like a step backward. We have a simple model now. Click on CVS > "update" (or equivalent in your favorite client) and you get the latest > version of all files. CVS is the only tool needed. Sure, but we also have documentation that's inconsistent across libraries, not indexable, and unavailable in any format other than HTML. Our current simple model is simple for simple uses, but doesn't extend to any more advanced cases. > It really isn't practical for many Boost developers to download a whole > tarball and unpack it every time they want to be sure their Boost tree is > up to date. Unpacking doesn't do things like getting rid of obsolete files > either. Need a way to just download the changed files - and that sounds > like CVS to me. It's my hope that developers will adopt BoostBook for their own documentation. Then any time they want to be sure their local copy of the documentation is up-to-date they just regenerate the format they want locally. It's really not much different from rebuilding, e.g., libboost_regex with Boost Jam. > So I think we need to figure out a way for generated docs to work in the > context of CVS. Or am I just being too picky? If I can stabilize the filenames a bit, it _might_ be plausible to use CVS along with the "cvs admin -o" command, which can erase completely certain revisions of a file. It would be possible for a little grim reaper script to come by and erase all but the most recent version of each file on a nightly basis, after checking in the new version. Sounds tenuous to me... > >They will only break if the links try to link inside the documentation > >files, > >e.g., to a specific anchor. Links that go directly to the library's entry > > > >point (index.html) will find the meta-refresh index.html that redirects > > to > > >the generated documentation. I've checked with inspect: nothing broke. > > Well, but that's because there are only three libraries being generated > now. Some lib's docs do a lot more linking to other boost docs. > > --Beman It's easy to link out of the generated documentation to static documentation (of course), and it's much easier to link amongst entities in BoostBook than in HTML. For instance, Tuple will link to the Tuple library, regardless of where the HTML is (even if it isn't generated); boost::ref will link to the function boost::ref, regardless of where it is. Broken link detection is built into the BoostBook XSL, because it emits a warning whenever name lookup fails (and won't generate a link). What we do now is much more involved: find the HTML file and anchor documenting the entity we want to link, put in an explicit link , and checking the links will have to be run manually prior to a release. Using generated documentation has some up-front costs: you'll need to get an XSLT processor, and maybe some stylesheets (if you don't want them downloaded on demand), and probably run a simple configuration command (now a shell script; will be in Jam eventually). The time savings from the generated documentation will come in little pieces: you won't need to keep the synopsis in sync with the detailed description, you won't need to keep a table of contents in sync, keep example code in a separate test file in sync with the HTML version in the documentation, or
Re: [boost] Any, Function, and Signals documentation
> >We don't want to stick all of the generated HTML into CVS (too big). > >If it is too big for the regular CVS, isn't it too big for the >distribution too? How big is big? This is a radical idea, but maybe that's what's needed. What if we did this: 1) Create a new CVS repository ala the sandbox for boost xml docs 2) When an author using boost docs updates the XML he will generate the HTML which will get checked into the normal boost tree. These html docs should be about the same as something written by hand and the xml is now a totally optional part of the distribution. If you want PDF you have to use the documentation CVS tree or a optional download snapshot of the xml tree. This makes things a bit harder for those using the xml docs, but I don't see how we can move away from the current html delivery scheme. Jeff ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
At 02:00 PM 2/17/2003, Douglas Gregor wrote: >On Monday 17 February 2003 11:21 am, Beman Dawes wrote: >> Ouch! That means the current HTML docs for these libraries aren't >> available to Boosters who depend on CVS to keep up-to-date, > >They're always available here, regenerated nightly in HTML, DocBook, FO, >PDF, and man pages: > http://www.cs.rpi.edu/~gregod/boost/doc/html/libraries.html That really isn't very satisfactory. In the last hour for example, pages on that web site have only been available sporadically. One minute access is OK, the next minute the site or page can't be found. No problems with other popular web sites. Having the docs locally on my own machine is just a lot more satisfactory. Cheaper, too (my Internet access is metered service.) >Extract http://www.cs.rpi.edu/~gregod/boost/doc/boost-doc-html.tar.gz into >$(BOOST_ROOT) and you'll have a full release. > >> I think you need to develop a procedure so that a documentation change is >> reflected in the CVS doc/html files right away. > >We don't want to stick all of the generated HTML into CVS (too big). If it is too big for the regular CVS, isn't it too big for the distribution too? How big is big? >Documentation changes will show up the next morning at the aforementioned >site. I'd like to add a link to this generated documentation on the main >page (so it is obvious that both the current release documentation and the >current CVS documentation are available on-line). Seems like a step backward. We have a simple model now. Click on CVS "update" (or equivalent in your favorite client) and you get the latest version of all files. CVS is the only tool needed. It really isn't practical for many Boost developers to download a whole tarball and unpack it every time they want to be sure their Boost tree is up to date. Unpacking doesn't do things like getting rid of obsolete files either. Need a way to just download the changed files - and that sounds like CVS to me. So I think we need to figure out a way for generated docs to work in the context of CVS. Or am I just being too picky? >They will only break if the links try to link inside the documentation >files, >e.g., to a specific anchor. Links that go directly to the library's entry >point (index.html) will find the meta-refresh index.html that redirects to >the generated documentation. I've checked with inspect: nothing broke. Well, but that's because there are only three libraries being generated now. Some lib's docs do a lot more linking to other boost docs. --Beman ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
On Monday 17 February 2003 11:21 am, Beman Dawes wrote: > Ouch! That means the current HTML docs for these libraries aren't available > to Boosters who depend on CVS to keep up-to-date, They're always available here, regenerated nightly in HTML, DocBook, FO, PDF, and man pages: http://www.cs.rpi.edu/~gregod/boost/doc/html/libraries.html > or to the inspect > program, or any other operations that depends on the CVS tree including an > exact representation of what a release would look like. I just ran inspect without any doc/ subdirectory. You'll see broken links from the forwarding HTML to $(BOOST_ROOT)/doc/html. Extract http://www.cs.rpi.edu/~gregod/boost/doc/boost-doc-html.tar.gz into $(BOOST_ROOT) and you'll have a full release. > I think you need to develop a procedure so that a documentation change is > reflected in the CVS doc/html files right away. We don't want to stick all of the generated HTML into CVS (too big). Documentation changes will show up the next morning at the aforementioned site. I'd like to add a link to this generated documentation on the main page (so it is obvious that both the current release documentation and the current CVS documentation are available on-line). Then the top-level site would look like this: http://www.cs.rpi.edu/~gregod/boost/index.htm > Another effect of that change was to break all links to these docs from > other Boost libraries. We won't even mention links from other web sites. They will only break if the links try to link inside the documentation files, e.g., to a specific anchor. Links that go directly to the library's entry point (index.html) will find the meta-refresh index.html that redirects to the generated documentation. I've checked with inspect: nothing broke. Doug ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
At 12:04 AM 2/17/2003, Douglas Gregor wrote: >I've removed the HTML-only documentation for these three libraries from >CVS,as the documentation for each is now maintained in BoostBook. >/index.html forwarding documents are in place to get to the >generated documentation (in doc/html), and when we near the release I will >provide a tarball/zip archive of the generated HTML, the contents of which >should be extracted into $BOOST_ROOT before it is archived for release. > >Any questions/problems/objections/requests? Another effect of that change was to break all links to these docs from other Boost libraries. We won't even mention links from other web sites. --Beman ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Re: [boost] Any, Function, and Signals documentation
At 12:04 AM 2/17/2003, Douglas Gregor wrote: >I've removed the HTML-only documentation for these three libraries from >CVS, as the documentation for each is now maintained in BoostBook. >/index.html forwarding documents are in place to get to the >generated documentation (in doc/html), and when we near the release I will >provide a tarball/zip archive of the generated HTML, the contents of which >should be extracted into $BOOST_ROOT before it is archived for release. > >Any questions/problems/objections/requests? Ouch! That means the current HTML docs for these libraries aren't available to Boosters who depend on CVS to keep up-to-date, or to the inspect program, or any other operations that depends on the CVS tree including an exact representation of what a release would look like. I think you need to develop a procedure so that a documentation change is reflected in the CVS doc/html files right away. --Beman ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
[boost] Any, Function, and Signals documentation
I've removed the HTML-only documentation for these three libraries from CVS, as the documentation for each is now maintained in BoostBook. /index.html forwarding documents are in place to get to the generated documentation (in doc/html), and when we near the release I will provide a tarball/zip archive of the generated HTML, the contents of which should be extracted into $BOOST_ROOT before it is archived for release. Any questions/problems/objections/requests? Doug ___ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
