From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 23 Jul 2024 15:52:31 GMT
Subject: Re: [PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor
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:

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