[v3,0/5] doc: git diff reformatting

Message

Jean-Noël Avila via GitGitGadget Nov. 16, 2024, 7:36 p.m. UTC

This is the continuation of the editing of the manpages to reflect the new
formatting rules.

Changes since V1:

 * restate the formatting rules in the message of the first commit
 * fix typos
 * convert more parts to backticked
 * filter out most annoying self-referencing links
 * propose to separate with 'or' the -1 --ours options and the likes

Jean-Noël Avila (5):
  doc: git-diff: apply new documentation guidelines
  doc: git-diff: apply format changes to diff-options
  doc: git-diff: apply format changes to diff-format
  doc: git-diff: apply format changes to diff-generate-patch
  doc: git-diff: apply format changes to config part

 Documentation/config/diff.txt         | 204 +++++++------
 Documentation/diff-format.txt         |  42 +--
 Documentation/diff-generate-patch.txt |  44 +--
 Documentation/diff-options.txt        | 423 +++++++++++++-------------
 Documentation/git-diff.txt            | 108 +++----
 5 files changed, 424 insertions(+), 397 deletions(-)


base-commit: facbe4f633e4ad31e641f64617bc88074c659959
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1769%2Fjnavila%2Fgit_diff_new-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1769/jnavila/git_diff_new-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1769

