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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20190624082950.5e338d37@lwn.net>
Date:   Mon, 24 Jun 2019 08:29:50 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
Cc:     linux-doc@...r.kernel.org, Matthew Wilcox <willy@...radead.org>,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH 1/3] Docs: An initial automarkup extension for sphinx

On Sat, 22 Jun 2019 14:46:10 -0300
Mauro Carvalho Chehab <mchehab+samsung@...nel.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.  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.

jon