forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <terrac...@mac.com>
Subject Re: draft howto dtd
Date Thu, 16 May 2002 12:37:09 GMT
Steven,

> 1) too few optional elements
>
>    - overview, audience, purpose and prerequisites (or is it really
> prerequesites?) should be optional, I guess...

I don't understand. A howto should be more structured than your average 
document page. I consider those elements vital and user-friendly. They 
are only a few sentences. Why make them optional? It creates more work 
others.

>    - furthermore, I believe there will be confusion between
> header>abstract, overview and purpose, especially if they all need to be
> filled in

Ok, I considered that too. However, abstract is optional in the document 
dtd, and I wanted it required. I wasn't sure how to override that. Any 
suggestions?

>    - reference to faqs elements, but not reusing the one defined in
> faq-v11.dtd
Good point. I'll add that.

> 3) Obviously, I don't like the s2/title attributes... :-)
>
> This is a nice example of the tedious result of including a
> hierarchy/nesting indication in an element name...
>
> I'd much prefer this:
>
>     <!ELEMENT steps (section | %blocks;)+ >
>     <!ATTLIST steps %common.att;>

Not all how-tos will fit perfectly into the step by step model. I had 
this originally, but I took it out.

> On a related note: why provide title elems/attrs with the various parts
> of your DTD... the meaning of the parts (and the title using which they
> should be rendered) is pretty clear and perhaps is something which can
> be automated using a stylesheet, I believe:
>
> <xsl:template match="steps">
>   <section>
>     <title>Steps</title>
>     <xsl:apply-templates/>
>   </section>
> </xsl:template>

I wasn't sure if I should allow readers to write their own section 
titles. Most how-tos do... My titles are too generic, and I don't really 
like that.

>> 1. I think the header element contains a lot of useful
>> cms-related info.
>> Perhaps version can be used to imply status:
>> draft/release/revision. I'm
>> not sure of its precise meaning with code, but perhaps
>> "draft" document
>> versions could have a value less than 1, etc.
>
> We could provide use a list of possible attribute values for that, too -
> so that not everybody starts to invent his own classification.

Great.

>> 5. Steve, I wonder if you're going to dislike the way I'm treating
>> titles (as attributes) in each howto part. I just found it a little
>> simpler to implement this way. Feel free to revise, in
>> anticipation of
>> your v11 work.
>
> That's Steven ;-)

Ooops. Really sorry ;).

> See above - will you update, or will I do? Decision to be made is
> integration with the new doc-v11 or not.

Let me try another pass, and then you can refine it as necessary. I'm 
still rather confused, v10 or v11? Please, I just don't want the doc-v11 
decision to delay the howto effort. I have put warnings on the how to 
write a how-to, etc. pages (which are based on v10), so potential 
authors are alerted that things will change.

Diana


Mime
View raw message