Re: [docbook] Class attribute values on refmiscinfo

["Michael(tm) Smith" <smith@sideshowbarker.net>]

"Rowland, Larry" <larry.rowland@hp.com> writes:

> On Thu, 2006-04-06 at 08:05 -0400, Norman Walsh wrote:
> > 
> > In DocBook V4.x (and prior versions), the refmiscinfo element has
> > a CDATA class attribute. That's inconsistent with the general
> > principle in DocBook that class attributes have enumerated values.
> > In DocBook V5.0, there are three possibilities:
> > 
> > 1. Convert class to an enumerated list (with the other/otherclass
> >    escape hatch)
> > 
> > 2. Rename the attribute 'type' (that's consistent with existing
> >    conventions)
> > 
> > 3. Leave it CDATA and don't rename it
> > 
> > For the record, I prefer either of 1 or 2 over 3. Strongly.
>
> I lean toward 1; I think it is more consistent with other areas.  I
> always prefer enumerated types for authors but frequently find the
> escape-hatch useful.  Less desirable, but acceptable would be 2.  I
> agree with you that the third options is much less desirable.

I strongly favor 1, for the same reason: Having an enumerated list
gives authors guidance on how to mark up their content. And the
other/otherclass mechanism gives them a way to specify arbitrary
values for the attribute if they don't find what they're looking
for in the enumerated list of values in the schema.

> > If you use refmiscinfo, and if you've used the class attribute, what
> > values have you put in it? For reference, out of the box, the XSL
> > stylesheets currently only recognize 'source', 'version', and
> > 'manual'.

Part of the reason is that those are specifically mentioned in the
man(7) man page as metadata that forms the content of the page
header/footer for each man page; in roff markup, this:

  .TH TITLE  section  date  source  manual

The DocBook manpages stylesheets pull the TITLE part from the
Refname, the "section" part from Manvolnum, and the "date" part
from Date or Pubdate. We don't have specific elements in DocBook
for marking up the "source" and "manual" parts, so an obvious
place to put that information is in refmiscinfo/@class="source"
and refmiscinfo/@class="manual".

There is at least one other tool that uses refmiscinfo/@class in
that same way -- Eric Raymond's doclifter(1), which "up converts"
existing roff man pages to DocBook XML. It takes the "source"
argument to the .TH macro and converts it to
refmiscinfo/@class="source"; same for the "manual" part. (And it
changes the "date" part into refmiscinfo/@class="date"; but it
probably should instead convert it to an Refentry/Info/Date.)

The "version" value is not explicitly mentioned in the man(7) man
page, but that page does say this about the "source" value:

  For system calls, use the version of the kernel that you are
  currently looking at: Linux 0.99.11

  For library calls, use the source of the function: GNU, BSD 4.3,
  Linux DLL 4.4.1

So many existing man pages do in fact have a sort of two-part
value for "source": a source name (Linux DLL), plus a version
(4.4.1). A good number of existing pages actually have no name
part at all for it -- they just have a (version) number for the
"source" contents.

So the DocBook manpages stylesheet tries to support/anticipate
that by checking for refmiscinfo/@class="version"

  --Mike

smime.p7s