Skip to contentSkip to conversation

documentation fixes for 2.48.0

PATCH In review Martin Ågren 3 participants 6 messages Jan 3, 2025 Documentation

lore
Share & tools
lore
#0 lore raw

cover documentation fixes for 2.48.0

These two patches fix some misrenderings of the built documentation, introduced during the 2.48 cycle. As usual, the exact current behaviors (symptoms) differ a bit between AsciiDoc and Asciidoctor.

Martin

Martin Ågren (2):
git.txt: fix heading line of tildes
gitcli.txt: typeset pathnames as monospace

 Documentation/git.txt    | 2 +-
 Documentation/gitcli.txt | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
Signature · 1 line
2.48.0.rc1.241.g6c04ab211c
#1 lore raw

PATCH 1/2 git.txt: fix heading line of tildes

The two-line heading added in 8525e92886 (Document HOME environment variable, 2024-12-09) uses too many tilde characters, so the heading isn't detected as such. Both AsciiDoc and Asciidoctor end up misrendering this in different ways.

Use the correct number of tilde characters to fix this.

---
 Documentation/git.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git.txt +1 -1
index 81498393af..e89a91dd0d 100644
@@ -478,7 +478,7 @@ their values the same way as Boolean valued configuration variables, e.g.
 Here are the variables:
 
 System
-~~~~~~~~~~~~~~~~~~
+~~~~~~
 `HOME`::
 	Specifies the path to the user's home directory. On Windows, if
 	unset, Git will set a process environment variable equal to:
Signature · 1 line
2.48.0.rc1.241.g6c04ab211c
#2 lore raw

PATCH 2/2 gitcli.txt: typeset pathnames as monospace

In reply to Martin Ågren

Commit 1bc1e94091 (doc: option value may be separate for valid reasons, 2024-11-25) added a paragraph discussing tilde-expansion of, e.g., ~/directory/file.

The tilde character has a special meaning to asciidoc tools. In this particular case, AsciiDoc matches up the two tildes in "e.g. ~/directory/file or ~u/d/f" and sets the text between them using subscript. In the manpage, where subscripting is not possible, this renders as "e.g. /directory/file oru/d/f".

These paths are literal values, which our coding guidelines want typeset as verbatim using backticks. Do that. One effect of this is indeed that the asciidoc tools stop interpreting tilde and other special characters.

---
 Documentation/gitcli.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/gitcli.txt +1 -1
index bd62cbd043..fcd86d2eee 100644
@@ -91,7 +91,7 @@ scripting Git:
    written in the 'stuck' form.
 
  * Despite the above suggestion, when Arg is a path relative to the
-   home directory of a user, e.g. ~/directory/file or ~u/d/f, you
+   home directory of a user, e.g. `~/directory/file` or `~u/d/f`, you
    may want to use the separate form, e.g. `git foo --file ~/mine`,
    not `git foo --file=~/mine`.  The shell will expand `~/` in the
    former to your home directory, but most shells keep the tilde in
Signature · 1 line
2.48.0.rc1.241.g6c04ab211c
#3 lore raw
In reply to Martin Ågren
Quoted 3 lines · Martin Ågren

These two patches fix some misrenderings of the built documentation, introduced during the 2.48 cycle. As usual, the exact current behaviors (symptoms) differ a bit between AsciiDoc and Asciidoctor.

Both patches make sense. Out of curiosity, how are you discovering these problems? Are you, for instance, running doc-diff and manually scanning the output?

#4 lore raw
Quoted 9 lines · Eric Sunshine
Quoted 3 lines · Martin Ågren

These two patches fix some misrenderings of the built documentation, introduced during the 2.48 cycle. As usual, the exact current behaviors (symptoms) differ a bit between AsciiDoc and Asciidoctor.

Both patches make sense. Out of curiosity, how are you discovering these problems? Are you, for instance, running doc-diff and manually scanning the output?

Yes, exactly. Something like

./doc-diff v2.47.0 v2.48.0-rc1

is a nice way of finding out what's new. Occasionally, some oddity like these stick out.

(The diff can easily look huge, but often several pages contain the same content, so the 2nd/3rd/4th/... instance of a particular diff can be skipped. Inclusion of diff-options.txt would be the typical example.)

Martin

#5 lore raw
In reply to Martin Ågren
Quoted 3 lines · Martin Ågren

These two patches fix some misrenderings of the built documentation, introduced during the 2.48 cycle. As usual, the exact current behaviors (symptoms) differ a bit between AsciiDoc and Asciidoctor.

Thanks.