Invalid URLs in container documentation

[alexey kutumov <alexey.kutumov@…>]

Container library has wrong index, any link from this page cannot be found:

http://www.boost.org/doc/libs/1_52_0/doc/html/container/index.html

[alexey kutumov <alexey.kutumov@…>]

Also same problem exists in http://www.boost.org/doc/libs/1_52_0/doc/html/interprocess/index.html

I think that problem is in auto indexing

[John Maddock]

This is an issue with how the HTML docs for the website are built - there is a docbook limitation that there can only be one index - so if you build multiple library's docs in one big build you have a problem. In this case it seems like the index for Boost.Build is getting inserted into every docbook <index> element.

Daniel, is there any way the HTML doc build can be changed to build docs with indexes separately? It doesn't matter whether they're manual indexes like Boost.Build or auto-generated ones, xsltproc just overwrites them all with the first one seen if they're all in one big doc.

[Daniel James]

I think that would be up to the individual library maintainers. The problem is linking between libraries, linking to other documentation is tricky. Docbook does have a mechanism for doing it (the olink tag). It'd be great to support it, but it's complicated, I wouldn't know how to implement support in the build system. The other option is to link using 'boost' urls, but that's pretty fragile. We get a lot of broken links that way, and no one really checks them.

[Alexey.kutumov@…]

I asked question in mailing list about auto_index: maybe it is possible to add support for boostbook and pefrorm indexing for every boostbook before merging to single file. I think that in this case we can get correct indexes for individual libraries.

[John Maddock]

You're right of course - if the container docs were translated all the way to docbook prior to inclusion in the "big build" then it would work. I'm experimenting with that now, but it's not helped by the fact that the doc build takes so long...

[John Maddock]

I've looked into this, but I simply cannot make it work: if I modify doc/Jamfile and doc/src/boost.xml to load the processed docbook ("container.auto_index.docbook") then I get XML validity errors inside the program_options docs :-(

Daniel, do you know if this should work or not? I thought Boostbook was a superset of Docbook?

[Daniel James]

