mbox series

[v2,0/3] List all guides in git(1)

Message ID pull.691.v2.git.1596500459.gitgitgadget@gmail.com
Headers show
Series List all guides in git(1) | expand

Message

Philippe Blain via GitGitGadget Aug. 4, 2020, 12:20 a.m. UTC
Changes since v1:

 * Incorporated Junio's suggestion to reduce duplication.

v1: This series adds a list of the guides to git(1).

The first commit adds the misssing guides 'gitcredentials' and
'gitremote-helpers' to command-list.txt. The only missing guide after this
change is 'gitweb.conf', but I think this one is obscure anough, and already
linked to in 'gitweb.txt', that it does not matter much.

The second commit drops the usage of 'common' and 'useful' for guides. This
was suggested as one of two ways forward by Duy in [1] but was not commented
on. I'm CC'ing the people that were CC'ed on that message.

The third commit tweaks 'Documentation/cmd-list.perl' so that it also
generates a list of the guides, which gets included in 'git.txt'. I chose to
put this list just after the end of the list of commands.

[1] 
https://lore.kernel.org/git/CACsJy8ADj-bTMYDHxRNLOMppOEdPbVwL49u3XCfNBCmoLLZo+A@mail.gmail.com/

Philippe Blain (3):
  command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers'
  help: drop usage of 'common' and 'useful' for guides
  git.txt: add list of guides

 Documentation/Makefile           |  4 +++-
 Documentation/cmd-list.perl      | 27 ++++++++++++++-------------
 Documentation/git-help.txt       |  6 +++---
 Documentation/git.txt            |  7 +++++++
 Documentation/gitcredentials.txt |  2 +-
 builtin/help.c                   |  2 +-
 command-list.txt                 |  2 ++
 help.c                           |  4 ++--
 help.h                           |  2 +-
 9 files changed, 34 insertions(+), 22 deletions(-)


base-commit: e8ab941b671da6890181aea5b5755d1d9eea24ec
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-691%2Fphil-blain%2Flist-guides-in-git.1-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-691/phil-blain/list-guides-in-git.1-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/691

