Re: [PATCH] MyFirstContribution: render literal *

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Apr 6, 2023, 08:52 UTC
Message-ID: <CAMP44s0_-DaXNMfvfQG8PUbKu9tbbdv4WCYuxY7y58Waoz=nkA@mail.gmail.com>
In-Reply-To: <owlywn2qtj75.fsf@fine.c.googlers.com>

On Wed, Apr 5, 2023 at 10:58 AM Linus Arver <linusa@google.com> wrote:

Show 16 quoted lines

>
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
> > "We" probably don't want to change it, *I* do. Because in AsciiDoc
> > there's a difference between a listing block and a literal block, but
> > the Git documentation does a very poor job of being compatible with
> > AsciiDoc anyway.
>
> TIL. I'll be happy to apply the listing block -> literal block changes
> you suggested in a separate follow-up patch (probably looking at other
> docs we have as well, not just for MyFirstContribution.txt).
>
> > It doesn't even use the modern syntax.
>
> I am new to asciidoc; if you know any other examples of modernizations
> we can do, feel free to chime in. Thanks.

Unfortunately I cannot recommend you to do any modernizations, because Git doesn't use modern AsciiDoc: it uses legacy asciiidoc.py.

If you still want to do some modernization, it would have to be compatible with legacy asciidoc.py, so it would require testing in both. I tried to explain the differences in [1], but that's not yet accepted, so I don't know what a documentation writer is supposed to do at this point.

There's too many considerations to think about before even attempting to do `make doc`, so I don't know.

Cheers.

[1] https://lore.kernel.org/git/20230405125453.49674-2-felipe.contreras@gmail.com/

-- 
Felipe Contreras