Messages in this thread | | | Date | Mon, 14 Jun 2021 09:27:06 +0200 | From | Mauro Carvalho Chehab <> | 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@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
| |