OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [docbook] Marking-up class documentation


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 <rwdalpe@gmail.com> 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</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 &amp;</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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]