Re: DOCBOOK: enumerating role

[Bob Stayton <bobs@caldera.com>]

On Sat, Feb 01, 2003 at 11:31:53PM +0100, Tobias Reif wrote:
> Bob Stayton wrote:
> 
> 
> > Officially the DocBook DTD does not enumerate any
> > specific values for the role attribute on any element.
> > They are defined as CDATA so they can take any value.
> 
> 
> That's why I would like to specify a list of allowed values in the 
> internal subset. I have my list of allowed values, and I need to 
> validate them.
> 
> For example, I'm doing
>    programlisting role="XML"
>    (which hopefully will become s.th. like
>     programlisting role="snippet" syntax="XML")
> and stuff like
>    simpara role="NotForPrint"
>    ([1])
> 

Oh, sorry, I misunderstood your question.
The DocBook DTD has parameter entities for most (all?)
declarations of the role attribute in elements.  You can
override the default declarations in your internal subset.
For example:

<DOCTYPE book SYSTEM "docbookx.dtd" [
<!ENTITY % programlisting.role.attrib "role  (XML|C-code|XSL) #IMPLIED">
<!ENTITY % simpara.role.attrib "role  (NotForPrint|NotForHTML) #IMPLIED">
]<

You have to look in the DTD to make sure a given element
has a parameter entity for role.  I can't say for sure that
they all do.

> 
> > However, the stylesheets will respond to certain values
> > on certain elements.
> 
> 
> Yes, my XSLTs know what to do with these role attribute values. For 
> example, syntax="XML" turns on XHTML syntax markup for programlistings.
> 
> I'll have to see if my role attributes will interfere with the 
> NW-DBK2FO-XSLTs that I'm using.
> (I'm using my own XSLTs to get XHTML, and Norman's XSLTs to get FO.)
> 
> 
> > You should scan through the stylesheet parameter reference
> > pages to get an idea of how the formatting of
> > certain elements might be affected by role values.
> 
> 
> Other than deprecated stuff (use.role.as.xrefstyle.html, 
> profile.role.html) only
>    preferred.mediaobject.role.html
>    use.role.for.mediaobject.html
> seem to remain.
> 
> Thanks,
> 
> Tobi
> 
> 
> [1] Yes I should look at
>    http://docbook.sourceforge.net/projects/xsl/doc/tools/profiling.html ,
> but a) it's 404,

I guess it got moved:

http://docbook.sourceforge.net/release/xsl/current/doc/tools/profiling.html

and b) my own mechanism is supersimple and works well 

That's fine too.

> so far. Here's my print filter:
>    <t:template match="*[
>      @role='InteractiveOnly'
>      or
>      @role='HTMLOnly'
>      or
>      @role='DisplayOnly'
>      or
>      @role='DynamicOnly'
>      or
>      @role='NotForPrint'
>      or
>      @role='ColorPic'
>      ]"/>
> Then there is
> doc/fo/profile.role.html
> "For this reason it is not recommended to use role attribute for 
> profiling. You should rather use profiling specific attributes like 
> userlevel, os, arch, condition, etc."
> ... I guess I'd need some target media specific profiling attribute 
> (role print/printBW/hyper would suffice).

The 'condition' attribute is general purpose enough to
use for output media, I think.  Unfortunately, condition
is not set up  with parameter entities per element,
so it would be harder to enforce enumerated values in
the internal DTD subset.

You can certainly use 'role' with your filter.
The admonition is really for the profiling stylesheets,
because they work differently. They look at every role
value, and select only those that are turned on.
If role is used for other purposes, and you forget to
include those values in your selection list, then you
may filter out content unintentionally.

In your filter, you are turning off specific values you
don't want.  So you won't get any interference from
other role values that are not part of your profiling.

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com