Documentation: Generate command lists.

This moves the source of the list of commands and categorization
to the end of Documentation/cmd-list.perl, so that re-categorization
and re-ordering would become easier to manage.

Signed-off-by: Junio C Hamano <junkio@cox.net>

9 files changed, 196 insertions, 379 deletions

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index c87c61af00..a531be32dc 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -5,3 +5,4 @@
 howto-index.txt
 doc.dep
 README
+cmds-*.txt
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 9f2d242e59..96755ad687 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -71,11 +71,21 @@ doc.dep : $(wildcard *.txt) build-docdep.perl
 
 -include doc.dep
 
-git.7 git.html: git.txt core-intro.txt
+cmds_txt = cmds-ancillaryinterrogators.txt \
+	cmds-ancillarymanipulators.txt \
+	cmds-mainporcelain.txt \
+	cmds-plumbinginterrogators.txt \
+	cmds-plumbingmanipulators.txt \
+	cmds-synchingrepositories.txt
+
+$(cmds_txt): cmd-list.perl $(MAN1_TXT) $(MAN7_TXT)
+	perl ./cmd-list.perl
 
+git.7 git.html: git.txt core-intro.txt
 
 clean:
 	rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html doc.dep
+	rm -f $(cmds_txt)
 
 %.html : %.txt
 	asciidoc -b xhtml11 -d manpage -f asciidoc.conf $<
diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
new file mode 100755
index 0000000000..5680dcbf9a
--- /dev/null
+++ b/Documentation/cmd-list.perl
@@ -0,0 +1,184 @@
+#
+
+sub format_one {
+	my ($out, $name) = @_;
+	my ($state, $description);
+	open I, '<', "$name.txt" or die "No such file $name.txt";
+	while (<I>) {
+		if (/^NAME$/) {
+			$state = 1;
+			next;
+		}
+		if ($state == 1 && /^----$/) {
+			$state = 2;
+			next;
+		}
+		next if ($state != 2);
+		chomp;
+		$description = $_;
+		last;
+	}
+	close I;
+	if (!defined $description) {
+		die "No description found in $name.txt";
+	}
+	if (my ($verify_name, $text) = ($description =~ /^($name) - (.*)/)) {
+		print $out "gitlink:$name\[1\]::\n";
+		print $out "\t$text.\n\n";
+	}
+	else {
+		die "Description does not match $name: $description";
+	}
+}
+
+my %cmds = ();
+while (<DATA>) {
+	next if /^#/;
+
+	chomp;
+	my ($name, $cat) = /^(\S+)\s+(.*)$/;
+	push @{$cmds{$cat}}, $name;
+}
+
+for my $cat (qw(ancillaryinterrogators
+		ancillarymanipulators
+		mainporcelain
+		plumbinginterrogators
+		plumbingmanipulators
+		synchingrepositories)) {
+	my $out = "cmds-$cat.txt";
+	open O, '>', "$out+" or die "Cannot open output file $out+";
+	for (@{$cmds{$cat}}) {
+		format_one(\*O, $_);
+	}
+	close O;
+	rename "$out+", "$out";
+}
+
+__DATA__
+git-add                                 mainporcelain
+git-am                                  mainporcelain
+git-annotate                            ancillaryinterrogators
+git-applymbox                           mainporcelain
+git-applypatch                          ancillarymanipulators
+git-apply                               plumbingmanipulators
+git-archimport                          ancillarymanipulators
+git-archive                             mainporcelain
+git-bisect                              mainporcelain
+git-blame                               ancillaryinterrogators
+git-branch                              mainporcelain
+git-cat-file                            plumbinginterrogators
+git-checkout-index                      plumbingmanipulators
+git-checkout                            mainporcelain
+git-check-ref-format                    ancillaryinterrogators
+git-cherry                              ancillaryinterrogators
+git-cherry-pick                         mainporcelain
+git-clean                               mainporcelain
+git-clone                               mainporcelain
+git-commit                              mainporcelain
+git-commit-tree                         plumbingmanipulators
+git-convert-objects                     ancillarymanipulators
+git-count-objects                       ancillaryinterrogators
+git-cvsexportcommit                     ancillarymanipulators
+git-cvsimport                           ancillarymanipulators
+git-cvsserver                           ancillarymanipulators
+git-daemon                              ancillaryinterrogators
+git-describe                            plumbinginterrogators
+git-diff-files                          plumbinginterrogators
+git-diff-index                          plumbinginterrogators
+git-diff                                mainporcelain
+git-diff-stages                         plumbinginterrogators
+git-diff-tree                           plumbinginterrogators
+git-fetch                               mainporcelain
+git-fetch-pack                          synchingrepositories
+git-fmt-merge-msg                       ancillaryinterrogators
+git-for-each-ref                        plumbinginterrogators
+git-format-patch                        mainporcelain
+git-fsck-objects                        plumbinginterrogators
+git-gc                                  ancillarymanipulators
+git-get-tar-commit-id                   ancillaryinterrogators
+git-grep                                mainporcelain
+git-hash-object                         plumbingmanipulators
+git-http-fetch                          synchingrepositories
+git-http-push                           synchingrepositories
+git-imap-send                           ancillaryinterrogators
+git-index-pack                          plumbingmanipulators
+git-init                                plumbingmanipulators
+git-instaweb                            ancillaryinterrogators
+gitk                                    mainporcelain
+git-local-fetch                         synchingrepositories
+git-log                                 mainporcelain
+git-lost-found                          ancillarymanipulators
+git-ls-files                            plumbinginterrogators
+git-ls-remote                           mainporcelain
+git-ls-tree                             plumbinginterrogators
+git-mailinfo                            ancillaryinterrogators
+git-mailsplit                           ancillaryinterrogators
+git-merge-base                          plumbinginterrogators
+git-merge-file                          plumbingmanipulators
+git-merge-index                         plumbingmanipulators
+git-merge                               mainporcelain
+git-merge-one-file                      ancillarymanipulators
+git-merge-tree                          ancillaryinterrogators
+git-mktag                               plumbingmanipulators
+git-mktree                              plumbingmanipulators
+git-mv                                  mainporcelain
+git-name-rev                            plumbinginterrogators
+git-pack-objects                        plumbingmanipulators
+git-pack-redundant                      plumbinginterrogators
+git-pack-refs                           mainporcelain
+git-parse-remote                        ancillaryinterrogators
+git-patch-id                            ancillaryinterrogators
+git-peek-remote                         synchingrepositories
+git-prune                               ancillarymanipulators
+git-prune-packed                        plumbingmanipulators
+git-pull                                mainporcelain
+git-push                                mainporcelain
+git-quiltimport                         ancillarymanipulators
+git-read-tree                           plumbingmanipulators
+git-rebase                              mainporcelain
+git-receive-pack                        synchingrepositories
+git-reflog                              ancillarymanipulators
+git-relink                              ancillarymanipulators
+git-repack                              mainporcelain
+git-repo-config                         plumbingmanipulators
+git-request-pull                        ancillaryinterrogators
+git-rerere                              mainporcelain
+git-reset                               mainporcelain
+git-resolve                             mainporcelain
+git-revert                              mainporcelain
+git-rev-list                            plumbinginterrogators
+git-rev-parse                           ancillaryinterrogators
+git-rm                                  mainporcelain
+git-runstatus                           ancillaryinterrogators
+git-send-email                          ancillaryinterrogators
+git-send-pack                           synchingrepositories
+git-shell                               synchingrepositories
+git-shortlog                            mainporcelain
+git-show                                mainporcelain
+git-show-branch                         mainporcelain
+git-show-index                          plumbinginterrogators
+git-show-ref                            plumbinginterrogators
+git-sh-setup                            ancillarymanipulators
+git-ssh-fetch                           synchingrepositories
+git-ssh-upload                          synchingrepositories
+git-status                              mainporcelain
+git-stripspace                          ancillaryinterrogators
+git-svn                                 ancillarymanipulators
+git-svnimport                           ancillarymanipulators
+git-symbolic-ref                        ancillaryinterrogators
+git-symbolic-ref                        ancillarymanipulators
+git-tag                                 ancillarymanipulators
+git-tar-tree                            plumbinginterrogators
+git-unpack-file                         plumbinginterrogators
+git-unpack-objects                      plumbingmanipulators
+git-update-index                        plumbingmanipulators
+git-update-ref                          ancillarymanipulators
+git-update-server-info                  synchingrepositories
+git-upload-archive                      synchingrepositories
+git-upload-pack                         synchingrepositories
+git-var                                 plumbinginterrogators
+git-verify-pack                         plumbinginterrogators
+git-verify-tag                          mainporcelain
+git-whatchanged                         mainporcelain
+git-write-tree                          plumbingmanipulators
diff --git a/Documentation/cmds-ancillaryinterrogators.txt b/Documentation/cmds-ancillaryinterrogators.txt
deleted file mode 100644
index 7398348d13..0000000000
--- a/Documentation/cmds-ancillaryinterrogators.txt
+++ /dev/null
@@ -1,63 +0,0 @@
-gitlink:git-annotate[1]::
-	Annotate file lines with commit info.
-
-gitlink:git-blame[1]::
-	Show what revision and author last modified each line of a file.
-
-gitlink:git-check-ref-format[1]::
-	Make sure ref name is well formed.
-
-gitlink:git-cherry[1]::
-	Find commits not merged upstream.
-
-gitlink:git-count-objects[1]::
-	Count unpacked number of objects and their disk consumption.
-
-gitlink:git-daemon[1]::
-	A really simple server for git repositories.
-
-gitlink:git-fmt-merge-msg[1]::
-	Produce a merge commit message.
-
-gitlink:git-get-tar-commit-id[1]::
-	Extract commit ID from an archive created using git-tar-tree.
-
-gitlink:git-imap-send[1]::
-	Dump a mailbox from stdin into an imap folder.
-
-gitlink:git-instaweb[1]::
-	Instantly browse your working repository in gitweb.
-
-gitlink:git-mailinfo[1]::
-	Extracts patch and authorship from a single e-mail message.
-
-gitlink:git-mailsplit[1]::
-	Simple UNIX mbox splitter program.
-
-gitlink:git-merge-tree[1]::
-	Show three-way merge without touching index.
-
-gitlink:git-parse-remote[1]::
-	Routines to help parsing remote repository access parameters.
-
-gitlink:git-patch-id[1]::
-	Compute unique ID for a patch.
-
-gitlink:git-request-pull[1]::
-	Generates a summary of pending changes.
-
-gitlink:git-rev-parse[1]::
-	Pick out and massage parameters.
-
-gitlink:git-runstatus[1]::
-	A helper for git-status and git-commit.
-
-gitlink:git-send-email[1]::
-	Send a collection of patches as emails.
-
-gitlink:git-stripspace[1]::
-	Filter out empty lines.
-
-gitlink:git-symbolic-ref[1]::
-	Read and modify symbolic refs.
-
diff --git a/Documentation/cmds-ancillarymanipulators.txt b/Documentation/cmds-ancillarymanipulators.txt
deleted file mode 100644
index 638a132aed..0000000000
--- a/Documentation/cmds-ancillarymanipulators.txt
+++ /dev/null
@@ -1,57 +0,0 @@
-gitlink:git-applypatch[1]::
-	Apply one patch extracted from an e-mail.
-
-gitlink:git-archimport[1]::
-	Import an Arch repository into git.
-
-gitlink:git-convert-objects[1]::
-	Converts old-style git repository.
-
-gitlink:git-cvsexportcommit[1]::
-	Export a single commit to a CVS checkout.
-
-gitlink:git-cvsimport[1]::
-	Salvage your data out of another SCM people love to hate.
-
-gitlink:git-cvsserver[1]::
-	A CVS server emulator for git.
-
-gitlink:git-gc[1]::
-	Cleanup unnecessary files and optimize the local repository.
-
-gitlink:git-lost-found[1]::
-	Recover lost refs that luckily have not yet been pruned.
-
-gitlink:git-merge-one-file[1]::
-	The standard helper program to use with git-merge-index.
-
-gitlink:git-prune[1]::
-	Prunes all unreachable objects from the object database.
-
-gitlink:git-quiltimport[1]::
-	Applies a quilt patchset onto the current branch.
-
-gitlink:git-reflog[1]::
-	Manage reflog information.
-
-gitlink:git-relink[1]::
-	Hardlink common objects in local repositories.
-
-gitlink:git-sh-setup[1]::
-	Common git shell script setup code.
-
-gitlink:git-svn[1]::
-	Bidirectional operation between a single Subversion branch and git.
-
-gitlink:git-svnimport[1]::
-	Import a SVN repository into git.
-
-gitlink:git-symbolic-ref[1]::
-	Read and modify symbolic refs.
-
-gitlink:git-tag[1]::
-	Create or verify a tag object signed with GPG.
-
-gitlink:git-update-ref[1]::
-	Update the object name stored in a ref safely.
-
diff --git a/Documentation/cmds-mainporcelain.txt b/Documentation/cmds-mainporcelain.txt
deleted file mode 100644
index 05c5965dcc..0000000000
--- a/Documentation/cmds-mainporcelain.txt
+++ /dev/null
@@ -1,108 +0,0 @@
-gitlink:git-add[1]::
-	Add file contents to the changeset to be committed next.
-
-gitlink:git-am[1]::
-	Apply a series of patches from a mailbox.
-
-gitlink:git-applymbox[1]::
-	Apply a series of patches in a mailbox.
-
-gitlink:git-archive[1]::
-	Creates an archive of files from a named tree.
-
-gitlink:git-bisect[1]::
-	Find the change that introduced a bug by binary search.
-
-gitlink:git-branch[1]::
-	List, create, or delete branches.
-
-gitlink:git-checkout[1]::
-	Checkout and switch to a branch.
-
-gitlink:git-cherry-pick[1]::
-	Apply the change introduced by an existing commit.
-
-gitlink:git-clean[1]::
-	Remove untracked files from the working tree.
-
-gitlink:git-clone[1]::
-	Clones a repository into a new directory.
-
-gitlink:git-commit[1]::
-	Record changes to the repository.
-
-gitlink:git-diff[1]::
-	Show changes between commits, commit and working tree, etc.
-
-gitlink:git-fetch[1]::
-	Download objects and refs from another repository.
-
-gitlink:git-format-patch[1]::
-	Prepare patches for e-mail submission.
-
-gitlink:git-grep[1]::
-	Print lines matching a pattern.
-
-gitlink:gitk[1]::
-	The git repository browser.
-
-gitlink:git-log[1]::
-	Show commit logs.
-
-gitlink:git-ls-remote[1]::
-	List references in a remote repository.
-
-gitlink:git-merge[1]::
-	Join two or more development histories together.
-
-gitlink:git-mv[1]::
-	Move or rename a file, a directory, or a symlink.
-
-gitlink:git-pack-refs[1]::
-	Pack heads and tags for efficient repository access.
-
-gitlink:git-pull[1]::
-	Fetch from and merge with another repository or a local branch.
-
-gitlink:git-push[1]::
-	Update remote refs along with associated objects.
-
-gitlink:git-rebase[1]::
-	Forward-port local commits to the updated upstream head.
-
-gitlink:git-repack[1]::
-	Pack unpacked objects in a repository.
-
-gitlink:git-rerere[1]::
-	Reuse recorded resolution of conflicted merges.
-
-gitlink:git-reset[1]::
-	Reset current HEAD to the specified state.
-
-gitlink:git-resolve[1]::
-	Merge two commits.
-
-gitlink:git-revert[1]::
-	Revert an existing commit.
-
-gitlink:git-rm[1]::
-	Remove files from the working tree and from the index.
-
-gitlink:git-shortlog[1]::
-	Summarize 'git log' output.
-
-gitlink:git-show[1]::
-	Show various types of objects.
-
-gitlink:git-show-branch[1]::
-	Show branches and their commits.
-
-gitlink:git-status[1]::
-	Show the working tree status.
-
-gitlink:git-verify-tag[1]::
-	Check the GPG signature of tag.
-
-gitlink:git-whatchanged[1]::
-	Show logs with difference each commit introduces.
-
diff --git a/Documentation/cmds-plumbinginterrogators.txt b/Documentation/cmds-plumbinginterrogators.txt
deleted file mode 100644
index 28580eae99..0000000000
--- a/Documentation/cmds-plumbinginterrogators.txt
+++ /dev/null
@@ -1,60 +0,0 @@
-gitlink:git-cat-file[1]::
-	Provide content or type/size information for repository objects.
-
-gitlink:git-describe[1]::
-	Show the most recent tag that is reachable from a commit.
-
-gitlink:git-diff-files[1]::
-	Compares files in the working tree and the index.
-
-gitlink:git-diff-index[1]::
-	Compares content and mode of blobs between the index and repository.
-
-gitlink:git-diff-stages[1]::
-	Compares two merge stages in the index.
-
-gitlink:git-diff-tree[1]::
-	Compares the content and mode of blobs found via two tree objects.
-
-gitlink:git-for-each-ref[1]::
-	Output information on each ref.
-
-gitlink:git-fsck-objects[1]::
-	Verifies the connectivity and validity of the objects in the database.
-
-gitlink:git-ls-files[1]::
-	Show information about files in the index and the working tree.
-
-gitlink:git-ls-tree[1]::
-	List the contents of a tree object.
-
-gitlink:git-merge-base[1]::
-	Find as good common ancestors as possible for a merge.
-
-gitlink:git-name-rev[1]::
-	Find symbolic names for given revs.
-
-gitlink:git-pack-redundant[1]::
-	Find redundant pack files.
-
-gitlink:git-rev-list[1]::
-	Lists commit objects in reverse chronological order.
-
-gitlink:git-show-index[1]::
-	Show packed archive index.
-
-gitlink:git-show-ref[1]::
-	List references in a local repository.
-
-gitlink:git-tar-tree[1]::
-	Create a tar archive of the files in the named tree object.
-
-gitlink:git-unpack-file[1]::
-	Creates a temporary file with a blob's contents.
-
-gitlink:git-var[1]::
-	Show a git logical variable.
-
-gitlink:git-verify-pack[1]::
-	Validate packed git archive files.
-
diff --git a/Documentation/cmds-plumbingmanipulators.txt b/Documentation/cmds-plumbingmanipulators.txt
deleted file mode 100644
index 4363877107..0000000000
--- a/Documentation/cmds-plumbingmanipulators.txt
+++ /dev/null
@@ -1,51 +0,0 @@
-gitlink:git-apply[1]::
-	Apply a patch on a git index file and a working tree.
-
-gitlink:git-checkout-index[1]::
-	Copy files from the index to the working tree.
-
-gitlink:git-commit-tree[1]::
-	Create a new commit object.
-
-gitlink:git-hash-object[1]::
-	Compute object ID and optionally creates a blob from a file.
-
-gitlink:git-index-pack[1]::
-	Build pack index file for an existing packed archive.
-
-gitlink:git-init[1]::
-	Create an empty git repository or reinitialize an existing one.
-
-gitlink:git-merge-file[1]::
-	Run a three-way file merge.
-
-gitlink:git-merge-index[1]::
-	Run a merge for files needing merging.
-
-gitlink:git-mktag[1]::
-	Creates a tag object.
-
-gitlink:git-mktree[1]::
-	Build a tree-object from ls-tree formatted text.
-
-gitlink:git-pack-objects[1]::
-	Create a packed archive of objects.
-
-gitlink:git-prune-packed[1]::
-	Remove extra objects that are already in pack files.
-
-gitlink:git-read-tree[1]::
-	Reads tree information into the index.
-
-gitlink:git-repo-config[1]::
-	Get and set repository or global options.
-
-gitlink:git-unpack-objects[1]::
-	Unpack objects from a packed archive.
-
-gitlink:git-update-index[1]::
-	Register file contents in the working tree to the index.
-
-gitlink:git-write-tree[1]::
-	Create a tree object from the current index.
-
diff --git a/Documentation/cmds-synchingrepositories.txt b/Documentation/cmds-synchingrepositories.txt
deleted file mode 100644
index 01b5bb992e..0000000000
--- a/Documentation/cmds-synchingrepositories.txt
+++ /dev/null
@@ -1,39 +0,0 @@
-gitlink:git-fetch-pack[1]::
-	Receive missing objects from another repository.
-
-gitlink:git-http-fetch[1]::
-	Download from a remote git repository via HTTP.
-
-gitlink:git-http-push[1]::
-	Push objects over HTTP/DAV to another repository.
-
-gitlink:git-local-fetch[1]::
-	Duplicate another git repository on a local system.
-
-gitlink:git-peek-remote[1]::
-	List the references in a remote repository.
-
-gitlink:git-receive-pack[1]::
-	Receive what is pushed into the repository.
-
-gitlink:git-send-pack[1]::
-	Push objects over git protocol to another reposiotory.
-
-gitlink:git-shell[1]::
-	Restricted login shell for GIT-only SSH access.
-
-gitlink:git-ssh-fetch[1]::
-	Fetch from a remote repository over ssh connection.
-
-gitlink:git-ssh-upload[1]::
-	Push to a remote repository over ssh connection.
-
-gitlink:git-update-server-info[1]::
-	Update auxiliary info file to help dumb servers.
-
-gitlink:git-upload-archive[1]::
-	Send archive back to git-archive.
-
-gitlink:git-upload-pack[1]::
-	Send objects packed back to git-fetch-pack.
-