This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Re: Request for comments: adding a Fileoutput element(RFE 613293)


On Fri, Dec 06, 2002 at 04:35:01PM -0500, Norman Walsh wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> / Michael Smith <smith@xml-doc.org> was heard to say:
> |  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]
> 
> I really dislike the name 'filecontents'. For one thing, if I use
> 
> <filecontents>
> I put stuff in
> here.
> </filecontents>
> 
> My "stuff" is clearly not the content of any file, it's inline in my
> document.
> 
> I think what this really boils down to is, I want to shove some text
> in here that should be displayed just the way it appears. How about
> "verbatim"?
> 
> |  2. add a new attribute to Literallayout, with either 'filecontents' or
> |     various filetypes being among its enumerated values[3].
> |
> |     Example: <literallayout type='configfile'>foo bar</literallayout>
> 
> This would be ok, I think, but often when a file is being inserted, the
> goal is to have the text presented in a fixed-width font, which means
> you have to say
> 
>   <literallayout type='configfile' class="monospaced">foo bar</literallayout>
> 
> That's a little verbose.
> 
> |  3. do nothing; keep things just the way they are.
> |
> |     Advantage: Hey, we don't have to change anything. 
> 
> Sigh. On the one hand, I like this best, on the other, new users don't
> often figure it out.
> 
> It really seems like we shouldn't need all of these: programlisting,
> screen, synopsis, literallayout, and verbatim.
> 
> How does this sound:
> 
> 1. Add 'verbatim'.
> 
> <!ELEMENT verbatim (...)>
> <!ATTLIST verbatim
>     class    (normal|monospaced) "monospaced"
>     contents CDATA               #IMPLIED
> 
> Contents is where you can say it's a configfile or a cprogram or
> whatever you like.

This seems to be reinventing literallayout.
I mean, the names literallayout and verbatim
seem to convey the same concept: that the
content is text that should not be messed with.

I think the original goal of the request was for an
element name that identified the content, not
how it should be displayed.

> 2. We consider removing 'screen', 'synopsis', and 'literallayout' in
> favor of 'verbatim' at some point in the future.
> 
> We could remove programlisting too, but I'm very hesitant to do that.

Please keep programlisting.  Its name is a nice tight fit
to its content.  It is literallayout that
is the general catch-all for any other kind of displayed lines. 
I think an attribute on literallayout that can be used
to identify its type of content would be the easiest
solution.
-- 

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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]