Re: [PATCH 3/3] doc: notes: unify configuration variables definitions

[Junio C Hamano <gitster@pobox.com>]

Matheus Tavares <matheus.bernardino@usp.br> writes:

>  	`cat_sort_uniq`.  Defaults to `manual`.  See "NOTES MERGE STRATEGIES"
> -	section of linkgit:git-notes[1] for more information on each strategy.
> +	section
> +ifdef::git-notes[above]
> +ifndef::git-notes[of linkgit:git-notes[1]]
> +	for more information on each strategy.

This is the first use of the single line ifdef/ifndef in our
Documentation.  I assume you have verified the rendered output on
both AsciiDoc and AsciiDoctor?

> -	"notes.mergeStrategy".  See the "NOTES MERGE STRATEGIES" section in
> -	linkgit:git-notes[1] for more information on the available strategies.
> +	"notes.mergeStrategy".  See the "NOTES MERGE STRATEGIES" section
> +ifdef::git-notes[above]
> +ifndef::git-notes[in linkgit:git-notes[1]]
> +	for more information on the available strategies.

Ditto.

>  notes.displayRef::
> -	The (fully qualified) refname from which to show notes when
> -	showing commit messages.  The value of this variable can be set
> -	to a glob, in which case notes from all matching refs will be
> -	shown.  You may also specify this configuration variable
> -	several times.  A warning will be issued for refs that do not
> -	exist, but a glob that does not match any refs is silently
> -	ignored.
> -+
> -This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
> -environment variable, which must be a colon separated list of refs or
> -globs.
> -+
> -The effective value of "core.notesRef" (possibly overridden by
> -GIT_NOTES_REF) is also implicitly added to the list of refs to be
> -displayed.
> +	Which ref (or refs, if a glob or specified more than once), in
> +	addition to the default set by `core.notesRef` or
> +	`GIT_NOTES_REF`, to read notes from when showing commit
> +	messages with the 'git log' family of commands.
> +	This setting can be overridden on the command line or by the
> +	`GIT_NOTES_DISPLAY_REF` environment variable.
> +	See linkgit:git-log[1].

This is unrelated to the "unify description in git-foo.txt and
config/foo.txt in the documentation" topic, isn't it?

I haven't formed an opinion on the updated text, and it makes it
harder to review when the content change is mixed in the "unify
description in two places" topic, so I won't comment on the change
of the contents.  Please split them into two steps (a step with only
content change, and then another step to remove the duplicated one
by making one include the other).  Same comment applies to [2/3].

>  notes.rewrite.<command>::
>  	When rewriting commits with <command> (currently `amend` or
> -	`rebase`) and this variable is set to `true`, Git
> -	automatically copies your notes from the original to the
> -	rewritten commit.  Defaults to `true`, but see
> -	"notes.rewriteRef" below.
> +	`rebase`), if this variable is `false`, git will not copy
> +	notes from the original to the rewritten commit.  Defaults to
> +	`true`.  See also "`notes.rewriteRef`" below.
> ++
> +This setting can be overridden by the `GIT_NOTES_REWRITE_REF`
> +environment variable.

Ditto.

>  notes.rewriteMode::
> -	When copying notes during a rewrite (see the
> -	"notes.rewrite.<command>" option), determines what to do if
> -	the target commit already has a note.  Must be one of
> -	`overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.
> -	Defaults to `concatenate`.
> +	When copying notes during a rewrite, what to do if the target
> +	commit already has a note.  Must be one of `overwrite`,
> +	`concatenate`, `cat_sort_uniq`, or `ignore`.  Defaults to
> +	`concatenate`.
>  +
>  This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
>  environment variable.

We are losing the mention of "notes.rewrite.<command>", which is
outside the "unify" topic, isn't it?

>  notes.rewriteRef::
>  	When copying notes during a rewrite, specifies the (fully
> -	qualified) ref whose notes should be copied.  The ref may be a
> -	glob, in which case notes in all matching refs will be copied.
> -	You may also specify this configuration several times.
> +	qualified) ref whose notes should be copied.  May be a glob,
> +	in which case notes in all matching refs will be copied.  You
> +	may also specify this configuration several times.
>  +
>  Does not have a default value; you must configure this variable to
>  enable note rewriting.  Set it to `refs/notes/commits` to enable
>  rewriting for the default commit notes.
>  +
> -This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
> -environment variable, which must be a colon separated list of refs or
> -globs.
> +Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.

Ditto.

Thanks.