From c455bd8950e0e5593949b746ad96d1449bbbf9d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0t=C4=9Bp=C3=A1n=20N=C4=9Bmec?= Date: Thu, 4 Nov 2010 18:12:48 +0100 Subject: [PATCH 1/3] CodingGuidelines: Add a section on writing documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Provide a few examples on argument and option notation in usage strings and command synopses. Signed-off-by: Štěpán Němec Signed-off-by: Junio C Hamano --- Documentation/CodingGuidelines | 52 ++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 09ffc4656..5aa2d34f8 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -139,3 +139,55 @@ For C programs: - When we pass pair to functions, we should try to pass them in that order. + +Writing Documentation: + + Every user-visible change should be reflected in the documentation. + The same general rule as for code applies -- imitate the existing + conventions. A few commented examples follow to provide reference + when writing or modifying command usage strings and synopsis sections + in the manual pages: + + 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: + [] + (Zero or one .) + + --exec-path[=] + (Option with an optional argument. Note that the "=" is inside the + brackets.) + + [...] + (Zero or more of . Note that the dots are inside, not + outside the brackets.) + + Multiple alternatives are indicated with vertical bar: + [-q | --quiet] + [--utf8 | --no-utf8] + + Parentheses are used for grouping: + [(|)...] + (Any number of either or . Parens are needed to make + it clear that "..." pertains to both and .) + + [(-p )...] + (Any number of option -p, each with one argument.) + + git remote set-head (-a | -d | ) + (One and only one of "-a", "-d" or "" _must_ (no square + brackets) be provided.) + + And a somewhat more contrived example: + --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]] + Here "=" is outside the brackets, because "--diff-filter=" is a + valid usage. "*" has its own pair of brackets, because it can + (optionally) be specified only when one or more of the letters is + also provided. From 9edb8a0f7b3e2ca06b360abce2e2aaa2b5760a68 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0t=C4=9Bp=C3=A1n=20N=C4=9Bmec?= Date: Thu, 4 Nov 2010 18:18:17 +0100 Subject: [PATCH 2/3] diff,difftool: Don't use the {0,2} notation in usage strings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This was the only occurence of that usage, and square brackets are sufficient and already well-established for that purpose. Signed-off-by: Štěpán Němec Acked-by: Sverre Rabbelier Signed-off-by: Junio C Hamano --- Documentation/git-diff.txt | 2 +- Documentation/git-difftool.txt | 2 +- builtin/diff.c | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index dd1fb3278..61728f697 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -8,7 +8,7 @@ git-diff - Show changes between commits, commit and working tree, etc SYNOPSIS -------- -'git diff' [] {0,2} [--] [...] +'git diff' [] [ []] [--] [...] DESCRIPTION ----------- diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 8250bad2c..a02e3b519 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -7,7 +7,7 @@ git-difftool - Show changes using common diff tools SYNOPSIS -------- -'git difftool' [] {0,2} [--] [...] +'git difftool' [] [ []] [--] [...] DESCRIPTION ----------- diff --git a/builtin/diff.c b/builtin/diff.c index a43d32636..945e7583a 100644 --- a/builtin/diff.c +++ b/builtin/diff.c @@ -22,7 +22,7 @@ struct blobinfo { }; static const char builtin_diff_usage[] = -"git diff {0,2} -- *"; +"git diff [] [ []] [--] [...]"; static void stuff_change(struct diff_options *opt, unsigned old_mode, unsigned new_mode, From 49bd56a5f7b09f89b59a6a77d331e8f85f6d7fde Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 4 Nov 2010 17:17:29 -0400 Subject: [PATCH 3/3] docs: clarify git diff modes of operation It is an oversimplification to say that we can take "[ []]", as it really depends on what options have been given. Instead, let's list the major modes of operation separately, as we do in other manpages. This patch also adjusts the text immediately after the synopsis to match the lines given in the synopsis. For git-difftool, which has the same issue, let's refer the user to the git-diff manpage rather than spelling it all out again. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/git-diff.txt | 11 ++++++++--- Documentation/git-difftool.txt | 3 ++- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 61728f697..f6ac84750 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -8,12 +8,17 @@ git-diff - Show changes between commits, commit and working tree, etc SYNOPSIS -------- -'git diff' [] [ []] [--] [...] +[verse] +'git diff' [options] [] [--] [...] +'git diff' [options] --cached [] [--] [...] +'git diff' [options] [--] [...] +'git diff' [options] [--no-index] [--] DESCRIPTION ----------- -Show changes between two trees, a tree and the working tree, a -tree and the index file, or the index file and the working tree. +Show changes between the working tree and the index or a tree, changes +between the index and a tree, changes between two trees, or changes +between two files on disk. 'git diff' [--options] [--] [...]:: diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index a02e3b519..6fffbc7bf 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -13,7 +13,8 @@ DESCRIPTION ----------- 'git difftool' is a git command that allows you to compare and edit files between revisions using common diff tools. 'git difftool' is a frontend -to 'git diff' and accepts the same options and arguments. +to 'git diff' and accepts the same options and arguments. See +linkgit:git-diff[1]. OPTIONS -------