Re: [RFC PATCH 1/2] docs: automarkup.py: Add literal markup of known constants

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Tue,  8 Jun 2021 22:43:07 -0300
Nícolas F. R. A. Prado <n@nfraprado.net> escreveu:

> 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 <n@nfraprado.net>
> ---
>  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).

> +
> +#
> +# 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