Re: [docbook] Description/signal/properties links in html pages (generated using xsltproc) not working

[Vishnu Motghare <vishnumotghare@gmail.com>]

Hello Thomas,

On Mon, May 4, 2020 at 7:03 PM Thomas Schraitle <tom_schr@web.de> wrote:
>
> Hi Vishnu,
>
> On Montag, 4. Mai 2020 15:09:35 CEST Vishnu Motghare wrote:
> > I'm trying to generate documentation for gdbus interfaces.
> > I've used gdbus-codegen command  to generate docbook,xml files.
> > [...]
> > Above command generated docbook-net.Corp.MyApp.Frobber.xml which Is
> > included in my-doc.xml file.
> >
> > Example my-doc.xml
> > {{{
> > <?xml version="1.0"?>
> > <!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V5.0//EN'
> >
> > 'http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd' [ <!ENTITY %
> > local.common.attrib "xmlns:xi  CDATA  #FIXED
> > 'http://www.w3.org/2003/XInclude'">
> > ]>
>
> The XInclude namespace is wrong. Change "2003" to "2001". See here:
>
>   https://www.w3.org/TR/xinclude/#syntax

Thanks for correcting me, I observed that docbook xml
(docbook-net.Corp.MyApp.Frobber.xml) generated by gdbus-codegen has
Docbook V4.1.2, So I change my-doc.xml accordingly.
{{{
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
]>
}}}

> If I remember correctly, there was an failed attempt to change the namespace.
> However, they switched back to the "old" one.
>
> Apart from that, even if you add the correct namespace, it won't work. There
> are no XInclude elements in the DocBook 5.0 DTD. Better use the solution
> below.
>
> Just to let you know, upcoming releases of DocBook does _not_ contain the DTD
> anymore. You should consider switching to RELAX NG and validating your DocBook
> documents with jing.
>
>
> > [...]
> >     <xi:include href="docbook-net.Corp.MyApp.Frobber.xml"/>
> > [...]
> > Html pages generated, but description, signal,properties links at top
> > left are not working properly.
>
> The referenced resource could not be included due to the wrong namespace.
> Better add the XInclude namespace directly like so:
>
>   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
>               href="docbook-net.Corp.MyApp.Frobber.xml"/>
>
> Can you add it and see if that works? If that doesn't help, watch for any
> error messages.

I checked for error using xmlint , which throws following error ,
which I fixed it & then tried above solution. It didn't  work
{{{
$ xmllint --noout --xinclude --postvalid --noent my-doc.xml
my-doc.xml:9: element part: validity error : Element part content does
not follow the DTD, expecting (beginpage? , partinfo? , (title ,
subtitle? , titleabbrev?) , partintro? , (appendix | chapter | toc |
lot | index | glossary | bibliography | article | preface | refentry |
reference)+), got (partintro title refentry )
Document my-doc.xml does not validate
}}}

I checked the .html file generated by xsltproc & found that following
code generated for shortcut  (description, signal ..)
{{{
<a href="#" class="shortcut">Top</a><span id="nav_description">  <span
class="dim">|</span>
                  <a href="#gdbus-net.Corp.MyApp.Frobber.description"
class="shortcut">Description</a></span><span id="nav_properties">
<span class="dim">|</span>
                  <a href="#gdbus-net.Corp.MyApp.Frobber.properties"
class="shortcut">Properties</a></span><span id="nav_signals">  <span
class="dim">|</span>
                  <a href="#gdbus-net.Corp.MyApp.Frobber.signals"
class="shortcut">Signals</a></span>
}}}

The reference for above link should be present in html file to work it
properly. I checked for reference code

Following  reference code is generated for description in .html file
{{{
<div class="refsect1">
<a name="gdbus-interface-net-Corp-MyApp-Frobber"></a><h2>Description</h2>
<p>    NetworkInterface provides methods to configure ip, mask, dhcp,
gateway, dns etc.
    It handles network up/down activity and configures the network
automatically.
</p>
</div>
}}}

Modified above code  as below and it worked
{{{
<div class="refsect1">
<a name="gdbus-net.Corp.MyApp.Frobber.description"></a><h2>Description</h2>
<p>    NetworkInterface provides methods to configure ip, mask, dhcp,
gateway, dns etc.
    It handles network up/down activity and configures the network
automatically.
</p>
</div
}}}

Any idea why reference links for description, signal are not creating properly?

Regards,
Vishnu