Message-ID: <20190619232402.20970470@coco.lan>
Date:   Wed, 19 Jun 2019 23:24:02 -0300
From:   Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
To:     Peter Zijlstra <peterz@...radead.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

Em Wed, 19 Jun 2019 23:27:53 +0200
Peter Zijlstra <peterz@...radead.org> escreveu:

> 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.

ReStructured text is just text with a stricter style + some commands,
if the text author wants to enhance it.

Btw, I'm glad you mentioned c. 

This is c:

	int
	func( int a, int
			 b ) {
	 return a + b;
	}

This is also c:

	func(int a,int b) { goto foo;
	foo:
	   return(a+b) }

K&R style is also c, and this is also c:

	#define f(a,b) (a+b)

Despite none of the above matches my taste - and some have issues - they
all build with gcc.

Yet, none of the above follows the Kernel coding style.

The way we use ReST (with absolute minimal changes), it becomes just
a text style.

Btw, I agree with you: there are some odd things at its style - and we 
should work to try to reduce this to its minimal extent.

> 
> > > >  .../{ => 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.

Rename is on patch 1/22.

No matter the extension, all the above files pass at the Sphinx style
validation without warnings or errors. Patch 1/22 doesn't make any
conversion.

Btw, the .rst extension is just a convenient way to help identifying what
was not validated. If I'm not mistaken, when the discussions about a
replacement for DocBook started at at linux-doc, someone proposed to
keep the .txt extension (changing it to accept .rst, .txt or both is
a single line change at conf.py).

> 
> > 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. 

OK.

> And i've no idea where
> GCC plugins go, but it's definitely nothing to do with drivers.

I suspect that Documentation/security would be a better place
for GCC plugins (as it has been discussed at kernel-hardening ML),
but I'm waiting a feedback from Kees.

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

Yeah, it makes sense to place sys_futex there.

Despite being an old dir, it is not too popular: there are
very few document there. I only discovered this one a few
days ago.

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

I don't pretend to know precisely where each document will fit.
If you read carefully the content of each orphaned document, you'll see
that many of them have uAPI, kAPI and admin-guide info inside.

To be frank, I actually tried to get rid of this document shift
part, but a Jon's feedback when I submitted a much simpler RFC
patchset challenged me to try to place each document on some place. The 
renaming part is by far a lot more complex than the conversion, 
because depending on how you interpret the file contents -
and the description of each documentation chapter - it may fit on a
different subdir.

-

My main goal is to have an organized body with the documentation. 

Try to read our docs as if it is a book, and you'll see what I'm talking
about: there are important missing parts, the document order isn't in
an order that would make easier for the headers, several documents are
placed on random places, etc.

Just like we have Makefiles, the index.rst files, plus the subdirectories
help to classify and organize the documentation on a coherent way.

- 

The main problem I want to address with this particular patch is that 
there are so many random documents from all sorts of subject at
Documentation/*.txt that it makes really hard to see the document
structure or to organize them.

Also, keeping txt files there at the root doc dir is a bad idea, as 
people keep flooding Documentation/ root with new unclassified documents
on almost every Kernel version.

After 5.1, there are two new documents added inside Documentation/*.txt
(I guess both added at linux-next for 5.3).

I proposed a few months ago to create a Documentation/staging, and do:

	mv Documentation/*.txt Documentation/*.rst Documentation/staging 

Jani proposed today something similar to it (Documentation/attic)

The name is not important. Having a place were we can temporarily
place documents while we organize the directory structure and the
documentation indexes seem to be the best way to reorganize the
docs on a coherent way.

Thanks,
Mauro

Powered by blists - more mailing lists