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 15:29:00 GMT
Diana,

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

Extra work to me seems like having a lot of similar elements which
*have* to be filled in before you can submit a how-to. I'm not saying
all of these should be made optional, I'l just saying that the barrier
for would-be document editors is quite high of you have a lot of
(similar) elements which have to be filled in. So OK for more structure,
i.e. providing useful elements for people who want to add these elements
to their how-to's - but not OK for making them required. If they are
made optional, others can come in afterwards to fill them in when
needed.

Look at your own remark 4) - it's the same discussion I guess... not?

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

You can't :-|

(Well, technically, you can, but that would mean redeclaring the header
element inside the local declaration subset (i.e.: in the instance),
something which looks really hairy to XML-newbies:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-To V1.0//EN" "howto-v10.dtd"
[
    <!ELEMENT header (title, subtitle?, version?, type?, authors,
                      notice*, abstract %local.headers;)>
    <!ATTLIST header %common.att;>

]>
<howto>
  ...
</howto>

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

Won't be simple since the faq.dtd already references the document.dtd,
too, so you would get duplicate element declarations, too. We'd better
split up the DTDs in two documents, i.e. one specifying the external
entity references needed, and one describing the DTD-specific content
model. I'll think of that and commit a better infrastructure when I
found a more maintainable solution.

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

OK for me, as long as we don't use <s2> inside that content model ;-)

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

Hm. If you want your authors to be able to create their own titles for
specific sections, how will you prevent this:

    <!ELEMENT prerequesites (%blocks;)* >
    <!ATTLIST prerequesites %title.att; %common.att;>

<prerequesites title="Audience">
 ...
</prerequesites>

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

Will do... suggestions?

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

OK - let's please swap files again so that we reach a consensus.

Thanks,

Diane ;-)


Mime
View raw message