Message-ID: <33E63319.41C67EA6@topsail.org>
Date: Mon, 04 Aug 1997 15:52:57 -0400
From: Chuck Murcko <chuck@topsail.org>
Organization: The Topsail Group
MIME-Version: 1.0
To: new-httpd@apache.org
Subject: Re: RFD: Apache Documentation Project !!
References: <199708041535.RAA20385@en1.engelschall.com>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Sender: new-httpd-owner@apache.org
Precedence: bulk
Reply-To: new-httpd@apache.org

We only ever did HTML docs. Then we converted them to postscript with a
converter, which should still be somewhere on hyperreal.org.

Ralf S. Engelschall wrote:
> 
> While sitting around for a few hours today I was angry because for Apache 1.0
> there was a Postscript version available of the documentation. Then we only
> did HTML coding. And this coding also is somewhat ugly. Ok, one can print out
> every page from htdocs/ via Netscape, but thats no solution.  A lot of people
> really want one paper to print out where they can find all core docs, all
> module docs, etc.  Nothing reads better then on paper....
> 
> Hmmmm.... now I've evaluated my knowledge for document preparation systems
> which we can use for such an "Apache Documentation System".  Of course Linux
> and FreeBSD use the SGML approach. Perl uses the POD approach. So I tested
> today the old LinuxDOC-SGML package, the new SGML-Tools package, FreeBSD's
> sgmlfmt (based on the old LinuxDOC-SGML package), Perl's POD and SDF, a
> successor of POD. Every one had its advantages, especially SDF which leads to
> very compact sources. But when it comes to the generation of the output
> formats, the really best one currently is SGML-Tools 0.99.14.
> 
> So, I've started with this one and the sources of the FreeBSD handbook,
> aligned this source for SGML-Tools and wrote two wrappers for the gneration of
> HTML and TeX to be able to receive a little bit better formatting and layout
> in these two major target formats than SGML-Tools provides. Now only SGML-Tool
> 0.99.14 and the two Perl wrapper scripts together with a Makefile are needed
> to compile ASCII, HTML, DVI and Postscript directly out of the *.sgml files.
> 
> To test it the result, I've converted the first part of mod_rewrite.html from
> htdocs/ into a mod_rewrite.sgml. The result is very nice, both as HTML and on
> the paper. Want to have a look? Then just try
> 
> http://www.apache.org/~rse/ADP/handbook-4.html
> 
> I've also put an overview page under http://www.apache.org/~rse/ for this
> stuff.
> 
> Ok, now I/we now that is is easy to be able to provide really nice Apache
> docs, what should we do? There are a few possibilities:
> 
>    1. Forget RSE's idea because its not what we want
> 
>    2. Be happy about RSE's idea and start a real
>       Apache Documentation Project similar to what Linux and FreeBSD folks
>       did. RSE is accepting the role of the maintainer of this subproject.  We
>       create a mailing-list apache-docs@apache.org, a repository area
>       apache-docs and a new URL for the webpages, e.g.
>       http://www.apache.org/docs/ADP/.
> 
>    3. Think about this idea much deeper and discover
>       an even better approach.
> 
> I vote for 2. and hope there are others who want to help me to do this
> project. The goals then would be: Try to collect all stuff from htdocs/* and
> create an Apache Handbook out of it. Then convert the existing FAQ.html to
> FAQ.sgml for an Apache FAQ. Then try to incorporate more stuff in the future
> and maintain docs in the new format. And if we do good work, Apache 1.3.X
> could be shipped with nicer docs....
> 
> Feedback?
>                                        Ralf S. Engelschall
>                                        rse@engelschall.com
>                                        www.engelschall.com

-- 
chuck
Chuck Murcko
The Topsail Group, West Chester PA USA
chuck@topsail.org