[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook] Re: Class attribute values on refmiscinfo
Norman Walsh <email@example.com> writes: > / Norman Walsh <firstname.lastname@example.org> 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).