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]

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


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]
    
    Example: <filecontents class='config'>foo bar</filecontents>

    Advantage: adding a new element allows for 'sub-classing' to
    distingush different types of files from one another.
    
    Disadvantage: well, it adds another element to the DTD.

      - or -

 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>
             <literallayout type='docfile'>foo bar</literallayout>
 
                        - or -
    
             <literallayout type='filecontents'>foo bar</literallayout>

    Advantage: using a new attribute/value is generally perceived as
    adding less complexity to the DTD than adding a new element (think
    of Systemitem -- one element with a 'class' attribute that has a
    list of 16 enumerated values: 'username', 'ipaddress', etc., instead
    of 16 different elements)

    Disadvantage: if we go with an attribute value such as
    'filecontents', it can't be properly subclassed (that is,
    <literallayout type='filecontents'> could only be used to indicate
    that a chunk of content was from a file, but not what type of file
    it was from).

      - or -

 3. do nothing; keep things just the way they are.

    Advantage: Hey, we don't have to change anything. 

    Disadvantage: Individual users are stuck with trying to figure out
    to mark up filecontents stuff on their own; we risk having different
    people come up with different ad-hoc ways of marking it up, instead
    of having a standard, documented way of doing it.

      - or -

 4. (any other options I may have neglected to consider) 
    
** If you have any interest at all in this issue, please take a minute
   to think and respond, even if just briefly, about which of the
   above choices you consider to be the best solution.
   
   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.  :)

Thanks,

  --Mike


[1] http://sourceforge.net/tracker/index.php?func=detail&aid=613293&group_id=21935&atid=384107

[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.

[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').


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