Docbook application discussion

Stefan Seefeld | 23 Jul 2012 23:29

Mapping OMG / ISO specification files to DocBook

Hello,

I'm trying to write DocBook documents (formal specifications) that
conform to the format requirements by the Object Management Group (OMG)
and the International Standards Organization (ISO).

Please find attached a titlepage sequence that I'm trying to map to DocBook.
There are a couple of mapping issues, which I have worked around with
hacks, so I'd like to know whether there are better alternatives (short
of adding my own customization of the DB5 RelaxNG grammar):

1) The recto titlepage contains content that doesn't fit into any of the
elements meant to be used on a titlepage. I have abused "preface"
elements for this, but that requires a couple of hacks, in particular
because prefaces require titles, and the content here doesn't have any
(as you can see).

2) The verso page sequence contains something semantically akin to a
"legalnotice", though it's quite a bit more (and more structured) than a
simple notice. So again, I couldn't use the existing "legalnotice"
element, but used a preface with a "legalnotice" id. Here again, there
is not a single title (instead, each of the subsections has a title), so
I had to cheat somewhat.

Are there any better ways I could have mapped this text to DocBook ?

Please note that the OMG formally supports DocBook as input format for
specifications. It appears I'm the first person to attempt to actually
use it, and thus I'm running into a couple of issues like the above. I
think it would be great to find a way to get this working, especially if

(Continue reading)

headers

Bob Stayton | 27 Jul 2012 22:35

Re: Mapping OMG / ISO specification files to DocBook

Hi Stefan,
Short of schema customization, the  <at> role attribute in DocBook is the preferred 
mechanism to refine the semantics of an existing element into another "element".  In a 
situation similar to yours, I used preface with role="frontmatter" as the container 
for the special information, likewise because it required sections.  I customized the 
stylesheet to skip <preface role="frontmatter"> when generating output, and I modified 
the titlepage templates to pull information from it where needed.  That makes such a 
preface more like an info container, which is not output by default but only handled 
as a special case.  I don't consider it an abuse of preface, as this information does 
come before the body of the document, and the role attribute makes it clear that it is 
not a normal preface.

You also said:

> Please note that the OMG formally supports DocBook as input format for
> specifications.

In what way do they support DocBook?

Bob Stayton
Sagehill Enterprises
bobs <at> sagehill.net

----- Original Message ----- 
From: "Stefan Seefeld" <stefan <at> seefeld.name>
To: "DocBook Apps Mailing List" <docbook-apps <at> lists.oasis-open.org>
Sent: Monday, July 23, 2012 2:29 PM
Subject: [docbook-apps] Mapping OMG / ISO specification files to DocBook

> Hello,

(Continue reading)

headers

Stefan Seefeld | 29 Jul 2012 23:09

Re: Mapping OMG / ISO specification files to DocBook

On 07/27/2012 04:35 PM, Bob Stayton wrote:
> Hi Stefan,
> Short of schema customization, the  <at> role attribute in DocBook is the
> preferred mechanism to refine the semantics of an existing element
> into another "element".  In a situation similar to yours, I used
> preface with role="frontmatter" as the container for the special
> information, likewise because it required sections.  I customized the
> stylesheet to skip <preface role="frontmatter"> when generating
> output, and I modified the titlepage templates to pull information
> from it where needed.  That makes such a preface more like an info
> container, which is not output by default but only handled as a
> special case.  I don't consider it an abuse of preface, as this
> information does come before the body of the document, and the role
> attribute makes it clear that it is not a normal preface.

OK. Perhaps the title of a preface could be made optional, then ?

> You also said:
>
>> Please note that the OMG formally supports DocBook as input format for
>> specifications.
>
> In what way do they support DocBook?

That's a good question, and it appears the OMG is trying to figure that
out right now. 

OMG allows for submissions of new standards to be made using the DocBook
format. Apparently, no-one had ever done that before, though. Most
people send in MS Word documents. In the process of adoption the

(Continue reading)