Re: [docbook-apps] DocBook XSL 1.67.0 released

[Elliotte Harold <elharo@metalab.unc.edu>]

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