git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Eric Sunshine <sunshine@sunshineco.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Sébastien Guimmara" <sebastien.guimmara@gmail.com>, git@vger.kernel.org
Subject: Re: [PATCH v8 5/5] help: respect new common command grouping
Date: Mon, 18 May 2015 20:43:56 -0400	[thread overview]
Message-ID: <20150519004356.GA12854@flurp.local> (raw)
In-Reply-To: <xmqqr3qda7kx.fsf@gitster.dls.corp.google.com>

On Mon, May 18, 2015 at 02:39:42PM -0700, Junio C Hamano wrote:
> Sébastien Guimmara  <sebastien.guimmara@gmail.com> writes:
> > 'git help' shows common commands in alphabetical order:
> > [...]
> > without any indication of how commands relate to high-level
> > concepts or each other. Revise the output to explain their relationship
> > with the typical Git workflow:
> > [...]
> > The typical Git workflow includes:
> >
> > Helped-by: Eric Sunshine <sunshine@sunshineco.com>
> > Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> 
> I cannot exactly pinpoint what bothers me, but "The typical Git
> workflow includes:" sounds a bit awkward.
> What does a workflow "include"? [...]
> 
> Other than that, this round looks ready for 'next'.

I came to the same conclusion. FWIW, the entire series is:

Reviewed-by: Eric Sunshine <sunshine@sunshineco.com>

> I am not absolutely sure if new dependency on "awk" will not present
> portability issues, though.  So far we only used it in scripts in
> the fringes and only a few tests.

The awk script restricts itself to POSIX, and I did test it on Linux,
Mac OS X, and FreeBSD, so it seems pretty portable. However, if it
worries you sufficiently, here's the equivalent Perl version:

--- >8 ---
From: Eric Sunshine <sunshine@sunshineco.com>
Subject: [PATCH 3/5] generate-cmdlist: parse common group commands

Parse the group block to create the array of group descriptions:

static char *common_cmd_groups[] = {
    N_("starting a working area"),
    N_("working on the current change"),
    N_("working with others"),
    N_("examining the history and state"),
    N_("growing, marking and tweaking your history"),
};

then map each element of common_cmds[] to a group via its index:

static struct cmdname_help common_cmds[] = {
    {"add", N_("Add file contents to the index"), 1},
    {"branch", N_("List, create, or delete branches"), 4},
    {"checkout", N_("Checkout a branch or paths to the ..."), 4},
    {"clone", N_("Clone a repository into a new directory"), 0},
    {"commit", N_("Record changes to the repository"), 4},
    ...
};

so that 'git help' can print those commands grouped by theme.

Only commands tagged with an attribute from the group block are emitted to
common_cmds[].

[commit message by Sébastien Guimmara <sebastien.guimmara@gmail.com>]

Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---
 Makefile              |  4 ++--
 generate-cmdlist.perl | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 generate-cmdlist.sh   | 23 -----------------------
 3 files changed, 52 insertions(+), 25 deletions(-)
 create mode 100755 generate-cmdlist.perl
 delete mode 100755 generate-cmdlist.sh

diff --git a/Makefile b/Makefile
index 5ed0acf..c133a96 100644
--- a/Makefile
+++ b/Makefile
@@ -1693,10 +1693,10 @@ $(BUILT_INS): git$X
 	ln -s $< $@ 2>/dev/null || \
 	cp $< $@
 
-common-cmds.h: ./generate-cmdlist.sh command-list.txt
+common-cmds.h: generate-cmdlist.perl command-list.txt
 
 common-cmds.h: $(wildcard Documentation/git-*.txt)
-	$(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@
+	$(QUIET_GEN)$(PERL_PATH) generate-cmdlist.perl command-list.txt > $@+ && mv $@+ $@
 
 SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\
 	$(localedir_SQ):$(NO_CURL):$(USE_GETTEXT_SCHEME):$(SANE_TOOL_PATH_SQ):\
diff --git a/generate-cmdlist.perl b/generate-cmdlist.perl
new file mode 100755
index 0000000..31516e3
--- /dev/null
+++ b/generate-cmdlist.perl
@@ -0,0 +1,50 @@
+#!/usr/bin/perl
+use strict;
+use warnings;
+
+print <<"EOT";
+/* Automatically generated by $0 */
+
+struct cmdname_help {
+	char name[16];
+	char help[80];
+	unsigned char group;
+};
+
+static char *common_cmd_groups[] = {
+EOT
+
+my $n = 0;
+my %grp;
+while (<>) {
+	last if /^### command list/;
+	next if (1../^### common groups/) || /^#/ || /^\s*$/;
+	chop;
+	my ($k, $v) = split ' ', $_, 2;
+	$grp{$k} = $n++;
+	print "\tN_(\"$v\"),\n";
+}
+
+print "};\n\nstatic struct cmdname_help common_cmds[] = {\n";
+
+while (<>) {
+	next if /^#/ || /^\s*$/;
+	my @tags = split;
+	my $cmd = shift @tags;
+	for my $t (@tags) {
+		if (exists $grp{$t}) {
+			my $s;
+			open my $f, '<', "Documentation/$cmd.txt" or die;
+			while (<$f>) {
+				($s) = /^$cmd - (.+)$/;
+				last if $s;
+			}
+			close $f;
+			$cmd =~ s/^git-//;
+			print "\t{\"$cmd\", N_(\"$s\"), $grp{$t}},\n";
+			last;
+		}
+	}
+}
+
+print "};\n";
diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
deleted file mode 100755
index 9a4c9b9..0000000
--- a/generate-cmdlist.sh
+++ /dev/null
@@ -1,23 +0,0 @@
-#!/bin/sh
-
-echo "/* Automatically generated by $0 */
-struct cmdname_help {
-    char name[16];
-    char help[80];
-};
-
-static struct cmdname_help common_cmds[] = {"
-
-sed -n -e 's/^git-\([^ 	]*\)[ 	].* common.*/\1/p' command-list.txt |
-sort |
-while read cmd
-do
-     sed -n '
-     /^NAME/,/git-'"$cmd"'/H
-     ${
-	    x
-	    s/.*git-'"$cmd"' - \(.*\)/  {"'"$cmd"'", N_("\1")},/
-	    p
-     }' "Documentation/git-$cmd.txt"
-done
-echo "};"
-- 
2.4.1.260.ga2776d4

--- >8 ---

  reply	other threads:[~2015-05-19  0:44 UTC|newest]

Thread overview: 12+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2015-05-18 19:18 [PATCH v8 0/5] group common commands by theme Sébastien Guimmara
2015-05-18 19:18 ` [PATCH v8 1/5] command-list: prepare machinery for upcoming "common groups" section Sébastien Guimmara
2015-05-18 19:18 ` [PATCH v8 2/5] command-list.txt: add the common groups block Sébastien Guimmara
2015-05-18 19:18 ` [PATCH v8 3/5] generate-cmdlist: parse common group commands Sébastien Guimmara
2015-05-18 19:18 ` [PATCH v8 4/5] command-list.txt: drop the "common" tag Sébastien Guimmara
2015-05-18 19:18 ` [PATCH v8 5/5] help: respect new common command grouping Sébastien Guimmara
2015-05-18 21:39   ` Junio C Hamano
2015-05-19  0:43     ` Eric Sunshine [this message]
2015-05-19 16:09       ` Junio C Hamano
2015-05-19 16:35         ` Eric Sunshine
2015-05-19 18:20           ` Junio C Hamano
2015-05-19 17:57     ` Sébastien Guimmara

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20150519004356.GA12854@flurp.local \
    --to=sunshine@sunshineco.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=sebastien.guimmara@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).