Re: [RFD/PATCH] Documentation: mention category
Junio C Hamano schrieb am 09.12.2014 um 21:26: Michael J Gruber g...@drmicha.warpmail.net writes: Rather than changing git-foo.txt, we could do the substitution magic from Documentation/Makefile, of course, to keep man pages and command-list in sync. Although this would keep me from submitting the final series with 1 patch per file :) I do not get that smiley. Are you saying that these noisy patches add to your karma points? Well, I didn't and I won't send them as 1p/f. Have I ever split my patches noisilly atomically? diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 9631526..b6a8bc6 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -13,6 +13,10 @@ SYNOPSIS [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--] [pathspec...] +CATEGORY + +Main user interface command (porcelain) + DESCRIPTION --- While I do not have objection to adding this information, I have a few problems with the execution: - These four lines at the very beginning is a precious real estate. The new reader would not benefit from the distinction before reading the first paragraph of description to learn what it does and what it is for anyway. Move it much later, perhaps at the end. Then we can just leave it out. The aim is to give new(er) users some orientation about which commands to use and which to stay away from, unless they want to do scripting. There's no point in putting a stop sign at the end of the road. This series was triggered by the recent update-index discussion. I think it showed: Sometimes users get confused by the plumbing man pages who shouldn't even read them at all (and rather stick with porcelain commands). - A phrase Main user interface command to a new user does not help very much if it does not tell enough what that phrase really means (e.g. you should not be using it for scripting). Extend the description more, after moving it to the end. I'm all open for different wording, this is just a POC. Even though I think that it should be okay to use a term like porcelain (defined in the glossary) the same way as we use other central terms (revision, object) which we don't spell out in each man page. The point is to give some direction. - As you said, this should be done in a way to keep the two sources of information in sync. Either add these from command-list, or generate command-list from these. Does the categorisation change a lot? My impression is that this is a one-time business like adding a new command, which causes redundant work already. If we really want to automate it, Doc/Makefile would probably need to translate foo.txt to foo.txt+ and operate on that. I'm not sure automatisation is worth that effort. Michael -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[RFD/PATCH] Documentation: mention category
Quite a few users seem to get confused about which commands to use as the main git interface. While `git --help' gives an overview, users seem to discover commands from the man page which does not tell them to stay away from plumbing commands first. Introduce a category section in each man page which helps users decide whether to read on at all. Signed-off-by: Michael J Gruber g...@drmicha.warpmail.net --- This is just a suggestion to give new users better orientation. The naming for the categories is up for discussion, of course. The categorization itself is taken from command-list.txt and translated via: ---%--- case $category in ancillaryinterrogators*) out=Ancillary interrogator ;; ancillarymanipulator*) out=Ancillary manipulator ;; foreignscminterface*) out=Interface to foreign SCM ;; mainporcelain*) out=Main user interface command (porcelain) ;; plumbing*) out=Low level command for script writers (plumbing) ;; purehelpers*) out=Helper command for script writers ;; sync*) out=Commands used internally for synching repositories ;; *) out= echo What to do with $command - $category ;; esac ---%--- Rather than changing git-foo.txt, we could do the substitution magic from Documentation/Makefile, of course, to keep man pages and command-list in sync. Although this would keep me from submitting the final series with 1 patch per file :) Documentation/git-add.txt| 4 Documentation/git-am.txt | 4 Documentation/git-annotate.txt | 4 Documentation/git-apply.txt | 4 Documentation/git-archimport.txt | 4 Documentation/git-archive.txt| 4 Documentation/git-bisect.txt | 4 Documentation/git-blame.txt | 4 Documentation/git-branch.txt | 4 Documentation/git-bundle.txt | 4 Documentation/git-cat-file.txt | 4 Documentation/git-check-attr.txt | 4 Documentation/git-check-ignore.txt | 4 Documentation/git-check-mailmap.txt | 4 Documentation/git-check-ref-format.txt | 4 Documentation/git-checkout-index.txt | 4 Documentation/git-checkout.txt | 4 Documentation/git-cherry-pick.txt| 4 Documentation/git-cherry.txt | 4 Documentation/git-citool.txt | 4 Documentation/git-clean.txt | 4 Documentation/git-clone.txt | 4 Documentation/git-column.txt | 4 Documentation/git-commit-tree.txt| 4 Documentation/git-commit.txt | 4 Documentation/git-config.txt | 4 Documentation/git-count-objects.txt | 4 Documentation/git-credential-cache.txt | 4 Documentation/git-credential-store.txt | 4 Documentation/git-credential.txt | 4 Documentation/git-cvsexportcommit.txt| 4 Documentation/git-cvsimport.txt | 4 Documentation/git-cvsserver.txt | 4 Documentation/git-daemon.txt | 4 Documentation/git-describe.txt | 4 Documentation/git-diff-files.txt | 4 Documentation/git-diff-index.txt | 4 Documentation/git-diff-tree.txt | 4 Documentation/git-diff.txt | 4 Documentation/git-difftool.txt | 4 Documentation/git-fast-export.txt| 4 Documentation/git-fast-import.txt| 4 Documentation/git-fetch-pack.txt | 4 Documentation/git-fetch.txt | 4 Documentation/git-filter-branch.txt | 4 Documentation/git-fmt-merge-msg.txt | 4 Documentation/git-for-each-ref.txt | 4 Documentation/git-format-patch.txt | 4 Documentation/git-fsck.txt | 4 Documentation/git-gc.txt | 4 Documentation/git-get-tar-commit-id.txt | 4 Documentation/git-grep.txt | 4 Documentation/git-gui.txt| 4 Documentation/git-hash-object.txt| 4 Documentation/git-help.txt | 4 Documentation/git-http-backend.txt | 4 Documentation/git-http-fetch.txt | 4 Documentation/git-http-push.txt | 4 Documentation/git-imap-send.txt | 4 Documentation/git-index-pack.txt | 4 Documentation/git-init.txt | 4 Documentation/git-instaweb.txt | 4 Documentation/git-interpret-trailers.txt | 4 Documentation/git-log.txt| 4
Re: [RFD/PATCH] Documentation: mention category
Michael J Gruber g...@drmicha.warpmail.net writes: Rather than changing git-foo.txt, we could do the substitution magic from Documentation/Makefile, of course, to keep man pages and command-list in sync. Although this would keep me from submitting the final series with 1 patch per file :) I do not get that smiley. Are you saying that these noisy patches add to your karma points? diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 9631526..b6a8bc6 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -13,6 +13,10 @@ SYNOPSIS [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--] [pathspec...] +CATEGORY + +Main user interface command (porcelain) + DESCRIPTION --- While I do not have objection to adding this information, I have a few problems with the execution: - These four lines at the very beginning is a precious real estate. The new reader would not benefit from the distinction before reading the first paragraph of description to learn what it does and what it is for anyway. Move it much later, perhaps at the end. - A phrase Main user interface command to a new user does not help very much if it does not tell enough what that phrase really means (e.g. you should not be using it for scripting). Extend the description more, after moving it to the end. - As you said, this should be done in a way to keep the two sources of information in sync. Either add these from command-list, or generate command-list from these. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
