OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Automatic numbering in DocBook

At the May TC meeting, I took an action to write up a proposal for
uniform handling of automatic numbering. This stems from our
discussion of RFE #1478012: add linumsep and linenumstep to
programlisting and screen.

Automatic numbering occurs in the following places:

1. Chapters/appendixes
2. Sections
3. Ordered lists
4. Procedures
5. Verbatim environments (programlisting, screen, etc.)
6. Callouts

What control does DocBook provide?

a. Chapter, appendix, and section have @label
b. Listitem has @override to change the number (or mark)
c. Orderedlist has @continuation, @numeration, and @inheritnum
d. Verbatim environments have @continuation, @linenumbering, and
e. Procedures have steps, usually numbered, and stepalternatives,
   explicitly not numbered.

That turns out to be more uniform and rational than I thought. (I had,
for example, forgotten that we added @startinglinenumber to the
verbatim environments.)

Looking at the processing instructions provided by the XSL stylesheets,
it seems that the only additional controls are for the first item in
an orderedlist and for the every-nth (or step), separator, and width
of verbatim environment numbers.

I'm inclined, mildly, to add @startingnumber (or something like that)
to orderedlist. I tend to think, however, that the number of lines in
a verbatim environment is really a global style issue more than a
case-by-case issue. Why number one program listing every 3 lines,
another every 5 lines, and another every 10 lines *in a single
document*? One case, numbering differently for very short verbatim
environments, is something I think the stylesheets should handle
better, but not by forcing the author to specify it each time.


                                        Be seeing you,

Norman Walsh <ndw@nwalsh.com>      | Until death, it is all life.--
http://www.oasis-open.org/docbook/ | Cervantes
Chair, DocBook Technical Committee |

PGP signature

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]