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

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

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

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1826%2Fjnavila%2Fnew_git_add-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1826/jnavila/new_git_add-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1826

 Documentation/config/add.txt |  19 +++---
 Documentation/git-add.txt    | 111 ++++++++++++++++++-----------------
 2 files changed, 68 insertions(+), 62 deletions(-)

index 4d753f006ec..7497533cbcc 100644
@@ -1,7 +1,12 @@
-add.ignoreErrors::
-add.ignore-errors (deprecated)::
-	Tells 'git add' to continue adding files when some files cannot be
-	added due to indexing errors. Equivalent to the `--ignore-errors`
-	option of linkgit:git-add[1].  `add.ignore-errors` is deprecated,
-	as it does not follow the usual naming convention for configuration
-	variables.
+`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[]
+	`add.ignore-errors` is deprecated, as it does not follow the usual
+	naming convention for configuration variables.

base-commit: facbe4f633e4ad31e641f64617bc88074c659959

gitgitgadget

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?

Le 12/11/2024 à 01:38, Junio C Hamano a écrit :

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.

begin:vcard
fn;quoted-printable:Jean-No=C3=ABl Avila
n;quoted-printable:Avila;Jean-No=C3=ABl
org:Scantech S.A.
adr;quoted-printable:Savoie Technolac BP 244;;B=C3=A2timent Androm=C3=A8de - 108 Avenue du Lac L=C3=A9man ; LA MOTTE SERVOLEX;;73290;France email;internet:[email protected]
title:Embedded systems manager
tel;work:+33 479 25 54 50
tel;cell:+33 633 04 64 18
x-mozilla-html:FALSE
url:http://www.scantech.com
version:2.1
end:vcard

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.

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

While we are at it, let's refactor the corresponding configuration documentation to prevent auto-referencing git-add in its own manpage.

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

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1826%2Fjnavila%2Fnew_git_add-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1826/jnavila/new_git_add-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1826

Range-diff vs v1:

1: 9caabbcb263 ! 1: 7028145ae4d doc: git-add.txt: convert to new style convention
@@ Metadata
## Commit message ##
doc: git-add.txt: convert to new style convention

+ While we are at it, let's refactor the corresponding configuration
+ documentation to prevent auto-referencing git-add in its own manpage.
+

## Documentation/config/add.txt ##

 Documentation/config/add.txt |  19 +++---
 Documentation/git-add.txt    | 111 ++++++++++++++++++-----------------
 2 files changed, 68 insertions(+), 62 deletions(-)

index 4d753f006ec..7497533cbcc 100644
@@ -1,7 +1,12 @@
-add.ignoreErrors::
-add.ignore-errors (deprecated)::
-	Tells 'git add' to continue adding files when some files cannot be
-	added due to indexing errors. Equivalent to the `--ignore-errors`
-	option of linkgit:git-add[1].  `add.ignore-errors` is deprecated,
-	as it does not follow the usual naming convention for configuration
-	variables.
+`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[]
+	`add.ignore-errors` is deprecated, as it does not follow the usual
+	naming convention for configuration variables.

base-commit: facbe4f633e4ad31e641f64617bc88074c659959

gitgitgadget