From: Mauro Carvalho Chehab <mchehab@infradead.org>
To: Jonathan Corbet <corbet@lwn.net>
Cc: "Nícolas F. R. A. Prado" <n@nfraprado.net>,
linux-doc@vger.kernel.org, "Matthew Wilcox" <willy@infradead.org>,
linux-kernel@vger.kernel.org,
"André Almeida" <andrealmeid@collabora.com>,
~lkcamp/patches@lists.sr.ht
Subject: Re: [RFC PATCH 1/2] docs: automarkup.py: Add literal markup of known constants
Date: Mon, 14 Jun 2021 09:27:06 +0200 [thread overview]
Message-ID: <20210614092706.341f8177@coco.lan> (raw)
In-Reply-To: <874ke1bbo6.fsf@meer.lwn.net>
Em Sun, 13 Jun 2021 17:13:45 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>
> > It sounds a nightmare to maintain this by hand, as a list of used
> > constants will only grow. IMO, an explicit list should be kept only to
> > with the absolute minimum, e.g. for highly-used constants that aren't
> > error codes nor FOO_BAR. The only case that occurs to me that fits
> > on this rule is 'NULL'.
>
> This is my concern as well. It seems to me like we would always have a
> situation where some constants are magically marked up and others
> aren't, and people will spend a lot of time trying to figure out why.
Yeah, people wasting their time trying to fix it doesn't sound
good.
>
> Might it not be better to just adopt the convention that these constants
> don't need to be marked up at all? NULL is entirely understandable even
> when presented in a proportional font. Seems like maybe the best of
> both worlds?
I doubt we'll have a consensus here. IMO it is a lot easier for the
reader to have constants displayed on a different way. I guess other
developers may have similar opinions, while others won't care or would
think otherwise ;-)
Granted, the ones who care could always explicitly add ``FOO`` at
the rst file (we do that on media, as this was imported from our
old docbooks - and we try to preserve it on newer symbols), but I bet
that people will still do things like: "FOO", 'FOO' or ‘FOO’ in order
to distinguish at least some of them.
So, if we want consistency, I can see only two alternatives:
- a treewide patchset manually replacing the conts;
- use automarkup.py.
IMO, the latter is better. We can also agree that there won't be
an agreement, and keep as is ;-)
-
Assuming that this would be addressed by automarkup.py, there are
3 cases that automarkup.py can identify without much efforts:
1. uppercases with underscore;
2. error codes: Easy to parse the errno files and get the codes at
runtme;
3. NULL.
Dealing with the remaining cases, however, are a lot more complex, as
documents may have:
4. Simple uppercase texts:
THIS README FILE IS PROVIDED BY ADAPTEC AND CONTRIBUTORS ``AS IS`` AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, ANY
...
FILE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
(this one is at Documentation/scsi/aic79xx.rst, but there are
other variants of similar licensing style texts on other places)
5. uppercase acronyms, like DIMM, RAM, etc;
6. names of boards, manufacturers, etc;
7. syscalls, like:
SIOCDEVPRIVATE
SIOCETHTOOL
SIOCGHWTSTAMP
...
8. other constants
It should also be noticed that some files use uppercase letters for
variables like "A", "B" and "C". On those, using a different font
would make a lot easier for the readers.
It sounds to me that one size doesn't fit all. I can't see a
way to address it on a way that it would make easy to maintain
while keeping it fully transparent.
Maybe there's one alternative: automarkup could gain support to read
extra files with non-treewide regex rules.
For instance, a Documentation/foo/.automarkup could contain extra
regex rules for the files under Documentation/foo/.
Another possibility would be to have a ".. automarkup_file" tag.
This way, (1), (2) and (3) would be handled automatically,
treewide, but things like sockios.h (SIO* ioctls) would be there
only for network, for instance, using some file with the extra
regexes for automarkup stored under Documentation/networking.
Not sure how hard/easy would be to implement it, nor if one
directory can/should inherit extra regexes from its parent,
but, at a first glance, this seems to be a way to go.
Thanks,
Mauro
next prev parent reply other threads:[~2021-06-14 7:27 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-06-09 1:43 [RFC PATCH 0/2] docs: automarkup.py: Add literal markup of known constants Nícolas F. R. A. Prado
2021-06-09 1:43 ` [RFC PATCH 1/2] " Nícolas F. R. A. Prado
2021-06-09 8:11 ` Mauro Carvalho Chehab
2021-06-13 23:13 ` Jonathan Corbet
2021-06-14 7:27 ` Mauro Carvalho Chehab [this message]
2021-06-09 1:43 ` [RFC PATCH 2/2] XArray: Remove literal markup from " Nícolas F. R. A. Prado
2021-06-09 7:50 ` Mauro Carvalho Chehab
2021-06-09 7:45 ` [RFC PATCH 0/2] docs: automarkup.py: Add literal markup of " Mauro Carvalho Chehab
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210614092706.341f8177@coco.lan \
--to=mchehab@infradead.org \
--cc=andrealmeid@collabora.com \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=n@nfraprado.net \
--cc=willy@infradead.org \
--cc=~lkcamp/patches@lists.sr.ht \
/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.
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 NNTP newsgroup(s).