linux-kernel - Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

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]

Date:   Wed, 19 Jun 2019 23:27:53 +0200
From:   Peter Zijlstra <peterz@...radead.org>
To:     Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Jonathan Corbet <corbet@....net>, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main
 dir

On Wed, Jun 19, 2019 at 10:19:22AM -0300, Mauro Carvalho Chehab wrote:
> (c/c list cleaned)
> 
> Em Wed, 19 Jun 2019 13:43:56 +0200
> Peter Zijlstra <peterz@...radead.org> escreveu:
> 
> > On Tue, Jun 18, 2019 at 05:53:17PM -0300, Mauro Carvalho Chehab wrote:
> > 
> > >  .../{ => driver-api}/atomic_bitops.rst        |  2 -  
> > 
> > That's a .txt file, big fat NAK for making it an rst.
> 
> Rst is a text file. This one is parsed properly by Sphinx without
> any changes.

In my tree it is a .txt file, I've not seen patches changing it. And I
disagree, rst is just as much 'a text file' as .c is.

> > >  .../{ => driver-api}/futex-requeue-pi.rst     |  2 -  
> > 
> > >  .../{ => driver-api}/gcc-plugins.rst          |  2 -  
> > 
> > >  Documentation/{ => driver-api}/kprobes.rst    |  2 -
> > >  .../{ => driver-api}/percpu-rw-semaphore.rst  |  2 -  
> > 
> > More NAK for rst conversion
> 
> Again, those don't need any conversion. Those files already parse 
> as-is by Sphinx, with no need for any change.

And yet, they're a .txt file in my tree. And I've not seen a rename,
just this move.

> The only change here is that, on patch 1/22, the files that
> aren't listed on an index file got a :orphan: added in order
> to make this explicit. This patch removes it.

I've no idea what :orphan: is. Text file don't have markup.

> > >  Documentation/{ => driver-api}/pi-futex.rst   |  2 -
> > >  .../{ => driver-api}/preempt-locking.rst      |  2 -  
> > 
> > >  Documentation/{ => driver-api}/rbtree.rst     |  2 -  
> > 
> > >  .../{ => driver-api}/robust-futex-ABI.rst     |  2 -
> > >  .../{ => driver-api}/robust-futexes.rst       |  2 -  
> > 
> > >  .../{ => driver-api}/speculation.rst          |  8 +--
> > >  .../{ => driver-api}/static-keys.rst          |  2 -  
> > 
> > >  .../{ => driver-api}/this_cpu_ops.rst         |  2 -  
> > 
> > >  Documentation/locking/rt-mutex.rst            |  2 +-  
> > 
> > NAK. None of the above have anything to do with driver-api.
> 
> Ok. Where do you think they should sit instead? core-api?

Pretty much all of then are core-api I tihnk, with exception of the one
that are ABI, which have nothing to do with API. And i've no idea where
GCC plugins go, but it's definitely nothing to do with drivers.

Many of the futex ones are about the sys_futex user API, which
apparently we have Documentation/userspace-api/ for.

Why are you doing this if you've no clue what they're on about?

Just randomly moving files about isn't helpful.