From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Tue, 28 Jun 2022 10:22:18 GMT
Subject: Re: [PATCH] git-rebase.txt: use back-ticks consistently
Message-ID: <220628.86k091f5fy.gmgdl@evledraar.gmail.com>
In-Reply-To: <pull.1270.git.1656364861242.gitgitgadget@gmail.com>


On Mon, Jun 27 2022, Derrick Stolee via GitGitGadget wrote:

> From: Derrick Stolee <derrickstolee@github.com>

This looks 99% good, but...

> While inspecting the 'git rebase' documentation, I noticed that it is
> inconsistent with how it uses back-ticks (or other punctuation) for
> identifying Git commands, command-line arguments, or values for those
> arguments.
>
> Sometimes, an argument (like '--interactive') would appear without any
> punctuation, causing the argument to not have any special formatting.
> Other times, arguments or 'git rebase' itself would have single-quotes
> giving a bold look (in the HTML documentation at least).
>
> By consistently using back-ticks, these types of strings appear in a
> monospace font with special highlighting to appear more clearly as text
> that exists in a command-line invocation of a Git command.
>
> This rather-large diff is the result of scanning git-rebase.txt and
> adding back-ticks as appropriate. Some are adding back-ticks where there
> was no punctuation. Others are replacing single quotes.
>
> There are also a few minor cleanups in the process, such as one place
> that did not use tabs for the first paragraph in a bulletted list.
> Another case still referred to the dashed form, but it was the only use
> in the file except for the heading and NAME section.

I think the commit message should speak more matter-of-factly & briefly,
i.e. just "change so and so...".


>     While I noticed this inconsistency when looking at git rebase as part of
>     the git rebase --update-refs work, I didn't know the best way to update
>     the document from start to finish.
>     
>     This giant update is probably not the best way to present the change.
>     
>     I can see splitting it up in a few ways, but I wanted to check to first
>     see if that was necessary. If it is, then here are the strategies I
>     considered:
>     
>      1. Focus on type of update. This would mean a change for adding
>         back-ticks on all --<option> text, adding back-ticks on all "git
>         rebase" instances, adding back-ticks on things like <upstream>, and
>         doing other types of changes like whitespace updates or "git-rebase"
>         to "git rebase".
>     
>      2. Focus on the section of the document. This would limit the diff by
>         the section size, such as OPTIONS or the discussion on the backends.
>     
>      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.:
	
	$ 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.

For the last hunk I'd think just:

    When rebase is run, it will...

Would be briefer & better in that case.

I also see that we have other spots in our wider docs where we use the
dashed form, I'm fine with converting this case, but maybe better to
leave it aside to make this only a ``-quotation change, or to split up
this & the whitespace & other things you mentioned into another commit.

Any way you're OK with is fine with me, thanks for fixing these.