forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Ivelin Ivanov" <ive...@apache.org>
Subject Re: draft howto dtd
Date Fri, 17 May 2002 13:30:01 GMT

Do you guys thing its time to switch the DTD to XML Schema ?
Xalan supports XML Schema validation and I've used it in production for a
while now.

----- Original Message -----
From: "Diana Shannon" <terracare@mac.com>
To: <forrest-dev@xml.apache.org>
Sent: Thursday, May 16, 2002 7:37 AM
Subject: Re: draft howto dtd


> 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