#296 Include Equivalent format Attribute Name to DocBook Elements

v5.1
closed-fixed
Norman Walsh
5
2013-02-19
2012-06-04
Thomas Schraitle
No

Hi,

not only in the light of the new assembly mechanism, output formats are always a major topic for DocBook and the stylesheets. However, there is currently no standardized method to add an attribute specific for such a purpose. For simplicity reasons, I use "format" in this text. Feel free to use a different name like "outputformat", "targetformat", or whatever you think is appropriate. Actually, I don't care about the name, only about the idea. :)

I know the committee is hesitant to add additional attributes to the schema, but I think it has several benefits. Here is why I think this is useful:

1. Currently, the DocBook stylesheets support several output formats. Probably this list will grow in the future.

Dealing with such a variety of possible output formats makes it sometimes harder to write in a "format independant" way. However, if someone really
wants to express that a certain element is only useful for PDF, the current list of common attributes doesn't support this. The user is forced to use a more general attribute like role or condition.

From a semantic point of view, no common effectivity attributes are suited for this task. By using a "format" attribute in combination with profiling, I can distinguish such a case.

2. The current assembly schema contains in its <output/> element a "format" attribute (actually that's where this idea originated).

However, with the raise of assemblies and modules, output formats will become much more important. From a usability point of view, having a consistent
"format" attribute in DocBook and in <output/> does make sense: users can recognize that as the same "thing".

3. Adding a "format" attribute improves usability of children of mediaobject

If you want several images but for different output formats, you need to use the role attribute in imagedata. This distinguish the high-resolution SVG for PDF from the low-resolution for HTML which is fine. However, from a usability point of view, the role attribute does a poor job on self-marketing. A "format" attribute would make it much more clear to the user what its purpose is.

4. Adding "only" an attribute to the DocBook schema is not as intrusive than adding a new element. :) The changes to the schema are minimal:

db.format.attribute =
## Identifies the target format to which the element applies
attribute format { text }

db.effectivity.attributes =
...
& db.format.attribute?

Some might think, role or condition could be suitable. I don't think so, as role shouldn't be recommended for profiling and condition is the only general profiling attribute which is "freely" available to our users with no special semantic. Or in other words: it is occupied already by other meanings and shouldn't be (ab)used for output formats. As such, in my humble opinion, a "format" attribute should be added to the schema.

The discussion can be followed on the mailinglist, see https://lists.oasis-open.org/archives/docbook/201206/msg00003.html

Discussion

    • summary: Including format Equivalent Attribute Name --> Include Equivalent format Attribute Name to DocBook Elements
     
  • Norman Walsh
    Norman Walsh
    2012-11-14

    The TC elected to add a new common effectivity attribute named 'outputformat' to address this RFE. Fixed in 5.1.

     
  • Norman Walsh
    Norman Walsh
    2012-11-14

    • status: open --> open-accepted
     
  • Norman Walsh
    Norman Walsh
    2012-11-14

    • status: open-accepted --> open-fixed
     
  • Robert Stayton
    Robert Stayton
    2013-02-19

    • status: open-fixed --> closed-fixed