You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by Brad Miller <br...@beldamar.com> on 2002/02/27 03:43:11 UTC
dtd for httpd-docs
Here is the low down on the DTD.
I was able to add most of the XHTML tags that were listed on the
http://httpd.apache.org/docs-project/docsformat.html page.
There were a few I left out because I didn't see them being used. If we need
to add them later I can do that.
Also the one tag that I left out of the XML tag list was the "section" tag.
I did not see that being used anywhere either. Point me to an example if it
is being used and I will get that fixed.
The rules are pretty basic and if you are using an editor that validates on
the fly, the required tags should fill themselves in when you add the root.
Some editors may not do this so I am making a template XML file that has all
the tags and a description of the rules for each of those tags. Hopefully I
can have this finished tonight. I should probably write a document on the
rules kinda like a w3c doc, but that could take some time and I don't know
how necessary that is. And I am sure we will have some tweaking to do so
that can probably wait.
There are only 2 tags that allow you to add anything. The first is <p> we
can refine it if needed but it looked like just about anything can be placed
inside it. The other is <td>. Although I did not see tables being used in
any of the files I used for samples I am sure this will need to be pretty
open.
I added 3 attributes to <td> "rowspan", "colspan", and "class". I wasn't
sure about the class attribute and we can remove it or add it to other tags
if needed.
<a> has the attribute "href".
<directive> has the attribute "module".
Am I missing anything here?
Changes needed to existing XML files will be nothing more than a little
reorganization of tags. The DTD requires a sequence for certain tags and
that sequence is not being followed through out all of the files. I used
mod_setenvif.xml as the default template and then compared tags and
sequences with 5 other files.
I checked the DTD against several files and with minor changes to the
sequence they validate. Let me know if anyone has any problems with this or
needs something changed.
I should have the template file up later tonight.
Thanks,
Brad Miller
brad@beldamar.com
www.beldamar.com
RE: dtd for httpd-docs
Posted by Brad Miller <br...@beldamar.com>.
You didn't scare me off.
I have been kinda busy.
I will get back to work on the dtd this weekend.
I didn't get to do anything on the xsl file yet.
I hope to get to that after I get the DTD finalized.
Thanks,
Brad Miller
brad@beldamar.com
www.beldamar.com
-----Original Message-----
From: Joshua Slive [mailto:joshua@slive.ca]
Sent: Friday, March 01, 2002 11:46 AM
To: docs@httpd.apache.org
Subject: RE: dtd for httpd-docs
> On Tue, 26 Feb 2002, Brad Miller wrote:
>
> > Here is the low down on the DTD.
Hmmm... I hope I didn't scare you off Brad.
The DTD will take some work. But you also mentioned you had done some work
on the xsl file. That I could probably commit right away.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: dtd for httpd-docs
Posted by Rich Bowen <rb...@rcbowen.com>.
On Tue, 5 Mar 2002, Joshua Slive wrote:
> Alright. I got things working with emacs at least at a basic level and I
> played around a little with the DTD. The results are inline below.
> A few questions:
>
> - Does this look right to everyone?
>
> - Where should it go? manual/style/, manual/mod/, ... ?
I would vote for manual/style, as we want to use the same thing in
howto, vhosts, faq, misc, ssl, and so on.
> - Should we use a PUBLIC or a SYSTEM identifier. SYSTEM is easier to setup,
> because we don't need to much with CATALOGs, but I'm not sure what the
> "right thing" is.
>
> As I've mentioned, I really don't know what I'm doing with DTDs, so any
> comments will be appreciated.
Well, I'm very much new to this as well, but it looks good to me! Can we
get another XML expert to look at it and tell us what sucks about it?
--
Who can say where the road goes
Where the day flows
Only time
--Pilgrim (Enya - A Day Without Rain)
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: dtd for httpd-docs
Posted by Joshua Slive <jo...@slive.ca>.
> From: Brad Miller [mailto:brad@beldamar.com]
>
> <pre> was not defined as an element.
> I added it and everything validates now.
> Thanks for the help with the grouping of elements.
I'll commit this in a few minutes with a few more changes.
I'm not sure why you added "*" after all the Inline's. The "*" is already
embedded in the entity.
I also had to make most of the <directorysynopsis> optional, unfortunately.
When we use <directorysynopsis location="somewhereelse">, then only the
<name> is required. I don't think a DTD can be smart enough to
differentiate these two situations, so all the tags except <name> will be
set to optional.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: dtd for httpd-docs
Posted by Brad Miller <br...@beldamar.com>.
<pre> was not defined as an element.
I added it and everything validates now.
Thanks for the help with the grouping of elements.
Brad
<?xml version='1.0' encoding='UTF-8' ?>
<!ENTITY nbsp " ">
<!ENTITY % inlinetags "em | strong | code | a | br | directive | module">
<!ENTITY % blocktags "p | example | note | table | ul | ol | dl | pre">
<!ENTITY % Block "(%blocktags;)*">
<!ENTITY % Inline "(#PCDATA | %inlinetags;)*">
<!ENTITY % BlockOrInline "(#PCDATA | %inlinetags; | %blocktags;)*">
<!ELEMENT modulesynopsis (name , description , status , sourcefile? ,
identifier? , compatibility? , summary? , seealso* , directivesynopsis+)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT status (#PCDATA)>
<!ELEMENT identifier (#PCDATA)>
<!ELEMENT sourcefile (#PCDATA)>
<!ELEMENT compatibility %Inline;*>
<!ELEMENT description %Inline;*>
<!ELEMENT module (#PCDATA)>
<!ELEMENT example (#PCDATA | title | %inlinetags; | %blocktags;)*>
<!ELEMENT seealso %Inline;*>
<!ELEMENT a %Inline;*>
<!ATTLIST a href CDATA #REQUIRED >
<!ELEMENT directivesynopsis (name , description , syntax , default? ,
contextlist , override? , compatibility? , usage , seealso*)>
<!ATTLIST directivesynopsis type CDATA #IMPLIED
location CDATA #IMPLIED >
<!ELEMENT syntax %Inline;*>
<!ELEMENT default (#PCDATA)>
<!ELEMENT contextlist (context+)+>
<!ELEMENT context (#PCDATA)>
<!ELEMENT override (#PCDATA)>
<!ELEMENT note (#PCDATA | title | %inlinetags; | %blocktags;)*>
<!ELEMENT title %Inline;*>
<!ELEMENT p %Inline;*>
<!ELEMENT ul (li+)>
<!ELEMENT ol (li+)>
<!ELEMENT li %Inline;*>
<!ELEMENT strong %Inline;*>
<!ELEMENT br EMPTY>
<!ELEMENT table (tr)+>
<!ELEMENT tr (td)+>
<!ELEMENT td %BlockOrInline;*>
<!ATTLIST td colspan CDATA #IMPLIED
rowspan CDATA #IMPLIED
class CDATA #IMPLIED >
<!ELEMENT directive (#PCDATA)>
<!ATTLIST directive module CDATA #IMPLIED
type CDATA #IMPLIED >
<!ELEMENT code %Inline;*>
<!ELEMENT dl (dd | dt)+>
<!ELEMENT dt %Inline;*>
<!ELEMENT dd %BlockOrInline;*>
<!ELEMENT em %Inline;*>
<!ELEMENT usage %Block;>
<!ELEMENT summary %Block;>
<!ELEMENT pre %Inline;*>
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: dtd for httpd-docs
Posted by Patrik Grip-Jansson <pa...@gnulix.org>.
On Tue, 5 Mar 2002, Joshua Slive wrote:
> - Where should it go? manual/style/, manual/mod/, ... ?
I think it fits nicely in manual/style/, along with the xsl files.
> - Should we use a PUBLIC or a SYSTEM identifier. SYSTEM is easier to setup,
> because we don't need to much with CATALOGs, but I'm not sure what the
> "right thing" is.
I don't really think there is a "right thing" here. I'd say; go with
SYSTEM.
> As I've mentioned, I really don't know what I'm doing with DTDs, so any
> comments will be appreciated.
I'll give you some, as soon as I get to play around with this new DTD-toy
:-)
--
.---------------------.
| 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
RE: dtd for httpd-docs
Posted by Joshua Slive <jo...@slive.ca>.
> From: Brad Miller [mailto:brad@beldamar.com]
>
> I am trying to catch up with all the suggestions and comments
> that have been
> passing through the list.
> I took little snippets from several different emails and added my comments
> and what I did to the DTD to try to conform.
> 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.
Alright. I got things working with emacs at least at a basic level and I
played around a little with the DTD. The results are inline below.
The main things I've done is to introduce two "classes" of tags: inline and
block. With these, we can allow flexibility in what goes where, without
having to allow everything.
(I've also removed the "authored by" comment. I'm not trying to take away
credit from Brad for his great work, but it doesn't make much sense for a
document lots of people are editting.)
There is still fine-tuning to be done, but this seems to work in general.
A few questions:
- Does this look right to everyone?
- Where should it go? manual/style/, manual/mod/, ... ?
- Should we use a PUBLIC or a SYSTEM identifier. SYSTEM is easier to setup,
because we don't need to much with CATALOGs, but I'm not sure what the
"right thing" is.
As I've mentioned, I really don't know what I'm doing with DTDs, so any
comments will be appreciated.
Joshua.
<?xml version='1.0' encoding='UTF-8' ?>
<!ENTITY nbsp " ">
<!ENTITY % inlinetags "em | strong | code | a | br | directive | module">
<!ENTITY % blocktags "p | example | note | table | ul | ol | dl | pre">
<!ENTITY % Block "(%blocktags;)*">
<!ENTITY % Inline "(#PCDATA | %inlinetags;)*">
<!ENTITY % BlockOrInline "(#PCDATA | %inlinetags; | %blocktags;)*">
<!ELEMENT modulesynopsis (name , description, status , sourcefile?,
identifier? , compatibility? , summary? , seealso* , directivesynopsis+)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT status (#PCDATA)>
<!ELEMENT identifier (#PCDATA)>
<!ELEMENT sourcefile (#PCDATA)>
<!ELEMENT compatibility %Inline;>
<!ELEMENT description %Inline;>
<!ELEMENT module (#PCDATA)>
<!ELEMENT example (#PCDATA | title | %inlinetags; | %blocktags;)*>
<!ELEMENT seealso %Inline;>
<!ELEMENT a %Inline;>
<!ATTLIST a href CDATA #REQUIRED >
<!ELEMENT directivesynopsis (name , description , syntax , default? ,
contextlist , override? , compatibility? , usage, seealso*)>
<!ATTLIST directivesynopsis type CDATA #IMPLIED >
<!ATTLIST directivesynopsis location CDATA #IMPLIED >
<!ELEMENT syntax %Inline;>
<!ELEMENT default (#PCDATA)>
<!ELEMENT contextlist (context+)+>
<!ELEMENT context (#PCDATA)>
<!ELEMENT override (#PCDATA)>
<!ELEMENT note (#PCDATA | title | %inlinetags; | %blocktags;)*>
<!ELEMENT title %Inline;>
<!ELEMENT p %Inline;>
<!ELEMENT ul (li+)>
<!ELEMENT ol (li+)>
<!ELEMENT li %Inline;>
<!ELEMENT strong %Inline;>
<!ELEMENT br EMPTY>
<!ELEMENT table (tr)+>
<!ELEMENT tr (td)+>
<!ELEMENT td %BlockOrInline;>
<!ATTLIST td colspan CDATA #IMPLIED
rowspan CDATA #IMPLIED
class CDATA #IMPLIED >
<!ELEMENT directive (#PCDATA)>
<!ATTLIST directive module CDATA #IMPLIED
type CDATA #IMPLIED >
<!ELEMENT code %Inline;>
<!ELEMENT dl (dd | dt)+>
<!ELEMENT dt %Inline;>
<!ELEMENT dd %BlockOrInline;>
<!ELEMENT em %Inline;>
<!ELEMENT usage %Block;>
<!ELEMENT summary %Block;>
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: dtd for httpd-docs
Posted by Joshua Slive <jo...@slive.ca>.
On Mon, 4 Mar 2002, Brad Miller wrote:
> I am trying to catch up with all the suggestions and comments that have been
> passing through the list.
> I took little snippets from several different emails and added my comments
> and what I did to the DTD to try to conform.
> 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.
Looking good. I still think we need "inline" and "block" elements to
allow the proper flexibility. I also think I know how to do it. The only
problem is, I don't have the patience to set up (X)Emacs to properly
parse an xml file with a DTD today. By the time I get psgml, a validator,
a catalog file, etc, all set up, I'm too frustrated to do anything ;-)
(This is why I was skeptical about DTDs in the first place; they are damn
complicated to use.)
Anyway, I'll try again later and see if my frustration level can be
supressed.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: dtd for httpd-docs
Posted by Patrik Grip-Jansson <pa...@gnulix.org>.
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
RE: dtd for httpd-docs
Posted by Brad Miller <br...@beldamar.com>.
I am trying to catch up with all the suggestions and comments that have been
passing through the list.
I took little snippets from several different emails and added my comments
and what I did to the DTD to try to conform.
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.
~~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?
~~The thing I like the most is that I added some basic support for
~~internationalization. One can switch language by adding <language>
~~to <directivesynopsis>. It defaults to English, but I've also added "sv"
~~so that the template be generated in Swedish.
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.
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>.
~~<section id="hereiam"><title>lala</title>...
~~should create the appropriate <a href="#hereiam">reference</a>.
~~
~~Yes, sections can be nested. Main sections get <h2> and nested ones get
~~<h3> at the moment.
Do I need to specify an "id" attribute? I never was too clear on id's, some
dtd's I have seen it looks like they just assume id and others specify them.
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.
Converting to a schema at this point wouldn't take much effort.
Thanks,
Brad Miller
brad@beldamar.com
www.beldamar.com
RE: dtd for httpd-docs
Posted by Joshua Slive <jo...@slive.ca>.
On Sat, 2 Mar 2002, Patrik Grip-Jansson wrote:
> On Fri, 1 Mar 2002, Joshua Slive wrote:
>
> > The DTD will take some work. But you also mentioned you had done some work
> > on the xsl file. That I could probably commit right away.
>
> I hope you guys haven't done too many changes to the xsl file. I've
> changed it pretty extensively. I've tried to clean it up a bit and fixed a
> number of quirks in it (some of them have no doubt been replace by quirks
> of my own :-) I've especially tried to minimise the number of variables
> used when creating URI:s.
Great. Please post as soon as you can so that we don't let CVS get
out-of-step with your work.
> How about adding a <warning> tag, similiar to the <note> tag? Which could
> be rendered with a red border or something, to indicate that it is
> extremely important.
Sure. 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.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: dtd for httpd-docs
Posted by Patrik Grip-Jansson <pa...@gnulix.org>.
On Fri, 1 Mar 2002, Joshua Slive wrote:
> The DTD will take some work. But you also mentioned you had done some work
> on the xsl file. That I could probably commit right away.
I hope you guys haven't done too many changes to the xsl file. I've
changed it pretty extensively. I've tried to clean it up a bit and fixed a
number of quirks in it (some of them have no doubt been replace by quirks
of my own :-) I've especially tried to minimise the number of variables
used when creating URI:s.
The thing I like the most is that I added some basic support for
internationalization. One can switch language by adding <language>
to <directivesynopsis>. It defaults to English, but I've also added "sv"
so that the template be generated in Swedish.
I've also added extensive comments, which should make it much easier for
others to begin playing around with the transformations.
I need to clean it up a bit before it's appropriate for public
consumption. Hopefully, I'll be able to fix it up during the day...
How about adding a <warning> tag, similiar to the <note> tag? Which could
be rendered with a red border or something, to indicate that it is
extremely important.
--
.---------------------.
| 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
RE: dtd for httpd-docs
Posted by Joshua Slive <jo...@slive.ca>.
> On Tue, 26 Feb 2002, Brad Miller wrote:
>
> > Here is the low down on the DTD.
Hmmm... I hope I didn't scare you off Brad.
The DTD will take some work. But you also mentioned you had done some work
on the xsl file. That I could probably commit right away.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: dtd for httpd-docs
Posted by Joshua Slive <jo...@slive.ca>.
On Fri, 1 Mar 2002, Brad Miller wrote:
> I can't help with emacs but I am working on a sample XML file that has
> comments and
> uses all situations for examples. I'll forward it to the list as soon as I
> get a
> little more done on it.
Cool. When I get the chance, I'll look into emacs instructions. I
believe it will involve adding a <Doctype> reference to the xml files and
then modifying the emacs "catalog" to point to the appropriate DTD.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
RE: dtd for httpd-docs
Posted by Brad Miller <br...@beldamar.com>.
~~Sure, there are things missing (including some I added just recently), but
~~we should be able to clean that up pretty easily. For example, the
~~<directive> and <directivesynopsis> tags take the attribute "type". See
~~core.xml for an example.
done.
~~A couple basic questions to consider:
~~1. How strict do we want to be? For example, in your dtd, we do not allow
~~<note>This is a note</note>. Instead, it must be <note><p>This is a
~~note</p></note>. The former is probably "more correct", but do we want to
~~enforce it? I'm not really sure about the answer to this.
I agree with this and have made it so text can be added without any tags.
~~2. I think we need to have some concept of block vs inline element.
~~Certain tags (for example, <description>, <compatibility>) could probably
~~take any inline element (<em>, <strong>, <a>, <directive>, etc). Other
~~tags (for example, <note>, <example>, <usage>) can take any block element
~~(<p>, <example>, <table>, etc). I believe that there is a way to define
~~sets of elements like this in a DTD, and this would make the DTD both
~~cleaner and more flexible.
I have done attribute groups but not element groups. I'm looking into this
now.
~~3. We'll need to provide some instructions on how to use this. In
~~general, I think the majority of people here are using emacs, so
~~instructions for that platform would be good. If nobody else can figure
~~it out, I will spend some time on it. We will also need to reference the
~~DTD in the xml files, I guess.
I can't help with emacs but I am working on a sample XML file that has
comments and
uses all situations for examples. I'll forward it to the list as soon as I
get a
little more done on it.
Thanks,
Brad Miller
brad@beldamar.com
www.beldamar.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: dtd for httpd-docs
Posted by Joshua Slive <jo...@slive.ca>.
On Tue, 26 Feb 2002, Brad Miller wrote:
> Here is the low down on the DTD.
Looks like a great start.
> I was able to add most of the XHTML tags that were listed on the
> http://httpd.apache.org/docs-project/docsformat.html page.
> There were a few I left out because I didn't see them being used. If we need
> to add them later I can do that.
> Also the one tag that I left out of the XML tag list was the "section" tag.
> I did not see that being used anywhere either. Point me to an example if it
> is being used and I will get that fixed.
> There are only 2 tags that allow you to add anything. The first is <p> we
> can refine it if needed but it looked like just about anything can be placed
> inside it. The other is <td>. Although I did not see tables being used in
> any of the files I used for samples I am sure this will need to be pretty
> open.
>
> I added 3 attributes to <td> "rowspan", "colspan", and "class". I wasn't
> sure about the class attribute and we can remove it or add it to other tags
> if needed.
> <a> has the attribute "href".
> <directive> has the attribute "module".
> Am I missing anything here?
Sure, there are things missing (including some I added just recently), but
we should be able to clean that up pretty easily. For example, the
<directive> and <directivesynopsis> tags take the attribute "type". See
core.xml for an example.
A couple basic questions to consider:
1. How strict do we want to be? For example, in your dtd, we do not allow
<note>This is a note</note>. Instead, it must be <note><p>This is a
note</p></note>. The former is probably "more correct", but do we want to
enforce it? I'm not really sure about the answer to this.
2. I think we need to have some concept of block vs inline element.
Certain tags (for example, <description>, <compatibility>) could probably
take any inline element (<em>, <strong>, <a>, <directive>, etc). Other
tags (for example, <note>, <example>, <usage>) can take any block element
(<p>, <example>, <table>, etc). I believe that there is a way to define
sets of elements like this in a DTD, and this would make the DTD both
cleaner and more flexible.
3. We'll need to provide some instructions on how to use this. In
general, I think the majority of people here are using emacs, so
instructions for that platform would be good. If nobody else can figure
it out, I will spend some time on it. We will also need to reference the
DTD in the xml files, I guess.
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org