From: "brian m. carlson" <sandals@crustytoothpaste•net>
To: Julia Evans via GitGitGadget <gitgitgadget@gmail•com>
Cc: git@vger•kernel.org, Julia Evans <julia@jvns•ca>
Subject: Re: [PATCH 0/2] doc: git-push: clarify section
Date: Fri, 19 Sep 2025 00:39:12 +0000 [thread overview]
Message-ID: <aMymMLkJg7PkmxL7@fruit.crustytoothpaste.net> (raw)
In-Reply-To: <pull.1973.git.1758144815.gitgitgadget@gmail.com>
[-- Attachment #1: Type: text/plain, Size: 2850 bytes --]
On 2025-09-17 at 21:33:33, Julia Evans via GitGitGadget wrote:
> This is a continuation of the changes to git push, from
> https://lore.kernel.org/git/pull.1964.git.1756240823.gitgitgadget@gmail.com/
> . These changes to the refspec section got kind of big so I'm moving them
> into a separate topic.
>
> Since the last review, the main change is to move the rules for pushing out
> of the section and into their own section ("PUSH RULES") so that it can be
> easily referenced from other places in the man page.
>
> I don't love the nested list in PUSH RULES but the sentence starting with
> "If the source is a tag or commit object..." is really a tough one to read,
> it's not going to be relevant to the vast majority of people, and I think
> keeping it contained inside a bullet point will make it much easier to skip
> over to get to later information which is more likely to be relevant to
> folks.
>
> Other changes:
>
> * removed "+:<dst> is optional.", from Junio's review
> * kept "+ is optional and does the same thing as --force", since now the
> push rules are in their own section.
> * fixed the fully expanded refspec form (main:refs/heads/main =>
> refs/heads/main:refs/heads/main)
> * switched from a numbered list to an unordered list, from Junio's review.
> I think the numbered list looks a lot nicer in the terminal output, but
> it's true that there isn't any order. I briefly attempted to understand
> how AsciiDoc's nroff (?) generation works to see if it's possible to make
> unordered lists indent with fewer spaces (2 instead of 4) but I was left
> feeling that nroff/troff/etc are not for mere mortals like me to
> understand.
I have used groff for many years to write letters and address envelopes
(as well as write a few manual pages and design some awards) and I still
don't understand much of it, so I understand how you feel.
In this case we have two possible implementations, AsciiDoc and
Asciidoctor, but both use the man macros. I think if there were some
way to control the value generated as the argument to the `.RS` macro,
then that would be what you want, but I have no idea how to adjust that
in either one. Personally, I would just leave it as it is, since I
believe 4 is the traditional value used with the man macros, even if
typographically or aesthetically it might be suboptimal.
Having said all that, I think this documentation is much improved and
easier to understand, so thank you for that. I don't have specific
comments on the patches (although I see that Junio has suggested some
clarifying comments), but I do deeply appreciate your efforts to improve
the documentation (and, outside of the list, to clarify difficult
technical topics in general).
--
brian m. carlson (they/them)
Toronto, Ontario, CA
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]
next prev parent reply other threads:[~2025-09-19 0:39 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-09-17 21:33 [PATCH 0/2] doc: git-push: clarify section Julia Evans via GitGitGadget
2025-09-17 21:33 ` [PATCH 1/2] doc: git-push: create PUSH RULES section Julia Evans via GitGitGadget
2025-09-17 22:35 ` Junio C Hamano
2025-09-18 20:48 ` Julia Evans
2025-09-17 21:33 ` [PATCH 2/2] doc: git-push: rewrite refspec specification Julia Evans via GitGitGadget
2025-09-19 0:39 ` brian m. carlson [this message]
2025-09-19 4:25 ` [PATCH 0/2] doc: git-push: clarify section Jeff King
2025-09-23 18:08 ` Julia Evans
2025-09-23 18:10 ` [PATCH v2 " Julia Evans via GitGitGadget
2025-09-23 18:10 ` [PATCH v2 1/2] doc: git-push: create PUSH RULES section Julia Evans via GitGitGadget
2025-09-23 18:10 ` [PATCH v2 2/2] doc: git-push: rewrite refspec specification Julia Evans via GitGitGadget
2025-09-23 21:54 ` [PATCH v2 0/2] doc: git-push: clarify section Junio C Hamano
2025-09-23 22:10 ` Julia Evans
2025-09-23 23:09 ` Junio C Hamano
2025-09-25 15:59 ` 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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=aMymMLkJg7PkmxL7@fruit.crustytoothpaste.net \
--to=sandals@crustytoothpaste$(echo .)net \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=julia@jvns$(echo .)ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox