Re: [docbook-apps] DocBook XSL 1.67.0 released

[Michael Smith <smith at xml-doc dot org>]

Elliotte Harold <elharo@metalab.unc.edu> writes:

[...]

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

I understand that. I think the current design was done for the
sake of keeping things simple. I am not sure yet if this is a case
where it's worth adding complexity to the stylesheets just for the
sake of generating slightly more precise HTML.

[...]

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

The var element is not a monospaced style. It's typically
rendered in italic (non-monospaced). Which makes it inappropriate
for marking up programming variables or program arguments. When
they decided on italic as the rendering for it, I think maybe what
they had in mind was mathematical variables, not programming variables.

[...]

> >  command                strong+code
> 
> This one's tricky, but I'd probably say b+kbd.

Argh. We're not going back to using b.

> >  constant               code
> 
> var

Nope. See my comment above.

> >  email                  code
> 
> samp

I could see somebody else suggesting this should be kbd. How do we
decide?

> >  envar                  code
> 
> var

Nope. Not unless we want environment variables to be rendered in
italic.

> >  exceptionname          code
> >  filename               code
> 
> samp

And why not kbd? As in "Type in the following:
<userinput><command>tail</command> <option>-f</option>
<filename>mta.log</filename></userinput>"

> >  userinput              strong+kbd
> 
> No strong. Just kbd.

There's actually a reason why it's strong. See below.

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

I think that would be a step backward.

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

I don't think we are changing the semantics by using "code".
Instead, what we're doing it mapping to the next best thing -- to
overcome a fundamental design deficiency in HTML (one of many...)

If HTML had the equivalent of a "literal" element, we'd be fine.
We could use it for filename, email, whatever. Problem is, it
doesn't. So we use the next best thing: code. If I were
terrifically impressed with the insight that went in the design of
the HTML element set, I guess I might see that as an abuse of the
code element. But given that the HTML element set it deficient in
the area, it doesn't personally trouble me a whole lot.

Maybe not the best solution -- but I don't think falling back to
<span style="font-style: monospace"> is a better one.

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

Yes there is, though you may not agree with it. The reason is so
that when it get rendered, the "stuff you need to type in" shows
up more strongly than the "stuff that computer outputs" -- so
that you can easily distinguish between them. This is a convention
that's used in many books and is not unique to DocBook.

I guess you could say that people who wanted commands and
userinput to show up strongly should change it to do that via
CSS. My answer would be that people who _don't_ want it to show up
strongly should change it via CSS.

> What's being done here is using the strong and em 
> elements as font style elements.

No.

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

I disagree. I don't see that this is an abuse of strong and em at
all. In the case of command and userinput, it is simply saying,
this stuff should show up more strongly. For somebody using a
screen reader, "more strongly" might mean "louder". Or somebody
else making CSS tweaks may decide it means rendering it in red.

Going back to using b and i for these cases is plain wrong.

  --Mike

Attachment: smime.p7s
Description: S/MIME cryptographic signature