Em Sun, 13 Jun 2021 17:13:45 -0600
Jonathan Corbet <corbet@xxxxxxx> escreveu:
> Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 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
