Linux Virtualization - Nov 2016 - [PATCH v2 34/37] docs: fix locations of several documents that got moved

Em Wed, 19 Oct 2016 12:34:42 +0200
Pavel Machek <pavel at ucw.cz> escreveu:
> Hi!
> 
> 
> > --- a/Documentation/ABI/testing/sysfs-kernel-slab
> > +++ b/Documentation/ABI/testing/sysfs-kernel-slab
> > @@ -347,7 +347,7 @@ Description:
> >  		because of fragmentation, SLUB will retry with the minimum order
> >  		possible depending on its characteristics.
> >  		When debug_guardpage_minorder=N (N > 0) parameter is specified
> > -		(see Documentation/kernel-parameters.txt), the minimum possible
> > +		(see Documentation/admin-guide/kernel-parameters.rst), the minimum
possible
> >  		order is used and this sysfs entry can not be used to change
> >  		the order at run time.  
> 
> Dunno, but kernel-parameters.txt was already quite long... for a file
> that is referenced quite often. Adding admin-guide/ into the path does
> not really help.
The big string name starts with Documentation/ :) There are some discussions 
about changing it to doc/ (or docs/). Also, as you said, kernel-parameters
is already a big name. Perhaps we could use, instead, "kernel-parms".

If we rename kernel-parameters.rst to kernel-parms.rst, plus the doc/ rename,
then the string size will actually reduce:

-		(see Documentation/kernel-parameters.txt), the minimum possible
+		(see doc/admin-guide/kernel-parms.rst), the minimum possible
> Maybe admin-guide should go directly into Documentation/ , as that's
> what our users are interested in?
There are several problems if we keep them at Documentation/ dir:

- We'll end by mixing documents already converted to ReST with documents
  not converted yet;

- A rename is needed anyway, as Sphinx only accepts ReST files that end
  with the extension(s) defined at Documentation/conf.py (currently,
  .rst);

- A partial documentation build is made by sub-directory. If we put
  files under /Documentation, there's no way to build just one
  book.
> Plus, I'm not sure how many developers will figure out that process/
> is what describes kernel patch submission process. We have processes
> in the kernel, after all...
Do you have a better idea?
> Could we leave symlinks in place? 
My initial patch did that. It created symlinks on the
Documentation/user (with was the previous name for the admin's guide).

The big issue is how to identify what files at Documentation/ that
were not converted yet.

On this patch series, we opted to move the file and keep just a
reference to the most relevant ones, pointing to the new location:
	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=lkml-books-v2&id=217462c76ee1c12b45750723059a3461018b6975
	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=lkml-books-v2&id=d15595a318356804ed1bc42f509e72de9d031513

We could do something similar to Documentation/kernel-parameters.txt.
Yet, the best is, IMHO, to keep this on the absolute minimum of files,
as it also makes harder to identify what txt files still require conversion.
> People say "please follow
> CodingStyle" when reviewing patches. Saying "please follow
> process/conding-style.rst" ... somehow I don't think that's
going to
> happen.
As we have a Documentation/CodingStyle (pointing to the new location),
this should still work. 

That's said, using my maintainer's hat, when I review patches from a
newbie,
I actually prefer to point them to some location with the current
practices, as they usually don't know much about the Kernel's way to
receive patch. So, I reply with something like:

	"Please read this:
		https://mchehab.fedorapeople.org/kernel_docs/process/index.html
	 with instructions about how to submit your work"

For an old contributor, I just say: "please follow the coding style" 
or I reply with the output of checkpatch.pl.

Maybe it is just me, but I very much prefer to point to some URL with
everything packed altogether than to do several reviews until someone
RTFM (Read The Fine Manual), and starts to submit it right.

Thanks,
Mauro

Hi!
> > Dunno, but kernel-parameters.txt was already quite long... for a file
> > that is referenced quite often. Adding admin-guide/ into the path does
> > not really help.
> 
> The big string name starts with Documentation/ :) There are some
discussions
> about changing it to doc/ (or docs/). Also, as you said, kernel-parameters
> is already a big name. Perhaps we could use, instead,
> > "kernel-parms".
cmdline?
> If we rename kernel-parameters.rst to kernel-parms.rst, plus the doc/
rename,
> then the string size will actually reduce:
> 
> -		(see Documentation/kernel-parameters.txt), the minimum possible
> +		(see doc/admin-guide/kernel-parms.rst), the minimum possible
> 
> > Maybe admin-guide should go directly into Documentation/ , as
that's
> > what our users are interested in?
> 
> There are several problems if we keep them at Documentation/ dir:
> 
> - We'll end by mixing documents already converted to ReST with
documents
>   not converted yet;
> 
> - A rename is needed anyway, as Sphinx only accepts ReST files that end
>   with the extension(s) defined at Documentation/conf.py (currently,
>   .rst);
> 
> - A partial documentation build is made by sub-directory. If we put
>   files under /Documentation, there's no way to build just one
>   book.
Well, documentation is primarily for users. I'm sure tools can adapt...
> > Plus, I'm not sure how many developers will figure out that
process/
> > is what describes kernel patch submission process. We have processes
> > in the kernel, after all...
> 
> Do you have a better idea?
development/ ?

Best regards,
									Pavel
-- 
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures)
http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 181 bytes
Desc: Digital signature
URL:
<http://lists.linuxfoundation.org/pipermail/virtualization/attachments/20161102/6391d053/attachment.sig>

On 11/02/2016 05:31 AM, Pavel Machek wrote:
> Hi!
> 
>>> Dunno, but kernel-parameters.txt was already quite long... for a
file
>>> that is referenced quite often. Adding admin-guide/ into the path
does
>>> not really help.
>>
>> The big string name starts with Documentation/ :) There are some
discussions
>> about changing it to doc/ (or docs/). Also, as you said,
kernel-parameters
>> is already a big name. Perhaps we could use, instead,
>>> "kernel-parms".
> 
> cmdline?
You would not believe the number of users I've dealt with that have confused
"cmdline/command line" (aka prompt) with "kernel parameter".
I go back and edit
customer debug requests to make sure there's no use of cmdline in place of
kernel parameter.

For the love of every customer facing engineer out there, please stop using
cmdline ;).

P.
> 
>> If we rename kernel-parameters.rst to kernel-parms.rst, plus the doc/
rename,
>> then the string size will actually reduce:
>>
>> -		(see Documentation/kernel-parameters.txt), the minimum possible
>> +		(see doc/admin-guide/kernel-parms.rst), the minimum possible
>>
>>> Maybe admin-guide should go directly into Documentation/ , as
that's
>>> what our users are interested in?
>>
>> There are several problems if we keep them at Documentation/ dir:
>>
>> - We'll end by mixing documents already converted to ReST with
documents
>>   not converted yet;
>>
>> - A rename is needed anyway, as Sphinx only accepts ReST files that end
>>   with the extension(s) defined at Documentation/conf.py (currently,
>>   .rst);
>>
>> - A partial documentation build is made by sub-directory. If we put
>>   files under /Documentation, there's no way to build just one
>>   book.
> 
> Well, documentation is primarily for users. I'm sure tools can adapt...
> 
>>> Plus, I'm not sure how many developers will figure out that
process/
>>> is what describes kernel patch submission process. We have
processes
>>> in the kernel, after all...
>>
>> Do you have a better idea?
> 
> development/ ?
> 
> Best regards,
> 									Pavel
>