threads / rfc / 34981

RFC patchdoc: git-foo was obsoleted several years ago

Subject: [RFC/PATCH] doc: git-foo was obsoleted several years ago

## tl;dr

6 messages between Sep 21, 2013 and Oct 17, 2013. Diffs are folded; open one to read it.

replies: 5people: 5as markdown or json

Felipe Contreras· Sep 21, 2013, 11:37 UTC · lore
So replace 'git-foo' with 'git foo'.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-checkout.txt | 4 ++--
 Documentation/git-commit.txt   | 4 ++--
 Documentation/git-rebase.txt   | 4 ++--
 Documentation/git-status.txt   | 4 ++--
 4 files changed, 8 insertions(+), 8 deletions(-)
Show changes to 4 files +8 −8

Documentation/git-checkout.txt, Documentation/git-commit.txt, Documentation/git-rebase.txt, Documentation/git-status.txt

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index ca118ac..8d98383 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -1,9 +1,9 @@
-git-checkout(1)
+git checkout(1)
 ===============
 
 NAME
 ----
-git-checkout - Checkout a branch or paths to the working tree
+git checkout - Checkout a branch or paths to the working tree
 
 SYNOPSIS
 --------
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 1a7616c..51f6b81 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -1,9 +1,9 @@
-git-commit(1)
+git commit(1)
 =============
 
 NAME
 ----
-git-commit - Record changes to the repository
+git commit - Record changes to the repository
 
 SYNOPSIS
 --------
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 6b2e1c8..ed4f5f6 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -1,9 +1,9 @@
-git-rebase(1)
+git rebase(1)
 =============
 
 NAME
 ----
-git-rebase - Forward-port local commits to the updated upstream head
+git rebase - Forward-port local commits to the updated upstream head
 
 SYNOPSIS
 --------
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 9046df9..a128453 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -1,9 +1,9 @@
-git-status(1)
+git status(1)
 =============
 
 NAME
 ----
-git-status - Show the working tree status
+git status - Show the working tree status
 
 
 SYNOPSIS

-- 
1.8.4.9.g218b36e.dirty
Junio C Hamano· Oct 16, 2013, 21:38 UTC · re: Felipe Contreras · lore

Re: [RFC/PATCH] doc: git-foo was obsoleted several years ago

Felipe Contreras <felipe.contreras@gmail.com> writes:
Show 9 quoted lines
> So replace 'git-foo' with 'git foo'.
>
> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> ---
>  Documentation/git-checkout.txt | 4 ++--
>  Documentation/git-commit.txt   | 4 ++--
>  Documentation/git-rebase.txt   | 4 ++--
>  Documentation/git-status.txt   | 4 ++--
>  4 files changed, 8 insertions(+), 8 deletions(-)
Running
    $ head Documentaiton/git-c*.txt

shows that others e.g. git-cat-file.txt also begin with the same pattern, i.e. git-dashed-command(section) as the first header, and name section also lists the command in the dashed form, which makes one wonder why only these four are singled-out. It could have been "This is merely an RFC to show the kind fo things the submitter thinks we need to do; the real version, if list agrees that it is a good thing to do, would cover a lot more files.", but then it would have saved wasted time guessing if the message said so.

I recall that I wanted to see this change happen myself long time ago, and suspect that there may have been some reason that prevented us from doing so. I might have found that AsciiDoc back then did not like the input if the headline name "git-checkout(1)" did not match the filename "git-checkout.txt" and the command in the NAME section "git-checkout", or links "linkgit:git-checkout[1]" from other pages couldn't have SP there, or something silly like that.

Also doesn't our build infrastructure slurp the one-line description "git-checkout - Checkout a branch ..." from these files and expect a dash to be there?

In short, I personally do prefer to see dashless form at the top of the manpage, if it does not break other things, and there may need changes necessary to avoid breaking other things may to files other than these documentation-proper source files.

Show 17 quoted lines
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index ca118ac..8d98383 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -1,9 +1,9 @@
> -git-checkout(1)
> +git checkout(1)
>  ===============
>  
>  NAME
>  ----
> -git-checkout - Checkout a branch or paths to the working tree
> +git checkout - Checkout a branch or paths to the working tree
>  
>  SYNOPSIS
>  --------
> ...
Jeff King· Oct 17, 2013, 01:18 UTC · re: Junio C Hamano · lore

Re: [RFC/PATCH] doc: git-foo was obsoleted several years ago

On Wed, Oct 16, 2013 at 02:38:27PM -0700, Junio C Hamano wrote:
Show 9 quoted lines
> >  Documentation/git-checkout.txt | 4 ++--
> [...]
> I recall that I wanted to see this change happen myself long time
> ago, and suspect that there may have been some reason that prevented
> us from doing so.  I might have found that AsciiDoc back then did
> not like the input if the headline name "git-checkout(1)" did not
> match the filename "git-checkout.txt" and the command in the NAME
> section "git-checkout", or links "linkgit:git-checkout[1]" from
> other pages couldn't have SP there, or something silly like that.
Yes, I think it is still broken. After applying Felipe's patch:
  $ cd Documentation
  $ make git-checkout.1
      GEN cmd-list.made
      SUBDIR ../
  make[1]: `GIT-VERSION-FILE' is up to date.
      ASCIIDOC git-checkout.xml
      XMLTO git-checkout.1
So far, so good...
  $ man -l git-checkout.1
  man: git-checkout.1: No such file or directory
Huh?
  $ ls git?checkout.1
  git_checkout.1
Oh.

There is similar asciidoc (actually, I think it is docbook) cleverness with:

  $ make gitignore.1
      GEN cmd-list.made
      SUBDIR ../
      make[1]: `GIT-VERSION-FILE' is up to date.
      XMLTO gitignore.1
  $ ls gitignore.[0-9]
  gitignore.5

