Commit 42e0fae9 authored by Marc Branchaud's avatar Marc Branchaud Committed by Junio C Hamano

Provide some linguistic guidance for the documentation.

This will hopefully avoid questions over which spelling and grammar should
be used.  Translators are of course free to create localizations for
specific English dialects.
Signed-off-by: default avatarMarc Branchaud <[email protected]>
Signed-off-by: default avatarJunio C Hamano <[email protected]>
parent 8dc84fdc
......@@ -242,6 +242,14 @@ Writing Documentation:
processed into HTML and manpages (e.g. git.html and git.1 in the
same directory).
The documentation liberally mixes US and UK English (en_US/UK)
norms for spelling and grammar, which is somewhat unfortunate.
In an ideal world, it would have been better if it consistently
used only one and not the other, and we would have picked en_US
(if you wish to correct the English of some of the existing
documentation, please see the documentation-related advice in the
Documentation/SubmittingPatches file).
Every user-visible change should be reflected in the documentation.
The same general rule as for code applies -- imitate the existing
conventions. A few commented examples follow to provide reference
......@@ -65,7 +65,20 @@ feature does not trigger when it shouldn't. Also make sure that the
test suite passes after your commit. Do not forget to update the
documentation to describe the updated behaviour.
Oh, another thing. I am picky about whitespaces. Make sure your
Speaking of the documentation, it is currently a liberal mixture of US
and UK English norms for spelling and grammar, which is somewhat
unfortunate. A huge patch that touches the files all over the place
only to correct the inconsistency is not welcome, though. Potential
clashes with other changes that can result from such a patch are not
worth it. We prefer to gradually reconcile the inconsistencies in
favor of US English, with small and easily digestible patches, as a
side effect of doing some other real work in the vicinity (e.g.
rewriting a paragraph for clarity, while turning en_UK spelling to
en_US). Obvious typographical fixes are much more welcomed ("teh ->
"the"), preferably submitted as independent patches separate from
other documentation changes.
Oh, another thing. We are picky about whitespaces. Make sure your
changes do not trigger errors with the sample pre-commit hook shipped
in templates/hooks--pre-commit. To help ensure this does not happen,
run git diff --check on your changes before you commit.
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment