Date:   Mon, 14 Jun 2021 09:27:06 +0200
From:   Mauro Carvalho Chehab <mchehab@...radead.org>
To:     Jonathan Corbet <corbet@....net>
Cc:     "Nícolas F. R. A. Prado" <n@...aprado.net>,
        linux-doc@...r.kernel.org, Matthew Wilcox <willy@...radead.org>,
        linux-kernel@...r.kernel.org,
        André Almeida <andrealmeid@...labora.com>,
        ~lkcamp/patches@...ts.sr.ht
Subject: Re: [RFC PATCH 1/2] docs: automarkup.py: Add literal markup of
 known constants

Em Sun, 13 Jun 2021 17:13:45 -0600
Jonathan Corbet <corbet@....net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@...nel.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

Powered by blists - more mailing lists