| Message ID | pull.774.git.1603889270.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | blame: enable funcname blaming with userdiff driver | expand |
On Wed, Oct 28, 2020 at 8:48 AM Philippe Blain via GitGitGadget <gitgitgadget@gmail.com> wrote: > Improve the formatting of the description of the line-range option '-L' > for `git log`, `gitk` and `git blame`: > > - Use bold for <start>, <end> and <funcname> My impression is that it is more common in Git documentation for these placeholders to be formatted with backticks rather than as bold (or, if not more common currently, at least is trending that way). That's not to say that my impression is necessarily accurate.
On Wed, Oct 28, 2020 at 8:48 AM Philippe Blain via GitGitGadget <gitgitgadget@gmail.com> wrote: > Several Git commands can make use of the builtin userdiff patterns, but > it's not obvious in the documentation. Add pointers to the 'Defining a > custom hunk header' part of gitattributes(5) in the description of the > following options: > [...] > Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> > --- > diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt > @@ -695,7 +695,10 @@ endif::git-format-patch[] > --function-context:: > - Show whole surrounding functions of changes. > + Show whole functions as context lines for each changes. s/changes/change/ > + The function names are determined in the same way as > + `git diff` works out patch hunk headers (see 'Defining a > + custom hunk-header' in linkgit:gitattributes[5]).
Eric Sunshine <sunshine@sunshineco.com> writes: > On Wed, Oct 28, 2020 at 8:48 AM Philippe Blain via GitGitGadget > <gitgitgadget@gmail.com> wrote: >> Improve the formatting of the description of the line-range option '-L' >> for `git log`, `gitk` and `git blame`: >> >> - Use bold for <start>, <end> and <funcname> > > My impression is that it is more common in Git documentation for these > placeholders to be formatted with backticks rather than as bold (or, > if not more common currently, at least is trending that way). That's > not to say that my impression is necessarily accurate. I think the impression is fairly in line with the reality. That is not to say that it is a good future to aim for. My personal preference is - use `as-is` for things that must be typed as-is (e.g. `-L`) - use 'emph' for things that are placeholder (e.g. '<start>'').
> Le 29 oct. 2020 à 16:19, Junio C Hamano <gitster@pobox.com> a écrit : > > Eric Sunshine <sunshine@sunshineco.com> writes: > >> On Wed, Oct 28, 2020 at 8:48 AM Philippe Blain via GitGitGadget >> <gitgitgadget@gmail.com> wrote: >>> Improve the formatting of the description of the line-range option '-L' >>> for `git log`, `gitk` and `git blame`: >>> >>> - Use bold for <start>, <end> and <funcname> >> >> My impression is that it is more common in Git documentation for these >> placeholders to be formatted with backticks rather than as bold (or, >> if not more common currently, at least is trending that way). That's >> not to say that my impression is necessarily accurate. > > I think the impression is fairly in line with the reality. Yes, I compared using git grep '`<' | wc -l and git grep "'<" | wc -l and the same for their closing counterparts and the backticks win. > That is > not to say that it is a good future to aim for. > > My personal preference is > > - use `as-is` for things that must be typed as-is (e.g. `-L`) > > - use 'emph' for things that are placeholder (e.g. '<start>''). Thanks for clarifying. It is indeed what I tried to do.