{"thread":{"id":"35329","subject":"[PATCH 1/2] Rewrite man page explanation of git log's \"--log-size\" option","startedAt":"2013-11-13T06:21:48Z","lastAt":"2013-11-15T01:47:27Z","messageCount":5,"participants":["Jason St. John","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"230551","messageId":"1384323709-2690-1-git-send-email-jstjohn@purdue.edu","threadId":"35329","inReplyTo":null,"subject":"[PATCH 1/2] Rewrite man page explanation of git log's \"--log-size\" option","fromName":"Jason St. John","fromEmail":"jstjohn@purdue.edu","sentAt":"2013-11-13T06:21:48Z","receivedAt":"2013-11-13T06:21:48Z","isPatch":true,"sender":{"key":"jstjohn@purdue.edu","avatar":"https://avatars.githubusercontent.com/u/1393510?v=4"},"body":"Documentation/git-log.txt:\n--log-size was added in commit 9fa3465, and the commit message contained\na satisfactory explanation; however, the man page entry for it was\nunclear and cryptic.\n\nThanks-to: Jonathan Nieder \nSigned-off-by: Jason St. John \n---\nThis is effectively a resubmit of my previous patch here:\nhttp://marc.info/?l=git&m=138395803808196&w=2\n\nThanks to Jonathan Nieder for writing the text used in this commit:\nhttp://marc.info/?l=git&m=138395887208373&w=2\n\n\n Documentation/git-log.txt | 10 +++++-----\n 1 file changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 34097ef..a5de513 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -56,11 +56,11 @@ Note that this affects all diff-based output types, e.g. those\n produced by --stat etc.\n \n --log-size::\n-\tBefore the log message print out its size in bytes. Intended\n-\tmainly for porcelain tools consumption. If Git is unable to\n-\tproduce a valid value size is set to zero.\n-\tNote that only message is considered, if also a diff is shown\n-\tits size is not included.\n+\n+\tInclude a line ``log size '' in the output for each commit,\n+\twhere is the length of that commit's message in bytes.\n+\tIntended to speed up tools that read log messages from `git log`\n+\toutput by allowing them to allocate space in advance.\n \n -L ,:::\n -L ::::\n-- \n1.8.4.2\n"},{"id":"230552","messageId":"1384323709-2690-2-git-send-email-jstjohn@purdue.edu","threadId":"35329","inReplyTo":"1384323709-2690-1-git-send-email-jstjohn@purdue.edu","subject":"[PATCH 2/2] Fix minor grammatical and other formatting issues in the \"git log\" man page","fromName":"Jason St. John","fromEmail":"jstjohn@purdue.edu","sentAt":"2013-11-13T06:21:49Z","receivedAt":"2013-11-13T06:21:49Z","isPatch":true,"sender":{"key":"jstjohn@purdue.edu","avatar":"https://avatars.githubusercontent.com/u/1393510?v=4"},"body":"Documentation/git-log.txt:\n-- replace single quotes around options/commands with backticks\n-- use single quotes around references to sections\n-- replaced some double quotes with proper AsciiDoc quotes (e.g.\n ``foo'')\n-- use backticks around files and file paths\n-- use title case when referring to section headings\n-- use backticks around option arguments/defaults\n\nSigned-off-by: Jason St. John \n---\nWhen working on this commit, I noticed a difference in how options and\noption descriptions are separated (e.g. with a blank line or not). At least\nwith Vim's syntax highlighting, if there is a blank line between the option\nand its description, the text block is all colored the same; however, if\nthere isn't a blank line, then the text block is not specially colored.\n\nIs there an existing convention for how this should be done?\n\n\n Documentation/git-log.txt | 43 +++++++++++++++++++++----------------------\n 1 file changed, 21 insertions(+), 22 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex a5de513..1f7bc67 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -15,9 +15,9 @@ DESCRIPTION\n -----------\n Shows the commit logs.\n \n-The command takes options applicable to the 'git rev-list'\n+The command takes options applicable to the `git rev-list`\n command to control what is shown and how, and options applicable to\n-the 'git diff-*' commands to control how the changes\n+the `git diff-*` commands to control how the changes\n each commit introduces are shown.\n \n \n@@ -42,21 +42,20 @@ OPTIONS\n \n --use-mailmap::\n \tUse mailmap file to map author and committer names and email\n-\tto canonical real names and email addresses. See\n+\taddresses to canonical real names and email addresses. See\n \tlinkgit:git-shortlog[1].\n \n --full-diff::\n-\tWithout this flag, \"git log -p ...\" shows commits that\n+\tWithout this flag, `git log -p ...` shows commits that\n \ttouch the specified paths, and diffs about the same specified\n \tpaths. With this, the full diff is shown for commits that touch\n \tthe specified paths; this means that \"...\" limits only\n \tcommits, and doesn't limit diff for those commits.\n +\n Note that this affects all diff-based output types, e.g. those\n-produced by --stat etc.\n+produced by `--stat`, etc.\n \n --log-size::\n-\n \tInclude a line ``log size '' in the output for each commit,\n \twhere is the length of that commit's message in bytes.\n \tIntended to speed up tools that read log messages from `git log`\n@@ -64,7 +63,6 @@ produced by --stat etc.\n \n -L ,:::\n -L ::::\n-\n \tTrace the evolution of the line range given by \",\"\n \t(or the funcname regex ) within the . You may\n \tnot give any pathspec limiters. This is currently limited to\n@@ -80,16 +78,16 @@ include::line-range-format.txt[]\n \twhole history leading to the current commit). `origin..HEAD`\n \tspecifies all the commits reachable from the current commit\n \t(i.e. `HEAD`), but not from `origin`. For a complete list of\n-\tways to spell , see the \"Specifying Ranges\"\n+\tways to spell , see the 'Specifying Ranges'\n \tsection of linkgit:gitrevisions[7].\n \n [\\--] ...::\n \tShow only commits that are enough to explain how the files\n-\tthat match the specified paths came to be. See \"History\n-\tSimplification\" below for details and other simplification\n+\tthat match the specified paths came to be. See 'History\n+\tSimplification' below for details and other simplification\n \tmodes.\n +\n-Paths may need to be prefixed with \"\\-- \" to separate them from\n+Paths may need to be prefixed with ``\\-- '' to separate them from\n options or the revision range, when confusion arises.\n \n include::rev-list-options.txt[]\n@@ -113,12 +111,12 @@ EXAMPLES\n `git log v2.6.12.. include/scsi drivers/scsi`::\n \n \tShow all commits since version 'v2.6.12' that changed any file\n-\tin the include/scsi or drivers/scsi subdirectories\n+\tin the `include/scsi` or `drivers/scsi` subdirectories\n \n `git log --since=\"2 weeks ago\" -- gitk`::\n \n \tShow the changes during the last two weeks to the file 'gitk'.\n-\tThe \"--\" is necessary to avoid confusion with the *branch* named\n+\tThe ``--'' is necessary to avoid confusion with the *branch* named\n \t'gitk'\n \n `git log --name-status release..test`::\n@@ -129,7 +127,7 @@ EXAMPLES\n \n `git log --follow builtin/rev-list.c`::\n \n-\tShows the commits that changed builtin/rev-list.c, including\n+\tShows the commits that changed `builtin/rev-list.c`, including\n \tthose commits that occurred before the file was given its\n \tpresent name.\n \n@@ -147,17 +145,18 @@ EXAMPLES\n `git log -p -m --first-parent`::\n \n \tShows the history including change diffs, but only from the\n-\t\"main branch\" perspective, skipping commits that come from merged\n+\t``main branch'' perspective, skipping commits that come from merged\n \tbranches, and showing full diffs of changes introduced by the merges.\n \tThis makes sense only when following a strict policy of merging all\n \ttopic branches when staying on a single integration branch.\n \n `git log -L '/int main/',/^}/:main.c`::\n \n-\tShows how the function `main()` in the file 'main.c' evolved\n+\tShows how the function `main()` in the file `main.c` evolved\n \tover time.\n \n `git log -3`::\n+\n \tLimits the number of commits to show to 3.\n \n DISCUSSION\n@@ -172,12 +171,12 @@ See linkgit:git-config[1] for core variables and linkgit:git-diff[1]\n for settings related to diff generation.\n \n format.pretty::\n-\tDefault for the `--format` option. (See \"PRETTY FORMATS\" above.)\n-\tDefaults to \"medium\".\n+\tDefault for the `--format` option. (See 'Pretty Formats' above.)\n+\tDefaults to `medium`.\n \n i18n.logOutputEncoding::\n-\tEncoding to use when displaying logs. (See \"Discussion\", above.)\n-\tDefaults to the value of `i18n.commitEncoding` if set, UTF-8\n+\tEncoding to use when displaying logs. (See 'Discussion' above.)\n+\tDefaults to the value of `i18n.commitEncoding` if set, and UTF-8\n \totherwise.\n \n log.date::\n@@ -186,7 +185,7 @@ log.date::\n \tdates like `Sat May 8 19:35:34 2010 -0500`.\n \n log.showroot::\n-\tIf `false`, 'git log' and related commands will not treat the\n+\tIf `false`, `git log` and related commands will not treat the\n \tinitial commit as a big creation event. Any root commits in\n \t`git log -p` output would be shown without a diff attached.\n \tThe default is `true`.\n@@ -197,7 +196,7 @@ mailmap.*::\n notes.displayRef::\n \tWhich refs, in addition to the default set by `core.notesRef`\n \tor 'GIT_NOTES_REF', to read notes from when showing commit\n-\tmessages with the 'log' family of commands. See\n+\tmessages with the `log` family of commands. See\n \tlinkgit:git-notes[1].\n +\n May be an unabbreviated ref name or a glob and may be specified\n-- \n1.8.4.2\n"},{"id":"230577","messageId":"xmqqy54sc6ev.fsf@gitster.dls.corp.google.com","threadId":"35329","inReplyTo":"1384323709-2690-2-git-send-email-jstjohn@purdue.edu","subject":"Re: [PATCH 2/2] Fix minor grammatical and other formatting issues in the \"git log\" man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-11-13T21:56:24Z","receivedAt":"2013-11-13T21:56:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jason St. John\" writes:\n\n> Documentation/git-log.txt:\n> -- replace single quotes around options/commands with backticks\n> -- use single quotes around references to sections\n> -- replaced some double quotes with proper AsciiDoc quotes (e.g.\n> ``foo'')\n> -- use backticks around files and file paths\n> -- use title case when referring to section headings\n> -- use backticks around option arguments/defaults\n>\n> Signed-off-by: Jason St. John \n> ---\n> When working on this commit, I noticed a difference in how options and\n> option descriptions are separated (e.g. with a blank line or not). At least\n> with Vim's syntax highlighting, if there is a blank line between the option\n> and its description, the text block is all colored the same; however, if\n> there isn't a blank line, then the text block is not specially colored.\n>\n> Is there an existing convention for how this should be done?\n\nI do not think we have a written rule or convention (and I do not\nknow if we want one). While reading the text in the source form\n(and the point of choosing AsciiDoc was to be able to read the docs\nwithout formatting), I personally have a slight preference to\nimmediately follow the body text to the label in the labelled list,\nand a blank line after the item, i.e.\n\n\titem label::\n\t\tThis describes the item.\n\n\tnext item label::\n\t\tThis describes the next item.\n\nas it makes it clear that the body belongs to the heading that\nprecedes it.\n\nBut it does help to have a blank between the label and the beginning\nof the body when reflowing the body with fill-paragraph, i.e.\n\n\titem label::\n\n\t\tThis describes the item.\n\nYou say that it is also easier on Vim to have the blank line there,\nso perhaps we may want to aim for updating the documentation over\ntime to consistently do so. I dunno.\n"},{"id":"230659","messageId":"CAEjxke8vLtA5CgW8v4zv58kexe631koniNpdqTrr8LFYAOrMuA@mail.gmail.com","threadId":"35329","inReplyTo":"xmqqy54sc6ev.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 2/2] Fix minor grammatical and other formatting issues in the \"git log\" man page","fromName":"Jason St. John","fromEmail":"jstjohn@purdue.edu","sentAt":"2013-11-15T01:44:22Z","receivedAt":"2013-11-15T01:44:22Z","isPatch":true,"sender":{"key":"jstjohn@purdue.edu","avatar":"https://avatars.githubusercontent.com/u/1393510?v=4"},"body":"On Wed, Nov 13, 2013 at 4:56 PM, Junio C Hamano wrote:\n> \"Jason St. John\" writes:\n>\n>> Documentation/git-log.txt:\n>> -- replace single quotes around options/commands with backticks\n>> -- use single quotes around references to sections\n>> -- replaced some double quotes with proper AsciiDoc quotes (e.g.\n>> ``foo'')\n>> -- use backticks around files and file paths\n>> -- use title case when referring to section headings\n>> -- use backticks around option arguments/defaults\n>>\n>> Signed-off-by: Jason St. John \n>> ---\n>> When working on this commit, I noticed a difference in how options and\n>> option descriptions are separated (e.g. with a blank line or not). At least\n>> with Vim's syntax highlighting, if there is a blank line between the option\n>> and its description, the text block is all colored the same; however, if\n>> there isn't a blank line, then the text block is not specially colored.\n>>\n>> Is there an existing convention for how this should be done?\n>\n> I do not think we have a written rule or convention (and I do not\n> know if we want one). While reading the text in the source form\n> (and the point of choosing AsciiDoc was to be able to read the docs\n> without formatting), I personally have a slight preference to\n> immediately follow the body text to the label in the labelled list,\n> and a blank line after the item, i.e.\n>\n> item label::\n> This describes the item.\n>\n> next item label::\n> This describes the next item.\n>\n> as it makes it clear that the body belongs to the heading that\n> precedes it.\n>\n> But it does help to have a blank between the label and the beginning\n> of the body when reflowing the body with fill-paragraph, i.e.\n>\n> item label::\n>\n> This describes the item.\n>\n> You say that it is also easier on Vim to have the blank line there,\n> so perhaps we may want to aim for updating the documentation over\n> time to consistently do so. I dunno.\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n\nAs I stated in my recent resubmit[1], I decided to remove the blank\nlines after option subheadings because the syntax highlighting in Vim\nactually looks better with the blank lines removed. As such, I would\nprefer that we go with the option of removing these blank lines going\nforward.\n\nIf we are in agreement on this, should I send in a patch for\nCodingGuidelines to state this?\n\n[1] http://marc.info/?l=git&m=138447927208462&w=2\n"},{"id":"230661","messageId":"CAEjxke-O0MnWvPabeUOVGFnxs0rW6J0q72JRxh7s_zqqSxxkXw@mail.gmail.com","threadId":"35329","inReplyTo":"CAEjxke8vLtA5CgW8v4zv58kexe631koniNpdqTrr8LFYAOrMuA@mail.gmail.com","subject":"Re: [PATCH 2/2] Fix minor grammatical and other formatting issues in the \"git log\" man page","fromName":"Jason St. John","fromEmail":"jstjohn@purdue.edu","sentAt":"2013-11-15T01:47:27Z","receivedAt":"2013-11-15T01:47:27Z","isPatch":true,"sender":{"key":"jstjohn@purdue.edu","avatar":"https://avatars.githubusercontent.com/u/1393510?v=4"},"body":"On Thu, Nov 14, 2013 at 8:44 PM, Jason St. John wrote:\n> On Wed, Nov 13, 2013 at 4:56 PM, Junio C Hamano wrote:\n>> \"Jason St. John\" writes:\n>>\n>>> Documentation/git-log.txt:\n>>> -- replace single quotes around options/commands with backticks\n>>> -- use single quotes around references to sections\n>>> -- replaced some double quotes with proper AsciiDoc quotes (e.g.\n>>> ``foo'')\n>>> -- use backticks around files and file paths\n>>> -- use title case when referring to section headings\n>>> -- use backticks around option arguments/defaults\n>>>\n>>> Signed-off-by: Jason St. John \n>>> ---\n>>> When working on this commit, I noticed a difference in how options and\n>>> option descriptions are separated (e.g. with a blank line or not). At least\n>>> with Vim's syntax highlighting, if there is a blank line between the option\n>>> and its description, the text block is all colored the same; however, if\n>>> there isn't a blank line, then the text block is not specially colored.\n>>>\n>>> Is there an existing convention for how this should be done?\n>>\n>> I do not think we have a written rule or convention (and I do not\n>> know if we want one). While reading the text in the source form\n>> (and the point of choosing AsciiDoc was to be able to read the docs\n>> without formatting), I personally have a slight preference to\n>> immediately follow the body text to the label in the labelled list,\n>> and a blank line after the item, i.e.\n>>\n>> item label::\n>> This describes the item.\n>>\n>> next item label::\n>> This describes the next item.\n>>\n>> as it makes it clear that the body belongs to the heading that\n>> precedes it.\n>>\n>> But it does help to have a blank between the label and the beginning\n>> of the body when reflowing the body with fill-paragraph, i.e.\n>>\n>> item label::\n>>\n>> This describes the item.\n>>\n>> You say that it is also easier on Vim to have the blank line there,\n>> so perhaps we may want to aim for updating the documentation over\n>> time to consistently do so. I dunno.\n>> --\n>> To unsubscribe from this list: send the line \"unsubscribe git\" in\n>> the body of a message to majordomo@vger.kernel.org\n>> More majordomo info at http://vger.kernel.org/majordomo-info.html\n>\n> As I stated in my recent resubmit[1], I decided to remove the blank\n> lines after option subheadings because the syntax highlighting in Vim\n> actually looks better with the blank lines removed. As such, I would\n> prefer that we go with the option of removing these blank lines going\n> forward.\n>\n> If we are in agreement on this, should I send in a patch for\n> CodingGuidelines to state this?\n>\n> [1] http://marc.info/?l=git&m=138447927208462&w=2\n\nI forgot to mention that if we do go with this, then I will need to\nresubmit this patch.\n\nSorry for the extra email.\n"}]}