[PATCH 1/2] Rewrite man page explanation of git log's "--log-size" option

[PATCH 1/2] Rewrite man page explanation of git log's "--log-size" option

[Jason St. John]

Documentation/git-log.txt:
--log-size was added in commit 9fa3465, and the commit message contained
a satisfactory explanation; however, the man page entry for it was
unclear and cryptic.

Thanks-to: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Jason St. John <jstjohn@purdue.edu>
---
This is effectively a resubmit of my previous patch here:
http://marc.info/?l=git&m=138395803808196&w=2

Thanks to Jonathan Nieder for writing the text used in this commit:
http://marc.info/?l=git&m=138395887208373&w=2


 Documentation/git-log.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 34097ef..a5de513 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -56,11 +56,11 @@ Note that this affects all diff-based output types, e.g. those
 produced by --stat etc.
 
 --log-size::
-	Before the log message print out its size in bytes. Intended
-	mainly for porcelain tools consumption. If Git is unable to
-	produce a valid value size is set to zero.
-	Note that only message is considered, if also a diff is shown
-	its size is not included.
+
+	Include a line ``log size <number>'' in the output for each commit,
+	where <number> is the length of that commit's message in bytes.
+	Intended to speed up tools that read log messages from `git log`
+	output by allowing them to allocate space in advance.
 
 -L <start>,<end>:<file>::
 -L :<regex>:<file>::
-- 
1.8.4.2

[PATCH 2/2] Fix minor grammatical and other formatting issues in the "git log" man page

[Jason St. John]

Documentation/git-log.txt:
-- replace single quotes around options/commands with backticks
-- use single quotes around references to sections
-- replaced some double quotes with proper AsciiDoc quotes (e.g.
     ``foo'')
-- use backticks around files and file paths
-- use title case when referring to section headings
-- use backticks around option arguments/defaults

Signed-off-by: Jason St. John <jstjohn@purdue.edu>
---
When working on this commit, I noticed a difference in how options and
option descriptions are separated (e.g. with a blank line or not). At least
with Vim's syntax highlighting, if there is a blank line between the option
and its description, the text block is all colored the same; however, if
there isn't a blank line, then the text block is not specially colored.

Is there an existing convention for how this should be done?


 Documentation/git-log.txt | 43 +++++++++++++++++++++----------------------
 1 file changed, 21 insertions(+), 22 deletions(-)

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index a5de513..1f7bc67 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -15,9 +15,9 @@ DESCRIPTION
 -----------
 Shows the commit logs.
 
-The command takes options applicable to the 'git rev-list'
+The command takes options applicable to the `git rev-list`
 command to control what is shown and how, and options applicable to
-the 'git diff-*' commands to control how the changes
+the `git diff-*` commands to control how the changes
 each commit introduces are shown.
 
 
@@ -42,21 +42,20 @@ OPTIONS
 
 --use-mailmap::
 	Use mailmap file to map author and committer names and email
-	to canonical real names and email addresses. See
+	addresses to canonical real names and email addresses. See
 	linkgit:git-shortlog[1].
 
 --full-diff::
-	Without this flag, "git log -p <path>..." shows commits that
+	Without this flag, `git log -p <path>...` shows commits that
 	touch the specified paths, and diffs about the same specified
 	paths.  With this, the full diff is shown for commits that touch
 	the specified paths; this means that "<path>..." limits only
 	commits, and doesn't limit diff for those commits.
 +
 Note that this affects all diff-based output types, e.g. those
-produced by --stat etc.
+produced by `--stat`, etc.
 
 --log-size::
-
 	Include a line ``log size <number>'' in the output for each commit,
 	where <number> is the length of that commit's message in bytes.
 	Intended to speed up tools that read log messages from `git log`
@@ -64,7 +63,6 @@ produced by --stat etc.
 
 -L <start>,<end>:<file>::
 -L :<regex>:<file>::
-
 	Trace the evolution of the line range given by "<start>,<end>"
 	(or the funcname regex <regex>) within the <file>.  You may
 	not give any pathspec limiters.  This is currently limited to
@@ -80,16 +78,16 @@ include::line-range-format.txt[]
 	whole history leading to the current commit).  `origin..HEAD`
 	specifies all the commits reachable from the current commit
 	(i.e. `HEAD`), but not from `origin`. For a complete list of
-	ways to spell <revision range>, see the "Specifying Ranges"
+	ways to spell <revision range>, see the 'Specifying Ranges'
 	section of linkgit:gitrevisions[7].
 
 [\--] <path>...::
 	Show only commits that are enough to explain how the files
-	that match the specified paths came to be.  See "History
-	Simplification" below for details and other simplification
+	that match the specified paths came to be.  See 'History
+	Simplification' below for details and other simplification
 	modes.
 +
-Paths may need to be prefixed with "\-- " to separate them from
+Paths may need to be prefixed with ``\-- '' to separate them from
 options or the revision range, when confusion arises.
 
 include::rev-list-options.txt[]
