Re: [docbook] DocBook Technical Committee Meeting Minutes: 24 Sep2003

[Tobias Reif <tobiasreif at pinkjuice dot com>]

Dear TC

The decision is yours to make, but before you finalize it I want to make 
sure that you understand my request.

The addition of attribute "language" neither satisfies my request [RFE 
798616] nor does it solve the problem I have in the scenario I described.

The tool I use for transforming DBX to XHTML does syntax markup for 
syntax highlighting. It must know the syntax of a listing in order to 
find out if it can mark it up. Since some languages have more than one 
(alternative) syntax/notation, authors of DocBook documents must have a 
way to explicitly specify the syntax of listings (for elements "code", 
"programlisting", and ideally most or all literal layout elements such 
as "literallayout" and "screen" and "filelisting" if this will exist).

This
  <programlisting language="RNG">...
does not specify the syntax of the code listing.

Thus I need to be able to write something like
  <programlisting language="RNG" syntax="XML">...
especially since it could also be
  <programlisting language="RNG" syntax="text">...

A tool handling XML syntax can then act on all listings with syntax="XML".

If it must act on language="[any XML langauage]" then it would need to 
have a list of all XML languages which will never be sufficient since 
people invent their own grammars.

The transformastion tool can't be sure if it should treat the following 
as XML:
  <programlisting language="RNG">...
and a guess can be incorrect. It could to some sniffing which is never a 
good solution. The best solution I see is to specify the syntax, for 
example via syntax="XML" or notation="XML".

> The 'language' attribute is what we have for the synopsis elements.
> It's what HTML uses.

The latest version of XHTML uses attribute "xml:lang" and does not 
include attribute "lang".
see
http://www.w3.org/TR/xhtml11/changes.html#a_changes

The value of attribute "xml:lang" is one listed in
http://www.ietf.org/rfc/rfc1766.txt
which explicitly excludes computer languages.

> It seems like you can overload language with
> alternates if you really need to.

One workaround I see is to do

  <programlisting language="RNG/XML">...
  <programlisting language="RNG/text">...

which is neither clear nor specific enough, and is harder to work with 
(validation, combinations, etc).

> Perhaps 'syntax' is better, but we already have 'language'.

"syntax" is not a different name for "language".

Feel free to keep "language", but please add "syntax" or "notation".

> If we didn't have language, we might perfer syntax,

They are two different things which provide information about different 
aspects of the element content. Both attributes are useful, I especially 
need the latter one.

> but do we want to move to syntax?

I simply need "syntax" or "notation", there's no need to remove "language".

For example:

  <programlisting language="RNG" syntax="XML">...
  <programlisting language="RNG" syntax="text">...
or
  <programlisting language="RNG" notation="XML">...
  <programlisting language="RNG" notation="text">...

Please also see RFE 798616
https://sourceforge.net/tracker/index.php?func=detail&aid=798616&group_id=21935&atid=384107

Tobi

[RFE 798616]
syntax="" or notation="" needed for code listings
https://sourceforge.net/tracker/index.php?func=detail&aid=798616&group_id=21935&atid=384107
also see
http://sourceforge.net/tracker/index.php?func=detail&aid=692319&group_id=21935&atid=373750





To unsubscribe from this list, send a post to docbook-unsubscribe@lists.oasis-open.org.