Em Wed, 19 Oct 2016 12:34:42 +0200 Pavel Machek <pavel@xxxxxx> 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 _______________________________________________ Virtualization mailing list Virtualization@xxxxxxxxxxxxxxxxxxxxxxxxxx https://lists.linuxfoundation.org/mailman/listinfo/virtualization