Range-diff vs v2:

 1:  c104bd50b64 ! 1:  6841bd5825b doc: git-diff: apply new documentation guidelines
     @@ Metadata
       ## Commit message ##
          doc: git-diff: apply new documentation guidelines
      
     +    The documentation for git-diff has been updated to follow the new
     +    documentation guidelines. The following changes have been applied to
     +    the series of patches:
     +
     +    - switching the synopsis to a synopsis block which will automatically
     +      format placeholders in italics and keywords in monospace
     +    - use _<placeholder>_ instead of <placeholder> in the description
     +    - use `backticks for keywords and more complex option
     +    descriptions`. The new rendering engine will apply synopsis rules to
     +    these spans.
     +    - prevent git-diff from self-referencing itself via gitlink macro when
     +    the generated link would point to the same page.
     +
          Signed-off-by: Jean-Noël Avila <[e-mail]>
      
       ## Documentation/git-diff.txt ##
     @@ Documentation/git-diff.txt: OPTIONS
      --1 --base::
      --2 --ours::
      --3 --theirs::
     -+`-1` `--base`::
     -+`-2` `--ours`::
     -+`-3` `--theirs`::
     ++`-1`::
     ++`--base`::
     ++
     ++or `-2`::
     ++`--ours`::
     ++
     ++or `-3`::
     ++`--theirs`::
       	Compare the working tree with the "base" version (stage #1),
       	"our branch" (stage #2) or "their branch" (stage #3).  The
       	index contains these stages only for unmerged entries i.e.
     @@ Documentation/git-diff.txt: OPTIONS
       
      -<path>...::
      -	The <paths> parameters, when given, are used to limit
     -+_<path>_...::
     ++`<path>...`::
      +	The _<path>_ parameters, when given, are used to limit
       	the diff to the named paths (you can give directory
       	names and get diff for all files under them).
 2:  129763c2aae = 2:  07df397741b doc: git-diff: apply format changes to diff-options
 3:  8fec37ee174 = 3:  698628e076b doc: git-diff: apply format changes to diff-format
 4:  daed146639d = 4:  1154462f8be doc: git-diff: apply format changes to diff-generate-patch
 5:  17a2f028d59 ! 5:  4ec2fd9c3c6 doc: git-diff: apply format changes to config part
     @@ Metadata
       ## Commit message ##
          doc: git-diff: apply format changes to config part
      
     +    By the way, we also change the sentences where git-diff would refer to
     +    itself, so that no link is created in the HTML output.
     +
          Signed-off-by: Jean-Noël Avila <[e-mail]>
      
       ## Documentation/config/diff.txt ##
     @@ Documentation/config/diff.txt
       	Instead, silently run `git update-index --refresh` to
       	update the cached stat information for paths whose
       	contents in the work tree match the contents in the
     - 	index.  This option defaults to true.  Note that this
     +-	index.  This option defaults to true.  Note that this
      -	affects only 'git diff' Porcelain, and not lower level
      -	'diff' commands such as 'git diff-files'.
     ++	index.  This option defaults to `true`.  Note that this
      +	affects only `git diff` Porcelain, and not lower level
     -+	`diff` commands such as '`git diff-files`.
     ++	`diff` commands such as `git diff-files`.
       
      -diff.dirstat::
      +`diff.dirstat`::
     ++ifdef::git-diff[]
     ++	A comma separated list of `--dirstat` parameters specifying the
     ++	default behavior of the `--dirstat` option to `git diff` and friends.
     ++endif::git-diff[]
     ++ifndef::git-diff[]
       	A comma separated list of `--dirstat` parameters specifying the
       	default behavior of the `--dirstat` option to linkgit:git-diff[1]
     - 	and friends. The defaults can be overridden on the command line
     +-	and friends. The defaults can be overridden on the command line
      -	(using `--dirstat=<param1,param2,...>`). The fallback defaults
     ++	and friends.
     ++endif::git-diff[]
     ++	The defaults can be overridden on the command line
      +	(using `--dirstat=<param>,...`). The fallback defaults
       	(when not changed by `diff.dirstat`) are `changes,noncumulative,3`.
       	The following parameters are available:
     @@ Documentation/config/diff.txt: directories with less than 10% of the total amoun
       
      -diff.mnemonicPrefix::
      -	If set, 'git diff' uses a prefix pair that is different from the
     +-	standard "a/" and "b/" depending on what is being compared.  When
      +`diff.mnemonicPrefix`::
      +	If set, `git diff` uses a prefix pair that is different from the
     - 	standard "a/" and "b/" depending on what is being compared.  When
     ++	standard `a/` and `b/` depending on what is being compared.  When
       	this configuration is in effect, reverse diff output also swaps
       	the order of the prefixes:
     + `git diff`;;
      @@ Documentation/config/diff.txt: diff.mnemonicPrefix::
       	 compares a (c)ommit and the (w)ork tree;
       `git diff --cached`;;
     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::
      -`git diff HEAD:file1 file2`;;
      +`git diff HEAD:<file1> <file2>`;;
       	compares an (o)bject and a (w)ork tree entity;
     - `git diff --no-index a b`;;
     - 	compares two non-git things (1) and (2).
     +-`git diff --no-index a b`;;
     +-	compares two non-git things (1) and (2).
     ++`git diff --no-index <a> <b>`;;
     ++	compares two non-git things _<a>_ and _<b>_.
       
      -diff.noPrefix::
      -	If set, 'git diff' does not show any source or destination prefix.
     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::
      -diff.srcPrefix::
      -	If set, 'git diff' uses this source prefix. Defaults to "a/".
      +`diff.srcPrefix`::
     -+	If set, `git diff` uses this source prefix. Defaults to "a/".
     ++	If set, `git diff` uses this source prefix. Defaults to `a/`.
       
      -diff.dstPrefix::
      -	If set, 'git diff' uses this destination prefix. Defaults to "b/".
      +`diff.dstPrefix`::
     -+	If set, `git diff` uses this destination prefix. Defaults to "b/".
     ++	If set, `git diff` uses this destination prefix. Defaults to `b/`.
       
      -diff.relative::
      -	If set to 'true', 'git diff' does not show changes outside of the directory
     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::
      +`diff.orderFile`::
       	File indicating how to order files within a diff.
      -	See the '-O' option to linkgit:git-diff[1] for details.
     ++ifdef::git-diff[]
     ++	See the `-O` option for details.
     ++endif::git-diff[]
     ++ifndef::git-diff[]
      +	See the `-O` option to linkgit:git-diff[1] for details.
     ++endif::git-diff[]
       	If `diff.orderFile` is a relative pathname, it is treated as
       	relative to the top of the working tree.
       
     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::
      -	Whether and how Git detects renames.  If set to "false",
      -	rename detection is disabled. If set to "true", basic rename
      -	detection is enabled.  If set to "copies" or "copy", Git will
     +-	detect copies, as well.  Defaults to true.  Note that this
     +-	affects only 'git diff' Porcelain like linkgit:git-diff[1] and
      +`diff.renames`::
      +	Whether and how Git detects renames.  If set to `false`,
      +	rename detection is disabled. If set to `true`, basic rename
      +	detection is enabled.  If set to `copies` or `copy`, Git will
     - 	detect copies, as well.  Defaults to true.  Note that this
     --	affects only 'git diff' Porcelain like linkgit:git-diff[1] and
     ++	detect copies, as well.  Defaults to `true`.  Note that this
      +	affects only `git diff` Porcelain like linkgit:git-diff[1] and
       	linkgit:git-log[1], and not lower level commands such as
       	linkgit:git-diff-files[1].
     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::
       	for details.
       
      -diff.<driver>.trustExitCode::
     +-	If this boolean value is set to true then the
      +`diff.<driver>.trustExitCode`::
     - 	If this boolean value is set to true then the
     ++	If this boolean value is set to `true` then the
       	`diff.<driver>.command` command is expected to return exit code
       	0 if it considers the input files to be equal or 1 if it
      -	considers them to be different, like `diff(1)`.
     +-	If it is set to false, which is the default, then the command
      +	considers them to be different, like `diff`(1).
     - 	If it is set to false, which is the default, then the command
     ++	If it is set to `false`, which is the default, then the command
       	is expected to return exit code 0 regardless of equality.
       	Any other exit code causes Git to report a fatal error.
       
     @@ Documentation/config/diff.txt: diff.mnemonicPrefix::
       	details.
       
      -diff.<driver>.cachetextconv::
     +-	Set this option to true to make the diff driver cache the text
      +`diff.<driver>.cachetextconv`::
     - 	Set this option to true to make the diff driver cache the text
     ++	Set this option to `true` to make the diff driver cache the text
       	conversion outputs.  See linkgit:gitattributes[5] for details.
       
       include::../mergetools-diff.txt[]
     @@ Documentation/config/diff.txt: diff.wsErrorHighlight::
       
      -diff.colorMoved::
      -	If set to either a valid `<mode>` or a true value, moved lines
     -+`diff.colorMoved`::
     -+	If set to either a valid _<mode>_ or a true value, moved lines
     - 	in a diff are colored differently, for details of valid modes
     +-	in a diff are colored differently, for details of valid modes
      -	see '--color-moved' in linkgit:git-diff[1]. If simply set to
      -	true the default color mode will be used. When set to false,
     -+	see `--color-moved` in linkgit:git-diff[1]. If simply set to
     -+	`true` the default color mode will be used. When set to `false`,
     - 	moved lines are not colored.
     - 
     +-	moved lines are not colored.
     +-
      -diff.colorMovedWS::
     ++`diff.colorMoved`::
     ++	If set to either a valid _<mode>_ or a `true` value, moved lines
     ++	in a diff are colored differently.
     ++ifdef::git-diff[]
     ++	For details of valid modes see `--color-moved`.
     ++endif::git-diff[]
     ++ifndef::git-diff[]
     ++	For details of valid modes see `--color-moved` in linkgit:git-diff[1].
     ++endif::git-diff[]
     ++	If simply set to `true` the default color mode will be used. When
     ++	set to `false`, moved lines are not colored.
     ++
      +`diff.colorMovedWS`::
       	When moved lines are colored using e.g. the `diff.colorMoved` setting,
      -	this option controls the `<mode>` how spaces are treated.