From mboxrd@z Thu Jan 1 00:00:00 1970 From: =?utf-8?B?xaB0xJtww6FuIE7Em21lYw==?= Subject: [PATCH/RFC] Unify argument and option notation in the docs Date: Fri, 8 Oct 2010 02:52:56 +0200 Message-ID: <20101008005256.GA21738@headley> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Cc: git@vger.kernel.org, Jonathan Nieder To: Junio C Hamano X-From: git-owner@vger.kernel.org Fri Oct 08 02:54:18 2010 Return-path: Envelope-to: gcvg-git-2@lo.gmane.org Received: from vger.kernel.org ([209.132.180.67]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1P41E0-0002QA-Cs for gcvg-git-2@lo.gmane.org; Fri, 08 Oct 2010 02:54:17 +0200 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755008Ab0JHAyJ (ORCPT ); Thu, 7 Oct 2010 20:54:09 -0400 Received: from mail-bw0-f46.google.com ([209.85.214.46]:47631 "EHLO mail-bw0-f46.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751247Ab0JHAyG (ORCPT ); Thu, 7 Oct 2010 20:54:06 -0400 Received: by bwz11 with SMTP id 11so335124bwz.19 for ; Thu, 07 Oct 2010 17:54:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:received:date:from:to:cc:subject :message-id:mail-followup-to:mime-version:content-type :content-disposition:user-agent; bh=DsCi9qbbayYDOkvD7+K/TaJdbzr+KcAAU1M4Epg6sfI=; b=Zg3LudH7SbkR+l46oWQlmAyNb+hEAkSbwSBNOA0gdSgh5+WkhAQMCd2E9NoeBevyRv 3dKFTvGAu4JyWw7tap5aKzBsrnZEXnZczV+3pCOG8oRWVLDQtLm9IOsQ4fC6SXcPARmW N1MM+4ZeXxXZSyWDzDIKB8jZoqc7ayj7SiVuQ= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=date:from:to:cc:subject:message-id:mail-followup-to:mime-version :content-type:content-disposition:user-agent; b=vFbxr7Y9zJJJxGk7WwnybLBdxW6UtMgnIaCMiQt+Z4a/z2eEmDmv2MJCX0oWAx60IG D4Lz15DWWL1YKUGxUhSo9vk0MbW6ZuGnX3MuP/ZRUwMlz4IDRU8VLYsMW6E63h0Vfagj VzbiAJ5bSnc2DPU01j6X87i64asSgVvtWbmVc= Received: by 10.204.121.84 with SMTP id g20mr1357479bkr.37.1286499241034; Thu, 07 Oct 2010 17:54:01 -0700 (PDT) Received: from localhost (176.119.broadband10.iol.cz [90.177.119.176]) by mx.google.com with ESMTPS id v7sm2122457bkx.4.2010.10.07.17.53.57 (version=TLSv1/SSLv3 cipher=RC4-MD5); Thu, 07 Oct 2010 17:53:59 -0700 (PDT) Mail-Followup-To: Junio C Hamano , git@vger.kernel.org, Jonathan Nieder Content-Disposition: inline User-Agent: Mutt/1.5.20 (2009-06-14) Sender: git-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Archived-At: In general, the current usage is already pretty consistent, so it is not too hard to induce the guidelines and correct the rest based on them. Some examples of what this patch is based on (i.e., the current prevalent usage) follow (all coming from existing documentation): Placeholders are enclosed in angle brackets: --sort= --abbrev[=] Possibility of multiple occurences is indicated by three dots: ... (One or more of .) Optional parts are enclosed in square brackets: git-archive: [] (Zero or one .) git-apply: [...] (Any number of . Note that the dots are inside, not outside the brackets.) Parentheses are used for grouping: git-bisect: [(|)...] (Any number of either or . Parens are needed to make it clear that `...' pertains to both and .) git-remote: git remote set-head (-a | -d | ) (One and only one of `-a', `-d' or `' _must_ (no square brackets) be provided.) Limited number of occurences is indicated as follows: git-diff: {0,2} (Up to two s.) --- [It is conceivable I could submit this as a series of smaller patches, but the problems this is solving didn't seem diverse enough to me to warrant that. As for the "methodology" used -- I grepped for places similar to what I wanted to fix (cf. , then I noticed other related problems and grepped for them etc. All the edits are manual, though.] Two questions: 1. Is `[--refs [--unpacked | --all]]' in `git-pack-object' documentation correct? From my reading of builtin/pack-objects.c, `--unpacked' and `--all' do the same thing and both imply --refs, so perhaps [--refs | --unpacked | --all] would make more sense? (I also noticed that the --reflog option is shown in the usage string but undocumented.) 2. I left in one special case, namely the GIT_* variables in `git(1)' synopsis section as values for the `--exec-path' and other options. Further in the text the usual placeholders are used and I believe those should be used in the synopsis as well, but whoever used the GIT_* variables obviously did it to point out that they provide an alternative way to set those options, so I figured I'd leave them in for now and ask for opinions first. Documentation/diff-options.txt | 14 +++++----- Documentation/git-am.txt | 4 +- Documentation/git-apply.txt | 6 ++-- Documentation/git-archive.txt | 4 +- Documentation/git-bundle.txt | 6 ++-- Documentation/git-checkout-index.txt | 2 +- Documentation/git-commit-tree.txt | 2 +- Documentation/git-daemon.txt | 48 +++++++++++++++++----------------- Documentation/git-fast-export.txt | 2 +- Documentation/git-fetch.txt | 2 +- Documentation/git-filter-branch.txt | 2 +- Documentation/git-for-each-ref.txt | 2 +- Documentation/git-index-pack.txt | 4 +- Documentation/git-init.txt | 2 +- Documentation/git-ls-files.txt | 2 +- Documentation/git-ls-tree.txt | 10 +++--- Documentation/git-mailsplit.txt | 2 +- Documentation/git-mergetool.txt | 2 +- Documentation/git-pack-objects.txt | 16 +++++----- Documentation/git-relink.txt | 2 +- Documentation/git-remote.txt | 2 +- Documentation/git-repack.txt | 12 ++++---- Documentation/git-rev-list.txt | 18 ++++++------ Documentation/git-rev-parse.txt | 2 +- Documentation/git-shortlog.txt | 2 +- Documentation/git-show-branch.txt | 2 +- Documentation/git-svn.txt | 2 +- Documentation/git-update-index.txt | 4 +- Documentation/git-web--browse.txt | 16 +++++----- Documentation/git.txt | 6 ++-- Documentation/merge-strategies.txt | 2 +- Documentation/pretty-options.txt | 4 +- Documentation/rev-list-options.txt | 18 ++++++------ Documentation/user-manual.txt | 2 +- archive.c | 4 +- builtin/bundle.c | 4 +- builtin/checkout-index.c | 2 +- builtin/commit-tree.c | 2 +- builtin/fetch.c | 2 +- builtin/grep.c | 2 +- builtin/index-pack.c | 2 +- builtin/ls-files.c | 2 +- builtin/ls-tree.c | 2 +- builtin/mailsplit.c | 2 +- builtin/pack-objects.c | 10 +++--- builtin/remote.c | 2 +- builtin/rev-list.c | 8 +++--- builtin/show-branch.c | 2 +- builtin/update-index.c | 2 +- daemon.c | 18 ++++++------ fast-import.c | 2 +- git-am.sh | 2 +- git-relink.perl | 2 +- git.c | 4 +- upload-pack.c | 2 +- 55 files changed, 152 insertions(+), 152 deletions(-) diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index f77a0f8..719f589 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -48,9 +48,9 @@ endif::git-format-patch[] --patience:: Generate a diff using the "patience diff" algorithm. ---stat[=width[,name-width]]:: +--stat[=[,]]:: Generate a diffstat. You can override the default - output width for 80-column terminal by `--stat=width`. + output width for 80-column terminal by `--stat=`. The width of the filename part can be controlled by giving another width to it separated by a comma. @@ -66,14 +66,14 @@ endif::git-format-patch[] number of modified files, as well as number of added and deleted lines. ---dirstat[=limit]:: +--dirstat[=]:: Output the distribution of relative amount of changes (number of lines added or removed) for each sub-directory. Directories with changes below a cut-off percent (3% by default) are not shown. The cut-off percent - can be set with `--dirstat=limit`. Changes in a child directory is not + can be set with `--dirstat=`. Changes in a child directory are not counted for the parent directory, unless `--cumulative` is used. ---dirstat-by-file[=limit]:: +--dirstat-by-file[=]:: Same as `--dirstat`, but counts changed files instead of lines. --summary:: @@ -248,13 +248,13 @@ endif::git-log[] If `n` is specified, it has the same meaning as for `-M`. ifndef::git-format-patch[] ---diff-filter=[ACDMRTUXB*]:: +--diff-filter=:: + '' can be any combination of the characters `ACDMRTUXB*`. Select only files that are Added (`A`), Copied (`C`), Deleted (`D`), Modified (`M`), Renamed (`R`), have their type (i.e. regular file, symlink, submodule, ...) changed (`T`), are Unmerged (`U`), are Unknown (`X`), or have had their pairing Broken (`B`). - Any combination of the filter characters may be used. When `*` (All-or-none) is added to the combination, all paths are selected if there is any file that matches other criteria in the comparison; if there is no file diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 9e62f87..51297d0 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -14,7 +14,7 @@ SYNOPSIS [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=