Rendering back-ticks in plaintext docs (was Re: [PATCH] git-rebase.txt: use back-ticks consistently)

From: Derrick Stolee <derrickstolee@github.com>
Date: Jun 28, 2022, 13:20 UTC
Message-ID: <a01c1ff7-74a7-b32f-1a1e-a8f2e840ae31@github.com>
In-Reply-To: <220628.86k091f5fy.gmgdl@evledraar.gmail.com>

On 6/28/2022 6:22 AM, Ævar Arnfjörð Bjarmason wrote:

Show 6 quoted lines

> 
> On Mon, Jun 27 2022, Derrick Stolee via GitGitGadget wrote:
> 
>> From: Derrick Stolee <derrickstolee@github.com>
> 
> This looks 99% good, but...

Show 7 quoted lines

>>      3. Focus on the edits that most-recently edited these lines. Doing some
>>         scripting, I was able to construct this date-sorted list of previous
>>         edits (by diffing the git blame output before and after this
>>         change). The most-recent changes before this are:
> 
> I think this is fine, but I want to recommend doc-diff in your toolkit,
> e.g.:

Thanks for the recommendation!

Show 19 quoted lines

> 	$ Documentation/doc-diff HEAD~ HEAD -- -U0|cat
> 	diff --git a/e4a4b31577c7419497ac30cebe30d755b97752c5/home/avar/share/man/man1/git-rebase.1 b/e37244faa0a730bb930dac4e10d8eed4af682a5d/home/avar/share/man/man1/git-rebase.1
> 	index 91ccda823b2..41dfbee38a4 100644
> 	--- a/e4a4b31577c7419497ac30cebe30d755b97752c5/home/avar/share/man/man1/git-rebase.1
> 	+++ b/e37244faa0a730bb930dac4e10d8eed4af682a5d/home/avar/share/man/man1/git-rebase.1
> 	@@ -489,2 +489,2 @@ OPTIONS
> 	-           Append "exec <cmd>" after each line creating a commit in the final
> 	-           history. <cmd> will be interpreted as one or more shell commands.
> 	+           Append exec <cmd> after each line creating a commit in the final
> 	+           history.  <cmd> will be interpreted as one or more shell commands.
> 	@@ -502 +502 @@ OPTIONS
> 	-           If --autosquash is used, "exec" lines will not be appended for the
> 	+           If --autosquash is used, exec lines will not be appended for the
> 	@@ -880 +880 @@ NOTES
> 	-       When the git-rebase command is run, it will first execute a
> 	+       When the git rebase command is run, it will first execute a
> 
> I see Phillip spotted some of this already, but the "exec" change here
> looks unwanted, i.e. let's use double quotes there.

This is definitely an issue where I was looking at the HTML formatted output, which respects back-ticks. Thanks for pointing out that the text docs just ignore back-ticks. This seems problematic, in my opinion.

Is it possible to update our doc formatting to convert back-ticks into something like single quotes? That would help these plain-text documents point out these places where exact strings are very important.

I also have no idea where to look to make such a change, and it would be very wide-ranging. I just think that the plaintext docs are currently a lossy medium and we should work to improve that.

Thanks, -Stolee