forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Steven Noels" <stev...@outerthought.org>
Subject RE: draft howto dtd
Date Thu, 16 May 2002 09:37:42 GMT
Diana,

quickly reviewing:

<!ELEMENT howto (header, overview, audience, purpose, prerequesites,
steps, extension, faqs?, tips?, references?, revisions? )>

1) too few optional elements

   - overview, audience, purpose and prerequisites (or is it really
prerequesites?) should be optional, I guess...
   - furthermore, I believe there will be confusion between
header>abstract, overview and purpose, especially if they all need to be
filled in
   - reference to faqs elements, but not reusing the one defined in
faq-v11.dtd

2) the reference to the document-vxx.dtd should be done like this:

<!ENTITY % document PUBLIC
    "-//APACHE//DTD Documentation V1.1//EN"
    "document-v11.dtd">
%document;

so that it gets picked up by the entity resolving mechanism. We have to
decide which version of the document-vxx.dtd this howto-dtd will be
using. Personally, I'd like to isolate DTD management to Forrest, and
having the latest & greatest (+ archived) versions of the DTD modules on
our website.

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;>

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>

Further comments below...

> -----Original Message-----
> From: Diana Shannon [mailto:terracare@mac.com]
> Sent: woensdag 15 mei 2002 20:25
> To: forrest-dev@xml.apache.org
> Subject: draft howto dtd
>
>
> Attached is a howto dtd draft, along with a sample doc to validate. A
> few notes.
>
> 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.

> 2. id attribute (via %common.att;) is defined for howto, so
> if CMS needs
> to manage docs via that attribute, we're still ok.
>
> 3. I declared one additional child element of header:
> last-modified-content-date. Its purpose is to provide meaning to the
> reader based on content changes, not mere structural changes,
> etc. I'm
> not sure if it duplicates revision history structure at the bottom.

I like that, and maybe we should make it a default for header...

> 4. I'm trying to take what is a liberal approach to what is
> allowed by
> the dtd. For example, I didn't use %content.mix; anywhere. I
> wanted to
> allow authors the chance to use lists for prerequesites, intended
> audience, etc. Perhaps some of you will consider this too loose.
>
> 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 ;-)
            ^

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

> Anyway, please improve it. I'm certainly no expert.
> Snippets/tutorials
> dtds will be similarly structured, so I'll wait for comments before
> submitting those.
>
> Many thanks.

Obliged to do so. Just give a yell.

</Steven>


Mime
View raw message