Re: [PATCH v3 1/1] Documentation/ToolsForGit.txt: Tools for developing Git

[Junio C Hamano <gitster@pobox.com>]

COGONI Guillaume <cogoni.guillaume@gmail.com> writes:

> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index b20b2f94f1..509cd89aa2 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -492,17 +492,6 @@ For Perl programs:
>  
>   - Learn and use Git.pm if you need that functionality.
>  
> - - For Emacs, it's useful to put the following in
> -   GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:
> -
> -    ;; note the first part is useful for C editing, too
> -    ((nil . ((indent-tabs-mode . t)
> -                  (tab-width . 8)
> -                  (fill-column . 80)))
> -     (cperl-mode . ((cperl-indent-level . 8)
> -                    (cperl-extra-newline-before-brace . nil)
> -                    (cperl-merge-trailing-else . t))))
> -

Moving this out is OK as long as it is clear to readers of this
document that they can refer to the other one for tool specific
tips.

>   - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).
> @@ -733,3 +722,10 @@ Writing Documentation:
>   inline substituted text+ instead of `monospaced literal text`, and with
>   the former, the part that should not get substituted must be
>   quoted/escaped.
> +
> +
> +Documentation/ToolsForGit.txt:
> +
> + This document collects tips, scripts, and configuration files to help
> + contributors working with the Git codebase use their favorite tools while
> + following the Git coding style.

This looks strangely out of place.  The preceding "sections" of this
document are 

 - general coding principle
 - specific guidelines for each language.
 - how output should read
 - how error messages should read
 - how configuration variables are named
 - how documentation pages are written

The name of a single document and explanation on what is in it does
not make a good new entry in that existing list.

If we must mention the existence of this document in the guidelines
doc, I have a feeling that a better place might be near the preface
of the second item, e.g.

diff --git c/Documentation/CodingGuidelines w/Documentation/CodingGuidelines
index 509cd89aa2..64ff734ce7 100644
--- c/Documentation/CodingGuidelines
+++ w/Documentation/CodingGuidelines
@@ -43,7 +43,10 @@ the overall style of existing code. Modifications to existing
 code is expected to match the style the surrounding code already
 uses (even if it doesn't match the overall style of existing code).
 
-But if you must have a list of rules, here they are.
+But if you must have a list of rules, here are some language
+specific ones.  Note that Documentation/ToolsForGit document
+has a collection of tips to help you use some external tools
+to conform to these guidelines.
 
 For shell scripts specifically (not exhaustive):