Re-order dir-spec for readability and maintainability
I'd like to reorder a few things in dir-spec to make it easier to read and easier to extend.
I finished a first revision in my branch reorder-dirspec.
Here are the guidelines that I tried to follow:
There's supposed to be one section per role in the directory protocol (client, authority, cache, client) with one subsection per operation performed by this role. If necessary, subsubsections help structure more complex operations.
Changes are ordered from the top of the document to the bottom. There's typically one commit (or commit set) for every changed section or subsection.
For every change that moves more than a few lines of text, there are typically three commits: the first commit only moves text, the second commit only fixes references, and the third commit edits content.