boostorg/quickbook

Boost.org quickbook module

quickbook's Issues

Generated section ids have a colon prefix

This problem happens when I build Boost.Log docs locally with the following command line:

b2 -j8 release

The build process produces a lot of errors like this:

Error: no ID for constraint linkend: "log.design".

for various link ids mentioned in the QuickBook [link] tags, and the corresponding links in the final docs are broken.

The problem seems to be because the [link] tags get translated to <link> BoostBook tags with a linkend attribute that matches the id specified in [link] QuickBook tag, but the actual <section> in BoostBook has id with a colon character prepended. For example:

• In QuickBook there is [link log.design Design overview] and the section is started with [section:design Design overview] (which is included into the main document using [include:log design.qbk]).
• In the generated log_doc.xml, the link looks like <link linkend="log.design">Design overview</link> and the section starts with <section id=":log.design"> (note the leading colon in the id). Also, the section starts with a <title><link linkend=":log.design">Design overview</link></title>, where the link also has a leading colon.
• The generated log_doc.docbook is similar to log_doc.xml wrt. ids used in link and section.
• In the generated html documentation, the link looks like <a class="link" href="../"> and points to the root directory of the documentation (i.e. libs/log/doc/html in Boost root). There are log and _log directories in libs/log/doc/html, and in the latter, the design.html file contains <a name=":log.design">.

Here is an attached generated log_doc.xml:
log_doc.xml.gz

This happens on Kubuntu 21.04 with its stock xsltproc and DocBook packages.

Feature Request: Expandable code regions

I would like to be able to specify expandable code regions in the examples imported using import. Having that in the inline code sample would be nice, too, but not my concern right now.

The primary use case is to be able to include #includes in the code samples, hidden by default, so that users are able to view them by clicking on some marker. So, for example, by default the code sample would look like this:

+ #include ...

  void foo()
  {
    // example code here
  }

And after clicking on the "+" it would expand to:

- #include <foo>
  #include <bar>

  void foo()
  {
    // example code here
  }

I realize this would probably require some JavaScript and I have no idea if the BoostBook backend allows this at all, but the feature would be very useful in Boost.Log docs. In Boost.Log, users are asking to see the includes, but the amount of includes sometimes come close in size to the code sample itself, so I'd rather not show them by default.

There may be other cases for this feature as well, such as showing evolution of some code across several code samples, where the pieces of code added previously are shown hidden by default, expandable on click, and the new code is displayed. I'm not sure if there are cases when I'd want an expandable region shown by default, but it would probably be a good idea to have that option. I.e. the markup should probably allow a way to specify if the region has to be hidden or expanded by default.

Warning

Here:

quickbook/src/parsers.hpp

Line 81 in 5f2e8c2

phoenix::bind(&Impl::start)(phoenix::var(impl_), x[t0()])();

Warning:

\quickbook\src\parsers.hpp(81): warning C4709: comma operator within array index expression

Compiling with VS2019

Test suite does not fail on fails?

I see the same UBSAN error multiple times running the tests, but the result reports that everything is fine:

./b2 optimization=speed inlining=full cxxflags=-fno-omit-frame-pointer cxxflags=-fsanitize=address,undefined cxxflags=-fsanitize-address-use-after-scope linkflags=-fsanitize=address,undefined tools/quickbook/test toolset=clang
<...>
clang-linux.link bin.v2/tools/quickbook/src/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/quickbook
quickbook-testing.process-quickbook bin.v2/tools/quickbook/test/anchor-1_1.test/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/anchor-1_1
Generating output file: bin.v2/tools/quickbook/test/anchor-1_1.test/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/anchor-1_1
tools/quickbook/test/anchor-1_1.quickbook:3: warning: Quickbook version undefined. Version 1.1 is assumed
/mnt/g/boost-repo/tools/quickbook/src/main_grammar.cpp:295:28: runtime error: load of value 190, which is not a valid value for type 'bool'
SUMMARY: UndefinedBehaviorSanitizer: undefined-behavior /mnt/g/boost-repo/tools/quickbook/src/main_grammar.cpp:295:28 in
testing.capture-output bin.v2/tools/quickbook/test/anchor-1_1.test2/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/anchor-1_1.run
**passed** bin.v2/tools/quickbook/test/anchor-1_1.test2/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/anchor-1_1.test
<...>
clang-linux.compile.c++ bin.v2/tools/quickbook/test/xinclude/xmlbase2-1_6-alt2.test2/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/text_diff.o
quickbook-testing.process-quickbook-html bin.v2/tools/quickbook/test/xinclude/xmlbase2-1_6-alt2.test-html/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/xmlbase2-1_6-alt2
Generating output file: bin.v2/tools/quickbook/test/xinclude/xmlbase2-1_6-alt2.test-html/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/xmlbase2-1_6-alt2
/mnt/g/boost-repo/tools/quickbook/src/main_grammar.cpp:295:28: runtime error: load of value 190, which is not a valid value for type 'bool'
SUMMARY: UndefinedBehaviorSanitizer: undefined-behavior /mnt/g/boost-repo/tools/quickbook/src/main_grammar.cpp:295:28 in
Unsupported tag: article
Unsupported tag: xi:include
Unsupported tag: xi:include
Unsupported tag: xi:include
Unsupported tag: xi:include
clang-linux.link bin.v2/tools/quickbook/test/xinclude/xmlbase1-1_6-alt2.test-html/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/xmlbase1-1_6-alt2-compare-html
testing.capture-output bin.v2/tools/quickbook/test/xinclude/xmlbase1-1_6-alt2.test-html/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/xmlbase1-1_6-alt2-compare-html.run
**passed** bin.v2/tools/quickbook/test/xinclude/xmlbase1-1_6-alt2.test-html/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/xmlbase1-1_6-alt2-compare-html.test
clang-linux.link bin.v2/tools/quickbook/test/xinclude/xmlbase2-1_6-alt2.test2/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/xmlbase2-1_6-alt2
clang-linux.compile.c++ bin.v2/tools/quickbook/test/xinclude/xmlbase2-1_6-alt2.test-html/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/text_diff.o
testing.capture-output bin.v2/tools/quickbook/test/xinclude/xmlbase2-1_6-alt2.test2/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/xmlbase2-1_6-alt2.run
**passed** bin.v2/tools/quickbook/test/xinclude/xmlbase2-1_6-alt2.test2/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/xmlbase2-1_6-alt2.test
testing.capture-output bin.v2/tools/quickbook/test/xinclude/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/xmlbase-1_6-fail.run
**passed** bin.v2/tools/quickbook/test/xinclude/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/xmlbase-1_6-fail.test
clang-linux.link bin.v2/tools/quickbook/test/xinclude/xmlbase2-1_6-alt2.test-html/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/xmlbase2-1_6-alt2-compare-html
testing.capture-output bin.v2/tools/quickbook/test/xinclude/xmlbase2-1_6-alt2.test-html/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/xmlbase2-1_6-alt2-compare-html.run
**passed** bin.v2/tools/quickbook/test/xinclude/xmlbase2-1_6-alt2.test-html/clang-linux-14/debug/cxxstd-0x-iso/inlining-full/link-static/optimization-speed/xmlbase2-1_6-alt2-compare-html.test
...updated 4755 targets...

