Re: [RFC PATCH 1/2] docs: automarkup.py: Add literal markup of known constants
flat view
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: 2021-06-09 08:11:18
Also in:
lkml
Em Tue, 8 Jun 2021 22:43:07 -0300 Nícolas F. R. A. Prado [off-list ref] escreveu:
quoted hunk ↗ jump to hunk
There are some known constants that are used throughout the documentation, like NULL and error codes, and which are better formatted as literals by Sphinx. Make these words automatically literals. Suggested-by: Matthew Wilcox <willy@infradead.org> Signed-off-by: Nícolas F. R. A. Prado <redacted> --- Documentation/sphinx/automarkup.py | 45 ++++++++++++++++++++++++++++-- 1 file changed, 43 insertions(+), 2 deletions(-)diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index acf5473002f3..eb219783d9e3 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py@@ -72,6 +72,40 @@ Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap', 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl', 'socket' ] +# +# Words that are automatically converted to literals +# +Literals = [ 'NULL', 'ULONG_MAX', 'LONG_MAX', 'EPERM', 'ENOENT', 'ESRCH', + 'EINTR', 'EIO', 'ENXIO', 'E2BIG', 'ENOEXEC', 'EBADF', 'ECHILD', + 'EAGAIN', 'ENOMEM', 'EACCES', 'EFAULT', 'ENOTBLK', 'EBUSY', + 'EEXIST', 'EXDEV', 'ENODEV', 'ENOTDIR', 'EISDIR', 'EINVAL', + 'ENFILE', 'EMFILE', 'ENOTTY', 'ETXTBSY', 'EFBIG', 'ENOSPC', + 'ESPIPE', 'EROFS', 'EMLINK', 'EPIPE', 'EDOM', 'ERANGE', 'EDEADLK', + 'ENAMETOOLONG', 'ENOLCK', 'ENOSYS', 'ENOTEMPTY', 'ELOOP', + 'EWOULDBLOCK', 'ENOMSG', 'EIDRM', 'ECHRNG', 'EL2NSYNC', 'EL3HLT', + 'EL3RST', 'ELNRNG', 'EUNATCH', 'ENOCSI', 'EL2HLT', 'EBADE', 'EBADR', + 'EXFULL', 'ENOANO', 'EBADRQC', 'EBADSLT', 'EDEADLOCK', 'EBFONT', + 'ENOSTR', 'ENODATA', 'ETIME', 'ENOSR', 'ENONET', 'ENOPKG', + 'EREMOTE', 'ENOLINK', 'EADV', 'ESRMNT', 'ECOMM', 'EPROTO', + 'EMULTIHOP', 'EDOTDOT', 'EBADMSG', 'EOVERFLOW', 'ENOTUNIQ', + 'EBADFD', 'EREMCHG', 'ELIBACC', 'ELIBBAD', 'ELIBSCN', 'ELIBMAX', + 'ELIBEXEC', 'EILSEQ', 'ERESTART', 'ESTRPIPE', 'EUSERS', 'ENOTSOCK', + 'EDESTADDRREQ', 'EMSGSIZE', 'EPROTOTYPE', 'ENOPROTOOPT', + 'EPROTONOSUPPORT', 'ESOCKTNOSUPPORT', 'EOPNOTSUPP', 'EPFNOSUPPORT', + 'EAFNOSUPPORT', 'EADDRINUSE', 'EADDRNOTAVAIL', 'ENETDOWN', + 'ENETUNREACH', 'ENETRESET', 'ECONNABORTED', 'ECONNRESET', 'ENOBUFS', + 'EISCONN', 'ENOTCONN', 'ESHUTDOWN', 'ETOOMANYREFS', 'ETIMEDOUT', + 'ECONNREFUSED', 'EHOSTDOWN', 'EHOSTUNREACH', 'EALREADY', + 'EINPROGRESS', 'ESTALE', 'EUCLEAN', 'ENOTNAM', 'ENAVAIL', 'EISNAM', + 'EREMOTEIO', 'EDQUOT', 'ENOMEDIUM', 'EMEDIUMTYPE', 'ECANCELED', + 'ENOKEY', 'EKEYEXPIRED', 'EKEYREVOKED', 'EKEYREJECTED', + 'EOWNERDEAD', 'ENOTRECOVERABLE', 'ERFKILL', 'EHWPOISON' ]
There are some arch-specific error codes missing there: ECANCELLED EINIT EMAXERRNO ENOSYM EPROCLIM EREFUSED EREMDEV EREMOTERELEASE ERREMOTE 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'. As I said on patch 0/2, IMO the error codes should be parsed from the relevant errno files: ./arch/powerpc/include/uapi/asm/errno.h ./arch/parisc/include/uapi/asm/errno.h ./arch/sparc/include/uapi/asm/errno.h ./arch/alpha/include/uapi/asm/errno.h ./arch/mips/include/uapi/asm/errno.h ./arch/mips/include/asm/errno.h ./include/uapi/asm-generic/errno-base.h ./include/uapi/asm-generic/errno.h ./include/linux/errno.h Also, as pointed on patch 0/2 too, I would automatically parse all uppercase with a _ on it, as all of them look constants on my eyes (but only after checking at the references dictionary if they aren't a cross-reference to a macro).
quoted hunk ↗ jump to hunk
+ +# +# Any of the words in Literals, optionally prefixed with a '-' +# +RE_literal = re.compile(r'-?\b(' + str(r'|'.join(Literals)) + r')\b')
see my notes about "\b" on patch 0/2. Regards, Mauro