Mailing List Archive

Joshua Slive wrote:
>
> I realize I'm going to get the reputation of someone who just likes to
> sort everything, but....
>
> Attached is a reorganization of the directives section in core.html. It
> sorts directives first by purpose, and then alphabetically. This does not
> match the format of the other modules docs, but core.html is certainly a
> special case.
>
> I think this type of reorganization is important because it gives people a
> fighting chance to figure out what is going on with the core directives,
> without reading the entire file from top to bottom. The alphabetical
> listing is essentially useless, and duplicates what is already available
> in directives.html.
>
> Unless someone objects, I will commit this.

I like it! This definately makes this document more usable.

Rich

Its nice but please keep the alphabetical index also.


Raymond S Brand


Joshua Slive wrote:
>
> I realize I'm going to get the reputation of someone who just likes to
> sort everything, but....
>
> Attached is a reorganization of the directives section in core.html. It
> sorts directives first by purpose, and then alphabetically. This does not
> match the format of the other modules docs, but core.html is certainly a
> special case.
>
> I think this type of reorganization is important because it gives people a
> fighting chance to figure out what is going on with the core directives,
> without reading the entire file from top to bottom. The alphabetical
> listing is essentially useless, and duplicates what is already available
> in directives.html.
>
> Unless someone objects, I will commit this.
>
> --
> Joshua Slive
> slive@finance.commerce.ubc.ca
> http://finance.commerce.ubc.ca/~slive/
> Phone: (604) 822-1871
>
> --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
> Name: core-top.html
> core-top.html Type: Hypertext Markup Language (TEXT/html)
> Encoding: BASE64

At 11:31 AM -0400 2000/10/09, Raymond S Brand wrote:
>Its nice but please keep the alphabetical index also.

> Raymond S Brand

>Joshua Slive wrote:



> > Attached is a reorganization of the directives section in core.html. It
>> sorts directives first by purpose, and then alphabetically. This does not
>> match the format of the other modules docs, but core.html is certainly a
> > special case.

I like the new organization, but think the alpha listing is
also worthwhile. How about putting them into core-toc.html and
core-toc-alpha.html or equivalent, then linking to the actual
explanations? I also think it would be nice to have the relevant
stuff connected. Currently, when reading up on things, I do a lot of
cross-referencing across the whole core doc (by far the one I spend
the most time in); it would be nice to have the likely
cross-references in the same document....


Chris Pepper

--
Chris Pepper | Shooting Gallery Interactive | 212 905-2200

On Mon, 9 Oct 2000, Raymond S Brand wrote:

> Its nice but please keep the alphabetical index also.
>

Raymond, don't take this the wrong way, but every contribution that I have
seen you make to this list so far has been a conservative one. Several
times when I have proposed to remove something and replace it with
something better, you have proposed keeping both. This is certainly a
valid opinion, and I appreciate your feedback. However, you should
realize that the end result of doing this will be an ugly, hard to to
maintain, and not very useful set of documents. My experience in clear
and effective writing is that what you remove is probably *more* important
than what you leave in.

I have several objections to leaving in the alphabetical listing:

1. It is superfluous. Anyone looking for a particular directive by name
should be doing so in directives.html which is alphabetical.

2. It will add extra maintenance, and an extra listing which will tend to
get out of sync. I have already been troubled by the dual modules indexes
which have been a pain to maintain over their limited life.

3. It will make the file itself ugly and hard to use. Which should go
first? If the alphabetic index goes first, then "browsers" will never
find the new index. If the new index goes first, then we have lost any
benefit to the alphabetic index, since it will be harder to find and use
then the directives.html file.

Just my opinion, of course. If you have an argument for keeping the
alphabetic index that I have not addressed here, I would be very glad to
here it.

Joshua.

On Mon, 9 Oct 2000, Chris Pepper wrote:

> I like the new organization, but think the alpha listing is
> also worthwhile.

Why? What does it offer that directives.html does not?
(ie. In what circumstances would someone have to spend a non-trivial
amount of extra time searching for something because the alpha listing
was removed?)

> How about putting them into core-toc.html and
> core-toc-alpha.html or equivalent, then linking to the actual
> explanations?

Not a bad idea. core.html is big enough that breaking it up could be
okay. However, I still don't see the benefit to all this. The costs
I have outlined in my previous email.

> I also think it would be nice to have the relevant
> stuff connected. Currently, when reading up on things, I do a lot of
> cross-referencing across the whole core doc (by far the one I spend
> the most time in); it would be nice to have the likely
> cross-references in the same document....

Hmmm... Yes, cross-references are good. Wouldn't it be better to
include these as "See also" listings in the actual directive definitions?
That way, the cross-references would be there no matter how you get
to the directives. Could you give some examples of what type of
cross-references you are thinking about?

By the way, welcome to the list, and thanks for your feedback.

Joshua.

At 8:59 AM -0700 2000/10/09, Joshua Slive wrote:
>On Mon, 9 Oct 2000, Chris Pepper wrote:
>
>> I like the new organization, but think the alpha listing is
>> also worthwhile.
>
>Why? What does it offer that directives.html does not?
>(ie. In what circumstances would someone have to spend a non-trivial
>amount of extra time searching for something because the alpha listing
>was removed?)

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? :) ).

I think the Modules listings are better -- from the main doc
page, change:

>* Run-time configuration directives
>* Modules: By Type or Alphabetical

to

>* Run-time configuration directives: By Type or Alphabetical
>* Modules: By Type or Alphabetical

and put a similar prefatory para in both versions linking to
the others, as in the Modules docco.

> > How about putting them into core-toc.html and
>> core-toc-alpha.html or equivalent, then linking to the actual
>> explanations?
>
>Not a bad idea. core.html is big enough that breaking it up could be
>okay. However, I still don't see the benefit to all this. The costs
>I have outlined in my previous email.

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.

> > I also think it would be nice to have the relevant
>> stuff connected. Currently, when reading up on things, I do a lot of
>> cross-referencing across the whole core doc (by far the one I spend
>> the most time in); it would be nice to have the likely
>> cross-references in the same document....
>
>Hmmm... Yes, cross-references are good. Wouldn't it be better to
>include these as "See also" listings in the actual directive definitions?
>That way, the cross-references would be there no matter how you get
>to the directives. Could you give some examples of what type of
>cross-references you are thinking about?

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.

>By the way, welcome to the list, and thanks for your feedback.
>
>Joshua.

Thanks. Apache is great, but you all already knew that.


Chris
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....

--
Chris Pepper | Shooting Gallery Interactive | 212 905-2200

(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.