Re: [RFC PATCH v1 00/13][GSoC] doc: (monospace) apply CodingGuidelines on a large-scale

From: Firmin Martin <firminmartin24@gmail.com>
Date: Apr 13, 2021, 20:42 UTC
Message-ID: <87h7k9hq75.fsf@Inspiron.i-did-not-set--mail-host-address--so-tickle-me>
In-Reply-To: <d2e78646-6735-2a27-735c-331de6411ca2@gmail.com>

Hi Jean-Noël,

Jean-Noël Avila <avila.jn@gmail.com> writes:

Show 11 quoted lines

> Le 09/04/2021 à 06:02, Firmin Martin a écrit :
>> This patch series aims to make the documentation fully compliant to the
>> CodingGuidelines regarding monospace font. After it, new contributors
>> who just want to change a little portion of the documention could just
>> look around how it has been done without being confused by the
>> inconsistency between the documentation and the CodingGuidelines.
>
>
> Thank you for tackling the task of formating the docu and directing to
> CodingGuidelines for some markup rules. It appears that the last rule
> about backticks is wrong with late Asciidoctor, for which backticks are

Thanks. As a new Git contributor, I used to think that we don't use asciidoctor, until I see in Documentation/Makefile:

    ifdef USE_ASCIIDOCTOR
    ASCIIDOC = asciidoctor
    ...
    ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
    ...
    endif

So, we actually use both depending the variable USE_ASCIIDOCTOR.

> only a font switcher and no longer hold any semantic meaning. This means
> that double-hyphens may need escaping (see:
> https://asciidoctor.org/docs/migration/#migration-cheatsheet) when
> switching style and tools.

In the helpful link that you provide, it says that the "setext-style (i.e., two-line) section title" enables compatibility mode. As far as I can tell, most man pages (git.*.txt) fall under this category, except the most important one: user-manual.txt. But this is in fact not relevant, because the snippet above of the Makefile suggests that we actually explicitly running asciidoctor in compatibility mode.

> One other rule worth adding would be that tabs are banned from asciidoc
> because they cannot always be matched with correct indentation.

I'm an absolute novice regarding AsciiDoc vs. Asciidoctor. But from the user guide of AsciiDoc (https://asciidoc.org/userguide.html#_tabs), it says

    By default tab characters input files will translated to 8
    spaces. Tab expansion is set with the tabsize entry in the
    configuration file [miscellaneous] section and can be overridden in
    included files by setting a tabsize attribute in the include macro’s
    attribute list. For example:

    include::addendum.txt[tabsize=2] The tab size can also be set using
    the attribute command-line option, for example --attribute tabsize=4

... and we also explicitly set it to 8 spaces (see above). Could you elaborate a bit on the matter ?

Thanks,

Firmin