Re: DOCBOOK: Re: marking up keycaps according to their semantics

[Tobias Reif <tobiasreif@pinkjuice.com>]

Norman Walsh wrote:

 > I was implicitly saying that I don't generally see value in trying to
 > capture that level of detail.

But my proposal doesn't really change the level of detail; it just would 
allow authors to shift from marking up ASCII rendering (presentational) 
to marking up the input item (semantic), in a uniform way (specified by 
the official DTD and spec). Only when such a uniform way is offered can 
authors expect their documents to work with general tools, and only then 
can implementers/customizers/users expect their tools to work with any 
DocBook document.

(The spec could also specify that <keycap>Ctrl</keycap> stands for the 
control key, etc.)

 > It only works if documents are consistently marked up.

Exactly. But many of the DocBook tools (eg your XSLTs) work well with 
any DocBook document. In the case of input such as control, alt, etc, 
there currently is no way for a tool to be general.

A local tool will work for a local set of consistently marked up 
documents, but can't be known to work with other documents. With my 
proposal, all DocBook documents would use the same markup for the same 
input item, thus general tools could handle them. All documents could be 
consistently marked up, not just a local set.

 > | What if authors used "C-" (Emacs notation) or "Strg" (German key
 > | label) or "<C->" (Vim notation)? What if this tool is to be general,
 > | and has gets fed something other than <keycap>Ctrl</keycap> for
 > | control?
 >
 > It only works if documents are consistently marked up. :-)

But neither the DTD nor the spec specifies what to use for 
control/alt/etc input. There is no way for a general tool to know what 
to expect.

If I use your XSLTs, there's no way for them or my customization layer 
to use a pic for all control-foo sequences, unless I tell it what a 
certain (set of) document(s) uses as ASCII rendering.
The next day I receive a new document, and the mechanism stops to work 
if they used some other ASCII rendering, which is very possible, common, 
valid, and sensible (C is just as valid and sensible as ctrl).

 > | I see the latter as necessity. DocBook is mostly (should be 100%
 > | IMHO)
 > | about nothing but about being semantic. If I could markup input as
 >
 > Right. But there's a constant tension between ease of markup and
 > granularity of information.

How does my proposal make authoring / marking up less easy?

My proposal would add value without requiring authors to write more 
code. In many cases, it even saves some typing.

As you say, often trade-offs have to be balanced betweeen higher 
granularity  and added verbosity. But what's the disadvantage in this 
case? All that's needed is a simple enumerated attribute for keycap, and 
documents don't become more verbose.

It's not a shift to a higher level of granularity and verbosity, but 
instead it is a shift from arbitrary and non-standardized presentational 
markup to concise and standardized semantic markup.

Tobi

-- 
http://www.pinkjuice.com/