This is the mail archive of the
docbook-apps@lists.oasis-open.org
mailing list .
Re: [docbook-apps] DocBook XSL 1.67.0 released
Michael Smith wrote:
And are you saying that "code" should be used at all? That any
instance of code should be samp or kbd instead? It seems to me
that there are only a couple of cases where kbd and samp might be
appropriate.
No, of course not. code is clearly appropriate for content that is in
fact code. However it's not appropriate for user input, computer output,
e-mail messages, and other monospaced content that is not actually
source code.
Anyway, I was the one who made that change and at time time, I
actually we should be using samp or kbd in some instances.
The reason I didn't use samp or kbd is that the templates that
insert the HTML markup in these cases are named templates
(inline.monoseq, inline.boldmonoseq, inline.italicmonoseq,
format.sgmltag) that are called by the various element templates.
Perhaps the problem is that these templates assume there's a single
monospace font. This is not always the case. There are different uses of
monospace type in technical books, and these are often called out in
separate fonts and styles. Most O'Reilly books do this, for example.
So we would need to add some conditional logic to those named
templates to use code, samp, or kbd depending on the name of the
DocBook element. It didn't seem to me at the time like it was
worth the trouble, but I guess I can do t for the next release.
Here is the list of elements and the mappings that seem right to
me. Please let me know if it looks correct to you or what you
think should be changed.
This mostly looks right. However, looking at the HTML 4.0 spec we have
one additional monospaced style that's appropriate for some of these:
var, which "Indicates an instance of a variable or program argument.".
Based on that I'd make these changes:
classname code
code code
command strong+code
This one's tricky, but I'd probably say b+kbd.
computeroutput samp
constant code
var
email code
samp
envar code
var
exceptionname code
filename code
samp
function code
interfacename code
literal code
methodname code
option kbd
parameter em+code
var. No em.
prompt samp
replaceable em+kbd
sgmltag code
structfield code
var
sytemitem code
uri code
I'm not sure this one should be monospaced at all.
userinput strong+kbd
No strong. Just kbd.
varname code
var
Longer term, I'd also think about whether a few of these like
systemitem, filename, and email need to be indicated with <span
style="font-style: monospace"> instead of using code or samp at all.
HTML is not as expressive as DocBook so clearly we're going to lose some
semantics when transforming to HTML. However, we really shouldn't change
the semantics, or add inaccurate semantics if we can help it.
For the same reason we probably shouldn't be using strong or em for any
of these, except maybe replaceable. I can believe replaceable is
emphasized. However there's no fundamental reason that a command is
strongly emphasized. What's being done here is using the strong and em
elements as font style elements. If you don't want to use CSS it would
be preferable to use the genuine font style elements b and i, deprecated
though they are, to misusing strong and em.
--
Elliotte Rusty Harold elharo@metalab.unc.edu
XML in a Nutshell 3rd Edition Just Published!
http://www.cafeconleche.org/books/xian3/
http://www.amazon.com/exec/obidos/ISBN=0596007647/cafeaulaitA/ref=nosim