From: Julia Evans <julia@jvns.ca>
Date: Tue, 23 Sep 2025 18:08:37 GMT
Subject: Re: [PATCH 0/2] doc: git-push: clarify section
Message-ID: <955752f2-5695-433b-95d8-a7a40cb41d65@app.fastmail.com>
In-Reply-To: <20250919042545.GA3979@coredump.intra.peff.net>



On Fri, Sep 19, 2025, at 12:25 AM, Jeff King wrote:
> 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.

That's good to know, thanks. We'd need a way to indent unordered lists
by 2 and ordered lists by 4 anyway (to make space for the numbers in the
ordered lists) and at that point I'm not sure if it would even
look good. I think I'll leave this rabbit hole as is :)

> 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