Johannes Schindelin <Johannes.Schindelin@xxxxxx> 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. - : send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html