Re: [docbook] Re: Class attribute values on refmiscinfo

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

Norman Walsh <ndw@nwalsh.com> writes:

> / Norman Walsh <ndw@nwalsh.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/refmiscinfo@class=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).

Digital signature