Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Sat, 22 Jun 2019 08:43:46 -0600
From:   Jonathan Corbet <corbet@lwn.net>
To:     Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Cc:     linux-doc@vger.kernel.org, Matthew Wilcox <willy@infradead.org>,
        Jani Nikula <jani.nikula@linux.intel.com>,
        linux-kernel@vger.kernel.org
Subject: Re: [PATCH 1/3] Docs: An initial automarkup extension for sphinx
Message-ID: <20190622084346.28c7c748@lwn.net>
In-Reply-To: <20190621220046.3de30d9d@coco.lan>
References: <20190621235159.6992-1-corbet@lwn.net>
        <20190621235159.6992-2-corbet@lwn.net>
        <20190621220046.3de30d9d@coco.lan>
Organization: LWN.net
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Fri, 21 Jun 2019 22:00:46 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> > +#
> > +# The DVB docs create references for these basic system calls, leading
> > +# to lots of confusing links.  So just don't link them.
> > +#
> > +Skipfuncs = [ 'open', 'close', 'write' ]  
> 
> and yeah, of course, if there's something weird, it has to be at
> the media docs :-)
> 
> Btw, if I'm not mistaken, we do the same for ioctl.

So that's actually interesting.  In, for example,
Documentation/media/uapi/v4l/func-ioctl.rst, you see something that looks
like this:

> .. 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.  I wonder if the same should be done for the others?  I
think that would be better than putting a special-case hack into the
toolchain.

> I'm wandering if this could also handle the Documentation/* auto-replace.

I think it's the obvious place for it, yes.  Let's make sure I haven't
badly broken anything with the existing change first, though :)

Thanks,

jon