{"thread":{"id":"34981","subject":"[RFC/PATCH] doc: git-foo was obsoleted several years ago","startedAt":"2013-09-21T11:37:09Z","lastAt":"2013-10-17T19:44:16Z","messageCount":6,"participants":["Felipe Contreras","Junio C Hamano","Jeff King","Jakub Narębski","Antoine Pelisse"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"227964","messageId":"1379763429-3443-1-git-send-email-felipe.contreras@gmail.com","threadId":"34981","inReplyTo":null,"subject":"[RFC/PATCH] doc: git-foo was obsoleted several years ago","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2013-09-21T11:37:09Z","receivedAt":"2013-09-21T11:37:09Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"So replace 'git-foo' with 'git foo'.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/git-checkout.txt | 4 ++--\n Documentation/git-commit.txt | 4 ++--\n Documentation/git-rebase.txt | 4 ++--\n Documentation/git-status.txt | 4 ++--\n 4 files changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex ca118ac..8d98383 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -1,9 +1,9 @@\n-git-checkout(1)\n+git checkout(1)\n ===============\n \n NAME\n ----\n-git-checkout - Checkout a branch or paths to the working tree\n+git checkout - Checkout a branch or paths to the working tree\n \n SYNOPSIS\n --------\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 1a7616c..51f6b81 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -1,9 +1,9 @@\n-git-commit(1)\n+git commit(1)\n =============\n \n NAME\n ----\n-git-commit - Record changes to the repository\n+git commit - Record changes to the repository\n \n SYNOPSIS\n --------\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex 6b2e1c8..ed4f5f6 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -1,9 +1,9 @@\n-git-rebase(1)\n+git rebase(1)\n =============\n \n NAME\n ----\n-git-rebase - Forward-port local commits to the updated upstream head\n+git rebase - Forward-port local commits to the updated upstream head\n \n SYNOPSIS\n --------\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 9046df9..a128453 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -1,9 +1,9 @@\n-git-status(1)\n+git status(1)\n =============\n \n NAME\n ----\n-git-status - Show the working tree status\n+git status - Show the working tree status\n \n \n SYNOPSIS\n-- \n1.8.4.9.g218b36e.dirty\n"},{"id":"229088","messageId":"xmqq7gdc7v70.fsf@gitster.dls.corp.google.com","threadId":"34981","inReplyTo":"1379763429-3443-1-git-send-email-felipe.contreras@gmail.com","subject":"Re: [RFC/PATCH] doc: git-foo was obsoleted several years ago","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-10-16T21:38:27Z","receivedAt":"2013-10-16T21:38:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> So replace 'git-foo' with 'git foo'.\n>\n> Signed-off-by: Felipe Contreras \n> ---\n> Documentation/git-checkout.txt | 4 ++--\n> Documentation/git-commit.txt | 4 ++--\n> Documentation/git-rebase.txt | 4 ++--\n> Documentation/git-status.txt | 4 ++--\n> 4 files changed, 8 insertions(+), 8 deletions(-)\n\nRunning\n\n $ head Documentaiton/git-c*.txt\n\nshows that others e.g. git-cat-file.txt also begin with the same\npattern, i.e. git-dashed-command(section) as the first header, and\nname section also lists the command in the dashed form, which makes\none wonder why only these four are singled-out. It could have been\n\"This is merely an RFC to show the kind fo things the submitter\nthinks we need to do; the real version, if list agrees that it is a\ngood thing to do, would cover a lot more files.\", but then it would\nhave saved wasted time guessing if the message said so.\n\nI recall that I wanted to see this change happen myself long time\nago, and suspect that there may have been some reason that prevented\nus from doing so. I might have found that AsciiDoc back then did\nnot like the input if the headline name \"git-checkout(1)\" did not\nmatch the filename \"git-checkout.txt\" and the command in the NAME\nsection \"git-checkout\", or links \"linkgit:git-checkout[1]\" from\nother pages couldn't have SP there, or something silly like that.\n\nAlso doesn't our build infrastructure slurp the one-line description\n\"git-checkout - Checkout a branch ...\" from these files and expect a\ndash to be there?\n\nIn short, I personally do prefer to see dashless form at the top of\nthe manpage, if it does not break other things, and there may need\nchanges necessary to avoid breaking other things may to files other\nthan these documentation-proper source files.\n\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> index ca118ac..8d98383 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -1,9 +1,9 @@\n> -git-checkout(1)\n> +git checkout(1)\n> ===============\n> \n> NAME\n> ----\n> -git-checkout - Checkout a branch or paths to the working tree\n> +git checkout - Checkout a branch or paths to the working tree\n> \n> SYNOPSIS\n> --------\n> ...\n"},{"id":"229112","messageId":"20131017011807.GA14759@sigill.intra.peff.net","threadId":"34981","inReplyTo":"xmqq7gdc7v70.fsf@gitster.dls.corp.google.com","subject":"Re: [RFC/PATCH] doc: git-foo was obsoleted several years ago","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2013-10-17T01:18:07Z","receivedAt":"2013-10-17T01:18:07Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Oct 16, 2013 at 02:38:27PM -0700, Junio C Hamano wrote:\n\n> > Documentation/git-checkout.txt | 4 ++--\n> [...]\n> I recall that I wanted to see this change happen myself long time\n> ago, and suspect that there may have been some reason that prevented\n> us from doing so. I might have found that AsciiDoc back then did\n> not like the input if the headline name \"git-checkout(1)\" did not\n> match the filename \"git-checkout.txt\" and the command in the NAME\n> section \"git-checkout\", or links \"linkgit:git-checkout[1]\" from\n> other pages couldn't have SP there, or something silly like that.\n\nYes, I think it is still broken. After applying Felipe's patch:\n\n $ cd Documentation\n $ make git-checkout.1\n GEN cmd-list.made\n SUBDIR ../\n make[1]: `GIT-VERSION-FILE' is up to date.\n ASCIIDOC git-checkout.xml\n XMLTO git-checkout.1\n\nSo far, so good...\n\n $ man -l git-checkout.1\n man: git-checkout.1: No such file or directory\n\nHuh?\n\n $ ls git?checkout.1\n git_checkout.1\n\nOh.\n\nThere is similar asciidoc (actually, I think it is docbook) cleverness\nwith:\n\n $ make gitignore.1\n GEN cmd-list.made\n SUBDIR ../\n make[1]: `GIT-VERSION-FILE' is up to date.\n XMLTO gitignore.1\n\n $ ls gitignore.[0-9]\n gitignore.5\n\nNow obviously what I asked for is wrong (we do not actually know how to\nmake gitignore.1), but I have certainly been confused by this in the\npast when working on pages outside of section 1.\n\nIn both cases, it would be nice if we could tell xmlto \"no, really, put\nthe output in this file\". I'm not sure that is an option, though,\nbecause in theory docbook output may be multiple files (the \"-o\" option\nactually specifies an output directory).\n\nSince we know our manpages are a much simpler case, we could probably\nwork around it by teaching the Makefile that building \"git-foo.txt\"\ngenerates git_foo.1, and then moving that to git-foo.1.\n\n-Peff\n"},{"id":"229118","messageId":"525FC659.8020608@gmail.com","threadId":"34981","inReplyTo":"xmqq7gdc7v70.fsf@gitster.dls.corp.google.com","subject":"Re: [RFC/PATCH] doc: git-foo was obsoleted several years ago","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2013-10-17T11:13:29Z","receivedAt":"2013-10-17T11:13:29Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"W dniu 2013-10-16 23:38, Junio C Hamano pisze:\n> Felipe Contreras writes:\n[...]\n> I recall that I wanted to see this change happen myself long time\n> ago, and suspect that there may have been some reason that prevented\n> us from doing so. I might have found that AsciiDoc back then did\n> not like the input if the headline name \"git-checkout(1)\" did not\n> match the filename \"git-checkout.txt\" and the command in the NAME\n> section \"git-checkout\", or links \"linkgit:git-checkout[1]\" from\n> other pages couldn't have SP there, or something silly like that.\n>\n> Also doesn't our build infrastructure slurp the one-line description\n> \"git-checkout - Checkout a branch ...\" from these files and expect a\n> dash to be there?\n>\n> In short, I personally do prefer to see dashless form at the top of\n> the manpage, if it does not break other things, and there may need\n> changes necessary to avoid breaking other things may to files other\n> than these documentation-proper source files.\n>\n>> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n>> index ca118ac..8d98383 100644\n>> --- a/Documentation/git-checkout.txt\n>> +++ b/Documentation/git-checkout.txt\n>> @@ -1,9 +1,9 @@\n>> -git-checkout(1)\n>> +git checkout(1)\n>> ===============\n\nI wonder if it wouldn't be better to leave as is, in dashed form,\nas the manpage file name is git-checkout.1, and this manpage is\ninvoked as \"man git-checkout\", not \"man git checkout\"\nor \"man 'git checkout'\".\n\n>> NAME\n>> ----\n>> -git-checkout - Checkout a branch or paths to the working tree\n>> +git checkout - Checkout a branch or paths to the working tree\n>>\n>> SYNOPSIS\n>> --------\n>> ...\n\nBut change this, as we use this command as \"git checkout\", not\nas \"git-checkout\".\n\n-- \nJakub Narębski\n"},{"id":"229119","messageId":"CALWbr2yctBwGaA=9RK6ujDvcn29VvN0KPGAmBNfUVx1W5D67MA@mail.gmail.com","threadId":"34981","inReplyTo":"525FC659.8020608@gmail.com","subject":"Re: [RFC/PATCH] doc: git-foo was obsoleted several years ago","fromName":"Antoine Pelisse","fromEmail":"apelisse@gmail.com","sentAt":"2013-10-17T12:06:42Z","receivedAt":"2013-10-17T12:06:42Z","isPatch":true,"sender":{"key":"apelisse@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1929644?v=4"},"body":"On Thu, Oct 17, 2013 at 1:13 PM, Jakub Narębski wrote:\n>> Felipe Contreras writes:\n>>> diff --git a/Documentation/git-checkout.txt\n>>> b/Documentation/git-checkout.txt\n>>> index ca118ac..8d98383 100644\n>>> --- a/Documentation/git-checkout.txt\n>>> +++ b/Documentation/git-checkout.txt\n>>> @@ -1,9 +1,9 @@\n>>> -git-checkout(1)\n>>> +git checkout(1)\n>>> ===============\n>\n>\n> I wonder if it wouldn't be better to leave as is, in dashed form,\n> as the manpage file name is git-checkout.1, and this manpage is\n> invoked as \"man git-checkout\", not \"man git checkout\"\n> or \"man 'git checkout'\".\n\nThis is partly true, as you can also run it with `git checkout --help`\n"},{"id":"229129","messageId":"xmqqfvrz1y3z.fsf@gitster.dls.corp.google.com","threadId":"34981","inReplyTo":"525FC659.8020608@gmail.com","subject":"Re: [RFC/PATCH] doc: git-foo was obsoleted several years ago","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-10-17T19:44:16Z","receivedAt":"2013-10-17T19:44:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narębski writes:\n\n> W dniu 2013-10-16 23:38, Junio C Hamano pisze:\n>> I recall that I wanted to see this change happen myself long time\n>> ago,...\n>> In short, I personally do prefer to see dashless form at the top of\n>> the manpage, if it does not break other things, and there may need\n>> changes necessary to avoid breaking other things may to files other\n>> than these documentation-proper source files.\n>> ...\n> I wonder if it wouldn't be better to leave as is, in dashed form,\n> ...\n> But change this, as we use this command as \"git checkout\", not\n> as \"git-checkout\".\n\nYes, that is what I meant by \"dashless form at the top of the\nmanpage, if it does not break other things\". \"man git-cat-file\"\nis one of \"other things\".\n"}]}