Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Thu, 8 Oct 2020 03:47:06 +0100
From:   Matthew Wilcox <willy@infradead.org>
To:     =?iso-8859-1?Q?N=EDcolas_F=2E_R=2E_A=2E?= Prado 
        <nfraprado@protonmail.com>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        lkcamp@lists.libreplanetbr.org, andrealmeid@collabora.com
Subject: Re: [PATCH] docs: Make automarkup ready for Sphinx 3.1+
Message-ID: <20201008024706.GZ20115@casper.infradead.org>
References: <C674RBXSO9XN.1LXXU71QQNTF1@ArchWay>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <C674RBXSO9XN.1LXXU71QQNTF1@ArchWay>
Precedence: bulk

On Thu, Oct 08, 2020 at 02:15:24AM +0000, N?colas F. R. A. Prado wrote:
> > I have a feature request ... could you automarkup NULL as being
> > :c:macro?
> > Or maybe just anything matching \<[[:upper:]_[:digit:]]*\>
> > (i may have my regex syntax confused ... a word composed of any
> > arrangement of upper-case, digits and underscores.)
> 
> I think what you are suggesting are two separate things.
> 
> For NULL, what you're interested in is that it appears in a monospaced font, as
> if written ``NULL``, right? As I don't think a cross-reference to "the NULL
> macro definition" would make much sense.
> 
> While "anything containing only upper-case, digits and underscores" would
> actually be for cross-referencing to the definition of the macro symbol in
> question, right?

Well, maybe!  What I'd really like is to remove all the markup from
xarray.rst.  Jon managed to get rid of most of it with the (), but
there's still markup on:

LONG_MAX
NULL
-EBUSY
true
XA_MARK_[012]
XA_FLAGS_*
ENOMEM
EINVAL

I'm not sure there's much that automarkup can do about ``true``, but all
the others fit the all-caps-and-underscore-and-digits pattern.

I don't know how much we want errnos to link to anything in particular.
So maybe split these into 'well-known' (eg defined by ANSI C or POSIX)
definitions and things which are local macros:

LONG_MAX
NULL
-EBUSY
ENOMEM
EINVAL

vs

XA_MARK_[012]
XA_FLAGS_*

I'm willing to add more inline kernel-doc to get this to work better.
Or even convert #defines to enums ... whatever gets this working better.

> At the moment, this automarkup script is being used only for cross-referencing,
> but it is indeed a generic automarkup script, and could be used for the
> formatting of NULL.  But we also can't just make every upper-case word written
> in monospaced font, as that doesn't always makes sense.
> 
> So if I understood your two requests correctly, I think we could:
> 1. Always automatically format NULL using a literal ``.
> 2. Try to cross-reference every upper-case word with the macro definition using
> :c:macro, but if the cross-reference doesn't exist, format it normally, since
> it's just normal text (this is what we're doing for C references at the moment).
> 
> What do you think?

I think this works well, except that we need to match not just NULL
but other well-known ANSI/POSIX keywords.

Thanks for entertaining this!