httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rich Bowen <rbo...@rcbowen.com>
Subject Re: SSI tutorial
Date Thu, 02 Nov 2000 03:03:10 GMT
Joshua Slive wrote:
...
> I think the first decision that needs to be made is: should there be one
> section for "high level" docs (high meaning knowledge required to
> understand them), and a seperate section for "beginner level" docs, or can
> they be combined into a single section.

I think that it is valuable to have them in different sections. I have a
vague vision of having comprehensive beginner "how-to" documentation,
along the lines of my ApacheToday articles. And, indeed, much of it will
just be my articles reformatted. And this is all geared towards the
beginner.

> The format you are using is pretty close to the basic format I have been
> using.  I would just add a "Related Modules" (mod_include, mod_cgi) and
> "Related Directives" (XBitHack, AddHandler, Options, etc) section near the
> top someplace, and grab the header and footer material from one of the
> existing docs.

OK, done.

> I would suggest including the "credits" info either at the top or at the
> bottom, but not in both places.

Oops. Done.
 
> Content-wise it looks great.  I would probably change every occurence of
> <!--#exec cgi to <!--#include virtual, and obviously there needs to be
> links added back and forth to existing Apache docs, but that can be done
> later.

I've made the change. And I've put some of these links in. I realized
that it would be helpful to know where the doc will reside in the tree
in order to put in these other links, so I just put in some of those,
and will add the rest once that location decision is finalized.  My
recommendation is a "howto" or "tutorial" directory under the "manual"
directory. Or, perhaps, at the same level as the "manual" directory.

> Regarding HTML-POD-whatever, I am a pure HTML man myself.  However, I have
> no objection if people want to go with a more descriptive format.  I would
> think that if we did this, XML/DocBook/etc would probably be preferable
> over POD.  Until someone takes the initiative to research/discuss this in
> detail, I suggest we continue with plain HTML.

I have no problems with this. But I will almost certainly maintain the
POD in my own CVS tree, and just write a specialized pod2apachecdocs
conversion so that I can continue to do my actual content generation in
POD. XML and DocBook are not preferable over POD for any definition of
"preferable" that I am aware of. However, I realize that this sort of
thing is all about personal preference, so there's no value in turning
this in to a holy war. HTML it is.

Anyways, here's the second draft.

Rich
-- 
Author: Apache Server Unleashed - www.apacheunleashed.com
Director of Web Application Development - http://www.cre8tivegroup.com/
Mime
View raw message