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
manualpage.dtd
Description: Binary data
common.dtd
Description: Binary data
configuring.en.xml
Description: application/xml
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
