#118 Generalize programlisting

closed-rejected
nobody
None
5
2004-05-03
2002-09-23
John Daily
No

Currently, there does not seem to be a semantically-precise
way to wrap the contents of files that are not
programs. literallayout
is tolerable, but conveys no semantics.

Since the name of the "programlisting" element is not
really open to
interpretation, I would suggest replacing it with a
block-level
element ("filecontents"?) with classes like:
- interpreted
- compiled
- input
- output
- configuration
- documentation

I don't know if there would be value in stating whether
such
a file listing is partial or complete.

If it is reasonable to generalize this further, it
could also
wrap multi-line user commands, which don't seem to have a
home.

Perhaps all the above can be best achieved by adding
classes to
literallayout instead of creating a new element.

Discussion

  • Logged In: YES
    user_id=118135

    When I asked about this on the docbook mailing list[1],
    there were a significant number of responses in support
    of adding a new element, called 'filecontents' or
    'fileoutput', instead of just adding new attribute
    values to literallayout.

    [1]
    http://lists.oasis-open.org/archives/docbook/200211/msg00115.html

    Norm posted a couple of follow-up messages syntesizing
    the discussion, and concluding with a suggestion that
    we might name it 'filelisting' instead [2].

    [2]
    http://lists.oasis-open.org/archives/docbook/200212/msg00127.html

    The consensus supports the addition of a new element
    for purpose outlined in the RFE. But it should be noted
    that there was strong opinion against completely
    deprecating <programlisting> and replacing it with the
    new element. They would need to exist side by side.

     
  • Robert Stayton
    Robert Stayton
    2004-05-03

    Logged In: YES
    user_id=193218

    The TC does not want to add another element for this
    purpose. They felt that programlisting and literallayout,
    possibly with role attribute, sufficiently satisfy the need. The
    TC will reconsider the element names for 5.0 to make them
    more general.

     
  • Robert Stayton
    Robert Stayton
    2004-05-03

    • status: open --> closed-rejected