Class attribute values on refmiscinfo

Hello world,

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.

In 5.0b4, I implemented option 2. But at the last TC telcon,
we
wondered if, in fact, the number of values that people
actually use
was small enough to justify the class/otherclass mechanism.
In a
sense, this would aid in interoperability and authoring
since it would
provide a list of choices instead of requiring authors and
tools to
know about arbitrary values. OTOH, if there are hundreds of
values
already in use, making an enormous enumerated list seems
less useful.

So:

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'.

And do you have a preference for class/otherclass or type?

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndwnwalsh.com>      | 'Tis better to be
silent and be
http://www.oasis-o
pen.org/docbook/ | thought a fool, than to speak and
Chair, DocBook Technical Committee | remove all
doubt.--Abraham Lincoln

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.

Larry Rowland

On Thu, 2006-04-06 at 08:05 -0400, Norman Walsh wrote:
> Hello world,
> 
> 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.
> 
> In 5.0b4, I implemented option 2. But at the last TC
telcon, we
> wondered if, in fact, the number of values that people
actually use
> was small enough to justify the class/otherclass
mechanism. In a
> sense, this would aid in interoperability and authoring
since it would
> provide a list of choices instead of requiring authors
and tools to
> know about arbitrary values. OTOH, if there are
hundreds of values
> already in use, making an enormous enumerated list
seems less useful.
> 
> So:
> 
> 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'.
> 
> And do you have a preference for class/otherclass or
type?
> 
>                                         Be seeing you,
>                                           norm
> 

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

"Rowland, Larry" <larry.rowlandhp.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

/ Norman Walsh <ndwnwalsh.com> was heard to say:
| 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'.

To put a little urgency into this issue , I want to
do another 5.0
beta release next week to correct the broken DTD that's in
b4. Since
everyone who responded expressed a preference for
class/otherclass,
I'm going to do that next week. If you want more than
source, version,
and manual in the initial enumerated list (more can always
be added
later), please make your case soon.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndwnwalsh.com>      | Everything should be
made as
http://www.oasis-o
pen.org/docbook/ | simple as possible, but no simpler.
Chair, DocBook Technical Committee |

Norman Walsh <ndwnwalsh.com> writes:

> / Norman Walsh <ndwnwalsh.com> was heard to
say:
> | 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'.
> 
> To put a little urgency into this issue , I want to
do another 5.0
> beta release next week to correct the broken DTD
that's in b4. Since
> everyone who responded expressed a preference for
class/otherclass,
> I'm going to do that next week. If you want more than
source, version,
> and manual in the initial enumerated list (more can
always be added
> later), please make your case soon.

I found some doc instances and documentation which make me
think
that the values "sectdesc" and
"software" also ought to be included.

The reason is, in the solbook(5) man page (documentation for
Sun
SolBook), those are among the values mentioned as being
"four
classes that are routinely used" for refmiscinfo.

  http://docs.sun.com/app/docs/doc/816-0220/6m6nkorrf?a=
view

I think "software" is exactly the same as what
the man(7) man page
calls "source", and "sectdesc" is
the same as what it calls "manual".

Here's how the solbook(5) man page describes them:

  software
    This is the name of the software product that the topic
    discussed on the reference page belongs to. For example
UNIX
    commands are part of the "SunOS x.x"
release. The value of
    this attribute may be a text entity reference.

  sectdesc
    This is the section title of the reference page; for
example
    "User Commands". The value of this attribute
may be a text
    entity reference.

The solbook(5) page also mentions the values
"date", "arch", and
"copyright". To me, it seems like those might
not be necessary,
since DocBook already provides specific elements and
attributes
for them (*info/date, "arch" common attribute,
*info/copyright).

So I'm not sure if the TC would want to bless
"date", "arch", and
"copyright". One issue I can see with them is
the problem of
processing apps needing to figure out what choose/use if,
say, a
date is specified both in refentry/refmeta/refmiscinfoclass=date
and in the refentry/*info/date element.

Still, in keeping with the "descriptive rather than
prescriptive"
design philosophy of DocBook, I guess it may make sense to
include those. (And ss far as "copyright"
specifically, part of
the TDG description for refmisc class attribute actually
says "It
may hold copyright information, release or revision
information".)

Anyway, if those are included, the enumerated list would be:

  arch, copyright, date, sectdesc, software, source,
version, manual

Below, for the record, is the full text of the chunk of the
solbook(5) man page that discusses refmiscinfo.

  --Mike

------------------------------------------------------------
-----

  http://docs.sun.com/app/docs/doc/816-0220/6m6nkorrf?a=
view

  <refmiscinfo> 

  There are one or more <refmiscinfo> tags which
contain meta
  information. Meta information is information about the
reference
  page. The <refmiscinfo> tag has the class attribute.
There are
  four classes that are routinely used. 

  date 
    This is the date that the file was last modified. By
consensus
    this date is changed only when the technical information
on
    the page changes and not simply for an editorial change.

  sectdesc 
    This is the section title of the reference page; for
example
    "User Commands". The value of this attribute
may be a text
    entity reference.

  software 
    This is the name of the software product that the topic
    discussed on the reference page belongs to. For example
UNIX
    commands are part of the "SunOS x.x"
release. The value of
    this attribute may be a text entity reference.

  arch 
    This is the architectural platform limitation of the
subject
    discussed on the reference page. If there are no
limitations
    the value used is generic. Other values are sparc and
IA.

  copyright 
    This attribute contains the Sun Microsystems copyright.
Any
    other copyrights that may pertain to the individual
reference
    page file should be entered as separate
<refmiscinfo> entries.
    The value of this attribute may be a text entity
reference.

Yeah, it mentions "four classes" but actually
lists five; the same
page also mispells "refdiscriptor" as
"refdescriptor" -- several
times (but at least it is consistently mispelled).