Re: [PATCH] docs: Make automarkup ready for Sphinx 3.1+

[Matthew Wilcox]

On Thu, Oct 08, 2020 at 08:03:06AM +0200, Mauro Carvalho Chehab wrote:
> Em Thu, 8 Oct 2020 03:47:06 +0100
> Matthew Wilcox <willy@xxxxxxxxxxxxx> escreveu:
> 
> > 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
> 
> Yeah, a nice improvement would be to auto-markup error codes and NULL as
> literal blocks.
> 
> > 
> > vs
> > 
> > XA_MARK_[012]
> 
> > XA_FLAGS_*
> 
> Actually, things that end with an * (but doesn't start with an *)
> are good candidates for being literals - although extra care should
> be taken on such case, as parsing those automatically will likely hit
> lots of false-positives.

I do apologise.  I was trying to be concise in email.  In the actual
text file, I currently have:

``XA_FLAGS_ALLOC``
``XA_FLAGS_ALLOC1``
``XA_FLAGS_LOCK_IRQ``
``XA_FLAGS_LOCK_BH``
``XA_FLAGS_TRACK_FREE``

> > I'm willing to add more inline kernel-doc to get this to work better.
> 
> Why? inline kernel-doc should be evaluated just like normal blocks.
> 
> Right now, kernel-doc handles constants like NULL and XA_FLAGS_* using
> two ways:
> 
> 	%FOO
> or
> 	``FOO``
> 
> The regex for those are:
> 
> 	my $type_constant = '\b``([^\`]+)``\b';
> 	my $type_constant2 = '\%([-_\w]+)';

Right, but that's in kernel-doc ... in a .rst file, I believe we have
to use the ``SYMBOL`` syntax.