From: Firmin Martin <firminmartin24@gmail.com>
To: "Jean-Noël Avila" <avila.jn@gmail.com>, git <git@vger.kernel.org>
Subject: Re: [RFC PATCH v1 00/13][GSoC] doc: (monospace) apply CodingGuidelines on a large-scale
Date: Tue, 13 Apr 2021 22:42:06 +0200 [thread overview]
Message-ID: <87h7k9hq75.fsf@Inspiron.i-did-not-set--mail-host-address--so-tickle-me> (raw)
In-Reply-To: <d2e78646-6735-2a27-735c-331de6411ca2@gmail.com>
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 ?
Thanks,
Firmin
next prev parent reply other threads:[~2021-04-13 20:42 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-04-09 4:02 [RFC PATCH v1 00/13][GSoC] doc: (monospace) apply CodingGuidelines on a large-scale Firmin Martin
2021-04-09 4:02 ` [RFC PATCH v1 01/13] doc: typeset command-line options in monospace Firmin Martin
2021-04-09 9:49 ` Bagas Sanjaya
2021-04-10 1:12 ` Firmin Martin
2021-04-09 4:02 ` [RFC PATCH v1 02/13] doc: typeset branches and remotes " Firmin Martin
2021-04-09 4:02 ` [RFC PATCH v1 03/13] doc: typeset configuration options " Firmin Martin
2021-04-09 4:02 ` [RFC PATCH v1 04/13] doc: typeset git-related commands " Firmin Martin
2021-04-09 4:02 ` [RFC PATCH v1 05/13] doc: typeset git-svn subcommands " Firmin Martin
2021-04-09 4:02 ` [RFC PATCH v1 06/13] doc: typeset dummy URLs and protocols " Firmin Martin
2021-04-09 4:02 ` [RFC PATCH v1 07/13] doc: typeset git dotfiles " Firmin Martin
2021-04-09 4:02 ` [RFC PATCH v1 08/13] doc: typeset filepath and $variables " Firmin Martin
2021-04-09 4:02 ` [RFC PATCH v1 09/13] doc: typeset command/option/value entries " Firmin Martin
2021-04-09 4:02 ` [RFC PATCH v1 10/13] doc: typeset more command " Firmin Martin
2021-04-09 4:02 ` [RFC PATCH v1 11/13] doc: typeset config option " Firmin Martin
2021-04-09 4:03 ` [RFC PATCH v1 12/13] doc: typeset environment vars without $ " Firmin Martin
2021-04-09 4:03 ` [RFC PATCH v1 13/13] doc: typeset common programs " Firmin Martin
2021-04-12 13:37 ` [RFC PATCH v1 00/13][GSoC] doc: (monospace) apply CodingGuidelines on a large-scale Jean-Noël Avila
2021-04-13 20:42 ` Firmin Martin [this message]
2021-04-19 9:04 ` Jean-Noël Avila
2021-04-19 9:33 ` Jean-Noël Avila
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87h7k9hq75.fsf@Inspiron.i-did-not-set--mail-host-address--so-tickle-me \
--to=firminmartin24@gmail.com \
--cc=avila.jn@gmail.com \
--cc=git@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).