Re: [PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 23, 2024, 15:52 UTC
Message-ID: <xmqqv80w2ji8.fsf@gitster.g>
In-Reply-To: <89d00235-71db-4087-8ffb-7e93c3f470a0@free.fr>

Jean-Noël Avila <jn.avila@free.fr> writes:

Show 5 quoted lines

> Please hold on this patch. Cranking on your reflections about the ugly
> markup and upon advice from Dan Allen (of asciidoctor) [1], I'd like to
> push another way of managing the files, which would be to define a
> custom  'synopsis' paragraph style which would allow to process
> automatically the grammar.

Sounds good. Anything that lets documenters write what they mean without involving an absolute nightmare of a markup sequence is what we want here.

But I'd like to see such a larger scale work early in the next cycle, not close to the end of this cycle a few days before -rc2.

In the meantime, I am tempted to

 (1) apply Dscho's CSS change (but with fixes to avoid "make
     distclean" issue) and leaving git-clone as-is.  or

 (2) revert the git-clone and git-init mark-up patches (76880f05
     (doc: git-clone: apply new documentation formatting guidelines,
     2024-03-29) and (5cf7dfe9 (doc: git-init: apply new
     documentation formatting guidelines, 2024-03-29), which suffers
     from the <code> being blocks.  This will allow us not to worry
     about CSS change proposed by Dscho this close to the final.  or

 (3) do nothing.

I'd probably do (1). Even though chances of unintended regression might be smaller with (2), which would only affect clone and init manual pages (as opposed to anything that uses <code> inside <pre>), it's less work (and more work to validate the result visually, which may be a pain).

> [1]
> https://asciidoctor.zulipchat.com/#narrow/stream/279642-users/topic/Is.20there.20a.20way.20to.20disable.20role.20attributes.3F

I've always felt [verse] was a bad choice (I honestly do not know where its use came from), and I am glad to finally find somebody agreeing ;-)

Thanks.