Re: DOCBOOK: Request for comments: adding a Fileoutput element (RFE613293)

[Yann Dirson <ydirson at fr dot alcove dot com>]

On Thu, Nov 28, 2002 at 03:35:20PM +0900, Michael Smith wrote:
> The DocBook Technical Committee would like to ask for comments from
> readers of this list about a request for an enhancement to the DocBook
> DTD, RFE 613293, 'Generalize programlisting'[1], which proposes that the
> DTD be enhanced in some way to provide a 'semantically-precise way to
> wrap the contents of files that are not programs'.
> 
> If you have an interest in this proposed enhancement, please take a few
> minutes to
> 
>   * read through the descriptions of the potential solutions/choices
>     described below
> 
>   * reply on this list with your comments.
> 
> The potential solutions/choices appear to be:
> 
>  1. add a new element (for example, 'Filecontents') with a 'class'
>     attribute and enumerated values to indicate what type of file
>     the marked-up content is from (for example, a program file, a config
>     file, a documentation file, etc.)[2]

This looks like the best solution.


> [2] We can't immediately 'replace' the Programlisting element with a new
>     element, because that would break backward compatibility; TC policy
>     requires that we first need to announce that it was being replaced,
>     and then wait to change it in the next major version of the DTD.

Hey, that's not a problem :)


>  2. add a new attribute to Literallayout, with either 'filecontents' or
>     various filetypes being among its enumerated values[3].

Hm, I bet <literallayout> is mostly used for this type of things (file
contents).  However, its name is, well, somewhat more
"layout-oriented" than "descriptive of its content".

What about extending proposal 1. to obsolete <literallayout> as well
as <programlisting> ?  That way we even make the DTD simpler.


> [3] We can't use the 'class' attribute for this purpose, because it's
>     already in use with Literallayout to indicate the character spacing
>     to use in rendering the marked-up content (either 'monospaced' or
>     'normal').

...and that inconsistency in itself could be seen as an indication
that there's something to do here.  Changing the semantics of an
attribute in an element, even if it's to bring it in sync with the
whole, is surely more disruptive than obsoleting an element in favor
of a new one, and would probably take 1 or 2 additional major releases
to complete, to handle backward compatibility in the usual manner.


>    Generally, we get very few responses back from the user community
>    when we posts requests for comments such as this one. I think the
>    lack of responses isn't really an indication of lack of interest--
>    but maybe just an indication that not enough people realize that
>    there opinions on these issues aren't of much value. So, let me
>    reassure you: your responses are welcome and very much valued.  :)

The "is my opinion representative of anything" argument too may also
push people into not responding :)

-- 
Yann Dirson <Yann.Dirson@fr.alcove.com>                 http://www.alcove.com/
Technical support manager                Responsable de l'assistance technique
Senior Free-Software Consultant          Consultant senior en Logiciels Libres
Debian developer (dirson@debian.org)                        Développeur Debian