forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ferdinand Soethe <samm...@soethe.net>
Subject Re[2]: Proposal: New Instruction element in HowTo-DTD 2.0
Date Mon, 08 Nov 2004 15:54:18 GMT


RG> This is developer question, such questions should be asked on the dev at
RG> forrest.apache.org list (with this message I have moved it to the dev
RG> list, please respond there).

Sorry, I figured content related stuff belonged in the user list since
users would be the ones to ask whether they needed a new element or
didn't. Now I know better.

RG> How-To DTD extends the Document dtd. The document DTD provides plenty of
RG>   elements to distinguish different types of paragraph. Would <source>
RG> and <code> be sufficient?

I don't think they do for two reasons:

1. XML-markup is supposed to express function rather than the way a
   piece of info should be rendered. So even if <code> or <source> would
   get me the desired visual effect (which they don't, see 2), it
   doesn't seem to be a good idea to use the same element for
   different function.

   And the content of an instruction element (do this, do that) is
   very different from a source code example or a plain paragraph
   explaining the result of the instruction.

2. Instructions in most manuals and books have their very own style to
   clearly show that you should do something. As a minimum they would
   be bulleted or numbered, more often they have some graphic symbols
   like a checkmark instead of a bullet.

Important: Not all paragraphs in the steps-section are instructions.
Quite often you would have an instruction followed by a piece of code
or a normal paragraph explaining the result. So I couldn't just use a
style that sets all paras within a step that way.

I hope I could make myself reasonably clear,

--
Ferdinand Soethe



Mime
View raw message