You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Dave Brondsema <da...@brondsema.net> on 2004/11/16 14:49:35 UTC
Re: (howto DTD) List of open ended threads ... to be extended!
Ferdinand Soethe wrote:
>
> 3. Topic : Re[2]: Proposal: New Instruction element in HowTo-DTD 2.0
> Idea : Add an instruction element to HowTo DTD 2.0
> Affects: All Forrests
>
> This ended without decision. Does that mean it is not going to
> happend or did it just get lost?
>
The HowTo DTD is a simple document we developed for Forrest. If you
want complete functionality, DocBook was designed to handle exactly
that. See if it fits your needs.
--
Dave Brondsema : dave@brondsema.net
http://www.splike.com : programming
http://csx.calvin.edu : student org
http://www.brondsema.net : personal
Re: (howto DTD) List of open ended threads ... to be extended!
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Juan Jose Pablos wrote:
> Nicola Ken Barozzi wrote:
>
>> A possible implementation would be to use <div>s with special class
>> attributes, that get transformed internally to the namespaced HowTo tags.
>>
>> Another one would be to use special words and formatting to do the
>> same, which would make it very easy to write them:
>
> I rather add a new element on the dtd, with those solutions you lose the
> semantics.
Does
<part>
...
</part>
have more semantics than
<div class="part">
...
</div>
or than
<h4>Part</h4>
<p>
...
</p>
?
I am very excited about using HTML for the documents, and would like to
be able to use OpenOffice to edit HowTos too. With xml elements I
cannot, and with divs it's not very easy.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: (howto DTD) List of open ended threads ... to be extended!
Posted by Juan Jose Pablos <ch...@che-che.com>.
Nicola Ken Barozzi wrote:
> A possible implementation would be to use <div>s with special class
> attributes, that get transformed internally to the namespaced HowTo tags.
>
> Another one would be to use special words and formatting to do the same,
> which would make it very easy to write them:
>
I rather add a new element on the dtd, with those solutions you lose the
semantics.
Re: (howto DTD) List of open ended threads ... to be extended!
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Ferdinand Soethe wrote:
>
> Dave Brondsema wrote:
>
> DB> The HowTo DTD is a simple document we developed for Forrest. If you
> DB> want complete functionality, DocBook was designed to handle exactly
> DB> that. See if it fits your needs.
>
> Well, my point is, that we have a HowTo-DTD that should be used to
> write HowTos (and that I find very useful). So using another dtd is
> neither required nor really what we want, is it?
:-)
> The only issue that I have with it is, that there is no distinction
> between the instruction-part of a step and other paragraphs explaining
> the result of the step or introducing the instruction.
>
> And in a dtd that was specifically created to write howtos I think that
> is vital. Not just to be able to render it differently (which can be
> accomplished with style as well) but also because XML should express
> function as cleanly as possible.
Agreed.
Since we are redefining all of Forrest, we need to define a new schema
for this to be used with all html flavors.
Let me explain.
Since we will move to XHTML2 for our intermediate format, and since it
uses RelaxNG for validation, it would seem natural to make the HowTo a
RelaxNG schema that can have XHTML2 embedded.
Only that this prevents us from using XHTML1 and simple HTML for writing
HowTos... unless we define a special compatibility layer for them.
A possible implementation would be to use <div>s with special class
attributes, that get transformed internally to the namespaced HowTo tags.
Another one would be to use special words and formatting to do the same,
which would make it very easy to write them:
<h2>Steps</h2>
<h3>Open your Forrest</h3>
<p>...</p>
<h3>Open the CSS-Sidebar</h3>
<p>...</p>
...etc
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re[2]: (howto DTD) List of open ended threads ... to be extended!
Posted by Ferdinand Soethe <sa...@soethe.net>.
Dave Brondsema wrote:
DB> The HowTo DTD is a simple document we developed for Forrest. If you
DB> want complete functionality, DocBook was designed to handle exactly
DB> that. See if it fits your needs.
Well, my point is, that we have a HowTo-DTD that should be used to
write HowTos (and that I find very useful). So using another dtd is
neither required nor really what we want, is it?
The only issue that I have with it is, that there is no distinction
between the instruction-part of a step and other paragraphs explaining
the result of the step or introducing the instruction.
And in a dtd that was specifically created to write howtos I think that
is vital. Not just to be able to render it differently (which can be
accomplished with style as well) but also because XML should express
function as cleanly as possible.
And an instruction like "Start your Firefox Browser and open the
Forrest you'd like to work on/play with." is clearly something else
than a paragraph explaining the result of following the instruction
("The page you have pointed to will show up in Firefox's main
window.").
Apart from these theoretical concerns, I think it would add usability
to our HowTos if steps looked something like this (see included image,
the icon could be improved).
If is after all very common practice to outline instructions that way.
You see it in practically every book.
And finally, having steps extended by an instruction element will also
help howto-authors as it clearly indicates that there should be an
instruction in each step.
And here I quote from the HowTo-HowTo:
DB> Describe the Steps of your How-To
DB>
DB> In a precise, step-by-step approach, walk your reader through the
DB> process. Make sure your reader can reproduce your intended result
DB> by following your exact steps. Make the learning process efficient
DB> by supplying sample code snippets or configuration details as
DB> necessary.
Sorry this got so long, but as a technical writer, I take these issues
very seriously and perhaps sometimes being a bit stubborn about it.
Doesn't mean it should happen that way ...
--
Ferdinand Soethe