Winslow,
Your solution actually makes a lot of sense. One drawback for me: the use
of a customisation layer when processing the document. I'd rather go with
XInclude instead of it (make a reference to current document, with a
specific XPointer to the synopsis to copy); it seems however that few
processors are able to understand those references (errors like "An
xpointer was specified that points to a location in the source infoset.
This location cannot be accessed due to the streaming nature of the
processor." when using no href or href="", and recursive include with an
href pointing to the current document, completely forgetting about the
xpointer attribute), and this is far from new (
http://services.renderx.com/lists/xep-support/5736.html). Maybe with a
custom XInclude preprocessing step before generating any output…?
<xi:include href="" xpointer="METHODSYNOPSISID"/>
Thank you for your detailed answer!
Thibaut Cuvelier
On 10 July 2015 at 08:10, Winslow Dalpe <[email protected]> wrote:
> Thibaut,
>
> You might have luck posting this to the docbook-apps mailing list as well.
> My response is posted below the quote of your message.
>
>
> On 07/09/2015 08:52 AM, Thibaut Cuvelier wrote:
>
>> Dear list,
>>
>>
>> Currently, I'm trying to convert object-oriented documentation as DocBook
>> (specifically, a C++ library, Qt). The pages with linear content are no
>> problem (such as
>> http://doc.qt.io/qt-5/qtbluetooth-heartlistener-example.html), but I'm
>> ill-at-ease when it comes to class documentation, such as
>> http://doc.qt.io/qt-5/qlowenergycharacteristic.html.
>>
>> My first idea was to create an <article> for each class, with a first
>> section Detailed Description, then another one Member Function
>> Documentation (mapping the structure of the original documentation);
>> avoiding those sections would even be better, as they add no semantics to
>> the document. This second section would have contained a <classsynopsis>
>> with all the methods in <methodsynopsis> and their documentation (i.e. a
>> set of paragraphs for each method). However, a <methodsynopsis> does not
>> allow textual content as <para>.
>>
>> <?xml version="1.0" encoding="UTF-8"?>
>> <db:article xmlns:db="http://docbook.org/ns/docbook";
>> xmlns:xlink="http://www.w3.org/1999/xlink";
>> version="5.0">
>> <db:info>
>> <db:title>QLowEnergyCharacteristic</db:title>
>> </db:info>
>> <db:section>
>> <db:title>Detailed Description</db:title>
>> <db:para>The <db:link
>> xlink:href="qlowenergycharacteristic.html"
>> >QLowEnergyCharacteristic</db:link> class stores information about a
>> Bluetooth Low
>> Energy service characteristic.</db:para>
>> <!-- ... -->
>> </db:section>
>> <db:section>
>> <db:title>Member Function Documentation</db:title>
>> <db:classsynopsis>
>> <db:ooclass>
>> <db:classname>QLowEnergyCharacteristic</db:classname>
>> </db:ooclass>
>> <db:constructorsynopsis
>> xml:id="QLowEnergyCharacteristic">
>> <db:para>Construct a new
>> QLowEnergyCharacteristic. A default-constructed instance of this class is
>> always invalid.</db:para>
>> </db:constructorsynopsis>
>> <db:constructorsynopsis
>> xml:id="QLowEnergyCharacteristic-2">
>> <db:methodparam>
>> <db:modifier>const</db:modifier>
>> <db:type>QLowEnergyCharacteristic &</db:type>
>> <db:parameter>other</db:parameter>
>> </db:methodparam>
>> <db:para>Construct a new QLowEnergyCharacteristic
>> that is a copy of other.</db:para>
>> </db:constructorsynopsis>
>> <!-- ... -->
>> </db:classsynopsis>
>> </db:section>
>> </db:article>
>>
>> Few examples exist for class documentations; the only one I was able to
>> find is
>> https://raw.githubusercontent.com/mfuchs23/dbdoclet/39fdff549d4477cdaf29a12c3712411fbff0a489/org.dbdoclet.doclet.docbook/doc/Reference.xml.
>> It uses one section per class, starting with a <classsynopsis>, then nested
>> sections afterwards for the methods if there is anything to say about them.
>>
>> This way of doing things makes me feel dubious, as there is no direct
>> link between the class and its method: each method basically copies a part
>> of the class definition. In my case, as all methods have a few words about
>> them, there is a high risk of someone changing (inadvertently) a letter or
>> anything (<classsynopsis> could even be avoided); and at the semantic
>> level, the notion of class or method documentation would be completely lost
>> (as the real documentation would just be a set of sections).
>>
>> Going to the Definitive Guide for DocBook 5.1, <refentry> seems to be
>> preferred, but it's roughly the same idea.
>>
>> How would you do it? What's the best way of using the current mark-up?
>> (Ideally, I'd rather avoid customisation to have a standard content model,
>> but I'm not against using a prerelease version.)
>>
> Disclaimer: I'm still fairly new to Docbook and its associated toolchain,
> so someone may give better advice than this.
>
> The original sender in
> https://lists.oasis-open.org/archives/docbook/200302/msg00096.html asks a
> question similar in nature to yours ("Is there supposed to be a
> `methodsynopsisinfo` element?"), so that might be worth checking out. The
> answer to their question was "No."
>
> I think your best bet with fully uncustomized Docbook would be `refentry`.
> It is also available in Docbook V5.0, so you wouldn't need to use 5.1 if
> you don't want. Take a look at the last two examples of
> http://www.docbook.org/tdg5/en/html/refentry.html for example markup of
> functions and types. If you use `methodsynopsis` instead of `refentry` or
> some other combination of markup, here is my suggestion.
>
> If you don't want to add a customization to the schema, I would suggest
> building out the entirety of the `classsynopsis` with your
> `methodsynopsis`, and make their titles link to `section`s farther down in
> the document. That's basically what the QT documentation you linked to
> looks like to me (class synopsis with full method info at the top that
> links to sections which contain the method signature again and then a
> description).
>
> So you would have something like
>
> <classsynopsis>
> ...
> <methodsynopsis xml:id="METHODSYNOPSISID">
> ...
>
> <methodname><link linkend="SECTIONID">method
> title</link></methodname>
>
> ...
> </methodsynopsis>
> ...
> </classsynopsis>
> ...
> <section xml:id="SECTIONID">
> more details here
> ...
> </section>
>
>
> Then your challenge becomes whether or not you want to manually duplicate
> the `methodsynopsis` again in the linked `section` or somehow generate it.
> If you were generating it, my first, naive instinct would be an XSL
> customization of some sort. Maybe slapping a role on `xref` elements that
> link to the `methodsynopsis` and then adding a template that matches the
> role that would `apply-templates` on the element pointed to by the xref
> rather than doing all of the gentext and linking that xref normally does.
>
> So, in our above example it would become
>
> ...
>
> CLASSSYNOPSISS STUFF UP HERE
>
> ...
>
> <section xml:id="SECTIONID">
>
> <xref role="copy-methodsynopsis" endterm="METHODSYNOPSISID"/>
> ...
>
> </section>
>
>
> Then in your customization layer you would have a template (this might not
> be totally correct syntactically)
>
> <xsl:template match="db:xref[@role='copy-methodsynopsis']">
> <xsl:apply-templates
> select="//db:methodsynopsis[@id=current()/@linkend]"/>
> </xsl:template>
>
>
> Again, that's my beginner's take on the situation. Someone else with more
> experience may have a better idea. If you do receive a satisfactory
> solution that doesn't get posted to the mailing list, could you post it
> there so we can all benefit?
>
> Thank you,
> Winslow Dalpe
>
