RE: [docbook-tc] Followup to Norm's write up on numbering.

["Gershon L Joseph" <gershon@tech-tav.com>]

When I read Larry's message my initial reaction was similar to Jirka's. I
believe there are better ways to write procedures than the first example
shows, though I do understand there are many authors out there who do write
this way. I don't think you'll find that writing style in any best practice
for technical writing, and it's probably not being taught in technical
writing schools. I support Jirka fully in that DocBook should not contain
attributes for this type of markup. To summarize:

Example 1 is IMHO bad writing technique and I'd prefer if DocBook does not
support such writing style out of the box.

Example 2 is purely presentational and IMHO does not belong in a DTD. There
are ways to work around the need for line numbering in program listings.
None of our clients number their program listings and AFAIK none of them has
asked for it.


Best Regards,
Gershon

---
Gershon L Joseph
Member, OASIS DITA and DocBook Technical Committees
Director of Technology and Single Sourcing
Tech-Tav Documentation Ltd.

-----Original Message-----
From: Jirka Kosek [mailto:jirka@kosek.cz] 
Sent: Wednesday, July 19, 2006 12:22 PM
To: Rowland, Larry
Cc: Bob Stayton; DocBook Technical Committee; docbook@lists.oasis-open.org
Subject: Re: [docbook-tc] Followup to Norm's write up on numbering.

Rowland, Larry wrote:

>  2) Add an optional @linenumberstep (or something similar) that allows
>     the author to override the global setting for line number
>     increment.  This is not to say that the stylesheet should not be
>     as intelligent as possible about when to use the step increments
>     based on the length of the example.  This is to accommodate those
>     special cases where the stylesheet rules are producing
>     inappropriate behavior for the specific case being dealt with.
> 
>     Example:
> 
>     Two programs are being discussed, one a short program that
>     interacts with a longer program.  The short program is just over
>     the length of listing that triggers numbering by steps in the
>     style-sheets, but the author prefers the emphasis on details that
>     the line numbering provides when every line is numbered.  For the
>     fragments of the longer program, the decisions on when to use
>     steps in line numbers are considered appropriate.  The author
>     chooses to override the step size (setting @linenumberstep to 1)
>     for the short driver program, while leaving the default values in
>     place for the fragments of the larger program.
> 
>     This is, perhaps, even more important where the style-sheets do not
>     make any attempt at providing differing behaviors based on the
>     length of the code fragment.  The author would be likely to want
>     to override the step increment on more of the program listings.

Let me say that I still think that such attribute is completely presentional
and it should not be added to DocBook. Each programlisting has invisible
intrinsic line numbers -- you can always start counting line numbers from
the start of listing manually. Of course if you reference line numbers it is
more then reasonable to display line numbers to make navigation to
particular line number easier. But even without such facility, you can find
line number in discussion.

But particular type of numbering (fonts, number of digits, increment) is
completely presentional issue which should be handled by processing system
(stylesheets, editor, ...). Line numbering step is similar to auto numbering
of sections -- there is also no DocBook markup to control depth of auto
numbering.

I'm sure that in 99,99 % of cases you can control line numbering step
automatically in stylesheets. For this 0,01 % you can always put something
like role="densenumbering" to your programlistings.

During last telcon someone was arguing that he/she doesn't like using custom
attributes and custom stylesheets for handling such cases. Well, but how do
you then control situations in which for example:

- each document has different depth of autolabeling of sections
- some book/chapters should/shouldn't contain toc/lot
- ...

I would really appreciate if DocBook can contain as less presentational
markup as possible. DocBook was designed as an interchange format which
captures semantics. @linenumberstep attribute doesn't improve semantic, nor
possibilities of interchange.

			Jirka

--
------------------------------------------------------------------
   Jirka Kosek     e-mail: jirka@kosek.cz     http://www.kosek.cz
------------------------------------------------------------------
   Profesionální školení a poradenství v oblasti technologií XML.
      Podívejte se na náš nově spuštěný web http://DocBook.cz
        Podrobný přehled školení http://xmlguru.cz/skoleni/
------------------------------------------------------------------
                    Nejbližší termíny školení:
     ** XSLT 23.-26.10.2006 ** XML schémata 13.-15.11.2006 **
      ** DocBook 11.-13.12.2006 ** XSL-FO 11.-12.12.2006 **
------------------------------------------------------------------
   http://xmlguru.cz    Blog mostly about XML for English readers
------------------------------------------------------------------