Re: [quickbook] Broken links generated in locally built docs

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2021-03-04 16:26:08

On 3/4/21 6:17 PM, Paul A Bristow via Boost wrote:
> 
> 
>> -----Original Message-----
>> From: Boost <boost-bounces_at_[hidden]> On Behalf Of Andrey Semashev via Boost
>> Sent: 4 March 2021 13:51
>> To: boost_at_[hidden]
>> Cc: Andrey Semashev <andrey.semashev_at_[hidden]>
>> Subject: [boost] [quickbook] Broken links generated in locally built docs
>>
>> Hi,
>>
>> When I'm building QuickBook docs locally for Boost.Log, I'm seeing errors like the following in the end:
>>
>>     Error: no ID for constraint linkend: "log.design".
>>
>> and so on for basically any section id that is used in the QuickBook [link] tag. In the resulting HTML
>> documentation all such links point to the root directory where the HTML docs are located.
>>
>> Looking at the bin.v2/libs/log/doc/log_doc.xml file, for example, for the log.detailed.sink_frontends.sync
>> is, it looks like <link> tags use the id that is specified in QuickBook:
>>
>>     <link linkend="log.detailed.sink_frontends.sync">
>>
>> but the actual section has a colon in front of the id:
>>
>>     <section id=":log.detailed.sink_frontends.sync">
>>
>> Is this a known issue and is there a workaround?
>>
>> I'm using DocBook XML from the Kubuntu package, which has version 4.5-9, and a freshly built
>> QuickBook from develop. I used to build docs locally fine before, and did not change the configuration
>> since, but I may have upgraded Kubuntu since I last built the docs.
> 
> I've seem this error before - but not with the phantom colon.
> 
> I've got uptodate with
> 
> $ git log
> commit 699fcc12815fd91b2e3a3066097beb62cdffc957 (HEAD -> develop, origin/master, origin/develop, origin/HEAD)
> Author: Andrey Semashev <andrey.semashev_at_[hidden]>
> Date:   Wed Feb 10 14:45:52 2021 +0300
> 
> 
> And tried to build
> 
> It start with
> 
> Jamfile.v2:274: Unescaped special character in argument <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/log/doc/html
> 
> But I can't see the Unescaped special character - seems phantom 😉

Probably the colon in http://. Fixed, thanks.

> And after some OK stuff, goes wrong with these messages
> 
> Generate XML output for dir I:/boost/boost/log/utility/
> Running plantuml with JAVA...
> lookup cache used 2353/65536 hits=29808 misses=2615
> finished...
> Jamfile<I:\boost\libs\log\doc>.gen-references <l.>expressions_refs
> '#' is not recognized as an internal or external command,
> operable program or batch file.
> 'xsltproc' is not recognized as an internal or external command,
> operable program or batch file.
> 
> #    echo "*** Executing " xsltproc -o "tmp\expressions_reference.qbk" "gen_references.xsl" "tmp\expressions_reference.xml"
>      xsltproc -o "tmp\expressions_reference.qbk" "gen_references.xsl" "tmp\expressions_reference.xml"
> 
> ...failed Jamfile<I:\boost\libs\log\doc>.gen-references <l.>expressions_refs...

It looks like the commented line (starting with #) is passed to the 
system shell (cmd.exe on Windows), which causes the error. Also fixed in 
develop/master, thanks.

These two errors are not the culprit though, I still have the same issue 
after fixing those.

> So I commented the offending line out and re-ran without 1st error message,
> but with the same end result.
> 
> I am on Windows 10 and I think I am up-to-date with Doxygen and Quickbook.
> 
> I have re-run in administrator mode (seems necessary to access xsltproc) .
> 
> Lots of ambiguous namespaces. Log attached FWIW (not much?)

There are no "no ID for constraint linkend" errors in your output, 
though it still has errors from the commented line. Could you update 
libs/log and try again?

Also, what is your DocBook XML version and how are you running b2? I'm 
running:

   b2 -j8 release

from libs/log/doc.