Now obviously what I asked for is wrong (we do not actually know how to make gitignore.1), but I have certainly been confused by this in the past when working on pages outside of section 1.

In both cases, it would be nice if we could tell xmlto "no, really, put the output in this file". I'm not sure that is an option, though, because in theory docbook output may be multiple files (the "-o" option actually specifies an output directory).

Since we know our manpages are a much simpler case, we could probably work around it by teaching the Makefile that building "git-foo.txt" generates git_foo.1, and then moving that to git-foo.1.

-Peff
Jakub Narębski· Oct 17, 2013, 11:13 UTC · re: Junio C Hamano · lore

Re: [RFC/PATCH] doc: git-foo was obsoleted several years ago

W dniu 2013-10-16 23:38, Junio C Hamano pisze:
> Felipe Contreras<felipe.contreras@gmail.com>  writes:
[...]
Show 25 quoted lines
> I recall that I wanted to see this change happen myself long time
> ago, and suspect that there may have been some reason that prevented
> us from doing so.  I might have found that AsciiDoc back then did
> not like the input if the headline name "git-checkout(1)" did not
> match the filename "git-checkout.txt" and the command in the NAME
> section "git-checkout", or links "linkgit:git-checkout[1]" from
> other pages couldn't have SP there, or something silly like that.
>
> Also doesn't our build infrastructure slurp the one-line description
> "git-checkout - Checkout a branch ..." from these files and expect a
> dash to be there?
>
> In short, I personally do prefer to see dashless form at the top of
> the manpage, if it does not break other things, and there may need
> changes necessary to avoid breaking other things may to files other
> than these documentation-proper source files.
>
>> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
>> index ca118ac..8d98383 100644
>> --- a/Documentation/git-checkout.txt
>> +++ b/Documentation/git-checkout.txt
>> @@ -1,9 +1,9 @@
>> -git-checkout(1)
>> +git checkout(1)
>>  ===============

I wonder if it wouldn't be better to leave as is, in dashed form, as the manpage file name is git-checkout.1, and this manpage is invoked as "man git-checkout", not "man git checkout" or "man 'git checkout'".

Show 8 quoted lines
>>   NAME
>>   ----
>> -git-checkout - Checkout a branch or paths to the working tree
>> +git checkout - Checkout a branch or paths to the working tree
>>
>>   SYNOPSIS
>>   --------
>> ...

But change this, as we use this command as "git checkout", not as "git-checkout".

-- 
Jakub Narębski
Antoine Pelisse· Oct 17, 2013, 12:06 UTC · re: Jakub Narębski · lore

Re: [RFC/PATCH] doc: git-foo was obsoleted several years ago

On Thu, Oct 17, 2013 at 1:13 PM, Jakub Narębski <jnareb@gmail.com> wrote:
Show 16 quoted lines
>> Felipe Contreras<felipe.contreras@gmail.com>  writes:
>>> diff --git a/Documentation/git-checkout.txt
>>> b/Documentation/git-checkout.txt
>>> index ca118ac..8d98383 100644
>>> --- a/Documentation/git-checkout.txt
>>> +++ b/Documentation/git-checkout.txt
>>> @@ -1,9 +1,9 @@
>>> -git-checkout(1)
>>> +git checkout(1)
>>>  ===============
>
>
> I wonder if it wouldn't be better to leave as is, in dashed form,
> as the manpage file name is git-checkout.1, and this manpage is
> invoked as "man git-checkout", not "man git checkout"
> or "man 'git checkout'".
This is partly true, as you can also run it with `git checkout --help`
Junio C Hamano· Oct 17, 2013, 19:44 UTC · re: Jakub Narębski · lore

Re: [RFC/PATCH] doc: git-foo was obsoleted several years ago

Jakub Narębski <jnareb@gmail.com> writes:
Show 12 quoted lines
> W dniu 2013-10-16 23:38, Junio C Hamano pisze:
>> I recall that I wanted to see this change happen myself long time
>> ago,...
>> In short, I personally do prefer to see dashless form at the top of
>> the manpage, if it does not break other things, and there may need
>> changes necessary to avoid breaking other things may to files other
>> than these documentation-proper source files.
>> ...
> I wonder if it wouldn't be better to leave as is, in dashed form,
> ...
> But change this, as we use this command as "git checkout", not
> as "git-checkout".

Yes, that is what I meant by "dashless form at the top of the manpage, if it does not break other things". "man git-cat-file" is one of "other things".

← back to recent threads