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: <20190622144610.26b7d99c@coco.lan>
Date:   Sat, 22 Jun 2019 14:46:10 -0300
From:   Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
To:     Jonathan Corbet <corbet@....net>
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

Em Sat, 22 Jun 2019 08:43:46 -0600
Jonathan Corbet <corbet@....net> escreveu:

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

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.

> I think that would be better than putting a special-case hack into the
> toolchain.

Agreed. As you're doing this, if you prefer, feel free to send the
patches to media docs. Otherwise, I'll seek for some time next week.

> 
> > 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 :)

Yeah, sure. Just wanted to place the code at the same thread. There are
some tricks that need to be done in order to handle the relative paths.
It took me a lot more time to get it right than adding the replacing Regex :-)

(That reminds I should post a patch to one place where we have a
Documentation/Documentation typo)

Thanks,
Mauro