Unexpected character warning

I am trying to fix Spirit docs https://github.com/boostorg/spirit/blob/develop/doc/lex/lexer.qbk#L34, but having troubles with bogus warning or broken escaping.

Given:

    [[`"[xyz]\"foo"`]  [The literal string `[xyz]"foo`]]

Renders correctly:

But generates a warning:

lex/lexer.qbk:34: warning: in column:50, unexpected character: "

Fixing it like this:

    [[`"[xyz]\"foo"`]  [The literal string `[xyz]\"foo`]]

Does not eliminate it:

lex/lexer.qbk:34: warning: in column:51, unexpected character: "

And leads to incorrect rendering:

Simple bold formatting in a line beginning is always treated as a list element

The examples in docs are clearly shows that there are some issues with bold formatting https://www.boost.org/doc/libs/1_69_0/doc/html/quickbook/syntax/phrase.html#quickbook.syntax.phrase.line_break

Block elements in phrase templates does not work

[template foo[] [blurb Blah, blah, blah]]

(an example from https://www.boost.org/doc/libs/1_69_0/doc/html/quickbook/versions.html#language_versions.1_7.phrase_block_templates) renders as:

    <para>
      [blurb Blah, blah, blah]
    </para>

An example from https://www.boost.org/doc/libs/1_69_0/doc/html/quickbook/syntax/block.html#quickbook.syntax.block.block errors if typed as-is because of problems with nullary templates

foo.qbk:13: error: Invalid number of arguments passed. Expecting: 11 argument(s), got: 0 argument(s) instead.

but after fixing the error:

[template chapterend[]
[block'''</chapter>''']
]

it renders as:

    <para>
      [block<chapter><title>An example chapter</title>]
    </para>
    <para>
      Content
    </para>
    <para>
      [block</chapter>]
    </para>

boost.org/libs/quickbook gives 404 Not Found

Link in the description of this repository is http://boost.org/libs/quickbook and it is broken

Missing description of what QuickBook is

From the docs I cannot figure out what QuickBook is. The introduction tells me about the history but not what it is. It is a tool that converts qbk files to something else, right? But what?
Can I use QuickBook without a BoostBook? The docs do not tell me this in a straight way.

warning: saved_conditional may be used uninitialized

We get this warning every time we build the docs:

    inlined from ‘void quickbook::quickbook_grammar::impl::init_phrase_elements()’ at /home/alandefreitas/Documents/Code/C++/boost/tools/quickbook/src/phrase_element_grammar.cpp:41:65:
/home/alandefreitas/Documents/Code/C++/boost/tools/quickbook/src/actions.hpp:184:12: warning: ‘<unnamed>.quickbook::cond_phrase_push::saved_conditional’ may be used uninitialized [-Wmaybe-uninitialized]
  184 |     struct cond_phrase_push : scoped_action_base
      |            ^~~~~~~~~~~~~~~~

Boost.Algorithm docs fail to build; adding a blank line lets them build

See boostorg/algorithm@12ade33#commitcomment-77319137

Peter Dimov reports:

If I insert a newline before [endsect:copy_if_while] and [endsect:copy_if_until], it passes.

Boost Algorithm docs fail to build ... don't know why

See boostorg/algorithm@12ade33#commitcomment-77319137

Peter Dimov reports:

If I insert a newline before [endsect:copy_if_while] and [endsect:copy_if_until], it passes.

Spurious warning

This produces a warning when you write [br] in a QBK file:

quickbook/src/actions.cpp

Line 265 in 5f2e8c2

<< "line breaks generate invalid boostbook "

Thing is... it works fine. There is no other "boostbook processor" on the horizon, so the warning is rather pointless. We want to make doc warnings into errors in our CI builds but this is in the way.