Aristedes Maniatis | 18 Jul 12:42 2015
Picon

docbook to RSS

I'm wanting to write release notes for our product in docbook. We already have very successful docbook
tooling around the manual, so it makes sense to pull this in as well.

My goals are to create nice looking webpages (here is our existing docbook output [1]) and also a RSS feed. So
I was thinking that semantically it would be preferable to not just have sections/chapters, but
something that we could transform to RSS more precisely.

I looked at the <revision> element, but <revdescription> doesn't support sections, subheadings, etc.
and by default <revision> all wants to print on the title page, doesn't generate TOC, etc. So I'd have a lot
of customising to do.

* Has anyone tried to do this?

* What is the current state of <revision> for the purpose of versioning things other than the docbook
content itself?

* Is there any XSLT for creating RSS from docbook content? I see something in the docbook-website project
but the sourceforge pages are down and I don't really understand how docbook-website works.

* how does the docbook project itself produce release notes?

Thanks for any help
Ari Maniatis

[1] http://www.ish.com.au/s/onCourse/doc/latest/manual/

--

-- 
-------------------------->
Aristedes Maniatis
ish
(Continue reading)

Bob Stayton | 14 Jul 21:05 2015
Picon

DocBook Technical Committee Meeting Agenda: 15 July 2015

DocBook Technical Committee Meeting Agenda: 15 July 2015
=============================================================

The DocBook Technical Committee will meet on Wednesday, 15 July 2015
at 1:00pm ET for 90 minutes.

Attendance at teleconferences is restricted to members
(and prospective members) of the committee.

This is the phone number for Wednesday's DocBook TC call:

Phone: +1-719-387-5556
  Code: 902213

The DocBook TC uses the #docbook IRC channel on
irc.freenode.org.  The IRC channel is used for exchanging
URIs, providing out-of-band comments, and other aspects
of the teleconference, so please join us there if at
all possible.

Agenda

1. Roll call
2. Accepting the minutes [1] of the previous meeting.
3. Next meeting: 19 August 2015
4. Review of the agenda.
5. Review of open action items

   a.  Norm to convince someone to implement the new XInclude
       standard.
(Continue reading)

Thibaut Cuvelier | 12 Jul 18:33 2015
Picon

Re: 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 <at> 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.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 &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[ <at> role='copy-methodsynopsis']">
    <xsl:apply-templates select="//db:methodsynopsis[ <at> id=current()/ <at> 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

Thibaut Cuvelier | 9 Jul 17:52 2015
Picon

Marking-up class documentation

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 &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.)



A follow-up question is the handling of C and C++'s enum (equivalent to an integer type, where values can have names). I don't think there is anything suited for these cases in DocBook yet. https://github.com/mfuchs23/dbdoclet/blob/39fdff549d4477cdaf29a12c3712411fbff0a489/org.dbdoclet.doclet.docbook/doc/Reference.xml#L1634 uses a series of public fields for Java enumerations, but that makes no sense for C++.

For example, I'd like to convert the enumeration http://doc.qt.io/qt-5/qlowenergycharacteristic.html#PropertyType-enum. I would think about something like this:

        <db:enumsynopsis>
            <db:enumname>QLowEnergyCharacteristic::PropertyType</db:enumname>
            <db:enumvalue>
                <db:litteral type="constant">QLowEnergyCharacteristic::Unknown</db:litteral>
                <db:litteral type="int">0x00</db:litteral>
                <db:para>The type is not known.</db:para>
            </db:enumvalue>
        </db:enumsynopsis>

Is there anything that I've missed about this?


Thanks in advance for your thoughts!
Thibaut Cuvelier

Hussein Shafie | 26 Jun 10:03 2015

Re: New resources for those interested in DocBook 5.1 new assembly and topic elements

On 06/26/2015 01:25 AM, Aaron DaMommio wrote:
> Hussein,
> Would the assembly allow one to compose a document from multiple source
> files that did NOT contain topic elements, but rather chapter or section
> elements? Or must the components of an assembly always derive from a topic?

You may reference in an  assembly any container having title elements 
and/or info, that is, chapter, section, appendix, etc.

