From: brian m. carlson Date: Fri, 19 Sep 2025 00:39:12 GMT Subject: Re: [PATCH 0/2] doc: git-push: clarify section Message-ID: In-Reply-To: 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 "+: 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