Re: [PATCHv2] CodingGuidelines: make it clear which files in Documentation/ are the sources

From: Junio C Hamano <gitster@pobox.com>
Date: May 8, 2013, 20:38 UTC
Message-ID: <7vy5bpdx64.fsf@alter.siamese.dyndns.org>
In-Reply-To: <201305082024.r48KOH55003964@freeze.ariadne.com>

worley@alum.mit.edu (Dale R. Worley) writes:

Show 5 quoted lines

> From e87227498ef3d50dc20584c24c53071cce63c555 Mon Sep 17 00:00:00 2001
> From: Dale Worley <worley@ariadne.com>
> Date: Tue, 7 May 2013 13:39:46 -0400
> Subject: [PATCH] CodingGuidelines:  make it clear which files in
>  Documentation/ are the sources

These five lines are present in the output of the format-patch only to help you fill in the MUA's mail header (instead of typing the subject, you can cut and paste from here, for example); after you are done with the MUA headers, remove them and do not leave them in the body of the message.

>
> Signed-off-by: Dale R. Worley <worley@ariadne.com>

The title looks a bit too long. For a small and obviously correct patch like this, I do not think you would need anything in the log message, some of what you wrote below the three-dash line may deserve to be said here. Perhaps:

    Subject: [PATCH] CodingGuidelines: Documentation/*.txt are the sources

    People not familiar with AsciiDoc may not realize they are
    supposed to update *.txt files and not *.html/*.1 files when
    preparing patches to the project.

But it invites a question. Why do people patching Git not to know *.txt are the sources in the first place? Generated *.html files are not even tracked.

Show 15 quoted lines

>  Documentation/CodingGuidelines |    4 +++-
>  1 files changed, 3 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index 7e4d571..b8eef7c 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -238,7 +238,9 @@ For Python scripts:
>  Writing Documentation:
>  
>   Most (if not all) of the documentation pages are written in AsciiDoc
> - and processed into HTML output and manpages.
> + and processed into HTML output and manpages.  This means that the *.txt
> + files in this directory are usually the sources from which the
> + corresponding *.html, *.1, and *.xml files are generated.

Whenever you see somebody writing "This means that" or "In other words", it is a good habit to ask if the existing text can be improved so that it does not need such a follow-up clarification.

    Most (if not all) of the documentation pages are written in the
    AsciiDoc format in *.txt files (e.g. Documentation/git.txt), and
    processed into HTML and manpages (e.g. git.html and git.1 in the
    same directory).

>  
>   Every user-visible change should be reflected in the documentation.
>   The same general rule as for code applies -- imitate the existing