Re: [PATCH 1/3] Docs: An initial automarkup extension for sphinx

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

Em Mon, 24 Jun 2019 08:29:50 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Sat, 22 Jun 2019 14:46:10 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> 
> > > > .. c:function:: int ioctl( int fd, int request, void *argp )
> > > >     :name: v4l2-ioctl      
> > > 
> > > Some digging around didn't turn up any documentation for :name:, but it
> > > seems to prevent ioctl() from going into the list of functions that can be
> > > cross-referenced.     
> > 
> > It took me a while to discover this way to be able to re-define the
> > name of a symbol at the C domain, but I'm pretty sure I read this
> > somewhere at the Sphinx docs (or perhaps on some bug track or Stack
> > Overflow).
> > 
> > I don't remember exactly where I get it, but I guess it is related to
> > this:
> > 
> > 	http://docutils.sourceforge.net/docs/howto/rst-roles.html
> >   
> > > I wonder if the same should be done for the others?    
> > 
> > Sure.  
> 
> It actually occurs to me that it might be better to keep the skip list and
> maybe expand it.  There are vast numbers of places where people write
> open() or whatever(), and there is no point in even trying to
> cross-reference them. 

Yeah, subsystems will likely have their own "man pages" for for sysctls.

Both the dvb and the v4l2 ones are part of what used to be the DocBook
manpages for those syscalls. If I'm not mistaken, we ended by expanded 
the same approach for the media controller, for CEC and for RC.

> I should do some tests, it might even make a
> measurable difference in the build time to skip them :)  And in any case,
> somebody is bound to put one of those common names into the namespace in
> the future, recreating the current problem.

There is one way of keeping it while avoiding troubles: you could
create internal names, for example using the current dir, auto-adding
the ":name:" tag when a declaration conflict rises. Not sure how
easy/hard would be to implement it.

Btw, at get_abi.pl, I had to do a trick like that, as some symbols
have a "local context". The good thing at ABI files is that the context
is clear: it is valid only between "What:" and "Description:" fields.

Also, as it is a single script that parses the entire ABI (it takes
on ~0.1 seconds to parse everything and store internally on my machine),
the logic there detects when an existing symbol is re-used on a different
context. When this happens, it adds a random char at the end of the
internal reference, while keeping the original name[1].

[1] on the the highly unlikely event that the new name still repeats,
it adds a new random char - until the name gets different.

Probably doing it at automarkup won't be that simple, but it could
work.

Thanks,
Mauro