Mailing-List: contact apache-docs-help@apache.org; run by ezmlm
Date: Mon, 9 Oct 2000 11:01:19 -0700 (PDT)
From: Joshua Slive <slive@finance.commerce.ubc.ca>
To: apache-docs@apache.org
Subject: Re: reorg of core.html
In-Reply-To: <p0501020cb607ab0ea03b@[64.81.19.109]>
Message-ID: 
 <Pine.SOL.4.20.0010091023390.1726-100000@garibaldi.commerce.ubc.ca>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII


(Incidentally, no need to copy me on posts to the list.  I will read them
there, eventually.)

On Mon, 9 Oct 2000, Chris Pepper wrote:
> 	Sorry -- I had forgotten that there are currently two alpha 
> lists of directives. Yes, two alpha and one grouped would be silly 
> (even more silly than two consecutive alpha lists, as now? :) ).

But actually, there is no "overall" "by type" listing for directives.
The "by type" listing we are discussing is specific to core.html.  For
other modules, it is not as important, because each module is basically
task specific.  Therefore, you can get a "by type" listing of directives
simply by going to each module file.  It might be a good future project to
make a directives index that is sorted by type and includes ALL the
modules, but I have not done this.

> 
> 	Huh? I'm talking about breaking core.html into sections like 
> core-process.html, and core-files.html, instead of the single 
> core.html. This doesn't require parallel maintenance of two versions. 
> The only downside, which is significant, is that you can no longer 
> use browser's Find command to find all occurrences of a word in the 
> whole core.html.

Thanks, I understand now.  I have no objection to this, if it is done
carefully.

> 	The "See also" and inline links are what I mean by 
> cross-references. They're present now, and very useful, but 
> sectioning core.html would make it convenient to read a whole 
> section, rather than following many cross-references, and hoping not 
> to read the same thing twice or miss something important.
> 
> 	Ideally, this could address the same issue as the Location, 
> Files, etc. and Virtual Hosts documents, but that's a second-stage 
> question.
> 

Yah, this sounds good.  Perhaps these should be seperate documents,
however.  ie. a document that explains how process forking works in Apache
with LINKS to the core.html process-control directives.  That is how
the VirtualHost docs work at the moment.  They discuss all the directives,
but they do not themselves contain the directive definitions.
If such documents existed, then the reorg of core.html would probably 
not be necessary.  I really consider this a temporary measure to provide
some sort of help for people trying to figure out how things relate to
each other.

> PS-Have you all considered moving "See Also" to the end of the 
> Syntax/Default/Context/Status block? I think this would be 
> aesthetically nicer....

I have no objection to that.  It sounds like a good idea.  However,
it would be a fair amount of work to fix each module doc.

Joshua.