Re: [PATCH] doc: git-blame: convert blame to new doc format

From: Michael Lyons <git@michael.lyo.nz>
Date: Jan 6, 2026, 21:16 UTC
Message-ID: <9123496.T7Z3S40VBb@debian-mbp>
In-Reply-To: <7894506.EvYhyI6sBW@piment-oiseau>

On Tuesday, January 6, 2026 1:57:27 PM Eastern Standard Time you wrote:

> Thanks for helping out.

Glad to!

Show 10 quoted lines

> > --L <start>,<end>::
> > --L :<funcname>::
> > -	Annotate only the line range given by '<start>,<end>',
> > -	or by the function name regex '<funcname>'.
> > +`-L <start>,<end>`::
> > +`-L :<funcname>`::
> > +	Annotate only the line range given by _<start>,<end>_,
> 
> It would be better to use backticks, so that the comma is formatted as a
> keyword: `<start>,<end>`

Okay. I changed them back and forth a couple times before the first submission. I have a question about this further down...

Show 7 quoted lines

> > 
> > --S <revs-file>::
> > -	Use revisions from revs-file instead of calling linkgit:git-rev-
> > +`-S <revs-file>`::
> > +	Use revisions from _revs-file_ instead of calling linkgit:git-rev-
> 
> Placeholders keep their brackets: _<rev-file>_ in prose.

Smart.

Show 18 quoted lines

> > ---reverse <rev>..<rev>::
> > +`--reverse <rev>..<rev>`::
> Here, I would differentiate the names of the two placeholders,
> <start>..<end> as used below.
> 
> >  	Walk history forward instead of backward. Instead of showing
> >  	the revision in which a line appeared, this shows the last
> >  	revision in which a line has existed. This requires a range of
> > 
> > -	revision like START..END where the path to blame exists in
> > -	START.  `git blame --reverse START` is taken as `git blame
> > +	revision like _START..END_ where the path to blame exists in
> > +	_START_.  `git blame --reverse START` is taken as `git blame
> > 
> >  	--reverse START..HEAD` for convenience.
> 
> Here, let's transition to the <placeholder> format: <start>..<end> and so
> on.

This is the continuation of my question on `<start>,<end>`: Do these also go to backticks or keep the underscores? My impulse is backticks, but let me know: `<start>..<end>` or _<start>..<end>_?

The start/end change from rev/rev makes sense.

Show 16 quoted lines

> > ---progress::
> > ---no-progress::
> > +`--progress`::
> > 
> > +`--no-progress`::
> >  	Progress status is reported on the standard error stream
> >  	by default when it is attached to a terminal. This flag
> >  	enables progress reporting even if not attached to a
> >  	terminal. Can't use `--progress` together with `--porcelain`
> >  	or `--incremental`.
> 
> Here maybe swap the first two sentences, remove the "This flags" and convert
> to imperative mood. The first sentence is a bit redundant.
> 
> As a general rule, I tend to reorder/reword the paragraph to describe the
> effect in the first sentence of the description with an imperative mood.

New commit will reword a couple things here. Fingers crossed. :)

Show 7 quoted lines

> > -	marked with a '*'. In the porcelain modes, we print 'ignored' and
> > -	'unblamable' on a newline respectively.
> > +	marked with a `*`. In the porcelain modes, we print _ignored_ and
> > +	_unblamable_ on a newline respectively.
> 
> If the words are printed "verbatim", then the format is backticked:
> `ignored` and `unblamable`.

Another one where I had backticks originally and switched them. I'm not super- familiar with the porcelain parts.

> This diff is quite large. If there are no other reasons to split the patch
> according to some semantic reason, then please split file by file.

Okay. Next try will just be blame-options for now.

> 
> That's very good for a first try. Now, I hope that you will be ok to review
> my patches :-)

That's very kind. I'll probably need a couple more rounds before my changes pass inspection, let alone be declared competent to review yours. :)

For the purposes of re-submission, should I be doing something with scissors on this thread, or make a new thread?

Thanks again for the help! ML