[iterator] [documentation] need help generating
I'm a n00b regarding Boost's documentation generation. I've gone through https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted to set up my system (Windows 7, MSVC9, try to do everything from the Windows command line). I then navigate to trunk\libs\iterator\doc and run b2 (the b2 I have from the 1.51.0 release; would that matter?). I get -------- don't know how to make <p..\..\..\bin.v2\libs\iterator\doc\msvc-9.0\debug\threading-multi-object(xinclude-scanner)@987>iterator.xml ...found 37 targets... ...updating 5 targets... ...can't find 1 target... ...can't make 2 targets... common.mkdir ..\..\..\bin.v2\libs\iterator\doc common.mkdir ..\..\..\bin.v2\libs\iterator\doc\msvc-9.0 common.mkdir ..\..\..\bin.v2\libs\iterator\doc\msvc-9.0\debug common.mkdir ..\..\..\bin.v2\libs\iterator\doc\msvc-9.0\debug\threading-multi quickbook.quickbook-to-boostbook ..\..\..\bin.v2\libs\iterator\doc\msvc-9.0\debug\threading-multi\iterator.xml Generating Output File: ..\..\..\bin.v2\libs\iterator\doc\msvc-9.0\debug\threading-multi\iterator.xml quickbook\iterator.qbk:24: warning: Quickbook version undefined. Version 1.1 is assumed quickbook\concepts.qbk:159: warning: line breaks generate invalid boostbook (will only note first occurrence). quickbook\facade.qbk:491: warning: in column:6, unexpected character: ` [...lots more warnings of this nature...] quickbook\facade.qbk:612: warning: in column:52, unexpected character: ` quickbook\utilities.qbk:77: warning: in column:14, unexpected character: ` quickbook\utilities.qbk:77: warning: in column:44, unexpected character: ` quickbook\utilities.qbk:79: warning: in column:12, unexpected character: ` quickbook\utilities.qbk:79: warning: in column:15, unexpected character: ` quickbook\utilities.qbk:109: warning: in column:14, unexpected character: ` quickbook\utilities.qbk:109: warning: in column:46, unexpected character: ` ...skipped <p..\..\..\bin.v2\libs\iterator\doc\msvc-9.0\debug\threading-multi>iterator.docbook for lack of <p..\..\..\bin.v2\libs\iterator\doc\msvc-9.0\debug\threading-multi-object(xinclude-scanner)@987>iterator.xml... ...skipped <phtml>standalone_HTML.manifest for lack of <p..\..\..\bin.v2\libs\iterator\doc\msvc-9.0\debug\threading-multi>iterator.docbook... ...skipped 2 targets... ...updated 6 targets... -------- Then I run it again: -------- ...found 37 targets... ...updating 2 targets... xslt-xsltproc.windows ..\..\..\bin.v2\libs\iterator\doc\msvc-9.0\debug\threading -multi\iterator.docbook xslt-xsltproc-dir.windows html\standalone_HTML.manifest Error: no ID for constraint linkend: indirecct. ...updated 2 targets... -------- This seems to throw everything into trunk\libs\iterator\doc\html. However, these generated html documents don't seem to be the same as those in the Boost releases. For example, the table of contents is deeper in the generated index.html than the 1.51.0 release one (which looks be identical to trunk/libs/iterator/doc/index.html), and it lacks documentation for function_input_iterator. It seems like I'm doing something wrong, and I'm not really sure what to make of the various errors and warnings I'm getting. Would anyone be kind of enough to help me out here? Oh, my user-config.jam file, located in "C:/Users/Jeffrey/", looks like -------- using xsltproc : C:/Users/Jeffrey/boost-tools/libxslt-1.1.26.win32/bin/xsltproc.exe ; using boostbook : C:/Users/Jeffrey/boost-tools/xml/docbook-xsl-1.77.1 : C:/Users/Jeffrey/boost-tools/xml/docbook-xml-4.2 ; using quickbook : %BOOST_ROOT%/dist/bin/quickbook ; -------- BOOST_ROOT refers to my Boost 1.51.0 installation, and C:/Users/Jeffrey/boost-tools/bin is part of my path. Let me know if other information is needed. TIA, - Jeff
AMDG On 10/13/2012 03:07 PM, Jeffrey Lee Hellrung, Jr. wrote:
I'm a n00b regarding Boost's documentation generation. I've gone through
https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted
to set up my system (Windows 7, MSVC9, try to do everything from the Windows command line). I then navigate to
trunk\libs\iterator\doc
and run b2 (the b2 I have from the 1.51.0 release; would that matter?).
It does matter, but not that much. (trunk b2 fixes the "can't make" problem). I didn't notice this originally, so I still need to update the version number in the trunk to account for it.
I get
-------- don't know how to make <p..\..\..\bin.v2\libs\iterator\doc\msvc-9.0\debug\threading-multi-object(xinclude-scanner)@987>iterator.xml <snip> --------
Then I run it again:
-------- <snip> --------
This seems to throw everything into trunk\libs\iterator\doc\html. However, these generated html documents don't seem to be the same as those in the Boost releases. For example, the table of contents is deeper in the generated index.html than the 1.51.0 release one (which looks be identical to trunk/libs/iterator/doc/index.html), and it lacks documentation for function_input_iterator. It seems like I'm doing something wrong, and I'm not really sure what to make of the various errors and warnings I'm getting.
Would anyone be kind of enough to help me out here?
It looks like the the quickbook port of the iterator docs is incomplete. The docs in the release are built from the rst sources.
Oh, my user-config.jam file, located in "C:/Users/Jeffrey/", looks like
-------- using xsltproc : C:/Users/Jeffrey/boost-tools/libxslt-1.1.26.win32/bin/xsltproc.exe ;
using boostbook : C:/Users/Jeffrey/boost-tools/xml/docbook-xsl-1.77.1 : C:/Users/Jeffrey/boost-tools/xml/docbook-xml-4.2 ;
using quickbook : %BOOST_ROOT%/dist/bin/quickbook ; --------
BOOST_ROOT refers to my Boost 1.51.0 installation, and C:/Users/Jeffrey/boost-tools/bin is part of my path. Let me know if other information is needed.
In Christ, Steven Watanabe
On Sat, Oct 13, 2012 at 3:34 PM, Steven Watanabe <watanabesj@gmail.com>wrote:
AMDG
On 10/13/2012 03:07 PM, Jeffrey Lee Hellrung, Jr. wrote:
I'm a n00b regarding Boost's documentation generation. I've gone through
https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted
to set up my system (Windows 7, MSVC9, try to do everything from the Windows command line). I then navigate to
trunk\libs\iterator\doc
and run b2 (the b2 I have from the 1.51.0 release; would that matter?).
It does matter, but not that much. (trunk b2 fixes the "can't make" problem). I didn't notice this originally, so I still need to update the version number in the trunk to account for it.
Is the "don't know how to make" problem an issue here?
I get
-------- don't know how to make
<p..\..\..\bin.v2\libs\iterator\doc\msvc-9.0\debug\threading-multi-object(xinclude-scanner)@987>iterator.xml
<snip> --------
Then I run it again:
-------- <snip> --------
This seems to throw everything into trunk\libs\iterator\doc\html. However, these generated html documents don't seem to be the same as those in the Boost releases. For example, the table of contents is deeper in the generated index.html than the 1.51.0 release one (which looks be identical to trunk/libs/iterator/doc/index.html), and it lacks documentation for function_input_iterator. It seems like I'm doing something wrong, and I'm not really sure what to make of the various errors and warnings I'm getting.
Would anyone be kind of enough to help me out here?
It looks like the the quickbook port of the iterator docs is incomplete. The docs in the release are built from the rst sources.
- How do I build the docs from the rst sources? - In your opinion, would it best to update the quickbook docs (something I could probably do) and (somehow) have the release switch to it?
Oh, my user-config.jam file, located in "C:/Users/Jeffrey/", looks like
-------- using xsltproc : C:/Users/Jeffrey/boost-tools/libxslt-1.1.26.win32/bin/xsltproc.exe ;
using boostbook : C:/Users/Jeffrey/boost-tools/xml/docbook-xsl-1.77.1 : C:/Users/Jeffrey/boost-tools/xml/docbook-xml-4.2 ;
using quickbook : %BOOST_ROOT%/dist/bin/quickbook ; --------
BOOST_ROOT refers to my Boost 1.51.0 installation, and C:/Users/Jeffrey/boost-tools/bin is part of my path. Let me know if other information is needed.
In Christ, Steven Watanabe
Thanks Steven! I had a feeling you might say something :) - Jeff
AMDG On 10/13/2012 03:55 PM, Jeffrey Lee Hellrung, Jr. wrote:
Is the "don't know how to make" problem an issue here?
No. The commands executed are correct. It's mostly annoying.
I get
-------- don't know how to make
<p..\..\..\bin.v2\libs\iterator\doc\msvc-9.0\debug\threading-multi-object(xinclude-scanner)@987>iterator.xml
<snip> --------
Then I run it again:
-------- <snip> --------
This seems to throw everything into trunk\libs\iterator\doc\html. However, these generated html documents don't seem to be the same as those in the Boost releases. For example, the table of contents is deeper in the generated index.html than the 1.51.0 release one (which looks be identical to trunk/libs/iterator/doc/index.html), and it lacks documentation for function_input_iterator. It seems like I'm doing something wrong, and I'm not really sure what to make of the various errors and warnings I'm getting.
Would anyone be kind of enough to help me out here?
It looks like the the quickbook port of the iterator docs is incomplete. The docs in the release are built from the rst sources.
- How do I build the docs from the rst sources?
There's an rst2html script in the doc subdirectory. I don't really know anything about rst, though.
- In your opinion, would it best to update the quickbook docs (something I could probably do)
No opinion. I'm not the maintainer and I don't know how close the quickbook port is to being complete. I always use quickbook for my own documentation, but for a library that already exists, I usually stick with what's there unless I'm doing a complete overhaul.
and (somehow) have the release switch to it?
That's just a matter of changing the redirect in libs/iterator/index.html. I believe Daniel James builds the documentation for the releases, so you'll have to ask him if there's any global list of documentation to build. In Christ, Steven Watanabe
participants (2)
-
Jeffrey Lee Hellrung, Jr. -
Steven Watanabe