Angelo Borsotti [off-list ref] writes:
Why it is so difficult to convince people to make documentation better?
It is not difficult. The discussion on this list is usually done
via patches, and without one, constant talking is buried in other
noise and often go unnoticed.
There is however an issue about documentation consistency. Do we
use elsewhere ( A | B | C ... ) to denote "You must write one (and
only one) among A, B, C, ..." consistently in the documentation?
An ancient discussion $gmane/72243 might be of interest to kickstart
such a documentation clean-up effort.
Hi Junio
It is not difficult. The discussion on this list is usually done
via patches, and without one, constant talking is buried in other
noise and often go unnoticed.
Could you accept for very small changes also the simple indication of
the change itself instead of a patch?
There is however an issue about documentation consistency. Do we
use elsewhere ( A | B | C ... ) to denote "You must write one (and
only one) among A, B, C, ..." consistently in the documentation?
There is no standard for it. Posix provides a standard for commands:
http://pubs.opengroup.org/onlinepubs/9699919799/
but does not mention (normal) parentheses to indicate choice.
There is one applicable standard for this, though, the ISO 14977:
http://www.cl.cam.ac.uk/~mgk25/iso-14977.pdf
which gives parentheses "()" the meaning of grouping (and then with "|"
inside them, the meaning of choice).
Parentheses are used in:
- git branch
- git commit
- git reset
- git remote
- git submodule
- git bisect
- git grep
- git am
- git apply
- git format-patch
- git cat-file
- git commit-tree
- git rev-list
- git update-index
I did not find in the documentation an explanation of the use of
parentheses, but
to me they seem to have been used consistently.
-Angelo