I'm merging [72977] to release (<https://svn.boost.org/trac/boost/changeset/72977>) and am given a headache by the fact that Fusion has its HTML docs checked in. The docs are automatically generated from the qbk files so committing them to svn is strictly unnecessary, AFAICT. Why is this a problem? - Any change to any qbk file results in a huge number of diffs to the HTML docs (due to changed ids), resulting in a huge commit, long upload times, long download times, long merge times. - It makes viewing a changeset all but impossible because the meaningful changes are lost in the noise of meaningless diffs to automatically generated files. - It leads to unnecessary merge conflicts when merging commits from trunk to release. I'm going to have to regenerate the docs on the release branch and upload them all ... for no benefit! Can Fusion be changed to build its html docs as a normal part of Boost's doc build procedure like other Boost libraries? Thanks, -- Eric Niebler BoostPro Computing http://www.boostpro.com
On 7/17/2011 4:38 AM, Eric Niebler wrote:
I'm merging [72977] to release (<https://svn.boost.org/trac/boost/changeset/72977>) and am given a headache by the fact that Fusion has its HTML docs checked in. The docs are automatically generated from the qbk files so committing them to svn is strictly unnecessary, AFAICT.
Why is this a problem?
- Any change to any qbk file results in a huge number of diffs to the HTML docs (due to changed ids), resulting in a huge commit, long upload times, long download times, long merge times.
- It makes viewing a changeset all but impossible because the meaningful changes are lost in the noise of meaningless diffs to automatically generated files.
- It leads to unnecessary merge conflicts when merging commits from trunk to release. I'm going to have to regenerate the docs on the release branch and upload them all ... for no benefit!
Can Fusion be changed to build its html docs as a normal part of Boost's doc build procedure like other Boost libraries?
Those are very valid and good points, Eric. Well.. - I'm not sure of the "normal part of Boost's doc build procedure". We always regen the docs even before quickbook became predominant (remember quickdoc?). So, it's been the policy for Spirit, Fusion and Phoenix too, as well as quickbook itself while I was maintaining it. - The rationale is that it puts the burden on the committer, but saves the user from having to regen the docs herself, along with all the hassle of installing the tool-chain and all. What we wanted was for the user to have access to the latest docs snapshot that is always synced with the code. That's the real benefit. - We have had no problems merging spirit docs anymore since quickbook V1.6, which does not generate so many differences anymore. Perhaps it's time to revisit the policy. There are pros and cons to either approach but I personally would prefer carrying the burden for the sake of the user being presented the latest docs every time. Regards, -- Joel de Guzman http://www.boostpro.com http://boost-spirit.com
On Sun, 2011-07-17 at 07:12 +0800, Joel de Guzman wrote: > On 7/17/2011 4:38 AM, Eric Niebler wrote: > > I'm merging [72977] to release > > (<https://svn.boost.org/trac/boost/changeset/72977>) and am given a > > headache by the fact that Fusion has its HTML docs checked in. The docs > > are automatically generated from the qbk files so committing them to svn > > is strictly unnecessary, AFAICT. [...] > Those are very valid and good points, Eric. [...] > - The rationale is that it puts the burden on the committer, but saves > the user from having to regen the docs herself, along with all the > hassle of installing the tool-chain and all. What we wanted was for > the user to have access to the latest docs snapshot that is always > synced with the code. That's the real benefit. For an "end-user", I suspect that as long as the final boost tar-ball contain the documents, they don't care about what is in SVN. In fact, I'd suggest that most end users who download boost could even cope with the idea of having a boost-1.47.0.tar.gz and a boost-docs-1.47.0.tar.gz (The former being an export of the SVN tree, the latter being the generated docs.) People who play around with the boost SVN source tree are, I suspect, a rather different breed from most users of boost... > Perhaps it's time to revisit the policy. There are pros and cons to > either approach but I personally would prefer carrying the burden > for the sake of the user being presented the latest docs every time. Does this mean that every time you edit the source to the docs and commit it, you perform a regeneration of the docs and commit them at the same time? Phil -- Phil Richards, <news@derived-software.ltd.uk>
On 7/17/2011 5:44 PM, Phil Richards wrote: > On Sun, 2011-07-17 at 07:12 +0800, Joel de Guzman wrote: >> On 7/17/2011 4:38 AM, Eric Niebler wrote: >>> I'm merging [72977] to release >>> (<https://svn.boost.org/trac/boost/changeset/72977>) and am given a >>> headache by the fact that Fusion has its HTML docs checked in. The docs >>> are automatically generated from the qbk files so committing them to svn >>> is strictly unnecessary, AFAICT. > [...] >> Those are very valid and good points, Eric. > [...] >> - The rationale is that it puts the burden on the committer, but saves >> the user from having to regen the docs herself, along with all the >> hassle of installing the tool-chain and all. What we wanted was for >> the user to have access to the latest docs snapshot that is always >> synced with the code. That's the real benefit. > > For an "end-user", I suspect that as long as the final boost tar-ball > contain the documents, they don't care about what is in SVN. > > In fact, I'd suggest that most end users who download boost could even > cope with the idea of having a boost-1.47.0.tar.gz and a > boost-docs-1.47.0.tar.gz > (The former being an export of the SVN tree, the latter being the > generated docs.) > > People who play around with the boost SVN source tree are, I suspect, a > rather different breed from most users of boost... I don't know what you mean by a "different breed", but many Spirit users, especially those following the Spirit lists, use the SVN trunk. In fact, we advocate that and motivate the users to contribute to the code and docs.. And by doing so, we catch mistakes early, among other benefits. We do our best to always keep the trunk as release stable as possible. Perhaps Spirit users are a "different breed" ;-) >> Perhaps it's time to revisit the policy. There are pros and cons to >> either approach but I personally would prefer carrying the burden >> for the sake of the user being presented the latest docs every time. > > Does this mean that every time you edit the source to the docs and > commit it, you perform a regeneration of the docs and commit them at the > same time? Yes. Regards, -- Joel de Guzman http://www.boostpro.com http://boost-spirit.com
Eric Niebler wrote:
I'm merging [72977] to release (<https://svn.boost.org/trac/boost/changeset/72977>) and am given a headache by the fact that Fusion has its HTML docs checked in. The docs are automatically generated from the qbk files so committing them to svn is strictly unnecessary, AFAICT.
Why is this a problem?
- Any change to any qbk file results in a huge number of diffs to the HTML docs (due to changed ids), resulting in a huge commit, long upload times, long download times, long merge times.
Isn't this only a problem because the docs are generates as one Looong document with all the chapter numbering accross all of boost? If documentation for each library were done separately (that is by running bjam from withing the libraries doc directory) Then the ripple would be limitied to that one library. This would be compatible the movement to the "modularization/decoupling" of boost libraries.
- It makes viewing a changeset all but impossible because the meaningful changes are lost in the noise of meaningless diffs to automatically generated files.
- It leads to unnecessary merge conflicts when merging commits from trunk to release. I'm going to have to regenerate the docs on the release branch and upload them all ... for no benefit!
To me this suggests that we sould re-visit the "merge to release" concept. SVN does a "merge". What we really want is a "copy" to relese.
Can Fusion be changed to build its html docs as a normal part of Boost's doc build procedure like other Boost libraries?
Personally I like the way fusion does things. It permits me to browse the html documentation in the release branch on my own or some other machine without having to rebuild the docs - which for me has always been a very tiresome process. I think its probably time to re-start the discussion about the evolution of boost. I realize that the last boostcon talked about this. A lot of this stuff - e.g. quickbook - just sort of happened - not necessarily a bad thing - but it might be time to take a good look at how we do stuff to see if we can streamline the process. I know it's a pain - but as time goes on it becomes more attractive to consider changing things. Robert Ramey
On 17 July 2011 02:23, Robert Ramey <ramey@rrsd.com> wrote:
Isn't this only a problem because the docs are generates as one Looong document with all the chapter numbering accross all of boost?
No, the Fusion documentation doesn't do that. The long document is not checked into subversion.
To me this suggests that we sould re-visit the "merge to release" concept. SVN does a "merge". What we really want is a "copy" to relese.
That would make it difficult to make a simple fix (e.g.a link, an incorrect use of constexpr) when a library is being developed in other ways.
I'm merging [72977] to release (<https://svn.boost.org/trac/boost/changeset/72977>) and am given a headache by the fact that Fusion has its HTML docs checked in. The docs are automatically generated from the qbk files so committing them to svn is strictly unnecessary, AFAICT.
Why is this a problem?
- Any change to any qbk file results in a huge number of diffs to the HTML docs (due to changed ids), resulting in a huge commit, long upload times, long download times, long merge times.
That's pretty much fixed in the latest quickbook version, which is generating remarkably few spurious changes IMO.
- It leads to unnecessary merge conflicts when merging commits from trunk to release. I'm going to have to regenerate the docs on the release branch and upload them all ... for no benefit!
Granted, but it's not that much hassle revert the HTML folder and rebuild prior to commit.
Can Fusion be changed to build its html docs as a normal part of Boost's doc build procedure like other Boost libraries?
That also has issues: * Crazy long build times, IMO xsltproc just doesn't scale well to "build all of Boost's docs" - testing documentation changes can take almost forever. * No way for folks to read the HTML until it's actually released. * One size fit's all chunking scheme - it works for small libraries - but IMO larger libraries with complex documentation hierarchies would be rendered almost unreadable (I'm thinking of Boost.Math here). * No way to insert any library specific XSL options - for example the Math library uses .png's for html and SVG's for PDF output which requires some fancy XSL footwork that other libraries wouldn't want I'm sure. We could obviously move to a distributed scheme where doc/Jamfile.v2 just cycles through the individual libraries docs - in fact I don't why we haven't done this anyway ages ago, but it still doesn't solve the "can't read the trunk's docs" issue. Regards, John.
(reordered slightly to make replying easier) On 17 July 2011 09:44, John Maddock <boost.regex@virgin.net> wrote:
* Crazy long build times, IMO xsltproc just doesn't scale well to "build all of Boost's docs" - testing documentation changes can take almost forever. * One size fit's all chunking scheme - it works for small libraries - but IMO larger libraries with complex documentation hierarchies would be rendered almost unreadable (I'm thinking of Boost.Math here). * No way to insert any library specific XSL options - for example the Math library uses .png's for html and SVG's for PDF output which requires some fancy XSL footwork that other libraries wouldn't want I'm sure.
There's no need to build all the documentation together. For example, the geometry documentation is handled separately. Although I do need to clean up and check in my build script.
* No way for folks to read the HTML until it's actually released.
I upload the trunk documentation on the sourceforge sandbox site every time I build it, and there are redirects in subversion to take you there.
We could obviously move to a distributed scheme where doc/Jamfile.v2 just cycles through the individual libraries docs - in fact I don't why we haven't done this anyway ages ago, but it still doesn't solve the "can't read the trunk's docs" issue.
The problem is that boost build always builds the documentation under the directory from which it was run: https://svn.boost.org/trac/boost/ticket/3240
On 7/17/2011 5:50 PM, Daniel James wrote:
* No way for folks to read the HTML until it's actually released.
I upload the trunk documentation on the sourceforge sandbox site every time I build it, and there are redirects in subversion to take you there.
That's a very good compromise. The only drawback is that it requires an Internet connection, which is a PITA if you have to go offline and don't have access to the docs. This happens to me a lot of times and I hate it when it does. Regards, -- Joel de Guzman http://www.boostpro.com http://boost-spirit.com
On 17 July 2011 11:18, Joel de Guzman <joel@boost-consulting.com> wrote:
On 7/17/2011 5:50 PM, Daniel James wrote:
* No way for folks to read the HTML until it's actually released.
I upload the trunk documentation on the sourceforge sandbox site every time I build it, and there are redirects in subversion to take you there.
That's a very good compromise. The only drawback is that it requires an Internet connection, which is a PITA if you have to go offline and don't have access to the docs. This happens to me a lot of times and I hate it when it does.
Maybe they need to be easier to download. You can currently download them from the cowic server. But it only includes the generated files, so they aren't very readable until you unzip them into a copy of boost, and it'd be a bad idea to that into your working copy.
On 7/17/2011 3:18 AM, Joel de Guzman wrote:
On 7/17/2011 5:50 PM, Daniel James wrote:
* No way for folks to read the HTML until it's actually released.
I upload the trunk documentation on the sourceforge sandbox site every time I build it, and there are redirects in subversion to take you there.
That's a very good compromise. The only drawback is that it requires an Internet connection, which is a PITA if you have to go offline and don't have access to the docs. This happens to me a lot of times and I hate it when it does.
If you know you are going offline, you can just build Fusion's docs from the source locally. Proto's docs are both integrated into the main doc build as well as build-able standalone. To do it, you just go to libs/proto/doc and type bjam. Blam-o! local HTML docs that you can read offline in a jiffy. (That's also how I test that Proto's docs build correctly and look good.) -- Eric Niebler BoostPro Computing http://www.boostpro.com
On 7/18/2011 11:07 AM, Eric Niebler wrote:
On 7/17/2011 3:18 AM, Joel de Guzman wrote:
On 7/17/2011 5:50 PM, Daniel James wrote:
* No way for folks to read the HTML until it's actually released.
I upload the trunk documentation on the sourceforge sandbox site every time I build it, and there are redirects in subversion to take you there.
That's a very good compromise. The only drawback is that it requires an Internet connection, which is a PITA if you have to go offline and don't have access to the docs. This happens to me a lot of times and I hate it when it does.
If you know you are going offline, you can just build Fusion's docs from the source locally. Proto's docs are both integrated into the main doc build as well as build-able standalone. To do it, you just go to libs/proto/doc and type bjam. Blam-o! local HTML docs that you can read offline in a jiffy. (That's also how I test that Proto's docs build correctly and look good.)
Sure, but again, that requires you to be quickbook/docbook savvy. I have no problem with it, but I do not want to require the users to have to install the tool-chain just to be able to read the docs. We all know how painful that is. So essentially, we are telling users: if you want to read the docs, you must either be online, or be quickbook-savvy and gen the docs yourself. Regards, -- Joel de Guzman http://www.boostpro.com http://boost-spirit.com
On 7/17/2011 9:02 PM, Joel de Guzman wrote:
On 7/18/2011 11:07 AM, Eric Niebler wrote:
On 7/17/2011 3:18 AM, Joel de Guzman wrote:
On 7/17/2011 5:50 PM, Daniel James wrote:
* No way for folks to read the HTML until it's actually released.
I upload the trunk documentation on the sourceforge sandbox site every time I build it, and there are redirects in subversion to take you there.
That's a very good compromise. The only drawback is that it requires an Internet connection, which is a PITA if you have to go offline and don't have access to the docs. This happens to me a lot of times and I hate it when it does.
If you know you are going offline, you can just build Fusion's docs from the source locally. Proto's docs are both integrated into the main doc build as well as build-able standalone. To do it, you just go to libs/proto/doc and type bjam. Blam-o! local HTML docs that you can read offline in a jiffy. (That's also how I test that Proto's docs build correctly and look good.)
Sure, but again, that requires you to be quickbook/docbook savvy. I have no problem with it, but I do not want to require the users to have to install the tool-chain just to be able to read the docs. We all know how painful that is. So essentially, we are telling users: if you want to read the docs, you must either be online, or be quickbook-savvy and gen the docs yourself.
Or use the docs from a released version of boost that you have saved locally, which (I guess) is how the majority of people do it. So in essence, I'm echoing what Phil Richards said previously: the developers working with the svn tree are a different category as boost's end-users. Isn't it safe to assume that if you're using svn (which requires a net connection to do anything useful), then you have net access? In essence, you're optimizing for svn users who don't have net access and aren't savvy enough to set up the doc toolchain. I'd wager that that's a set with a very small membership. :-/ -- Eric Niebler BoostPro Computing http://www.boostpro.com
On Sunday, July 17, 2011 11:33:22 PM Eric Niebler wrote:
On 7/17/2011 9:02 PM, Joel de Guzman wrote:
On 7/18/2011 11:07 AM, Eric Niebler wrote:
On 7/17/2011 3:18 AM, Joel de Guzman wrote:
On 7/17/2011 5:50 PM, Daniel James wrote:
* No way for folks to read the HTML until it's actually released.
I upload the trunk documentation on the sourceforge sandbox site every time I build it, and there are redirects in subversion to take you there.
That's a very good compromise. The only drawback is that it requires an Internet connection, which is a PITA if you have to go offline and don't have access to the docs. This happens to me a lot of times and I hate it when it does.
If you know you are going offline, you can just build Fusion's docs from the source locally. Proto's docs are both integrated into the main doc build as well as build-able standalone. To do it, you just go to libs/proto/doc and type bjam. Blam-o! local HTML docs that you can read offline in a jiffy. (That's also how I test that Proto's docs build correctly and look good.)
Sure, but again, that requires you to be quickbook/docbook savvy. I have no problem with it, but I do not want to require the users to have to install the tool-chain just to be able to read the docs. We all know how painful that is. So essentially, we are telling users: if you want to read the docs, you must either be online, or be quickbook-savvy and gen the docs yourself.
Or use the docs from a released version of boost that you have saved locally, which (I guess) is how the majority of people do it. So in essence, I'm echoing what Phil Richards said previously: the developers working with the svn tree are a different category as boost's end-users.
Isn't it safe to assume that if you're using svn (which requires a net connection to do anything useful), then you have net access? In essence, you're optimizing for svn users who don't have net access and aren't savvy enough to set up the doc toolchain. I'd wager that that's a set with a very small membership. :-/
I wouldn't necessarily say so. For one, the doc toolchain setup is not very easy and second, the docs take quite a while to build. Additionally, if i just instruct the user: go checkout current trunk for feature X, I can directly point her to the svn url to the documentation of said feature, even before he checks out the complete svn trunk.
On 7/18/2011 12:12 AM, Thomas Heller wrote:
On Sunday, July 17, 2011 11:33:22 PM Eric Niebler wrote:
In essence, you're optimizing for svn users who don't have net access and aren't savvy enough to set up the doc toolchain. I'd wager that that's a set with a very small membership. :-/
I wouldn't necessarily say so. For one, the doc toolchain setup is not very easy and second, the docs take quite a while to build. Additionally, if i just instruct the user: go checkout current trunk for feature X, I can directly point her to the svn url to the documentation of said feature, even before he checks out the complete svn trunk.
Even easier: you as library maintainer can build the docs whenever they change and upload them to a place of your choosing, as Daniel was suggesting, and as I do for Proto (<http://boost-sandbox.sourceforge.net/libs/proto/>). All the benefits without forcing everybody who uses svn to download all the Fusion HTML docs every time they change. You can even leave a redirect file in svn, and Daniel was suggesting, so the user doesn't even need to know the special URL ... they're just taken there. -- Eric Niebler BoostPro Computing http://www.boostpro.com
On 7/18/2011 3:12 PM, Thomas Heller wrote:
On Sunday, July 17, 2011 11:33:22 PM Eric Niebler wrote:
On 7/17/2011 9:02 PM, Joel de Guzman wrote:
On 7/18/2011 11:07 AM, Eric Niebler wrote:
On 7/17/2011 3:18 AM, Joel de Guzman wrote:
On 7/17/2011 5:50 PM, Daniel James wrote:
> * No way for folks to read the HTML until it's actually > released.
I upload the trunk documentation on the sourceforge sandbox site every time I build it, and there are redirects in subversion to take you there.
That's a very good compromise. The only drawback is that it requires an Internet connection, which is a PITA if you have to go offline and don't have access to the docs. This happens to me a lot of times and I hate it when it does.
If you know you are going offline, you can just build Fusion's docs from the source locally. Proto's docs are both integrated into the main doc build as well as build-able standalone. To do it, you just go to libs/proto/doc and type bjam. Blam-o! local HTML docs that you can read offline in a jiffy. (That's also how I test that Proto's docs build correctly and look good.)
Sure, but again, that requires you to be quickbook/docbook savvy. I have no problem with it, but I do not want to require the users to have to install the tool-chain just to be able to read the docs. We all know how painful that is. So essentially, we are telling users: if you want to read the docs, you must either be online, or be quickbook-savvy and gen the docs yourself.
Or use the docs from a released version of boost that you have saved locally, which (I guess) is how the majority of people do it. So in essence, I'm echoing what Phil Richards said previously: the developers working with the svn tree are a different category as boost's end-users.
Isn't it safe to assume that if you're using svn (which requires a net connection to do anything useful), then you have net access? In essence, you're optimizing for svn users who don't have net access and aren't savvy enough to set up the doc toolchain. I'd wager that that's a set with a very small membership. :-/
I wouldn't necessarily say so. For one, the doc toolchain setup is not very easy and second, the docs take quite a while to build. Additionally, if i just instruct the user: go checkout current trunk for feature X, I can directly point her to the svn url to the documentation of said feature, even before he checks out the complete svn trunk.
I think what Eric is saying is that if you have to update from SVN anyway, then Daniel James's solution is reasonable: redirects in subversion to take you to the rebuilt docs, which means that 1) when you do a regen of the docs, you don't commit the HTML pages 2) You upload the docs somewhere where you can redirect to. Seems reasonable... What I am not sure about is that it seems that the steps needed to do this is basically the same (or even more laborious ?) than just committing the HTMLs. After all, quickbook/docbook is now better at avoiding extra diffs from regens. Regards, -- Joel de Guzman http://www.boostpro.com http://boost-spirit.com
On 18 July 2011 08:33, Joel de Guzman <joel@boost-consulting.com> wrote:
I think what Eric is saying is that if you have to update from SVN anyway, then Daniel James's solution is reasonable: redirects in subversion to take you to the rebuilt docs, which means that 1) when you do a regen of the docs, you don't commit the HTML pages 2) You upload the docs somewhere where you can redirect to.
Seems reasonable...
What I am not sure about is that it seems that the steps needed to do this is basically the same (or even more laborious ?) than just committing the HTMLs. After all, quickbook/docbook is now better at avoiding extra diffs from regens.
You don't have to upload the documentation yourself. Every few days I run a script which builds and uploads the documentation.
On 7/18/2011 5:10 PM, Daniel James wrote:
On 18 July 2011 08:33, Joel de Guzman <joel@boost-consulting.com> wrote:
I think what Eric is saying is that if you have to update from SVN anyway, then Daniel James's solution is reasonable: redirects in subversion to take you to the rebuilt docs, which means that 1) when you do a regen of the docs, you don't commit the HTML pages 2) You upload the docs somewhere where you can redirect to.
Seems reasonable...
What I am not sure about is that it seems that the steps needed to do this is basically the same (or even more laborious ?) than just committing the HTMLs. After all, quickbook/docbook is now better at avoiding extra diffs from regens.
You don't have to upload the documentation yourself. Every few days I run a script which builds and uploads the documentation.
That's good. Thanks, for doing this, Daniel! Regards, -- Joel de Guzman http://www.boostpro.com http://boost-spirit.com
On 7/18/2011 8:53 PM, Joel de Guzman wrote:
On 7/18/2011 5:10 PM, Daniel James wrote:
On 18 July 2011 08:33, Joel de Guzman <joel@boost-consulting.com> wrote:
I think what Eric is saying is that if you have to update from SVN anyway, then Daniel James's solution is reasonable: redirects in subversion to take you to the rebuilt docs, which means that 1) when you do a regen of the docs, you don't commit the HTML pages 2) You upload the docs somewhere where you can redirect to.
Seems reasonable...
What I am not sure about is that it seems that the steps needed to do this is basically the same (or even more laborious ?) than just committing the HTMLs. After all, quickbook/docbook is now better at avoiding extra diffs from regens.
You don't have to upload the documentation yourself. Every few days I run a script which builds and uploads the documentation.
That's good. Thanks, for doing this, Daniel!
For the record, I'm still unsure about which procedure to follow, but I'm glad to know that there are other reasonable solutions. I still dislike having to regen the docs when I am offline. While it is true that Eric says it's just a bjam away, well, it's still a bjam away. Often, I am in the middle of something and I need to know a function or typedef or something. Having to bjam and wait for the regen to finish just to get that crucial info gets in the way of the thought-flow. OTOH, I'm mostly online anyway. And, you can always have the full release at hand, with all the docs; -- unless of course when you need something new from the trunk. There's always a tradeoff, if anyone else out there cares about this, then please share your voice for the sake of consensus. Regards, -- Joel de Guzman http://www.boostpro.com http://boost-spirit.com
on Mon Jul 18 2011, Joel de Guzman <joel-AT-boost-consulting.com> wrote:
For the record, I'm still unsure about which procedure to follow, but I'm glad to know that there are other reasonable solutions.
I still dislike having to regen the docs when I am offline. While it is true that Eric says it's just a bjam away, well, it's still a bjam away. Often, I am in the middle of something and I need to know a function or typedef or something. Having to bjam and wait for the regen to finish just to get that crucial info gets in the way of the thought-flow. OTOH, I'm mostly online anyway. And, you can always have the full release at hand, with all the docs; -- unless of course when you need something new from the trunk.
There's always a tradeoff, if anyone else out there cares about this, then please share your voice for the sake of consensus.
I appreciate the trade-offs, but IMO in the long run checking in generated artifacts usually hurts more than it helps. -- Dave Abrahams BoostPro Computing http://www.boostpro.com
On 7/19/2011 10:51 PM, Dave Abrahams wrote:
on Mon Jul 18 2011, Joel de Guzman <joel-AT-boost-consulting.com> wrote:
For the record, I'm still unsure about which procedure to follow, but I'm glad to know that there are other reasonable solutions.
I still dislike having to regen the docs when I am offline. While it is true that Eric says it's just a bjam away, well, it's still a bjam away. Often, I am in the middle of something and I need to know a function or typedef or something. Having to bjam and wait for the regen to finish just to get that crucial info gets in the way of the thought-flow. OTOH, I'm mostly online anyway. And, you can always have the full release at hand, with all the docs; -- unless of course when you need something new from the trunk.
There's always a tradeoff, if anyone else out there cares about this, then please share your voice for the sake of consensus.
I appreciate the trade-offs, but IMO in the long run checking in generated artifacts usually hurts more than it helps.
Thanks for your input, Dave. We haven't had problems and as noted, quickbook now eliminates spurious diffs in generated html. What exactly do you mean by "usually hurts more than it helps". How will it hurt? What are we missing? Regards, -- Joel de Guzman http://www.boostpro.com http://boost-spirit.com
On 7/19/2011 6:43 PM, Joel de Guzman wrote:
On 7/19/2011 10:51 PM, Dave Abrahams wrote:
I appreciate the trade-offs, but IMO in the long run checking in generated artifacts usually hurts more than it helps.
Thanks for your input, Dave.
We haven't had problems and as noted, quickbook now eliminates spurious diffs in generated html. What exactly do you mean by "usually hurts more than it helps". How will it hurt? What are we missing?
Just today, you committed a change to the fusion/doc/sequence.qbk without the corresponding changes to the HTML. (Because we were discussing it, maybe?) https://svn.boost.org/trac/boost/changeset/73247 So I just generated the new Fusion HTML docs and did an svn diff. The resulting diff file is 1,617 lines, and is too large for me to post here, weighing in at 112K. The vast majority of those diffs are spurious, such as: -<a name="id857416"></a><p> +<a name="id843910"></a><p> and -<td align="left"><p><small>Last revised: July 08, 2011 at 18:14:46 GMT</small></p></td> +<td align="left"><p><small>Last revised: July 20, 2011 at 03:18:49 GMT</small></p></td> Can you tell me why I'm getting so many diffs? AFAIK, I'm using an up-to-date quickbook.exe. -- Eric Niebler BoostPro Computing http://www.boostpro.com
On 7/20/2011 11:30 AM, Eric Niebler wrote:
On 7/19/2011 6:43 PM, Joel de Guzman wrote:
On 7/19/2011 10:51 PM, Dave Abrahams wrote:
I appreciate the trade-offs, but IMO in the long run checking in generated artifacts usually hurts more than it helps.
Thanks for your input, Dave.
We haven't had problems and as noted, quickbook now eliminates spurious diffs in generated html. What exactly do you mean by "usually hurts more than it helps". How will it hurt? What are we missing?
Just today, you committed a change to the fusion/doc/sequence.qbk without the corresponding changes to the HTML. (Because we were discussing it, maybe?)
Yes.
https://svn.boost.org/trac/boost/changeset/73247
So I just generated the new Fusion HTML docs and did an svn diff. The resulting diff file is 1,617 lines, and is too large for me to post here, weighing in at 112K. The vast majority of those diffs are spurious, such as:
-<a name="id857416"></a><p> +<a name="id843910"></a><p>
and
-<td align="left"><p><small>Last revised: July 08, 2011 at 18:14:46 GMT</small></p></td> +<td align="left"><p><small>Last revised: July 20, 2011 at 03:18:49 GMT</small></p></td>
Can you tell me why I'm getting so many diffs? AFAIK, I'm using an up-to-date quickbook.exe.
If that's the case, then that is clearly unacceptable. I was under the impression that this has been fixed? Daniel? Hartmut? John? Regards, -- Joel de Guzman http://www.boostpro.com http://boost-spirit.com
On 20 July 2011 06:20, Joel de Guzman <joel@boost-consulting.com> wrote:
On 7/20/2011 11:30 AM, Eric Niebler wrote:
So I just generated the new Fusion HTML docs and did an svn diff. The resulting diff file is 1,617 lines, and is too large for me to post here, weighing in at 112K.
[snip]
If that's the case, then that is clearly unacceptable. I was under the impression that this has been fixed? Daniel? Hartmut? John?
Not fixed, but improved. In a previous check-in (r72930) the svn diff of the generated html was 872K. The improvement was acheived by adding ids to headings in quickbook, because if they don't have them docbook generates random ids for them. There are still ids generated for some things. I had a look at recent changes to the spirit documentation and fixed a couple of them the other day (on legalnotice and footnotes). Looking at the fusion documentation there also seem to be a few for tables, which I can probably fix. But I don't think I can completely fix this, certainly not for anyone using a boostbook generated reference. The last revised dates are generated by quickbook. It'd be quite easy to add a flag to suppress them. I don't like them much anyway, since they tend to be misleading.
On 7/19/2011 10:58 PM, Daniel James wrote:
On 20 July 2011 06:20, Joel de Guzman <joel@boost-consulting.com> wrote:
On 7/20/2011 11:30 AM, Eric Niebler wrote:
So I just generated the new Fusion HTML docs and did an svn diff. The resulting diff file is 1,617 lines, and is too large for me to post here, weighing in at 112K.
[snip]
If that's the case, then that is clearly unacceptable. I was under the impression that this has been fixed? Daniel? Hartmut? John?
Not fixed, but improved. In a previous check-in (r72930) the svn diff of the generated html was 872K.
The improvement was acheived by adding ids to headings in quickbook, because if they don't have them docbook generates random ids for them. There are still ids generated for some things. I had a look at recent changes to the spirit documentation and fixed a couple of them the other day (on legalnotice and footnotes). Looking at the fusion documentation there also seem to be a few for tables, which I can probably fix. But I don't think I can completely fix this, certainly not for anyone using a boostbook generated reference.
The last revised dates are generated by quickbook. It'd be quite easy to add a flag to suppress them. I don't like them much anyway, since they tend to be misleading.
Joel, would you accept a patch to remove the generated HTML docs and integrate Fusion docs into the regular Boost doc build? -- Eric Niebler BoostPro Computing http://www.boostpro.com
On 7/21/2011 4:30 AM, Eric Niebler wrote:
On 7/19/2011 10:58 PM, Daniel James wrote:
On 20 July 2011 06:20, Joel de Guzman <joel@boost-consulting.com> wrote:
On 7/20/2011 11:30 AM, Eric Niebler wrote:
So I just generated the new Fusion HTML docs and did an svn diff. The resulting diff file is 1,617 lines, and is too large for me to post here, weighing in at 112K.
[snip]
If that's the case, then that is clearly unacceptable. I was under the impression that this has been fixed? Daniel? Hartmut? John?
Not fixed, but improved. In a previous check-in (r72930) the svn diff of the generated html was 872K.
The improvement was acheived by adding ids to headings in quickbook, because if they don't have them docbook generates random ids for them. There are still ids generated for some things. I had a look at recent changes to the spirit documentation and fixed a couple of them the other day (on legalnotice and footnotes). Looking at the fusion documentation there also seem to be a few for tables, which I can probably fix. But I don't think I can completely fix this, certainly not for anyone using a boostbook generated reference.
The last revised dates are generated by quickbook. It'd be quite easy to add a flag to suppress them. I don't like them much anyway, since they tend to be misleading.
Joel, would you accept a patch to remove the generated HTML docs and integrate Fusion docs into the regular Boost doc build?
If we have to do it, let's do it for Spirit and Phoenix as well. There are some minor issues still not discussed though. Hand-picking from John: * One size fit's all chunking scheme - it works for small libraries - but IMO larger libraries with complex documentation hierarchies would be rendered almost unreadable (I'm thinking of Boost.Math here). * No way to insert any library specific XSL options - for example the Math library uses .png's for html and SVG's for PDF output which requires some fancy XSL footwork that other libraries wouldn't want I'm sure. If we could move to a unified, but still distributed scheme; (oxymoron (*)? ) or at least have that as a goal, then by all means. (* we have to move away from a monolithic one-big-doc for all libraries. I'm not sure how to best do it, but regardless of the docs being generated or not, it's still best to have the docs in each library's doc directory and have the top level doc link to each library's doc). Regards, -- Joel de Guzman http://www.boostpro.com http://boost-spirit.com
On 21 July 2011 00:49, Joel de Guzman <joel@boost-consulting.com> wrote:
On 7/21/2011 4:30 AM, Eric Niebler wrote:
On 7/19/2011 10:58 PM, Daniel James wrote:
Looking at the fusion documentation there also seem to be a few for tables, which I can probably fix.
Turns out this only happens for quickbook documents that use 1.4 or less, which is why I hadn't noticed it elsewhere. I've checked in a fix to quickbook, although you might want to wait until after the code freeze to use it, I'm planning on making some more changes to id generation.
The last revised dates are generated by quickbook. It'd be quite easy to add a flag to suppress them. I don't like them much anyway, since they tend to be misleading.
They only change one line, so I'll leave them alone for now.
Joel, would you accept a patch to remove the generated HTML docs and integrate Fusion docs into the regular Boost doc build?
If we have to do it, let's do it for Spirit and Phoenix as well. There are some minor issues still not discussed though. Hand-picking from John:
[snip] There's no need to combine it with the other documentation, I can build the documentation separately, as I do for the geometry library.
On 7/21/2011 4:19 PM, Daniel James wrote:
On 21 July 2011 00:49, Joel de Guzman <joel@boost-consulting.com> wrote:
On 7/21/2011 4:30 AM, Eric Niebler wrote:
On 7/19/2011 10:58 PM, Daniel James wrote:
Looking at the fusion documentation there also seem to be a few for tables, which I can probably fix.
Turns out this only happens for quickbook documents that use 1.4 or less, which is why I hadn't noticed it elsewhere. I've checked in a fix to quickbook, although you might want to wait until after the code freeze to use it, I'm planning on making some more changes to id generation.
The last revised dates are generated by quickbook. It'd be quite easy to add a flag to suppress them. I don't like them much anyway, since they tend to be misleading.
They only change one line, so I'll leave them alone for now.
Joel, would you accept a patch to remove the generated HTML docs and integrate Fusion docs into the regular Boost doc build?
If we have to do it, let's do it for Spirit and Phoenix as well. There are some minor issues still not discussed though. Hand-picking from John:
[snip]
Thanks for all our work on this, Daniel! We really appreciate this! Regards, -- Joel de Guzman http://www.boostpro.com http://boost-spirit.com
participants (8)
-
Daniel James -
Dave Abrahams -
Eric Niebler -
Joel de Guzman -
John Maddock -
Phil Richards -
Robert Ramey -
Thomas Heller