Boostbook isn't quite a superset of Docbook, they use classname and methodname differently. I've been thinking about fixing it (see #5244), but it didn't seem to be enough of an issue to be worth the hassle. Since program options uses classname, that might be your problem, but without seeing the error I couldn't tell. Have you checked that the program_options docs are valid boostbook?

[John Maddock]

OK there seem to be a number of issues here, you're correct that program_options doesn't validate as Boostbook. However, there are so many errors that it's hard to know where to begin. I'm not sure if our DTD is accurate enough to fully validate anyway? Either way I'll attach the error log.

The other issue is that if I gut boost.xml so that the only library included is the container docbook xml I still see errors from our XSL code:

runtime error: file file:///D:/data/boost/trunk/tools/boostbook/xsl/docbook.xsl line 436 element attribute
xsl:attribute: The QName 'rev:last-revision' has no namespace binding in scope in the stylesheet; this is an error, since the namespace was not specified by the instruction itself.
error: file src/boost.xml
xsltRunStylesheet : run failed

Do you have any ideas what that means and/or what the issue might be?

One possible hack (if it's possible) is to change the Boostbook XSL to allow a reference to an external docbook file, which doesn't get included at that point, but just outputs an xi:include so it's only processed at the docbook->HTML stage.

Thoughts?

[Daniel James]

The first errors in the log are because the validator doesn't like xincludes, you need to process them first somehow. I think you can use xmlint --xinclude.

The error for tutorial.xml:9 is correct, it just requires that the doctype in tutorial.xml be changed to section.

The "defaulted from external subset" errors can be fixed by changing standalone="yes" to standalone="no" at the beginning of the appropriate file. standalone="yes" means that the document can be parsed without consulting the schema - the error is saying that it needs the schema in order to get the defaults.

None of those errors should break anything though.

As for the xsl error, I'd have to look into it. I never understood the custom attribute stuff, it always seemed a bit pointless to me. Just the way that the attributes is copied is a bit odd - I believe the xsl:for-each can be replaced with something like <xsl:copy-of select="@*" />. How are you running xsl? (so I can replicate your errors).

[Daniel James]

(In [82863]) Boostbook: Simpler method for copying chapter attributes. Refs #7899.

I'm not sure if this will fix the issue, but it's worth a try.

[John Maddock]

Daniel you're a wizard: that fixes almost everything: certainly the two issues above, and I can get the container docs integrated into the build complete with correct index now.

However, when I also fix interprocess and intrusive the same way (the only other libraries effect by this issue, then xsltproc seems to go into an infinite loop processing the docbook :-(

I'll try and narrow it down later.

[John Maddock]

(In [82994]) Fix indexes in container/interprocess/intrusive libraries. Refs #7899.

[John Maddock]

Daniel: can you check that the above fix is OK for you?

Also will you take care of merging to release prior to the next release, or do you want me to do that?

Regards, John.

[Daniel James]

I just kicked off a documentation build. I'll merge if it works out.

[Daniel James]

(In [83017]) Remove autodoc dependencies from container/interprocess/intrusive libraries. Refs #7899

I was getting duplicate target errors because 'standalone' depends on autodoc, so they were added to the dependencies twice.

[Daniel James]

Still not working. My build script uses the automatically built quickbook, and it seems the auto index attributes are causing issues for it. The output from boost build follows. Any ideas on how to fix it? I can probably work around it by pre-building quickbook, but it'd be good to get this fixed. Maybe a question for the build list.

Performing configuration checks

    - has_icu builds           : no
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:1106: in virtual-target.register-actual-name from module virtual-target
error: Duplicate name of actual target: <p../bin.v2/libs/system/build/darwin-4.7.2/release/link-static>libboost_system.a
error: previous virtual target { darwin%darwin.archive-libboost_system.a.STATIC_LIB { darwin%darwin.compile.c++-error_code.o.OBJ { error_code.cpp.CPP } } }
error: created from ../libs/system/build/boost_system
error: another virtual target { darwin%darwin.archive-libboost_system.a.STATIC_LIB { darwin%darwin.compile.c++-error_code.o.OBJ { error_code.cpp.CPP } } }
error: created from ../libs/system/build/boost_system
error: added properties: <auto-index-internal>off <auto-index-no-duplicates>off <auto-index-section-names>on <auto-index-verbose>off <auto-index>off <format>docbook
error: removed properties: <format>html
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:491: in actualize-no-scanner from module object(file-target)@3093
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:134: in object(file-target)@3093.actualize from module object(file-target)@3093
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:822: in actualize-source-type from module object(action)@3496
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:843: in actualize-sources from module object(action)@3496
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:783: in object(action)@3496.actualize from module object(action)@3496
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:311: in actualize-action from module object(file-target)@3497
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:500: in actualize-no-scanner from module object(file-target)@3497
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:134: in object(file-target)@3497.actualize from module object(file-target)@3497
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:822: in actualize-source-type from module object(action)@3505
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:841: in actualize-sources from module object(action)@3505
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:783: in object(action)@3505.actualize from module object(action)@3505
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:311: in actualize-action from module object(file-target)@3506
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:500: in actualize-no-scanner from module object(file-target)@3506
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:134: in object(file-target)@3506.actualize from module object(file-target)@3506
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:822: in actualize-source-type from module object(action)@7004
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:841: in actualize-sources from module object(action)@7004
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:783: in object(action)@7004.actualize from module object(action)@7004
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:311: in actualize-action from module object(file-target)@7005
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:500: in actualize-no-scanner from module object(file-target)@7005
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build/virtual-target.jam:134: in object(file-target)@7005.actualize from module object(file-target)@7005
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/build-system.jam:736: in load from module build-system
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/kernel/modules.jam:289: in import from module modules
/Volumes/Boost/boost/docs/build/build-trunk/boost/tools/build/v2/kernel/bootstrap.jam:139: in boost-build from module
/Volumes/Boost/boost/docs/build/build-trunk/boost/boost-build.jam:17: in module scope from module

[Daniel James]

Pre-building quickbook worked around that issue, but now a lot of links are broken, because the standalone documentation is built with the wrong boost root. I think it should be possible to fix that by implementing a boost root feature in the build system. Ideally boost root should be set automatically by boost build, but I don't know how to do that.

[anonymous]

Still not working. My build script uses the automatically built quickbook, and it seems the auto index attributes are causing issues for it. The output from boost build follows. Any ideas on how to fix it? I can probably work around it by pre-building quickbook, but it'd be good to get this fixed. Maybe a question for the build list.

Shucks, sorry, no idea, I always use pre-built quickbook (and auto_index too).

Pre-building quickbook worked around that issue, but now a lot of links are broken, because the standalone documentation is built with the wrong boost root.

Can you give me an example of where the links break? I wonder if setting the boost.root XSL param on the reference docbook targets can fix this?

[Daniel James]

You can see the broken links at:

​http://boost.cowic.de/rc/docs-inspect-trunk.html#doc

Mainly the ones to hpp files.

If you mean adding the XSL params to doc/Jamfile.v2, I don't think that will work, because it will use all the xsl params set, so boost.root will be used twice. I'm not sure what exactly will happen, but if it happens to work, it will be fragile as the order of parameters might change in the future. So I think we really need a mechanism to properly override the parameter. A new feature will solve that.

Although there are other solutions, for example we could add another parameter to boostbook to tell it that it's doing a 'pre-process'. In which case it will just use 'boost:' for the root of these links, since that will be fixed up in the second run.

[John Maddock]

(In [83050]) Fix broken links in doc build. Move some xsl:param's into individual library's Jamfiles. Refs #7899.

[anonymous]

I've fixed the broken link issue - doc built locally within the lib sub-directory still build OK with the correct links as well.

I had hoped I would have solved your duplicate-target error when not using pre-built quickbook, but sadly not :-(

[Daniel James]

My phone line stopped working last night, so I might not be able to try this for a little while. FWIW you don't need to set the library parameter nowadays, the xsl works it out from boost root if it isn't already set.

[Daniel James]

(In [83132]) Merge auto-index fixes. Fixes #7899.

[Daniel James]

Also, [83131] which fixed the bug in boostbook.