httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a.@atm9.com.dtu.dk
Subject Re: Strawman XML
Date Thu, 26 Aug 1999 06:55:19 GMT


These are some thoughts on XML documentation for Apache proposed by Dick 

Issues that we are facing:
- General documentation written in XML, easier to convert to anything else
- Description of directives
     -> Describe current system
     -> Future XML format        (two very different things!)
	  
- Why a distinction between the current system and the future XML format?
In the Apache to-do list there is an item to move to a XML based
configuration language and we should take this into account too.
	  
- Separating the general documentation from the description
of the directive (how many arguments, order, type, etc) has some
advantages.
It makes it easier for non-tecnical people to edit the documentation (they
do not need to know the syntax for describing directives, which may change)
and tools for doing what Dick suggested (converting from XML to C code or
automatically generating XML from command_rec structure ) do not need to
know about the syntax of the general documentation (which may change as well)

- The general documentation references the name or id of the directive and
the tool that generates the actual end user documentation (XML -> HTML,
XML->PDF, etc) combines them to produce the end user manual.

- Like Dick said, keep the XML as simple as possible. Keeping it simple and
generic would potentially allow the documentation format to be shared with
other projects. Without entering on the specific DTD, the minimum set of
information the general description of the directive should be:
(first two ones required, rest optional)

   > Directive we are refering to 
   > Brief description  (one or two lines) 
   > Description
   > Example
   > Advanced or detailed explanation
   > Potential pitfalls or security implications
   > Related directives
   > Compatibility or OS dependant issues
   

The directive description would encompass the rest (default values,
arguments, type of the arguments, etc)


I have put a lot of thought into that already for sometime. The above is the
result of trying to summarize those  ideas. I would love to have this
for Comanche's online help. 

What are the thoughts, concerns, ideas  of the current Doc maintainer (Ken
Coar?)  

Cheers

Daniel

daniel@rawbyte.com

Mime
View raw message