Subject:
Re: DocBook number of elements rant
From:
"David Braun" ####@####.####
Date:
22 Aug 2003 20:45:19 -0000
Message-Id: <7442-54512@sneakemail.com>
Dan,
Thanks for your thoughts.
> >Holy cow there are a lot of elements in DocBook.
>
> So? Unless you write your own stylesheets, you don't have to worry about
> formatting them.
Formatting them is not my concern. My concern as an author is having to
wade through all the possible choices as I mark up my document. The
higher the number of elements, the greater my burden. If there were a
million elements to choose from (imagine <adjective-preceding-noun>), my
progress would be too slow, whereas if were only three elements, my
document would not be expressive enough. The number of elements should
strike a balance between cost and expressivity.
> >Is there justification for each of these somewhere?
>
> An explanation of each can be found in the O'Reilly book called (drumroll
> please) "DocBook".
Yes, I'm reading it. I don't see any justification.
> As for a justification, it's just a desire to be complete. You never know
> what kind of computer system is going to process the document, and you want
> to be prepared for all possibilities.
How do you define complete? That's the role of justification. What are
all the possibilities? That question is unanswerable--you have to draw
a line somewhere.
> Example:
> KeyCap - the name of a key, e.g., F1
> KeyCode - the numerical signal that a key sends when pressed, e.g., 2.
> KeySym - a symbolic name for a key, e.g., KeyEvent.KEY_F1.
>
> It sounds silly, but I'll bet some keyboard manufacturers use it.
Okay, how about a sillier example:
KeyCapLowerCase
KeyCapUpperCase
KeyCapNumber
KeyCapSymbol
etc.
When do you stop?
> >is there any interest in the LDP for listing a subset of the DocBook elements
>
> Why not just let the author decide?
Because, as an author, I'm tempted to use only one element for my whole
document: <literallayout>. It would save me the hassle of having to
look up all the elements in DocBook. I used to write documents in 80
column ASCII text long before HTML existed and it worked just fine.
I wouldn't actually do this because I like my documents to look good in
HTML. However, if I'm choosing only the elements I care about, that
means I'm going to use only the minimum number of elements necessary to
make the generated HTML look good, and not care about PDF, PostScript,
and Plucker.
Here are two concrete examples of what I'm talking about:
The Sample-HOWTO.xml contains a copyright block implemented with the
<para> element. After reading through the list of DocBook elements, I
added in <trademark class="copyright">. Both versions express the same
information to the reader (as it would have had I used only the
<literallayout>). So what's the justification for the <trademark>
element? Does anyone care? Will it make the final output in HTML, PDF,
PostScript, and Plucker any different? Is the Linux Documentation
Project, or its users, using any automated tools that look for
<trademark> elements? These are the kinds of questions best answered by
the LDP, not the author.
Second example: There's an element named <simplelist> for expressing a
list like this: one, two, three, four. My inclination is to just type
"one, two, three, four", but the DocBook way would be "<simplelist
type="inline"><member>one</member><member>two</member><member>three</member><member>four</member></simplelist>". Do you want me to write my lists the DocBook way?
Perhaps I'm making a tempest in a teapot, but I hope I've demonstrated
my point to you that the elements are there for the reader, not the
author. If this weren't true, then we'd all just use the HTML tag <i>
instead of <em>, because hey, <i> looks good on my screen, and who cares
about people with user agents that can't display italics?
David