@@ -113,12 +111,12 @@ EXAMPLES
 `git log v2.6.12.. include/scsi drivers/scsi`::
 
 	Show all commits since version 'v2.6.12' that changed any file
-	in the include/scsi or drivers/scsi subdirectories
+	in the `include/scsi` or `drivers/scsi` subdirectories
 
 `git log --since="2 weeks ago" -- gitk`::
 
 	Show the changes during the last two weeks to the file 'gitk'.
-	The "--" is necessary to avoid confusion with the *branch* named
+	The ``--'' is necessary to avoid confusion with the *branch* named
 	'gitk'
 
 `git log --name-status release..test`::
@@ -129,7 +127,7 @@ EXAMPLES
 
 `git log --follow builtin/rev-list.c`::
 
-	Shows the commits that changed builtin/rev-list.c, including
+	Shows the commits that changed `builtin/rev-list.c`, including
 	those commits that occurred before the file was given its
 	present name.
 
@@ -147,17 +145,18 @@ EXAMPLES
 `git log -p -m --first-parent`::
 
 	Shows the history including change diffs, but only from the
-	"main branch" perspective, skipping commits that come from merged
+	``main branch'' perspective, skipping commits that come from merged
 	branches, and showing full diffs of changes introduced by the merges.
 	This makes sense only when following a strict policy of merging all
 	topic branches when staying on a single integration branch.
 
 `git log -L '/int main/',/^}/:main.c`::
 
-	Shows how the function `main()` in the file 'main.c' evolved
+	Shows how the function `main()` in the file `main.c` evolved
 	over time.
 
 `git log -3`::
+
 	Limits the number of commits to show to 3.
 
 DISCUSSION
@@ -172,12 +171,12 @@ See linkgit:git-config[1] for core variables and linkgit:git-diff[1]
 for settings related to diff generation.
 
 format.pretty::
-	Default for the `--format` option.  (See "PRETTY FORMATS" above.)
-	Defaults to "medium".
+	Default for the `--format` option.  (See 'Pretty Formats' above.)
+	Defaults to `medium`.
 
 i18n.logOutputEncoding::
-	Encoding to use when displaying logs.  (See "Discussion", above.)
-	Defaults to the value of `i18n.commitEncoding` if set, UTF-8
+	Encoding to use when displaying logs.  (See 'Discussion' above.)
+	Defaults to the value of `i18n.commitEncoding` if set, and UTF-8
 	otherwise.
 
 log.date::
@@ -186,7 +185,7 @@ log.date::
 	dates like `Sat May 8 19:35:34 2010 -0500`.
 
 log.showroot::
-	If `false`, 'git log' and related commands will not treat the
+	If `false`, `git log` and related commands will not treat the
 	initial commit as a big creation event.  Any root commits in
 	`git log -p` output would be shown without a diff attached.
 	The default is `true`.
@@ -197,7 +196,7 @@ mailmap.*::
 notes.displayRef::
 	Which refs, in addition to the default set by `core.notesRef`
 	or 'GIT_NOTES_REF', to read notes from when showing commit
-	messages with the 'log' family of commands.  See
+	messages with the `log` family of commands.  See
 	linkgit:git-notes[1].
 +
 May be an unabbreviated ref name or a glob and may be specified
-- 
1.8.4.2

Re: [PATCH 2/2] Fix minor grammatical and other formatting issues in the "git log" man page

[Junio C Hamano]

"Jason St. John" <jstjohn@purdue.edu> writes:

> Documentation/git-log.txt:
> -- replace single quotes around options/commands with backticks
> -- use single quotes around references to sections
> -- replaced some double quotes with proper AsciiDoc quotes (e.g.
>      ``foo'')
> -- use backticks around files and file paths
> -- use title case when referring to section headings
> -- use backticks around option arguments/defaults
>
> Signed-off-by: Jason St. John <jstjohn@purdue.edu>
> ---
> When working on this commit, I noticed a difference in how options and
> option descriptions are separated (e.g. with a blank line or not). At least
> with Vim's syntax highlighting, if there is a blank line between the option
> and its description, the text block is all colored the same; however, if
> there isn't a blank line, then the text block is not specially colored.
>
> Is there an existing convention for how this should be done?

I do not think we have a written rule or convention (and I do not
know if we want one).  While reading the text in the source form
(and the point of choosing AsciiDoc was to be able to read the docs
without formatting), I personally have a slight preference to
immediately follow the body text to the label in the labelled list,
and a blank line after the item, i.e.

	item label::
		This describes the item.

	next item label::
		This describes the next item.

as it makes it clear that the body belongs to the heading that
precedes it.

But it does help to have a blank between the label and the beginning
of the body when reflowing the body with fill-paragraph, i.e.

	item label::

		This describes the item.

You say that it is also easier on Vim to have the blank line there,
so perhaps we may want to aim for updating the documentation over
time to consistently do so.  I dunno.

