Em Thu, 8 Oct 2020 12:31:27 +0100 Matthew Wilcox <wi...@infradead.org> escreveu:
> 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 <wi...@infradead.org> 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`` Ah, OK! > > > > 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. As you mentioned that you're "willing to add more inline kernel-doc", I assumed that you were talking about kernel-doc markups at the C files. Yeah, inside a .rst file, this should be ``SYMBOL``. As you suggested, the automarkup.py could help with replacing some of those. - Just my two cents: a documentation writer hat, it sounds weird to me to mix ``SYMBOL`` (with markup) with NULL (without explicit markup) at the same file. Thanks, Mauro
