From: Jeff King <peff@peff.net>
Date: Fri, 19 Sep 2025 04:25:45 GMT
Subject: Re: [PATCH 0/2] doc: git-push: clarify section
Message-ID: <20250919042545.GA3979@coredump.intra.peff.net>
In-Reply-To: <aMymMLkJg7PkmxL7@fruit.crustytoothpaste.net>

On Fri, Sep 19, 2025 at 12:39:12AM +0000, brian m. carlson wrote:

> 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.

I think both implementations will just generate XML via our Makefile,
and ultimately it is DocBook which will convert the <orderedlist> into
actual roff. So something like:

diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl
index beb5ff8ec2..b494fbb5df 100644
--- a/Documentation/manpage-normal.xsl
+++ b/Documentation/manpage-normal.xsl
@@ -11,4 +11,6 @@
 <!-- unset maximum length of title -->
 <xsl:param name="man.th.title.max.length"/>
 
+<xsl:param name="man.indent.width" select="2"/>
+
 </xsl:stylesheet>

would affect that process. And I think there might even be a specific
list-indent variable, but I didn't dig very far. I agree it's probably
not worth going too far into the rabbit hole of manpage styling. The
parameter docs are here:

  https://docbook.sourceforge.net/release/xsl/1.78.1/doc/manpages/indent.html

I believe Asciidocttor _can_ generate roff directly, but we don't use it
that way. I don't think it would make sense to do so unless we are ready
to drop AsciiDoc support entirely (since keeping them as close together
as possible reduces the maintenance burden).

-Peff