Em Fri, 16 Sep 2016 10:55:02 -0600 Jonathan Corbet <corbet@xxxxxxx> escreveu: > On Wed, 14 Sep 2016 07:52:53 -0300 > Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> wrote: > > > Based on the few comments it got on LKML, it seems people are accepting > > such renames. > > I suspect it just hasn't come to the attention of enough people yet. > > A quick grep through linux-kernel traffic shows a lot of emails with > references to Documentation/SubmittingPatches. I'm hesitant to break all > those "links" in the archives, and I fear what people may say to me if we > tell them they have to reference > Documentation/development-process/SubmittingPatches.rst instead. Well, we could use Markus suggestion of keeping a: Documentation/SubmittingPatches With a content like: This file was moved to Documentation/development-process/SubmittingPatches.rst Another alternative would be to try to include this file as: ../SubmittingPatches But I guess it will still need to be renamed to some extension (.rst), and we won't be organizing the documentation on a better way. There's another alternative that would be to use a symbolic link: SubmittingPatches -> development-process/SubmittingPatches.rst I guess git supports symlinks (although not sure if such feature is 100% reliable). > I'm going to make comments on the individual patches shortly. Sorry for > being slow - you're a hard guy to keep up with! :) > But I do have a couple of overall thoughts. > > - We do need to be careful to avoid sacrificing convenient direct access > to the text files for nice combined output. For most of the > documentation, I don't think there is much of a conflict there. For a > few heavily cited files, I worry a bit more. IMHO, the main reason to port them first is because they're heavily cited files :) Those are the important ones that we want every single Kernel developer to read, specially the newbies. IMHO, the main challenge for a new developer is to know what are the most important files at Documentation that they all should read. Yet, I share your concerns that this would break people's mental links, but, if we want to organize the house, this needs to be done. > - Documentation/development-process is, as I see it now, on the long and > verbose side. Yes, I know! It is almost impossible to avoid having lines smaller than 80 columns when adding references like: :ref:`file_name <foo>` for some files there ;) > I know I suggested it! I wonder if we should use > "dev-process" (or even just "process") instead? Just "process" sounds good enough for me. > (Someday I'd like to > rename Documentation to something like "doc" to be more in line with > the rest of the kernel's naming, but I'll leave that discussion for > another day :) I'm OK with that. > > - We may want to leave some files in place indefinitely. The list is > quite small - SubmittingPatches, CodingStyle, maybe not a whole lot > more - but doing that may well avoid much of the eventual pushback. > It's worth seeing how hard it would be to get the build process to > cope with that; otherwise maybe leaving a symlink in place will do. I'm not a Sphinx expert, and didn't try to include the files without renaming them yet. I suspect, however, that sphinx only relies on the extensions listed at conf.py. Perhaps there's a way to override it via some extension. Markus, any hints? > > I'm halfway tempted to revive the documentation thread on the kernel > summit list just to see whether I'm being overly nervous or not. Feel free to do it. We may also ask at KS and see how people would manifest about that. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