Range-diff vs v1:

 1:  2bd473e0aa = 1:  2bd473e0aa command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers'
 2:  f49cf08f4f = 2:  f49cf08f4f help: drop usage of 'common' and 'useful' for guides
 3:  9374d80f0c ! 3:  4394bb357b git.txt: add list of guides
     @@ Metadata
       ## Commit message ##
          git.txt: add list of guides
      
     -    Not all guides are mentioned in the 'git(1)' documentation,
     +    Not all man5/man7 guides are mentioned in the 'git(1)' documentation,
          which makes the missing ones somewhat hard to find.
      
     -    Add a list of the guides to git(1).
     +    Add a list of the guides to git(1) by leveraging the existing
     +    `Documentation/cmd-list.perl` script to generate a file `cmds-guide.txt`
     +    which gets included in git.txt.
      
     -    Tweak `Documentation/cmd-list.perl` so that it also generates
     -    a file `cmds-guide.txt` which gets included in git.txt.
     +    Instead of hard-coding the list of command categories in both
     +    `Documentation/Makefile` and `Documentation/cmd-list.perl`, make the
     +    Makefile the authoritative source and tweak `cmd-list.perl` so that it
     +    receives the list of command categories as argument.
      
          Also, do not hard-code the manual section '1'. Instead, use a regex so
          that the manual section is discovered from the first line of each
     @@ Commit message
          This addition was hinted at in 1b81d8cb19 (help: use command-list.txt for
          the source of guides, 2018-05-20).
      
     +    Helped-by: Junio C Hamano <gitster@pobox.com>
          Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
      
     + ## Documentation/Makefile ##
     +@@ Documentation/Makefile: cmds_txt = cmds-ancillaryinterrogators.txt \
     + 	cmds-plumbingmanipulators.txt \
     + 	cmds-synchingrepositories.txt \
     + 	cmds-synchelpers.txt \
     ++	cmds-guide.txt \
     + 	cmds-purehelpers.txt \
     + 	cmds-foreignscminterface.txt
     + 
     +@@ Documentation/Makefile: $(cmds_txt): cmd-list.made
     + 
     + cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
     + 	$(QUIET_GEN)$(RM) $@ && \
     +-	$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(QUIET_STDERR) && \
     ++	$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \
     + 	date >$@
     + 
     + mergetools_txt = mergetools-diff.txt mergetools-merge.txt
     +
       ## Documentation/cmd-list.perl ##
      @@ Documentation/cmd-list.perl: sub format_one {
       	my ($out, $nameattr) = @_;
     @@ Documentation/cmd-list.perl: sub format_one {
       			print $out "(deprecated) ";
       		}
      @@ Documentation/cmd-list.perl: sub format_one {
     - 		synchingrepositories
     - 		foreignscminterface
     - 		purehelpers
     + 	}
     + }
     + 
     +-while (<>) {
     ++my ($input, @categories) = @ARGV;
     ++
     ++open IN, "<$input";
     ++while (<IN>) {
     + 	last if /^### command list/;
     + }
     + 
     + my %cmds = ();
     +-for (sort <>) {
     ++for (sort <IN>) {
     + 	next if /^#/;
     + 
     + 	chomp;
     +@@ Documentation/cmd-list.perl: sub format_one {
     + 	$attr = '' unless defined $attr;
     + 	push @{$cmds{$cat}}, [$name, " $attr "];
     + }
     ++close IN;
     + 
     +-for my $cat (qw(ancillaryinterrogators
     +-		ancillarymanipulators
     +-		mainporcelain
     +-		plumbinginterrogators
     +-		plumbingmanipulators
     +-		synchingrepositories
     +-		foreignscminterface
     +-		purehelpers
      -		synchelpers)) {
     -+		synchelpers
     -+		guide)) {
     - 	my $out = "cmds-$cat.txt";
     +-	my $out = "cmds-$cat.txt";
     ++for my $out (@categories) {
     ++	my ($cat) = $out =~ /^cmds-(.*)\.txt$/;
       	open O, '>', "$out+" or die "Cannot open output file $out+";
       	for (@{$cmds{$cat}}) {
     + 		format_one(\*O, $_);
      
       ## Documentation/git.txt ##
      @@ Documentation/git.txt: users typically do not use them directly.

Comments

Junio C Hamano Aug. 4, 2020, 12:26 a.m. UTC | #1
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:

> Changes since v1:
>
>  * Incorporated Junio's suggestion to reduce duplication.
>
> v1: This series adds a list of the guides to git(1).
>
> The first commit adds the misssing guides 'gitcredentials' and
> 'gitremote-helpers' to command-list.txt. The only missing guide after this
> change is 'gitweb.conf', but I think this one is obscure anough, and already
> linked to in 'gitweb.txt', that it does not matter much.
>
> The second commit drops the usage of 'common' and 'useful' for guides. This
> was suggested as one of two ways forward by Duy in [1] but was not commented
> on. I'm CC'ing the people that were CC'ed on that message.
>
> The third commit tweaks 'Documentation/cmd-list.perl' so that it also
> generates a list of the guides, which gets included in 'git.txt'. I chose to
> put this list just after the end of the list of commands.
>
> [1] 
> https://lore.kernel.org/git/CACsJy8ADj-bTMYDHxRNLOMppOEdPbVwL49u3XCfNBCmoLLZo+A@mail.gmail.com/
>
> Philippe Blain (3):
>   command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers'
>   help: drop usage of 'common' and 'useful' for guides
>   git.txt: add list of guides

I think the "dedup the list of cmds-$category.txt" is logically a
separate step from "we forgot to add guide category so add it", so
either (1) "add guide twice, and then refactor" or (2) "refactor
before adding guide, and then add guide only in one place" would be
more appropriate than (3) "add guide while refactoring".  IMHO, (2)
would make the most sense.

Thanks.
Philippe Blain Aug. 4, 2020, 1:44 p.m. UTC | #2
> Le 3 août 2020 à 20:26, Junio C Hamano <gitster@pobox.com> a écrit :
> 
> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>> Changes since v1:
>> 
>> * Incorporated Junio's suggestion to reduce duplication.
>> 
>> v1: This series adds a list of the guides to git(1).
>> 
>> The first commit adds the misssing guides 'gitcredentials' and
>> 'gitremote-helpers' to command-list.txt. The only missing guide after this
>> change is 'gitweb.conf', but I think this one is obscure anough, and already
>> linked to in 'gitweb.txt', that it does not matter much.
>> 
>> The second commit drops the usage of 'common' and 'useful' for guides. This
>> was suggested as one of two ways forward by Duy in [1] but was not commented
>> on. I'm CC'ing the people that were CC'ed on that message.
>> 
>> The third commit tweaks 'Documentation/cmd-list.perl' so that it also
>> generates a list of the guides, which gets included in 'git.txt'. I chose to
>> put this list just after the end of the list of commands.
>> 
>> [1] 
>> https://lore.kernel.org/git/CACsJy8ADj-bTMYDHxRNLOMppOEdPbVwL49u3XCfNBCmoLLZo+A@mail.gmail.com/
>> 
>> Philippe Blain (3):
>>  command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers'
>>  help: drop usage of 'common' and 'useful' for guides
>>  git.txt: add list of guides
> 
> I think the "dedup the list of cmds-$category.txt" is logically a
> separate step from "we forgot to add guide category so add it", so
> either (1) "add guide twice, and then refactor" or (2) "refactor
> before adding guide, and then add guide only in one place" would be
> more appropriate than (3) "add guide while refactoring".  IMHO, (2)
> would make the most sense.
> 

I agree that (2) makes the most sense, I've split it for v3. (Your "SQUASH???" message on pb/guide-docs 
may have mislead me :)

Philippe.