Re: [PATCH 1/3] Alphabetize the glossary.

[Junio C Hamano <junkio@cox.net>]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> The idea of having it not alphabetized, but doing it by a script, was to 
> let people actually _read_ it. There is nothing more annoying than having 
> to jump forward and backward and eventually be lost.
>
> glossary, as I started it, was topologically ordered: no Git term was used 
> before it was described (at least that was the plan).

I myself rarely read either man nor html formatted ones.  When I
need to find something, I go straight to Documentation/
directory looking for *.txt files.  Being able to find things
from an alphabetized list is very handy.

On the other hand, we would want to make it easy for people to
read it in the logical order.  For that purpose, html formatted
version, thanks to the cross references the script creates, is a
lot easier than the plain text version.

Maybe we should do both.  We _could_ teach the sort script to
also do an topological sort, and have two sections in the
resulting formatted documentation, the top part being
"alphabetical", and the second part being "bedtime reading".

A random sort that is merely topologically correct probably is
not what we want, so it might make sense to have a hint that
instructs "these should come first before those although they
are topologically independent" to the sort script.  Of course
that "hint" could be the order entries appear in the source text
(which was what you had originally), but when somebody wants to
add a new entry to the glossary, it makes unambiguous where the
new entry should go if the source text is already sorted, which
I am hoping would make it somewhat easier to maintain.