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

[Bob Stayton <bobs at caldera dot com>]

On Thu, Nov 28, 2002 at 09:44:40AM +0100, Yann Dirson wrote:
> 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.

I support the addition of a filecontents element.
But I object to removing programlisting and literallayout.

A programlisting isn't necessarily the contents of a file.
I write example code that never gets into a file.
If I wanted to run it, it would have to be put into
a file.  But it exists as a programlisting in its own
right. 

And literallayout has many uses that are not filecontents.
Don't forget that tables are "layout-oriented", but convey
meaning by how the words are arranged relative to each
other.


Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com