This is explained in the tutorial which unfortunately must be used as a 
``reference'' because "DocBook 5.1: The Definitive Guide 1.4.14" 
(http://docbook.org/tdg51/en/html/docbook.html) is somewhat outdated:

---
2. What is a topic?

...

In this tutorial, we'll use assembly elements which reference topic 
elements exclusively. In fact, any DocBook container (chapter, section, 
appendix, etc) may act as a topic —some contents dealing about a single 
topic stored in its one file— and as such, be referenced in assemblies.
---

http://www.xmlmind.com/tutorials/DocBookAssemblies/index.html#what_is_topic

> Thanks,
> Aaron
>
>
> On Thu, Jun 25, 2015 at 3:06 AM, Hussein Shafie <hussein <at> xmlmind.com
> <mailto:hussein <at> xmlmind.com>> wrote:
>
>     Two new resources for those interested in DocBook 5.1 new assembly
>     and topic elements:
>
>     * Free, open source, assembly processor: XMLmind Assembly Processor.
>     http://www.xmlmind.com/xmleditor/assembly.shtml
>
>     * Tutorial: DocBook Assemblies and Topics for the Impatient.
>     http://www.xmlmind.com/tutorials.html
>
>     ---------------------------------------------------------------------
>     To unsubscribe, e-mail: docbook-unsubscribe <at> lists.oasis-open.org
>     <mailto:docbook-unsubscribe <at> lists.oasis-open.org>
>     For additional commands, e-mail: docbook-help <at> lists.oasis-open.org
>     <mailto:docbook-help <at> lists.oasis-open.org>
>
>
>
>
> --
> --------------------------------------
> Aaron DaMommio: Husband, father, writer, juggler, and expert washer of
> dishes.
> - My blog: http://aarondamommio.blogspot.com
> - Need a juggler? http://amazingaaronjuggler.blogspot.com/
> =======================================
Hussein Shafie | 25 Jun 10:06 2015

New resources for those interested in DocBook 5.1 new assembly and topic elements

Two new resources for those interested in DocBook 5.1 new assembly and 
topic elements:

* Free, open source, assembly processor: XMLmind Assembly Processor.
http://www.xmlmind.com/xmleditor/assembly.shtml

* Tutorial: DocBook Assemblies and Topics for the Impatient.
http://www.xmlmind.com/tutorials.html
Bob Stayton | 27 May 19:51 2015
Picon

DocBook Technical Committee Meeting Minutes: 27 May 2015

DocBook Technical Committee Meeting Minutes: 27 May 2015
=============================================================

The DocBook Technical Committee met on Wednesday, 27 May 2015
at 1:00pm ET.

1. Roll call

Present: Dick Hamilton, Scott Hudson, Larry Rowland,
Bob Stayton, Norm Walsh

Regrets: Jirka Kosek

2. Accepted the minutes [1] of the previous (March) meeting.

3. Next meeting: 17 June 2015

This was changed to 24 June 2015.

4. Review of the agenda.

No new items.

5. Review of open action items

   a.  Norm to convince someone to implement the new XInclude
       standard.
       CONTINUED

   b.  Bob to integrate publishers XSL into DocBook XSL.
       CONTINUED

   c.  Bob to work with Norm to request Oxygen to implement
       XInclude 1.1.
       COMPLETED

6.  Publisher's and eLearning subcommittee reports

No subcommittee meetings.

7.  XInclude 1.1 status.

Norm reported that the W3C will be publishing a new CR draft
soon, with changes regarding attribute copying.

8.  DocBook 5.1 release

Norm reported he has resolved all the open issues except for
four. He will address the final four, which don't require TC
input.  Norm proposed that when he has fixed them all, he will
resubmit to OASIS.  Seconded and approved.

8a.  DocBook marketing

Scott suggested we start thinking about a marketing plan for
getting the word out about DocBook 5.1, assuring the world that
DocBook is alive and well.

ACTION: Bob will ask Chet at OASIS about getting an OASIS press
release.

Other TC members will look into newsletters, social media, and
other avenues of getting the word out.

9.  Review of Requests for Enhancement

     To browse a specific RFE, enter the URL (on one line):

       https://sourceforge.net/p/docbook/rfes/300/

     RFEs to revisit for 6.0

     247   1907003  biblioid content model too broad

    RFEs under discussion

    Ticket  Tracker
     260   2820947  Ability to transclude text
     273   3035565  Allow sections at any level
     291   3491860  license tag  (hold for 5.2)
     306            Allow Block Elements inside abstract

    No new RFEs

-----

[1] https://lists.oasis-open.org/archives/docbook-tc/201503/msg00016.html

--

-- 
Bob Stayton
Sagehill Enterprises
bobs <at> sagehill.net
Bob Stayton | 26 May 19:00 2015
Picon

DocBook Technical Committee Meeting Agenda: 27 May 2015

DocBook Technical Committee Meeting Agenda: 27 May 2015
=============================================================

The DocBook Technical Committee will meet on Wednesday, 27 May 2015
at 1:00pm ET for 90 minutes.

Attendance at teleconferences is restricted to members
(and prospective members) of the committee.

This is the phone number for Wednesday's DocBook TC call:

Phone: +1-719-387-5556
  Code: 902213

The DocBook TC uses the #docbook IRC channel on
irc.freenode.org.  The IRC channel is used for exchanging
URIs, providing out-of-band comments, and other aspects
of the teleconference, so please join us there if at
all possible.

Agenda

1. Roll call
2. Accepting the minutes [1] of the previous (March) meeting.
3. Next meeting: 17 June 2015
4. Review of the agenda.
5. Review of open action items

   a.  Norm to convince someone to implement the new XInclude
       standard.

   b.  Bob to integrate publishers XSL into DocBook XSL.

   c.  Bob to work with Norm to request Oxygen to implement
       XInclude 1.1.

6.  Publisher's and eLearning subcommittee reports

7.  XInclude 1.1 status.

8.  DocBook 5.1 release

9.  Review of Requests for Enhancement

     To browse a specific RFE, enter the URL (on one line):

       https://sourceforge.net/p/docbook/rfes/300/

     RFEs to revisit for 6.0

     247   1907003  biblioid content model too broad

    RFEs under discussion

    Ticket  Tracker
     260   2820947  Ability to transclude text
     273   3035565  Allow sections at any level
     291   3491860  license tag  (hold for 5.2)
     306            Allow Block Elements inside abstract

    No new RFEs

-----

[1] https://lists.oasis-open.org/archives/docbook-tc/201503/msg00016.html

--

-- 
Bob Stayton
Sagehill Enterprises
bobs <at> sagehill.net
Daniel Pocock | 26 May 17:04 2015

bookinfo author blog URLs


Hi,

In the bookinfo <author/> element, is there a recommended way to add
URLs for an author's home page, blog, etc?

Regards,

Daniel
Bob Stayton | 23 Mar 16:44 2015
Picon

DocBook Technical Committee Meeting Agenda: 25 March 2015

DocBook Technical Committee Meeting Agenda: 25 March 2015
=============================================================

The DocBook Technical Committee will meet on Wednesday, 25 March 2015
at 1:00pm ET for 90 minutes.

Attendance at teleconferences is restricted to members
(and prospective members) of the committee.

This is the phone number for Wednesday's DocBook TC call:

Phone: +1-719-387-5556
  Code: 902213

The DocBook TC uses the #docbook IRC channel on
irc.freenode.org.  The IRC channel is used for exchanging
URIs, providing out-of-band comments, and other aspects
of the teleconference, so please join us there if at
all possible.

Agenda

1. Roll call
2. Accepting the minutes [1] of the previous (January) meeting.
3. Next meeting: 15 April 2015
4. Review of the agenda.
5. Review of open action items

   a.  Norm to work with OASIS to advance DocBook 5.1 to
       OASIS Standard.

   b.  Norm to convince someone to implement the new XInclude
       standard.

   c.  Bob to integrate publishers XSL into DocBook XSL.

   d.  Bob to work with Norm to request Oxygen to implement
       XInclude 1.1.

   e.  Jirka to work with Norm to post the new DocBook
       Transclusions document.

   f.  Bob to follow up with Norm about OASIS tickets for
       DocBook 5.1 submittal.

   g.  Dick will post a request for GSOC ideas and mentors.

6.  Publisher's and eLearning subcommittee reports

7.  XInclude 1.1 status.

8.  DocBook 5.1 release

9.  Review of Requests for Enhancement

     To browse a specific RFE, enter the URL (on one line):

       https://sourceforge.net/p/docbook/rfes/300/

     RFEs to revisit for 6.0

     247   1907003  biblioid content model too broad

    RFEs under discussion

    Ticket  Tracker
     260   2820947  Ability to transclude text
     273   3035565  Allow sections at any level
     291   3491860  license tag  (hold for 5.2)
     306            Allow Block Elements inside abstract

    No new RFEs

-----

[1] https://lists.oasis-open.org/archives/docbook-tc/201501/msg00003.html

--

-- 
Bob Stayton
Sagehill Enterprises
bobs <at> sagehill.net
Chet Ensign | 20 Mar 18:16 2015

Your Public Review for DocBook Version 5.1 has been announced

Members of the DocBook TC,

Your 30 day public review for DocBook Version 5.1 has been announced. The review ends on April 21st. You can find the announcement at https://www.oasis-open.org/news/announcements/30-day-public-review-for-docbook-v5-1-ends-april-21st.  

I have announced the public review to the membership and also tweeted it and posted the news on LinkedIn. Feel free to like/share/retweet/etc. to further spread the news. 

Also, because it has been a long time since your last public review, please review and keep in mind the OASIS requirements for handling comments as spelled out in [1]. 

- Non-TC member feedback can only be submitted to the TC's comment list docbook-comment <at> lists.oasis-open.org. The TC must have someone subscribed to this mail list to monitor comments. 

- All submitted comments must be acknowledged by the TC. 

- The TC needs to maintain a log of all comments received and their resolutions. The comment resolution log will need to be available when you begin your next public review or take other action on draft. A simple comment resolution log template is available in OpenDocument [2] and Office [3] format. 

Congratulations on getting this started. It is a great step forward. Let me know if you have any questions regarding the review or next steps.

=== Additional references:



--

/chet   [§] 
----------------
Chet Ensign
Director of Standards Development and TC Administration 
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393 

Check your work using the Support Request Submission Checklist at http://www.oasis-open.org/committees/download.php/47248/tc-admin-submission-checklist.html 

TC Administration information and support is available at http://www.oasis-open.org/resources/tcadmin

Follow OASIS on:
LinkedIn:    http://linkd.in/OASISopen
Twitter:        http://twitter.com/OASISopen
Facebook:  http://facebook.com/oasis.open

Gmane