Em Fri, 16 Sep 2016 10:55:02 -0600
Jonathan Corbet <cor...@lwn.net> escreveu:

> On Wed, 14 Sep 2016 07:52:53 -0300
> Mauro Carvalho Chehab <mche...@s-opensource.com> 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:

With a content like:
        This file was moved to 

Another alternative would be to try to include this file as:

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%

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


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.

To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to