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

> Hi Jean-Noël,
>
> Jean-Noël Avila <avila.jn@gmail.com> writes:
>
>> 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 ?