httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From (Ralf S. Engelschall)
Subject Re: List maintenance item
Date Thu, 07 Aug 1997 21:49:42 GMT

In article <Pine.GSO.3.95q.970807162157.4137B-100000@csa> you wrote:

> The documentation should be provided in the
> HTML format (I think so anyways), just because most of the people
> are familiar with it.  Providing a good template for the web page is
> essential.

Hmmmm... I disagree with this, because although everyone is familiar with HTML
you cannot easily create both TXT and Postscript from it. And even if it
works, it's a bad hack. What we really need is a meta-language from which we
can generate in batch the other formats. SGML and the LinuxDOC-DTD in
conjunction with SGML-Tools is such an approach. And, of course, the source is
very similar to HTML, so everyone should be happy with the markup language.

The other point is SDF: It is much simpler then SGML or HTML and also provides
really good output formats. And at least the Perl hackers like it because it
is like POD. Ok, its a totally different approach and away from HTML, but ok
for a meta-language.

> NOTE:	Some people may argue that HTML is not a best format and I 
> agree, so personally I do not care about the format per se, except that
> the only requirement is that there are tools to convert that format to
> HTML.  

Yes, but thats not all: We really need HTML _AND_ Postscript. Only HTML is not

> 	Now, there are a bunch of freeware tools out there to convert
> HTML to a number of different formats.  My thoughts on the matter are:
> 	- use HTML as a base and reference on the website
> 	- provide a single converted PostScript and PDF docs 
> 		-this is useful for downloading and printing whole docs
> 	- provide .HLP files via HTML->RTF converter.
> 	- then all we need is some .HPJ files and we got windows docs.
> Additional format maybe added later on if people are requesting them, but
> the above should be bare minimum.

Here SDF would be nice, because it already provides ASCII, HTML, Postscript
_AND_ Windows Help File Format.

> 	Regarding general setup
> 	- every page should have a link to searchable contents
> 	- multiple cross-referencing of topics
> 	- table of contents

Provided by both SGML-Tools and SDF.

> 	- tools (distributed with docs) to automatically
> 	regenerate documentations.

Fine with SGML-Tools and SDF.

> 	- some form of style guide for writing the docs

Can be minimal because all bells and whistles (header, footer) etc.  are
generated, the table of contents is given (after discussion!) and the SGML
approach is a pure markup approach with only a few markup tags. So, the only
required style guide would be how to structure the sections of the handbook,
etc. But this can be minimal.

> Plan:
> 	- everyone come up with a single page setup and put it on some
> 	web page where people can try it out and pick the best one.

Leads to a webdesigner fight who creates the coolest webpage.  And because
HTML is only one of our target formats this should be not needed. The goal is
more this: The handbook should look as similar as it can in all formats.
SGML-Tools with my post-processing filters is nic here: The HTML looks nearly
the same as the Postscript printed on paper.

> 	- negotiate a table of contents

Already put on STATUS and should be discussed after we have choosen the

> 	- write tools for automatic generation of docs

Good Makefiles can be enough, I think.

> 	- write docs 
> 		- ideally this would be a multicycle process, where 
> 		an "editor(s)" check contents before approval.
> 		- due to the everchanging nature of the server, it would
> 		be futile to write docs on new stuff, therefore we should
> 		start with stable (unlikely to change) topics, like :
> 			- CGI, SSI, etc.

+1. Good idea. But we have at least to incorporate the 90% of the current
apache/htdocs/* stuff. Because the Apache Handbook should _REPLACE_ this area
in the future. So at least every module and every config directive should be
documented in the handbook.


                                       Ralf S. Engelschall

View raw message