Re[2]: dtd for non-module documentation pages

[Astrid Keßler <ke...@kess-net.de>]

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

Re[3]: dtd for non-module documentation pages

[Astrid Keßler <ke...@kess-net.de>]

> I still don't like the index.  My opinion is that:

> - Every page should have an index
> - The location of that index should be the same on every page (perhaps
> just after the summary)
> - The index should be generated from the <section>s, and should not need
> manual intervention.  (ie any section with an "id" should be included)

> This is not how things are in the existing docs, but we don't need to
> replicate the exact format of the existing docs.

Well, this makes it much easier. Then the differences to
modulesynopsis.dtd are restricted to the following:


<?xml version='1.0' encoding='UTF-8' ?>
<!-- include common.dtd -->

<!-- <manualpage> is the root element -->
<!ELEMENT manualpage (title, summary?, seealso*, section*)>

<!-- a page may have one or more sections. Each section is named by an
     unique id. A section must have a title and some text. It may have
     subsections and a list of related modules and directives -->
<!ELEMENT section (title, (section | related | %blocktags;)*)>
<!ATTLIST section id ID #IMPLIED>

<!-- the lists of related modules and/or related directives -->
<!ELEMENT related (modulelist | directivelist)+>

<!-- list of related directives -->
<!ELEMENT directivelist (directive)+>


> Other than that, I am ready for this to go into the docs.  Astrid, do you
> have commit access?

No, I have not.

Kess

Re[2]: dtd for non-module documentation pages

[Joshua Slive <jo...@slive.ca>]

I'm pretty happy with this overall.  It looks nice and simple.

A few more comments inline.

On Tue, 11 Jun 2002, Astrid Keßler wrote:
> 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.

I still don't like the index.  My opinion is that:

- Every page should have an index
- The location of that index should be the same on every page (perhaps
just after the summary)
- The index should be generated from the <section>s, and should not need
manual intervention.  (ie any section with an "id" should be included)

This is not how things are in the existing docs, but we don't need to
replicate the exact format of the existing docs.

As far as pages that are "index" pages in themselves, linking to other
documents, these links should be an integral part of the content, either
in the <summary> or in one of the <section>s.

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

OK.  Don't worry about it for now.  It can be done later.

I'd like to hear at least one opinion from someone other than me on this.
Rich, have you had a chance to look this over?  Is there anything missing
that could add more structure?

Other than that, I am ready for this to go into the docs.  Astrid, do you
have commit access?

Joshua.


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