Docs don't build corectly

[John Maddock]

The signals2 docs don't build correctly when attempting to build the PDF documentation. The problem is the snippet_extractor program which gets invoked with the wrong destination path. In addition, the Jamfile should have a "using boostbook ;" statement at the start otherwise the doc build rules aren't found.

On Linux, building from either libs/signals2/doc or doc/pdf the snippet_extractor is invoked with:

/home/john/bin/boost/bin.v2/libs/signals2/doc/gcc-4.4.3/debug/snippet_extractor "/home/john/bin/boost/bin.v2/libs/signals2/doc/gcc-4.4.3/debug" ../example/custom_combiners.cpp ../example/disconnect_and_block.cpp ../example/doc_view.cpp ../example/doc_view_acm.cpp ../example/doc_view_acm_deconstruct.cpp ../example/extended_slot.cpp ../example/hello_world_multi_slot.cpp ../example/hello_world_slot.cpp ../example/ordering_slots.cpp ../example/passing_slots.cpp ../example/postconstructor_ex1.cpp ../example/postconstructor_ex2.cpp ../example/predestructor_example.cpp ../example/signal_return_value.cpp ../example/slot_arguments.cpp

Which places the xml files in the wrong place.

On Windows the command line is even more bizare:

..\..\..\bin.v2\libs\signals2\doc\msvc-10.0\debug\threading-multi\snippet_extractor.exe ..\..\..\bin.v2\libs\signals2\doc\msvc-10.0\debug\threading-multi\snippet_extractor.pdb "..\..\..\bin.v2\libs\signals2\doc\msvc-10.0\debug\threading
-multi" ..\example\custom_combiners.cpp ..\example\disconnect_and_block.cpp ..\example\doc_view.cpp ..\example\doc_view_acm.cpp ..\example\doc_view_acm_deconstruct.cpp ..\example\extended_slot.cpp ..\example\hello_world_multi_slot.cpp ..\example\hello_world_slot.cpp ..\example\ordering_slots.cpp ..\example\passing_slots.cpp ..\example\postconstructor_ex1.cpp ..\example\postconstructor_ex2.cpp ..\example\predestructor_example.cpp ..\example\signal_return_value.cpp ..\example\slot_arguments.cpp

Either way the net result is:

warning: failed to load external entity "hello_world_def_code_snippet.xml"
tutorial.xml:50: element include: XInclude error : could not load hello_world_def_code_snippet.xml, and no fallback was found
warning: failed to load external entity "hello_world_single_code_snippet.xml"
tutorial.xml:52: element include: XInclude error : could not load hello_world_single_code_snippet.xml, and no fallback was found
warning: failed to load external entity "hello_def_code_snippet.xml"
tutorial.xml:63: element include: XInclude error : could not load hello_def_code_snippet.xml, and no fallback was found
warning: failed to load external entity "world_def_code_snippet.xml"
tutorial.xml:67: element include: XInclude error : could not load world_def_code_snippet.xml, and no fallback was found
warning: failed to load external entity "hello_world_multi_code_snippet.xml"
tutorial.xml:74: element include: XInclude error : could not load hello_world_multi_code_snippet.xml, and no fallback was found
warning: failed to load external entity "hello_world_ordered_code_snippet.xml"
tutorial.xml:94: element include: XInclude error : could not load hello_world_ordered_code_snippet.xml, and no fallback was found
warning: failed to load external entity "good_morning_def_code_snippet.xml"
tutorial.xml:119: element include: XInclude error : could not load good_morning_def_code_snippet.xml, and no fallback was found
warning: failed to load external entity "hello_world_ordered_invoke_code_snippet.xml"

and the result is broken documentation.

[Frank Mori Hess]

(In [66694]) Patch from John Maddock: ​http://lists.boost.org/Archives/boost/2010/11/173288.php

Refs #4872.

[Frank Mori Hess]

I applied the patch posted by John Maddock which works around the bug for the signals2 doc: ​http://lists.boost.org/Archives/boost/2010/11/173288.php. However, according to the report the bug is in Boost.Build when compiling on msvc in debug mode. In the following line from libs/signals2/doc/snippet-extractor.jam:

$(EXTRACTOR-COMMAND) "$(<:D)" $(>)

the ":D" doesn't result in a directory as it should on msvc in debug mode.

[Vladimir Prus]

It seems to me that :D modifier is working as expected, and the problem is that $(EXTRACTOR-COMMAND) expands to two paths -- path to exe and path to pdb. Does $(EXTRACTOR-COMMAND[1]) fix the problem?

[Frank Mori Hess]

I changed EXTRACTOR_COMMAND to EXTRACTOR_COMMAND[1] locally and verified that signals2 doc build still works correctly under Linux after the change. I don't have msvc to verify it resolves the msvc/debug problem there though. Is EXTRACTOR-COMMAND[1] what I was supposed to be doing (that is, should I commit the change to svn)?

[anonymous]

I just tested that with msvc-10 on Windows, and yes it's working there too:

actions extract-snippets bind EXTRACTOR-COMMAND
{
    $(EXTRACTOR-COMMAND[1]) "$(<:D)" $(>)
}

HTH, John.

[Steven Watanabe]

(In [71058]) Make sure that the command works even in debug mode. Refs #4872.

[Steven Watanabe]

This is a pretty simple thing, so I checked it with msvc and gcc using both debug and release and committed it. (I temporarily reverted John's other patch to test debug).