doc: git-add.txt: convert to new style convention

[jnavila]

No description provided.

[jnavila]

/submit

[gitgitgadget]

Submitted as [email protected]

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1826/jnavila/new_git_add-v1

To fetch this version to local tag pr-1826/jnavila/new_git_add-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1826/jnavila/new_git_add-v1

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Jean-Noël Avila via GitGitGadget" <[email protected]> writes:

> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
>
> Signed-off-by: Jean-Noël Avila <[email protected]>
> ---
>     doc: git-add.txt: convert to new style convention

This does slightly more than converting to new style, though,
doesn't it?  Is it so annoying to see a link that points at the same
page you are reading right now to warrant duplicating some docs with
conditional inclusion?

> +`add.ignoreErrors`::
> +`add.ignore-errors` (deprecated)::
> +	Tells `git add` to continue adding files when some files cannot be
> +	added due to indexing errors.
> +ifdef::git-add[]
> +	Equivalent to the `--ignore-errors` option.
> +endif::git-add[]
> +ifndef::git-add[]
> +	Equivalent to the `--ignore-errors` option of linkgit:git-add[1].
> +endif::git-add[]

>  SYNOPSIS
>  --------
> -[verse]
> -'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
> -	  [--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse]
> -	  [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]
> -	  [--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]]
> -	  [--] [<pathspec>...]
> +[synopsis]
> +git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
> +	[--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse]
> +	[--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]
> +	[--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]]
> +	[--] [<pathspec>...]

Not having to worry about `mark-up` _rules_ in the synopsis section
is very nice ;-)

[gitgitgadget]

This patch series was integrated into seen via git@9ce5685.

[gitgitgadget]

On the Git mailing list, Jean-Noël Avila wrote (reply to this):

Le 12/11/2024 à 01:38, Junio C Hamano a écrit :
> "Jean-Noël Avila via GitGitGadget" <[email protected]> writes:
> 
>> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
>>
>> Signed-off-by: Jean-Noël Avila <[email protected]>
>> ---
>>     doc: git-add.txt: convert to new style convention
> 
> This does slightly more than converting to new style, though,
> doesn't it?  Is it so annoying to see a link that points at the same
> page you are reading right now to warrant duplicating some docs with
> conditional inclusion?
> 
>> +`add.ignoreErrors`::
>> +`add.ignore-errors` (deprecated)::
>> +	Tells `git add` to continue adding files when some files cannot be
>> +	added due to indexing errors.
>> +ifdef::git-add[]
>> +	Equivalent to the `--ignore-errors` option.
>> +endif::git-add[]
>> +ifndef::git-add[]
>> +	Equivalent to the `--ignore-errors` option of linkgit:git-add[1].
>> +endif::git-add[]
> 

This was already performed for git-clone (ebb55042a4) and git-init
(e7b3a7683c). Should it be separated in a dedicated commit?


If the link is not to a specific anchor in the doc (which is the aim in
html output), it is considered bad practice (against the "Make your
visitor confident that the link they're following will take them where
they want to go" principle). To create a sensible link, we would have to
bring the visitor to the corresponding option description. This is
doable, but would require an enhanced linkgit macro and additional anchors.

[gitgitgadget]

User Jean-Noël Avila <[email protected]> has been added to the cc: list.

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

Jean-Noël Avila <[email protected]> writes:

>> This does slightly more than converting to new style, though,
>> doesn't it?  Is it so annoying to see a link that points at the same
>> page you are reading right now to warrant duplicating some docs with
>> conditional inclusion?
> ...
> This was already performed for git-clone (ebb55042a4) and git-init
> (e7b3a7683c). Should it be separated in a dedicated commit?

My comment came primarily as a reaction to seeing this change that
was not part of what the proposed log message said.  As you say, as
a separate and orthogonal thing, we could make it a separate commit.
But it also is perfectly fine if the log message explained that we
are doing this independent change "while we are at it".

Thanks.

[gitgitgadget]

This patch series was integrated into seen via git@2cf6898.

[gitgitgadget]

This patch series was integrated into next via git@1af6d17.

[gitgitgadget]

This patch series was integrated into seen via git@bcc7663.