Re: [PATCH 2/2] Fix minor grammatical and other formatting issues in the "git log" man page

[Jason St. John]

On Wed, Nov 13, 2013 at 4:56 PM, Junio C Hamano <gitster@pobox.com> wrote:
> "Jason St. John" <jstjohn@purdue.edu> writes:
>
>> Documentation/git-log.txt:
>> -- replace single quotes around options/commands with backticks
>> -- use single quotes around references to sections
>> -- replaced some double quotes with proper AsciiDoc quotes (e.g.
>>      ``foo'')
>> -- use backticks around files and file paths
>> -- use title case when referring to section headings
>> -- use backticks around option arguments/defaults
>>
>> Signed-off-by: Jason St. John <jstjohn@purdue.edu>
>> ---
>> When working on this commit, I noticed a difference in how options and
>> option descriptions are separated (e.g. with a blank line or not). At least
>> with Vim's syntax highlighting, if there is a blank line between the option
>> and its description, the text block is all colored the same; however, if
>> there isn't a blank line, then the text block is not specially colored.
>>
>> Is there an existing convention for how this should be done?
>
> I do not think we have a written rule or convention (and I do not
> know if we want one).  While reading the text in the source form
> (and the point of choosing AsciiDoc was to be able to read the docs
> without formatting), I personally have a slight preference to
> immediately follow the body text to the label in the labelled list,
> and a blank line after the item, i.e.
>
>         item label::
>                 This describes the item.
>
>         next item label::
>                 This describes the next item.
>
> as it makes it clear that the body belongs to the heading that
> precedes it.
>
> But it does help to have a blank between the label and the beginning
> of the body when reflowing the body with fill-paragraph, i.e.
>
>         item label::
>
>                 This describes the item.
>
> You say that it is also easier on Vim to have the blank line there,
> so perhaps we may want to aim for updating the documentation over
> time to consistently do so.  I dunno.
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

As I stated in my recent resubmit[1], I decided to remove the blank
lines after option subheadings because the syntax highlighting in Vim
actually looks better with the blank lines removed. As such, I would
prefer that we go with the option of removing these blank lines going
forward.

If we are in agreement on this, should I send in a patch for
CodingGuidelines to state this?

[1] http://marc.info/?l=git&m=138447927208462&w=2

Re: [PATCH 2/2] Fix minor grammatical and other formatting issues in the "git log" man page

[Jason St. John]

On Thu, Nov 14, 2013 at 8:44 PM, Jason St. John <jstjohn@purdue.edu> wrote:
> On Wed, Nov 13, 2013 at 4:56 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> "Jason St. John" <jstjohn@purdue.edu> writes:
>>
>>> Documentation/git-log.txt:
>>> -- replace single quotes around options/commands with backticks
>>> -- use single quotes around references to sections
>>> -- replaced some double quotes with proper AsciiDoc quotes (e.g.
>>>      ``foo'')
>>> -- use backticks around files and file paths
>>> -- use title case when referring to section headings
>>> -- use backticks around option arguments/defaults
>>>
>>> Signed-off-by: Jason St. John <jstjohn@purdue.edu>
>>> ---
>>> When working on this commit, I noticed a difference in how options and
>>> option descriptions are separated (e.g. with a blank line or not). At least
>>> with Vim's syntax highlighting, if there is a blank line between the option
>>> and its description, the text block is all colored the same; however, if
>>> there isn't a blank line, then the text block is not specially colored.
>>>
>>> Is there an existing convention for how this should be done?
>>
>> I do not think we have a written rule or convention (and I do not
>> know if we want one).  While reading the text in the source form
>> (and the point of choosing AsciiDoc was to be able to read the docs
>> without formatting), I personally have a slight preference to
>> immediately follow the body text to the label in the labelled list,
>> and a blank line after the item, i.e.
>>
>>         item label::
>>                 This describes the item.
>>
>>         next item label::
>>                 This describes the next item.
>>
>> as it makes it clear that the body belongs to the heading that
>> precedes it.
>>
>> But it does help to have a blank between the label and the beginning
>> of the body when reflowing the body with fill-paragraph, i.e.
>>
>>         item label::
>>
>>                 This describes the item.
>>
>> You say that it is also easier on Vim to have the blank line there,
>> so perhaps we may want to aim for updating the documentation over
>> time to consistently do so.  I dunno.
>> --
>> To unsubscribe from this list: send the line "unsubscribe git" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>
> As I stated in my recent resubmit[1], I decided to remove the blank
> lines after option subheadings because the syntax highlighting in Vim
> actually looks better with the blank lines removed. As such, I would
> prefer that we go with the option of removing these blank lines going
> forward.
>
> If we are in agreement on this, should I send in a patch for
> CodingGuidelines to state this?
>
> [1] http://marc.info/?l=git&m=138447927208462&w=2

I forgot to mention that if we do go with this, then I will need to
resubmit this patch.

Sorry for the extra email.