httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Patrik Grip-Jansson <patr...@gnulix.org>
Subject RE: dtd for httpd-docs
Date Tue, 05 Mar 2002 08:22:33 GMT
On Mon, 4 Mar 2002, Brad Miller wrote:

> I also attached the template. This is a very rough draft and needs more
> refinement. For now this validates and can be used as a template with the
> new dtd attached.

I liked the template and the DTD is really coming along - nice work!

> ~~Or <note type="warning">?  Either way is fine with me.  You may
> ~~want to check the Docbook DTD to see how they do it.  One that might be
> ~~particularly useful in apache is <securitywarning> or something like that.
> I added <securitywarning> you can place any text or formating in it. Do we
> need any attributes for this?

I've also implemented this in the xsl file. I've added it as an type
attribute to the <note> tag, as suggested by Joshua. At the moment the 
type attribute can be; plain, warning, and securitywarning. Where plain is 
the default.

> I added <language>. I don't really have any rules for language. And I am not
> really following how you are switching languages here.
> Are you pulling information from another file if the stylesheet sees the
> <language> tag it will find whatever xml file for that language you specify
> with an attribute and include that? I guess I really don't understand how
> the language conversion works.

Yes, the language switching works more or less as you assumed. At the
beginning of the transform we set language to a default value of "en". If
there is a <language> tag in <directivesynopsis>, we take the value from
that node instead. Then the transform does a document() to pull in some
text nodes from the appropriate {$language}.xml file. The technique is  
right out of the xsl specification, where it is used as an example of how 
to use <xsl:message>.

> Can someone give me a list of attributes for this if that is how it is done?
> I also need to know where the language attribute will be used if anywhere
> other than <directivesynopsis>.

I've been thinking about this. And I can't see any reason to have it
anywhere else. I'm starting to think that it might be better to use
<directivesyopsis language="en"> rather than having the <language> tag.
 
> Lastly, do we want to stick with a DTD or should we be using a schema?
> I don't really have an opinion on this because I know dtd's better but
> schemas are more rubust.

I'm also more comfortable with DTD:s. So I suggest we stick with them for
the time being. The rule set we are trying to "enforce" isn't all that
complicated, nor would I assume that all the rules are really that strict
either. I don't think it would be the end of the world, should someone
put four paragraphs in a <summary>.

My belief is that the most important part is that we shouldn't impose 
arbitrary rules on the authors, as long as it doesn't make the 
transformation process too unruly (read impossible :-)

> Converting to a schema at this point wouldn't take much effort.

There are a couple of good DTD->Schema utilities out there ("out there",
being Freshmeat.) Why not keep to our DTD, and use some such utility when 
the need arises? No need to be bleeding edge :-)

-- 
.---------------------.
| Patrik Grip-Jansson |
| Ringen 4B           |    .--------------------.
| 78444 Borlänge   .--'----' http://gnulix.com/ `---------.
| Sweden           |  All views and opinions are my own,  |
`------------------| PH:+46(0)24382823 PW:+46(0)707354360 |
                   `--------------------------------------'



---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message