httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Astrid Ke├čler <k...@kess-net.de>
Subject Re[2]: dtd for non-module documentation pages
Date Mon, 10 Jun 2002 22:49:40 GMT
Sorry for my late answer.
Appending you'll find a second version of manualpage.dtd. I've corrected
some elements.
Additionally I added a common.dtd with all elements equal in
modulesynopsis.dtd and manualpage.dtd, and an example converted from
html to xml corresponding to the manualpage.dtd.

> Second, could you please summarize the changes that you made, and give
> us an idea of how the documentation will look in your proposed format. 
> (Perhaps marking up one of the current pages with your elements.)

First, I called the root element <manualpage>, supposing that there is a
1:1 relation between html files and xml files.

A manualpage must have a title, which can't be generated from the file
name or something else.

Each manualpage should have a summary. This is the first section of each
page. The <summary> element is optional, because some few pages (e.g.
vhosts/ip-based.html or new_features_2_0.html) miss them. Maybe you
want to decide, that each page must have a summary. But that would
require restructuring some pages.

Additionally to the summary defined at modulesynopsis.dtd, this one may
have an <index> element. This index element marks the position of the
table of contents of that page. It is neccessary to define the index
position within the summary, because the index is often surrounded by
some text.

The index itself can contain two types of entries and sometimes it has a
title. The two entry types may be anchors to sections at the same page
or links to other pages within the documentation. I defined these two
types to occure either the one or the other. An index of achors to
sections can be generated from the section titles. The <sectionref>
element is standing for such a generated index of anchors. In absence of
the <sectionref> element, you have to define one or more <a> elements to
the corresponding pages.

The second element which is named equal but defined different in both
dtds is <section>. In manualpage.dtd each section must have a title and
the id attribute, if defined, must be unique. Sections without an id
attribute may be handled different during generation of an index of
anchors. Maybe they are listed without a link or they are skipped. And
additionally, each section may have a <related> element for the list of
modules and/or directives. Therfore I created the <directivelist>
element, too.

> - Can we combine the two DTDs?  At minimum, we should put the common
> parts in a common file and pull them into each DTD.

I tried to define a dtd using an external subset, but I failed for the
correct definition. This may be done by someone else please.

> - I really don't like the idea of a <content> tag, both because 
> EVERYTHING should be content (the name is bad) and because I don't see 
> why it is needed.  If an index is wanted, it should be generated 
> automatically by the xslt or whatever.

Well, that's a good point. I renamed it into index.

> - For the "related" stuff, do we want it at all?  I'm the one who 
> invented the "related modules/related directives" sections, but it 
> hasn't seemed to catch on with other doc writers.  Is it a good thing, 
> or should they just be removed and the related material be linked inline?

After my first meeting with the apache documentation I had been very
confused. It took some starts to understand the structure of the
documents and directives. But after that I loved the related list. They
give a very quick overview. But sometimes they are a little bit
neglected.

Kess
Mime
View raw message