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

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

[Dale R. Worley]

>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

Signed-off-by: Dale R. Worley <worley@ariadne.com>
---
While learning about making a documentation patch, I noticed that
Documentation/CodingGuideles isn't as clear as it could be regarding
how to edit the documentation.  In particular, it says "Most (if not
all) of the documentation pages are written in AsciiDoc - and
processed into HTML output and manpages." without really specifying
the details for those of us who aren't familiar with AsciiDoc.  So I
added a sentence stating explicitly which files are the sources and
which are derived.

It's also a test for submitting a patch.  I've read SubmittingPatches
again, more carefully, and have corrected some problem with my
previous message.

 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.
 
  Every user-visible change should be reflected in the documentation.
  The same general rule as for code applies -- imitate the existing
-- 
1.7.7.6

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

[Junio C Hamano]

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

> 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.

>  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

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

[Dale R. Worley]

> From: Junio C Hamano <gitster@pobox.com>
> 
> > 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.

I was thinking that that was the intention.  But SubmittingPatches
makes it sound like the *entire* output of "git format-patch" is
intended to be the *body* of the e-mail message:

    "git format-patch" command follows the best current practice to
    format the body of an e-mail message.  At the beginning of the
    patch should come your commit message, ending with the
    Signed-off-by: lines, and a line that consists of three dashes,
    followed by the diffstat information and the patch itself.  If
    you are forwarding a patch from somebody else, optionally, at
    the beginning of the e-mail message just before the commit
    message starts, you can put a "From: " line to name that person.

In particular, while the line "From e87227..." appears to be the
typical Unix mailbox start-of-message line, it wasn't clear to me
whether it was supposed to be sent or not:  If I do the obvious
cut-and-paste of the "From:", "Date:", and "Subject:" lines into the
headers of the e-mail message and copy the following lines into the
body, the "From e87227..." line will have no place to go.  And perhaps
it is an important part of the patch, since "git format-patch" outputs
it?

If you could give me some guidance in regard to the "From e87227..."
line, that would be helpful.  (I suppose I should try to improve that
paragraph of SubmittingPatches to prevent anyone else from having the
same misunderstanding.)

> > 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.

Now that you mention it, I see the mistake I have made.  I had
forgotten that I did a build of Git from that working copy, and so the
*.html and *.1 files might be generated files rather than tracked
files.  And I hadn't yet learned that "git ls-files git-submodule.*"
would do about the same thing that "svn status git-submodule.*" does,
that is, tell the natures of the various files that are present.

> >  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.

That's true.  But it also appears to be a less risky approach to
someone who is editing the text and does not know its history.

>     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

Thank you for your help.  I will revise my patch (and learning
exercise) and resubmit it.

Dale

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

[Junio C Hamano]

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

> body, the "From e87227..." line will have no place to go.  And perhaps
> it is an important part of the patch, since "git format-patch" outputs
> it?

As you noticed (correctly), the output of "format-patch" is meant to
be usable by "am" that reads from the UNIX mbox format.  "From whom"
(not "From: whom") lines are traditional message boundaries, and
when you are sending your own patch, none of the RFC822 headers (nor
the "From whom" line) needs to be repeated in the message body.

Thanks.