From: Derrick Stolee <derrickstolee@github.com>
To: Junio C Hamano <gitster@pobox.com>,
Derrick Stolee via GitGitGadget <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, me@ttaylorr.com, Johannes.Schindelin@gmx.de
Subject: Re: [PATCH] git-rebase.txt: use back-ticks consistently
Date: Tue, 28 Jun 2022 15:40:38 -0400 [thread overview]
Message-ID: <3fa71e6f-ebc4-b3f3-4624-777ad03a4fe2@github.com> (raw)
In-Reply-To: <xmqqmtdwlodw.fsf@gitster.g>
On 6/28/2022 12:54 PM, Junio C Hamano wrote:
> "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> 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:
>>
>> 2005-08-26: 52a22d1e726 ([PATCH] Subject: [PATCH] Add some documentation., 2005-08-26)
>> ...
>> 2022-04-20: 9e5ebe9668a (rebase: use correct base for --keep-base when a branch is given, 2022-04-20)
>
> That is a new concept ;-)
>
> It is an interesting exercise to see which previous changes had
> these mark-up mistakes, but it is not immediately obvious to me how
> we can take advantage of the information.
I just wanted to see how much of these edits were due to "really old
documentation from when we had different habits" and how many were
related to recent updates, so I should give more pause. I think the
discussion about the "apply" versus "merge" backends should have
given me more pause because those sections were written recently and
are more likely to have correct punctuation.
>> I look forward to feedback on how to do this better (if it is indeed a
>> good idea to do in the first place).
>
> Correcting mark-up to result in an easier-to-read documentation is a
> good idea, of course. I wonder if we can also help the developers
> mark-up correctly in their first attempt (e.g. do we have clear and
> concise guidelines that are well publicized?)
I'm not sure we have them well publicized. It's worth thinking about.
Hopefully creating a more standard use within at least one (long) file
will help establish some patterns organically.
>> --strategy-option=<strategy-option>::
>> Pass the <strategy-option> through to the merge strategy.
>> This implies `--merge` and, if no strategy has been
>> - specified, `-s ort`. Note the reversal of 'ours' and
>> - 'theirs' as noted above for the `-m` option.
>> + specified, `-s ort`. Note the reversal of `ours` and
>> + `theirs` as noted above for the `-m` option.
>
> These references to "ours" and "theirs" is what we called out
> earlier in the "swapped" description (hunk -348,10), i.e.
>
> when a merge conflict happens, the side reported as 'ours'
> is the so-far rebased series ... and 'theirs' is the working
> branch.
>
> which the patch left in 'emphasis' not `verbatim`. I think this
> section should do the same.
>
> The 'ours' (but not 'theirs' because there is no such thing) that is
> explained as useless as a strategy in the intervening paragraph
> (hunk -360,9) refers to the name of a strategy, and it is correct to
> mark it as `verbatim`.
Thanks!
>> --ignore-whitespace::
>> Ignore whitespace differences when trying to reconcile
>> -differences. Currently, each backend implements an approximation of
>> -this behavior:
>> + differences. Currently, each backend implements an approximation of
>> + this behavior:
>> +
>> -apply backend: When applying a patch, ignore changes in whitespace in
>> +'apply backend:' When applying a patch, ignore changes in whitespace in
>> ...
>> -merge backend: Treat lines with only whitespace changes as unchanged
>> +'merge backend:' Treat lines with only whitespace changes as unchanged
>
> It somehow looks curious (at the source level---I haven't seen the
> formatted HTML output) to have the punctuation colon as part of the
> phrase marked up. I wonder if these were meant to be more like so:
>
> apply backend;;
> When applying a patch, ...
>
> merge backend;;
> Treat lines with ...
This appears to work well. The doc-diff shows this:
- apply backend: When applying a patch, ignore changes in whitespace
- in context lines. Unfortunately, this means that if the "old" lines
- being replaced by the patch differ only in whitespace from the
- existing file, you will get a merge conflict instead of a
- successful patch application.
+ apply backend:
+ When applying a patch, ignore changes in whitespace in context
+ lines. Unfortunately, this means that if the "old" lines being
+ replaced by the patch differ only in whitespace from the
+ existing file, you will get a merge conflict instead of a
+ successful patch application.
- merge backend: Treat lines with only whitespace changes as
- unchanged when merging. Unfortunately, this means that any patch
- hunks that were intended to modify whitespace and nothing else will
- be dropped, even if the other side had no changes that conflicted.
+ merge backend:
+ Treat lines with only whitespace changes as unchanged when
+ merging. Unfortunately, this means that any patch hunks that
+ were intended to modify whitespace and nothing else will be
+ dropped, even if the other side had no changes that conflicted.
>> @@ -536,8 +536,8 @@ See also REBASING MERGES and INCOMPATIBLE OPTIONS below.
>>
>> -x <cmd>::
>> --exec <cmd>::
>> - Append "exec <cmd>" after each line creating a commit in the
>> - final history. <cmd> will be interpreted as one or more shell
>> + Append `exec <cmd>` after each line creating a commit in the
>> + final history. `<cmd>` will be interpreted as one or more shell
>> commands. Any command that fails will interrupt the rebase,
>> with exit code 1.
>
> As noticed by others, "git help -m rebase" is somewhat harmed with
> this change when rendered to plain text without any attributes. The
> roff output actually is
>
> .RS 4
> Append
> \fBexec <cmd>\fR
> after each line creating a commit in the final history\&.
>
> and even on plain text tty, "exec <cmd>" part is now shown in bold
> (as opposed to be in plain text inside double quotes, which was how
> the original got rendered). So I think this change is an
> improvement.
Thanks for digging into the details here. It would be interesting if
doc-diff could make this clearer, but that's a project for another time.
Thanks,
-Stolee
next prev parent reply other threads:[~2022-06-28 19:59 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-06-27 21:21 [PATCH] git-rebase.txt: use back-ticks consistently Derrick Stolee via GitGitGadget
2022-06-28 9:59 ` Phillip Wood
2022-06-28 19:29 ` Derrick Stolee
2022-06-28 10:22 ` Ævar Arnfjörð Bjarmason
2022-06-28 13:20 ` Rendering back-ticks in plaintext docs (was Re: [PATCH] git-rebase.txt: use back-ticks consistently) Derrick Stolee
2022-06-28 16:59 ` Junio C Hamano
2022-06-28 16:54 ` [PATCH] git-rebase.txt: use back-ticks consistently Junio C Hamano
2022-06-28 19:40 ` Derrick Stolee [this message]
2022-06-28 20:02 ` [PATCH v2] " Derrick Stolee via GitGitGadget
2022-06-28 21:49 ` Junio C Hamano
2022-06-29 9:31 ` Phillip Wood
2022-06-29 12:40 ` Derrick Stolee
2022-06-30 17:18 ` Junio C Hamano
2022-06-29 12:43 ` Derrick Stolee
2022-06-29 9:27 ` Phillip Wood
2022-06-29 12:41 ` Derrick Stolee
2022-06-29 13:21 ` [PATCH v3] " Derrick Stolee via GitGitGadget
2022-06-29 15:21 ` Phillip Wood
2022-06-30 17:25 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=3fa71e6f-ebc4-b3f3-4624-777ad03a4fe2@github.com \
--to=derrickstolee@github.com \
--cc=Johannes.Schindelin@gmx.de \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=gitster@pobox.com \
--cc=me@ttaylorr.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).