Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Daniel Vetter]

On Thu, Oct 27, 2016 at 08:40:56PM -0200, Mauro Carvalho Chehab wrote:
> Em Thu, 27 Oct 2016 14:36:07 -0600
> Jonathan Corbet  escreveu:
> 
> > On Thu, 27 Oct 2016 13:17:33 -0700
> > Andrew Morton  wrote:
> > 
> > > > This patch series continues the efforts of converting the Linux Kernel
> > > > documentation to Sphinx.
> > > 
> > > hm, renaming Documentation/kernel-parameters.txt in linux-next is going
> > > to be a pain for the next two months.  I have one large patch series
> > > which alters that file and I expect more will come.  
> > 
> > That's going to be a continuing hassle as we try to bring a bit of order
> > to Documentation/, especially as so much stuff doesn't go through the docs
> > tree.  Hopefully this cycle will be done with the most obnoxious moves,
> > anyway.
> 
> Perhaps you could use git filter to handle it, with something like (untested):
> 
> $ git filter-branch -f --tree-filter 'for i in $(git grep -l 
> kernel-parameters.txt); do sed 
> s,Documentation/kernel-parameters.txt,Documentation/admin-guide/kernel-parameters.rst,g
>  $i >a && mv a $i; done' some_origin_branch..

Iirc Andrew uses quilt, so raw sed to change the filename in the diff
metadata of patches should do the job. We maintain a similar quilt patch
pile monstrosity for embargoed enabling internally ;-)
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Daniel Vetter]

On Thu, Oct 27, 2016 at 08:40:56PM -0200, Mauro Carvalho Chehab wrote:
> Em Thu, 27 Oct 2016 14:36:07 -0600
> Jonathan Corbet  escreveu:
> 
> > On Thu, 27 Oct 2016 13:17:33 -0700
> > Andrew Morton  wrote:
> > 
> > > > This patch series continues the efforts of converting the Linux Kernel
> > > > documentation to Sphinx.
> > > 
> > > hm, renaming Documentation/kernel-parameters.txt in linux-next is going
> > > to be a pain for the next two months.  I have one large patch series
> > > which alters that file and I expect more will come.  
> > 
> > That's going to be a continuing hassle as we try to bring a bit of order
> > to Documentation/, especially as so much stuff doesn't go through the docs
> > tree.  Hopefully this cycle will be done with the most obnoxious moves,
> > anyway.
> 
> Perhaps you could use git filter to handle it, with something like (untested):
> 
> $ git filter-branch -f --tree-filter 'for i in $(git grep -l 
> kernel-parameters.txt); do sed 
> s,Documentation/kernel-parameters.txt,Documentation/admin-guide/kernel-parameters.rst,g
>  $i >a && mv a $i; done' some_origin_branch..

Iirc Andrew uses quilt, so raw sed to change the filename in the diff
metadata of patches should do the job. We maintain a similar quilt patch
pile monstrosity for embargoed enabling internally ;-)
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Mauro Carvalho Chehab]

Em Thu, 27 Oct 2016 14:36:07 -0600
Jonathan Corbet  escreveu:

> On Thu, 27 Oct 2016 13:17:33 -0700
> Andrew Morton  wrote:
> 
> > > This patch series continues the efforts of converting the Linux Kernel
> > > documentation to Sphinx.
> > 
> > hm, renaming Documentation/kernel-parameters.txt in linux-next is going
> > to be a pain for the next two months.  I have one large patch series
> > which alters that file and I expect more will come.  
> 
> That's going to be a continuing hassle as we try to bring a bit of order
> to Documentation/, especially as so much stuff doesn't go through the docs
> tree.  Hopefully this cycle will be done with the most obnoxious moves,
> anyway.

Perhaps you could use git filter to handle it, with something like (untested):

$ git filter-branch -f --tree-filter 'for i in $(git grep -l 
kernel-parameters.txt); do sed 
s,Documentation/kernel-parameters.txt,Documentation/admin-guide/kernel-parameters.rst,g
 $i >a && mv a $i; done' some_origin_branch..

> > I guess I can cope with that, by staging these patch series after
> > linux-next but that means that I would very much like this patch series
> > of your to be merged *early* after the 4.9 release, please.  
> 
> I've been making a point of getting stuff merged early (for reasons very
> similar to this) for the last few cycles; will do so again.
> 
> Alternatively, if you want to pass those particular patches thisaway, I
> can do the merge and carry them with the rest.
> 
> jon



Thanks,
Mauro

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Mauro Carvalho Chehab]

Em Thu, 27 Oct 2016 14:36:07 -0600
Jonathan Corbet  escreveu:

> On Thu, 27 Oct 2016 13:17:33 -0700
> Andrew Morton  wrote:
> 
> > > This patch series continues the efforts of converting the Linux Kernel
> > > documentation to Sphinx.
> > 
> > hm, renaming Documentation/kernel-parameters.txt in linux-next is going
> > to be a pain for the next two months.  I have one large patch series
> > which alters that file and I expect more will come.  
> 
> That's going to be a continuing hassle as we try to bring a bit of order
> to Documentation/, especially as so much stuff doesn't go through the docs
> tree.  Hopefully this cycle will be done with the most obnoxious moves,
> anyway.

Perhaps you could use git filter to handle it, with something like (untested):

$ git filter-branch -f --tree-filter 'for i in $(git grep -l 
kernel-parameters.txt); do sed 
s,Documentation/kernel-parameters.txt,Documentation/admin-guide/kernel-parameters.rst,g
 $i >a && mv a $i; done' some_origin_branch..

> > I guess I can cope with that, by staging these patch series after
> > linux-next but that means that I would very much like this patch series
> > of your to be merged *early* after the 4.9 release, please.  
> 
> I've been making a point of getting stuff merged early (for reasons very
> similar to this) for the last few cycles; will do so again.
> 
> Alternatively, if you want to pass those particular patches thisaway, I
> can do the merge and carry them with the rest.
> 
> jon



Thanks,
Mauro

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Jonathan Corbet]

On Thu, 27 Oct 2016 13:17:33 -0700
Andrew Morton  wrote:

> > This patch series continues the efforts of converting the Linux Kernel
> > documentation to Sphinx.  
> 
> hm, renaming Documentation/kernel-parameters.txt in linux-next is going
> to be a pain for the next two months.  I have one large patch series
> which alters that file and I expect more will come.

That's going to be a continuing hassle as we try to bring a bit of order
to Documentation/, especially as so much stuff doesn't go through the docs
tree.  Hopefully this cycle will be done with the most obnoxious moves,
anyway.

> I guess I can cope with that, by staging these patch series after
> linux-next but that means that I would very much like this patch series
> of your to be merged *early* after the 4.9 release, please.

I've been making a point of getting stuff merged early (for reasons very
similar to this) for the last few cycles; will do so again.

Alternatively, if you want to pass those particular patches thisaway, I
can do the merge and carry them with the rest.

jon

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Jonathan Corbet]

On Thu, 27 Oct 2016 13:17:33 -0700
Andrew Morton  wrote:

> > This patch series continues the efforts of converting the Linux Kernel
> > documentation to Sphinx.  
> 
> hm, renaming Documentation/kernel-parameters.txt in linux-next is going
> to be a pain for the next two months.  I have one large patch series
> which alters that file and I expect more will come.

That's going to be a continuing hassle as we try to bring a bit of order
to Documentation/, especially as so much stuff doesn't go through the docs
tree.  Hopefully this cycle will be done with the most obnoxious moves,
anyway.

> I guess I can cope with that, by staging these patch series after
> linux-next but that means that I would very much like this patch series
> of your to be merged *early* after the 4.9 release, please.

I've been making a point of getting stuff merged early (for reasons very
similar to this) for the last few cycles; will do so again.

Alternatively, if you want to pass those particular patches thisaway, I
can do the merge and carry them with the rest.

jon

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Andrew Morton]

On Mon, 17 Oct 2016 14:55:37 -0200 Mauro Carvalho Chehab 
 wrote:

> This patch series continues the efforts of converting the Linux Kernel
> documentation to Sphinx.

hm, renaming Documentation/kernel-parameters.txt in linux-next is going
to be a pain for the next two months.  I have one large patch series
which alters that file and I expect more will come.

I guess I can cope with that, by staging these patch series after
linux-next but that means that I would very much like this patch series
of your to be merged *early* after the 4.9 release, please.

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Andrew Morton]

On Mon, 17 Oct 2016 14:55:37 -0200 Mauro Carvalho Chehab 
 wrote:

> This patch series continues the efforts of converting the Linux Kernel
> documentation to Sphinx.

hm, renaming Documentation/kernel-parameters.txt in linux-next is going
to be a pain for the next two months.  I have one large patch series
which alters that file and I expect more will come.

I guess I can cope with that, by staging these patch series after
linux-next but that means that I would very much like this patch series
of your to be merged *early* after the 4.9 release, please.

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Markus Heiser]

Am 19.10.2016 um 01:25 schrieb Jonathan Corbet :

> On Tue, 18 Oct 2016 08:20:18 -0200
> Mauro Carvalho Chehab  wrote:
> 
>>> While at it, how about unifying some of the FilenamesInCamelCase,
>>> filenames-with-hyphens, and filenames_with_underscores too...? To at
>>> least move things towards just one of them within one directory.  
>> 
>> Sure, let's do it. I would just keep README as README.rst , as people
>> are more used to see readme files on upercases.
>> 
>> For the rest, what's your preference?
>> 
>>  - FooBar.rst
>>  - foo_bar.rst
>>  - foo-bar.rst
>> 
>> My personal preference is for "foo-bar".
> 
> I guess that would be mine too.  CamelCase is not generally all that
> popular in kernel space.  On one hand, I worry about further renaming
> files that we're already moving; on the other, if we're going to do it, I
> guess this would be the time, when people will have to look for them
> anyway...

OT / but related to sphinx extension: python files should not named "foo-bar" 
[1].
I you do so, you can't use them as regular modules ...

>>> import foo-bar
 File "", line 1
   import foo-bar
 ^
SyntaxError: invalid syntax

Hope there comes the time, we rename Documentation/sphinx/kernel-doc.py
and make a py-package from the sphinx folder.

[1] https://www.python.org/dev/peps/pep-0008/#package-and-module-names
> 
> jon
> --
> 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

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Markus Heiser]

Am 19.10.2016 um 01:25 schrieb Jonathan Corbet :

> On Tue, 18 Oct 2016 08:20:18 -0200
> Mauro Carvalho Chehab  wrote:
> 
>>> While at it, how about unifying some of the FilenamesInCamelCase,
>>> filenames-with-hyphens, and filenames_with_underscores too...? To at
>>> least move things towards just one of them within one directory.  
>> 
>> Sure, let's do it. I would just keep README as README.rst , as people
>> are more used to see readme files on upercases.
>> 
>> For the rest, what's your preference?
>> 
>>  - FooBar.rst
>>  - foo_bar.rst
>>  - foo-bar.rst
>> 
>> My personal preference is for "foo-bar".
> 
> I guess that would be mine too.  CamelCase is not generally all that
> popular in kernel space.  On one hand, I worry about further renaming
> files that we're already moving; on the other, if we're going to do it, I
> guess this would be the time, when people will have to look for them
> anyway...

OT / but related to sphinx extension: python files should not named "foo-bar" 
[1].
I you do so, you can't use them as regular modules ...

>>> import foo-bar
 File "", line 1
   import foo-bar
 ^
SyntaxError: invalid syntax

Hope there comes the time, we rename Documentation/sphinx/kernel-doc.py
and make a py-package from the sphinx folder.

[1] https://www.python.org/dev/peps/pep-0008/#package-and-module-names
> 
> jon
> --
> 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

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Mauro Carvalho Chehab]

Em Tue, 18 Oct 2016 17:25:42 -0600
Jonathan Corbet  escreveu:

> On Tue, 18 Oct 2016 08:20:18 -0200
> Mauro Carvalho Chehab  wrote:
> 
> > > While at it, how about unifying some of the FilenamesInCamelCase,
> > > filenames-with-hyphens, and filenames_with_underscores too...? To at
> > > least move things towards just one of them within one directory.
> > 
> > Sure, let's do it. I would just keep README as README.rst , as people
> > are more used to see readme files on upercases.
> > 
> > For the rest, what's your preference?
> > 
> > - FooBar.rst
> > - foo_bar.rst
> > - foo-bar.rst
> > 
> > My personal preference is for "foo-bar".  
> 
> I guess that would be mine too.  CamelCase is not generally all that
> popular in kernel space.  On one hand, I worry about further renaming
> files that we're already moving; on the other, if we're going to do it, I
> guess this would be the time, when people will have to look for them
> anyway...

It was also somewhat painful to do the renames, but IMHO, it is for
a greater good. Anyway, the version 2 of this series, submitted
yesterday, is doing the renames to foo-bar.rst. I merged all renames
on a single patch, per book. So, if we still need to change something,
there will be no need on touching on the ReST conversion patches.

There were a few issues that I noticed on the version 2, but I
wait for a couple of days before sending the final version, in order
to give people more time to review.

Regards,
Mauro

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Mauro Carvalho Chehab]

Em Tue, 18 Oct 2016 17:25:42 -0600
Jonathan Corbet  escreveu:

> On Tue, 18 Oct 2016 08:20:18 -0200
> Mauro Carvalho Chehab  wrote:
> 
> > > While at it, how about unifying some of the FilenamesInCamelCase,
> > > filenames-with-hyphens, and filenames_with_underscores too...? To at
> > > least move things towards just one of them within one directory.
> > 
> > Sure, let's do it. I would just keep README as README.rst , as people
> > are more used to see readme files on upercases.
> > 
> > For the rest, what's your preference?
> > 
> > - FooBar.rst
> > - foo_bar.rst
> > - foo-bar.rst
> > 
> > My personal preference is for "foo-bar".  
> 
> I guess that would be mine too.  CamelCase is not generally all that
> popular in kernel space.  On one hand, I worry about further renaming
> files that we're already moving; on the other, if we're going to do it, I
> guess this would be the time, when people will have to look for them
> anyway...

It was also somewhat painful to do the renames, but IMHO, it is for
a greater good. Anyway, the version 2 of this series, submitted
yesterday, is doing the renames to foo-bar.rst. I merged all renames
on a single patch, per book. So, if we still need to change something,
there will be no need on touching on the ReST conversion patches.

There were a few issues that I noticed on the version 2, but I
wait for a couple of days before sending the final version, in order
to give people more time to review.

Regards,
Mauro

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Jonathan Corbet]

On Tue, 18 Oct 2016 08:20:18 -0200
Mauro Carvalho Chehab  wrote:

> > While at it, how about unifying some of the FilenamesInCamelCase,
> > filenames-with-hyphens, and filenames_with_underscores too...? To at
> > least move things towards just one of them within one directory.  
> 
> Sure, let's do it. I would just keep README as README.rst , as people
> are more used to see readme files on upercases.
> 
> For the rest, what's your preference?
> 
>   - FooBar.rst
>   - foo_bar.rst
>   - foo-bar.rst
> 
> My personal preference is for "foo-bar".

I guess that would be mine too.  CamelCase is not generally all that
popular in kernel space.  On one hand, I worry about further renaming
files that we're already moving; on the other, if we're going to do it, I
guess this would be the time, when people will have to look for them
anyway...

jon

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Jonathan Corbet]

On Tue, 18 Oct 2016 08:20:18 -0200
Mauro Carvalho Chehab  wrote:

> > While at it, how about unifying some of the FilenamesInCamelCase,
> > filenames-with-hyphens, and filenames_with_underscores too...? To at
> > least move things towards just one of them within one directory.  
> 
> Sure, let's do it. I would just keep README as README.rst , as people
> are more used to see readme files on upercases.
> 
> For the rest, what's your preference?
> 
>   - FooBar.rst
>   - foo_bar.rst
>   - foo-bar.rst
> 
> My personal preference is for "foo-bar".

I guess that would be mine too.  CamelCase is not generally all that
popular in kernel space.  On one hand, I worry about further renaming
files that we're already moving; on the other, if we're going to do it, I
guess this would be the time, when people will have to look for them
anyway...

jon

Re: Renaming Documentation/ [was [PATCH 00/32] Create an User's manual and improve development-process book]

[Theodore Ts'o]

On Tue, Oct 18, 2016 at 07:37:34AM -0600, Jonathan Corbet wrote:
> On Tue, 18 Oct 2016 06:30:48 +0200
> Markus Heiser  wrote:
> 
> > One Silly request of mine:
> > 
> > Is there a chance moving "./Documentation" to something shorter
> > like "./doc"? Even with "Text completion" (in Emacs [1]), IMO 
> > "Documentation" is to long.
> 
> I'd be entirely in favor of that.  It would require some pretty
> widespread and high-level buy-in, though, including from the device-tree
> folks.  That truly is something to raise at the kernel summit; if Linus
> incinerates me, we'll know it's not going to happen...:)

In the meantime, simply dropping in a symlink is a convenient shortcut
for individual developers (for example, I have a symlink at the
top-level from patches to .git/patches/origin to make accessing my
guilt patch stack more convenient).

- Ted

Re: Renaming Documentation/ [was [PATCH 00/32] Create an User's manual and improve development-process book]

[Theodore Ts'o]

On Tue, Oct 18, 2016 at 07:37:34AM -0600, Jonathan Corbet wrote:
> On Tue, 18 Oct 2016 06:30:48 +0200
> Markus Heiser  wrote:
> 
> > One Silly request of mine:
> > 
> > Is there a chance moving "./Documentation" to something shorter
> > like "./doc"? Even with "Text completion" (in Emacs [1]), IMO 
> > "Documentation" is to long.
> 
> I'd be entirely in favor of that.  It would require some pretty
> widespread and high-level buy-in, though, including from the device-tree
> folks.  That truly is something to raise at the kernel summit; if Linus
> incinerates me, we'll know it's not going to happen...:)

In the meantime, simply dropping in a symlink is a convenient shortcut
for individual developers (for example, I have a symlink at the
top-level from patches to .git/patches/origin to make accessing my
guilt patch stack more convenient).

- Ted

Renaming Documentation/ [was [PATCH 00/32] Create an User's manual and improve development-process book]

[Jonathan Corbet]

On Tue, 18 Oct 2016 06:30:48 +0200
Markus Heiser  wrote:

> One Silly request of mine:
> 
> Is there a chance moving "./Documentation" to something shorter
> like "./doc"? Even with "Text completion" (in Emacs [1]), IMO 
> "Documentation" is to long.

I'd be entirely in favor of that.  It would require some pretty
widespread and high-level buy-in, though, including from the device-tree
folks.  That truly is something to raise at the kernel summit; if Linus
incinerates me, we'll know it's not going to happen...:)

jon

Renaming Documentation/ [was [PATCH 00/32] Create an User's manual and improve development-process book]

[Jonathan Corbet]

On Tue, 18 Oct 2016 06:30:48 +0200
Markus Heiser  wrote:

> One Silly request of mine:
> 
> Is there a chance moving "./Documentation" to something shorter
> like "./doc"? Even with "Text completion" (in Emacs [1]), IMO 
> "Documentation" is to long.

I'd be entirely in favor of that.  It would require some pretty
widespread and high-level buy-in, though, including from the device-tree
folks.  That truly is something to raise at the kernel summit; if Linus
incinerates me, we'll know it's not going to happen...:)

jon

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Mauro Carvalho Chehab]

Em Tue, 18 Oct 2016 13:35:39 +0300
Jani Nikula  escreveu:

> On Tue, 18 Oct 2016, Mauro Carvalho Chehab  wrote:
> > Em Tue, 18 Oct 2016 13:01:01 +0300
> > Jani Nikula  escreveu:
> >  
> >> On Tue, 18 Oct 2016, Jonathan Corbet  wrote:  
> >> > So I raised this topic in talks at both Kernel Recipes and LinuxCon
> >> > Europe, and nobody threw things at me.  I have come to suspect that I'm
> >> > worrying a little too much about it; maybe we should go ahead and move
> >> > the documents and see who screams.
> >> 
> >> While at it, how about unifying some of the FilenamesInCamelCase,
> >> filenames-with-hyphens, and filenames_with_underscores too...? To at
> >> least move things towards just one of them within one directory.  
> >
> > Sure, let's do it. I would just keep README as README.rst , as people
> > are more used to see readme files on upercases.  
> 
> Right, I guess I'd keep the top level files as-is, and just do this
> within Documentation.

Well IMHO, the most important documentation for an user/admin's guide
is at /README. So, most of its contents (if not all) should be
moved to Documentation/admin-guide.

> 
> > For the rest, what's your preference?
> >
> > - FooBar.rst
> > - foo_bar.rst
> > - foo-bar.rst
> >
> > My personal preference is for "foo-bar".  
> 
> Same here, but I don't mind so much *which* one it is as long as at
> least each directory has consistent naming.

Yeah, my preference here is also not strong... whatever works
best for the others fit to me.

> 
> > Thanks! Life would be very boring if everybody would have the same
> > opinion :) So, feel free to disagree with me. Your views are very 
> > welcome, even when differs from my own :)  
> 
> Thanks, good to check we're on the same page here and not
> antagonizing. :)

:)

> 
> 
> BR,
> Jani.
> 
> 
> 



Thanks,
Mauro

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Mauro Carvalho Chehab]

Em Tue, 18 Oct 2016 13:35:39 +0300
Jani Nikula  escreveu:

> On Tue, 18 Oct 2016, Mauro Carvalho Chehab  wrote:
> > Em Tue, 18 Oct 2016 13:01:01 +0300
> > Jani Nikula  escreveu:
> >  
> >> On Tue, 18 Oct 2016, Jonathan Corbet  wrote:  
> >> > So I raised this topic in talks at both Kernel Recipes and LinuxCon
> >> > Europe, and nobody threw things at me.  I have come to suspect that I'm
> >> > worrying a little too much about it; maybe we should go ahead and move
> >> > the documents and see who screams.
> >> 
> >> While at it, how about unifying some of the FilenamesInCamelCase,
> >> filenames-with-hyphens, and filenames_with_underscores too...? To at
> >> least move things towards just one of them within one directory.  
> >
> > Sure, let's do it. I would just keep README as README.rst , as people
> > are more used to see readme files on upercases.  
> 
> Right, I guess I'd keep the top level files as-is, and just do this
> within Documentation.

Well IMHO, the most important documentation for an user/admin's guide
is at /README. So, most of its contents (if not all) should be
moved to Documentation/admin-guide.

> 
> > For the rest, what's your preference?
> >
> > - FooBar.rst
> > - foo_bar.rst
> > - foo-bar.rst
> >
> > My personal preference is for "foo-bar".  
> 
> Same here, but I don't mind so much *which* one it is as long as at
> least each directory has consistent naming.

Yeah, my preference here is also not strong... whatever works
best for the others fit to me.

> 
> > Thanks! Life would be very boring if everybody would have the same
> > opinion :) So, feel free to disagree with me. Your views are very 
> > welcome, even when differs from my own :)  
> 
> Thanks, good to check we're on the same page here and not
> antagonizing. :)

:)

> 
> 
> BR,
> Jani.
> 
> 
> 



Thanks,
Mauro

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Jani Nikula]

On Tue, 18 Oct 2016, Mauro Carvalho Chehab  wrote:
> Em Tue, 18 Oct 2016 13:01:01 +0300
> Jani Nikula  escreveu:
>
>> On Tue, 18 Oct 2016, Jonathan Corbet  wrote:
>> > So I raised this topic in talks at both Kernel Recipes and LinuxCon
>> > Europe, and nobody threw things at me.  I have come to suspect that I'm
>> > worrying a little too much about it; maybe we should go ahead and move
>> > the documents and see who screams.  
>> 
>> While at it, how about unifying some of the FilenamesInCamelCase,
>> filenames-with-hyphens, and filenames_with_underscores too...? To at
>> least move things towards just one of them within one directory.
>
> Sure, let's do it. I would just keep README as README.rst , as people
> are more used to see readme files on upercases.

Right, I guess I'd keep the top level files as-is, and just do this
within Documentation.

> For the rest, what's your preference?
>
>   - FooBar.rst
>   - foo_bar.rst
>   - foo-bar.rst
>
> My personal preference is for "foo-bar".

Same here, but I don't mind so much *which* one it is as long as at
least each directory has consistent naming.

> Thanks! Life would be very boring if everybody would have the same
> opinion :) So, feel free to disagree with me. Your views are very 
> welcome, even when differs from my own :)

Thanks, good to check we're on the same page here and not
antagonizing. :)


BR,
Jani.



-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Jani Nikula]

On Tue, 18 Oct 2016, Mauro Carvalho Chehab  wrote:
> Em Tue, 18 Oct 2016 13:01:01 +0300
> Jani Nikula  escreveu:
>
>> On Tue, 18 Oct 2016, Jonathan Corbet  wrote:
>> > So I raised this topic in talks at both Kernel Recipes and LinuxCon
>> > Europe, and nobody threw things at me.  I have come to suspect that I'm
>> > worrying a little too much about it; maybe we should go ahead and move
>> > the documents and see who screams.  
>> 
>> While at it, how about unifying some of the FilenamesInCamelCase,
>> filenames-with-hyphens, and filenames_with_underscores too...? To at
>> least move things towards just one of them within one directory.
>
> Sure, let's do it. I would just keep README as README.rst , as people
> are more used to see readme files on upercases.

Right, I guess I'd keep the top level files as-is, and just do this
within Documentation.

> For the rest, what's your preference?
>
>   - FooBar.rst
>   - foo_bar.rst
>   - foo-bar.rst
>
> My personal preference is for "foo-bar".

Same here, but I don't mind so much *which* one it is as long as at
least each directory has consistent naming.

> Thanks! Life would be very boring if everybody would have the same
> opinion :) So, feel free to disagree with me. Your views are very 
> welcome, even when differs from my own :)

Thanks, good to check we're on the same page here and not
antagonizing. :)


BR,
Jani.



-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Mauro Carvalho Chehab]

Em Tue, 18 Oct 2016 13:01:01 +0300
Jani Nikula  escreveu:

> On Tue, 18 Oct 2016, Jonathan Corbet  wrote:
> > So I raised this topic in talks at both Kernel Recipes and LinuxCon
> > Europe, and nobody threw things at me.  I have come to suspect that I'm
> > worrying a little too much about it; maybe we should go ahead and move
> > the documents and see who screams.  
> 
> While at it, how about unifying some of the FilenamesInCamelCase,
> filenames-with-hyphens, and filenames_with_underscores too...? To at
> least move things towards just one of them within one directory.

Sure, let's do it. I would just keep README as README.rst , as people
are more used to see readme files on upercases.

For the rest, what's your preference?

- FooBar.rst
- foo_bar.rst
- foo-bar.rst

My personal preference is for "foo-bar".

> 
> > Thanks for doing all of this,  
> 
> Yes! Despite all my nitpicking and disagreements about the Sphinx build
> stuff, I very much appreciate your efforts here, Mauro!

Thanks! Life would be very boring if everybody would have the same
opinion :) So, feel free to disagree with me. Your views are very 
welcome, even when differs from my own :)

Regards,
Mauro

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Mauro Carvalho Chehab]

Em Tue, 18 Oct 2016 13:01:01 +0300
Jani Nikula  escreveu:

> On Tue, 18 Oct 2016, Jonathan Corbet  wrote:
> > So I raised this topic in talks at both Kernel Recipes and LinuxCon
> > Europe, and nobody threw things at me.  I have come to suspect that I'm
> > worrying a little too much about it; maybe we should go ahead and move
> > the documents and see who screams.  
> 
> While at it, how about unifying some of the FilenamesInCamelCase,
> filenames-with-hyphens, and filenames_with_underscores too...? To at
> least move things towards just one of them within one directory.

Sure, let's do it. I would just keep README as README.rst , as people
are more used to see readme files on upercases.

For the rest, what's your preference?

- FooBar.rst
- foo_bar.rst
- foo-bar.rst

My personal preference is for "foo-bar".

> 
> > Thanks for doing all of this,  
> 
> Yes! Despite all my nitpicking and disagreements about the Sphinx build
> stuff, I very much appreciate your efforts here, Mauro!

Thanks! Life would be very boring if everybody would have the same
opinion :) So, feel free to disagree with me. Your views are very 
welcome, even when differs from my own :)

Regards,
Mauro

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Jani Nikula]

On Tue, 18 Oct 2016, Jonathan Corbet  wrote:
> So I raised this topic in talks at both Kernel Recipes and LinuxCon
> Europe, and nobody threw things at me.  I have come to suspect that I'm
> worrying a little too much about it; maybe we should go ahead and move
> the documents and see who screams.

While at it, how about unifying some of the FilenamesInCamelCase,
filenames-with-hyphens, and filenames_with_underscores too...? To at
least move things towards just one of them within one directory.

> Thanks for doing all of this,

Yes! Despite all my nitpicking and disagreements about the Sphinx build
stuff, I very much appreciate your efforts here, Mauro!

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Jani Nikula]

On Tue, 18 Oct 2016, Jonathan Corbet  wrote:
> So I raised this topic in talks at both Kernel Recipes and LinuxCon
> Europe, and nobody threw things at me.  I have come to suspect that I'm
> worrying a little too much about it; maybe we should go ahead and move
> the documents and see who screams.

While at it, how about unifying some of the FilenamesInCamelCase,
filenames-with-hyphens, and filenames_with_underscores too...? To at
least move things towards just one of them within one directory.

> Thanks for doing all of this,

Yes! Despite all my nitpicking and disagreements about the Sphinx build
stuff, I very much appreciate your efforts here, Mauro!

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Mauro Carvalho Chehab]

Em Mon, 17 Oct 2016 16:43:42 -0600
Jonathan Corbet  escreveu:

> I've only been able to take a quick look at these - I'm buried fairly deep
> at the moment.  A few superficial thoughts.
> 
> On Mon, 17 Oct 2016 14:55:37 -0200
> Mauro Carvalho Chehab  wrote:
> 
> > In my opinion, it would be better to move the converted files to be inside
> > a Sphinx build directory, but Jon seems reluctant to that, so, this series
> > use symlinks, as it is easy to move the files in the future with a very 
> > simple
> > patch, if we decide to do so.  
> 
> So I raised this topic in talks at both Kernel Recipes and LinuxCon
> Europe, and nobody threw things at me.  I have come to suspect that I'm
> worrying a little too much about it; maybe we should go ahead and move
> the documents and see who screams.  The work could go into docs-next soon,
> and there would be an opportunity to fix things up if all hell breaks
> loose at the kernel summit.
> 
> Can I make some silly requests?
> 
> - Can we move development-process to something shorter, like just
>   "process"?  We'll be typing it a lot, and tab completion doesn't work in
>   most email clients :)

OK!

> - I think we should leave pointers behind in the form of one-line "this
>   file has moved" messages.  Probably only SubmittingPatches and
>   CodingStyle need that treatment, I think.

Ok. Following such logic, I guess we should also add a similar notice to
the main README file too, that will be at the "user/admin-guide".

I would actually be a little more verbose there, providing pointers to the
main documentation books (e. g. the non-subsystem specific ones) there, 
like:

The content of this file was moved to
  Documentation/admin-guide/README.rst
For Kernel's build and admin documentation, please see 
  Documentation/admin-guide;
For guides about the Kernel development process, please see
  Documentation/process;
...

> - The "user manual" is certainly something that has been on my mind as
>   well.  We have documentation for completely separate audiences all mixed
>   together now, and definitely need to fix that.  But rather than "user",
>   can we paint that shed "admin-guide" or something like that?  

Ok! "admin-guide" sounds a good name.

> Thanks for doing all of this,

Anytime!

Thanks,
Mauro

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Mauro Carvalho Chehab]

Em Mon, 17 Oct 2016 16:43:42 -0600
Jonathan Corbet  escreveu:

> I've only been able to take a quick look at these - I'm buried fairly deep
> at the moment.  A few superficial thoughts.
> 
> On Mon, 17 Oct 2016 14:55:37 -0200
> Mauro Carvalho Chehab  wrote:
> 
> > In my opinion, it would be better to move the converted files to be inside
> > a Sphinx build directory, but Jon seems reluctant to that, so, this series
> > use symlinks, as it is easy to move the files in the future with a very 
> > simple
> > patch, if we decide to do so.  
> 
> So I raised this topic in talks at both Kernel Recipes and LinuxCon
> Europe, and nobody threw things at me.  I have come to suspect that I'm
> worrying a little too much about it; maybe we should go ahead and move
> the documents and see who screams.  The work could go into docs-next soon,
> and there would be an opportunity to fix things up if all hell breaks
> loose at the kernel summit.
> 
> Can I make some silly requests?
> 
> - Can we move development-process to something shorter, like just
>   "process"?  We'll be typing it a lot, and tab completion doesn't work in
>   most email clients :)

OK!

> - I think we should leave pointers behind in the form of one-line "this
>   file has moved" messages.  Probably only SubmittingPatches and
>   CodingStyle need that treatment, I think.

Ok. Following such logic, I guess we should also add a similar notice to
the main README file too, that will be at the "user/admin-guide".

I would actually be a little more verbose there, providing pointers to the
main documentation books (e. g. the non-subsystem specific ones) there, 
like:

The content of this file was moved to
  Documentation/admin-guide/README.rst
For Kernel's build and admin documentation, please see 
  Documentation/admin-guide;
For guides about the Kernel development process, please see
  Documentation/process;
...

> - The "user manual" is certainly something that has been on my mind as
>   well.  We have documentation for completely separate audiences all mixed
>   together now, and definitely need to fix that.  But rather than "user",
>   can we paint that shed "admin-guide" or something like that?  

Ok! "admin-guide" sounds a good name.

> Thanks for doing all of this,

Anytime!

Thanks,
Mauro

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Markus Heiser]

Hi Jon,

Am 18.10.2016 um 00:43 schrieb Jonathan Corbet :

> I've only been able to take a quick look at these - I'm buried fairly deep
> at the moment.  A few superficial thoughts.
> 
> On Mon, 17 Oct 2016 14:55:37 -0200
> Mauro Carvalho Chehab  wrote:
> 
>> In my opinion, it would be better to move the converted files to be inside
>> a Sphinx build directory, but Jon seems reluctant to that, so, this series
>> use symlinks, as it is easy to move the files in the future with a very 
>> simple
>> patch, if we decide to do so.
> 
> So I raised this topic in talks at both Kernel Recipes and LinuxCon
> Europe, and nobody threw things at me.

sounds good ;-)

> I have come to suspect that I'm
> worrying a little too much about it; maybe we should go ahead and move
> the documents and see who screams.  The work could go into docs-next soon,
> and there would be an opportunity to fix things up if all hell breaks
> loose at the kernel summit.
> 
> Can I make some silly requests?
> 
> - Can we move development-process to something shorter, like just
> "process"?  We'll be typing it a lot, and tab completion doesn't work in
> most email clients :)
> 
> - I think we should leave pointers behind in the form of one-line "this
> file has moved" messages.  Probably only SubmittingPatches and
> CodingStyle need that treatment, I think.
> 
> - The "user manual" is certainly something that has been on my mind as
> well.  We have documentation for completely separate audiences all mixed
> together now, and definitely need to fix that.  But rather than "user",
> can we paint that shed "admin-guide" or something like that?  
> 

One Silly request of mine:

Is there a chance moving "./Documentation" to something shorter
like "./doc"? Even with "Text completion" (in Emacs [1]), IMO 
"Documentation" is to long.

--Markus--

[1] https://www.emacswiki.org/emacs/CategoryCompletion

> Thanks for doing all of this,
> 
> jon
> --
> 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

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Markus Heiser]

Hi Jon,

Am 18.10.2016 um 00:43 schrieb Jonathan Corbet :

> I've only been able to take a quick look at these - I'm buried fairly deep
> at the moment.  A few superficial thoughts.
> 
> On Mon, 17 Oct 2016 14:55:37 -0200
> Mauro Carvalho Chehab  wrote:
> 
>> In my opinion, it would be better to move the converted files to be inside
>> a Sphinx build directory, but Jon seems reluctant to that, so, this series
>> use symlinks, as it is easy to move the files in the future with a very 
>> simple
>> patch, if we decide to do so.
> 
> So I raised this topic in talks at both Kernel Recipes and LinuxCon
> Europe, and nobody threw things at me.

sounds good ;-)

> I have come to suspect that I'm
> worrying a little too much about it; maybe we should go ahead and move
> the documents and see who screams.  The work could go into docs-next soon,
> and there would be an opportunity to fix things up if all hell breaks
> loose at the kernel summit.
> 
> Can I make some silly requests?
> 
> - Can we move development-process to something shorter, like just
> "process"?  We'll be typing it a lot, and tab completion doesn't work in
> most email clients :)
> 
> - I think we should leave pointers behind in the form of one-line "this
> file has moved" messages.  Probably only SubmittingPatches and
> CodingStyle need that treatment, I think.
> 
> - The "user manual" is certainly something that has been on my mind as
> well.  We have documentation for completely separate audiences all mixed
> together now, and definitely need to fix that.  But rather than "user",
> can we paint that shed "admin-guide" or something like that?  
> 

One Silly request of mine:

Is there a chance moving "./Documentation" to something shorter
like "./doc"? Even with "Text completion" (in Emacs [1]), IMO 
"Documentation" is to long.

--Markus--

[1] https://www.emacswiki.org/emacs/CategoryCompletion

> Thanks for doing all of this,
> 
> jon
> --
> 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

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Jonathan Corbet]

I've only been able to take a quick look at these - I'm buried fairly deep
at the moment.  A few superficial thoughts.

On Mon, 17 Oct 2016 14:55:37 -0200
Mauro Carvalho Chehab  wrote:

> In my opinion, it would be better to move the converted files to be inside
> a Sphinx build directory, but Jon seems reluctant to that, so, this series
> use symlinks, as it is easy to move the files in the future with a very simple
> patch, if we decide to do so.

So I raised this topic in talks at both Kernel Recipes and LinuxCon
Europe, and nobody threw things at me.  I have come to suspect that I'm
worrying a little too much about it; maybe we should go ahead and move
the documents and see who screams.  The work could go into docs-next soon,
and there would be an opportunity to fix things up if all hell breaks
loose at the kernel summit.

Can I make some silly requests?

- Can we move development-process to something shorter, like just
  "process"?  We'll be typing it a lot, and tab completion doesn't work in
  most email clients :)

- I think we should leave pointers behind in the form of one-line "this
  file has moved" messages.  Probably only SubmittingPatches and
  CodingStyle need that treatment, I think.

- The "user manual" is certainly something that has been on my mind as
  well.  We have documentation for completely separate audiences all mixed
  together now, and definitely need to fix that.  But rather than "user",
  can we paint that shed "admin-guide" or something like that?  

Thanks for doing all of this,

jon

Re: [PATCH 00/32] Create an User's manual and improve development-process book

[Jonathan Corbet]

I've only been able to take a quick look at these - I'm buried fairly deep
at the moment.  A few superficial thoughts.

On Mon, 17 Oct 2016 14:55:37 -0200
Mauro Carvalho Chehab  wrote:

> In my opinion, it would be better to move the converted files to be inside
> a Sphinx build directory, but Jon seems reluctant to that, so, this series
> use symlinks, as it is easy to move the files in the future with a very simple
> patch, if we decide to do so.

So I raised this topic in talks at both Kernel Recipes and LinuxCon
Europe, and nobody threw things at me.  I have come to suspect that I'm
worrying a little too much about it; maybe we should go ahead and move
the documents and see who screams.  The work could go into docs-next soon,
and there would be an opportunity to fix things up if all hell breaks
loose at the kernel summit.

Can I make some silly requests?

- Can we move development-process to something shorter, like just
  "process"?  We'll be typing it a lot, and tab completion doesn't work in
  most email clients :)

- I think we should leave pointers behind in the form of one-line "this
  file has moved" messages.  Probably only SubmittingPatches and
  CodingStyle need that treatment, I think.

- The "user manual" is certainly something that has been on my mind as
  well.  We have documentation for completely separate audiences all mixed
  together now, and definitely need to fix that.  But rather than "user",
  can we paint that shed "admin-guide" or something like that?  

Thanks for doing all of this,

jon

[PATCH 00/32] Create an User's manual and improve development-process book

[Mauro Carvalho Chehab]

This patch series continues the efforts of converting the Linux Kernel
documentation to Sphinx.

It contains text to ReST conversion of several files under Documentation,
and a few ones under the main dir (README, REPORTING-BUGS).

As several of the files that document the user's book and the development
process have a very known name and location, this series opts to keep them
in the same location, adding a symbolic link under Documentation/user and
Documentation/development-process.

The advantage of this approach is that people should not learn that those
files got moved, and sites/git history pointing to those files will still be
pointing to the real thing. The disadvantage is that it is more complex to
see what files were already added to a ReST book and on what book those
files were grouped. 

When compared with the patches I sent to ML before the merge window, I 
removed the patch adding MAINTAINERS to the User's manual, and added 
several other files to both books.

All patches on this series can be found on my development tree:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=lkml-books

and are all based on Kernel 4.9-rc1.

The Kernel docs html output after this series can be seen at:
https://mchehab.fedorapeople.org/kernel_docs/

NOTE:


In my opinion, it would be better to move the converted files to be inside
a Sphinx build directory, but Jon seems reluctant to that, so, this series
use symlinks, as it is easy to move the files in the future with a very simple
patch, if we decide to do so.

Mauro Carvalho Chehab (32):
  Documentation/applying-patches.txt: fix a bad external link
  REPORTING-BUGS: convert to ReST markup
  README: convert it to ReST markup
  Documentation/kernel-parameters.txt: convert to ReST markup
  docs-rst: add documents to development-process
  docs-rst: create an user's manual book
  Documentation/adding-syscalls.txt: convert it to ReST markup
  Documentation/bad_memory.txt: convert it to ReST markup
  Documentation/basic_profiling.rst: convert to ReST markup
  Documentation/binfmt_misc.txt: convert it to ReST markup
  Documentation/serial-console.txt: convert it to ReST markup
  Documentation/braille-console: convert it to ReST markup
  Documentation/BUG-HUNTING: convert to ReST markup
  Documentation/CodeOfConflict: add it to the development-process book
  Documentation/devices.rst: convert it to ReST markup
  Documentation/dynamic-debug-howto.txt: convert it to ReST markup
  Documentation/initrd.txt: convert to ReST markup
  Documentation/init.txt: convert to ReST markup
  Documentation/magic-number.txt: convert it to ReST markup
  Documentation/md.txt: Convert to ReST markup
  Documentation/module-signing.txt: convert to ReST markup
  Documentation/mono.txt: convert to ReST markup
  Documentation/java.txt: convert to ReST markup
  Documentation/oops-tracing.txt: convert to ReST markup
  Documentation/parport.txt: convert to ReST markup
  Documentation/ramoops.txt: convert it to ReST format
  Documentation/sysfs-rules.txt: convert it to ReST markup
  Documentation/sysrq.txt: convert to ReST markup
  Documentation/unicode.txt: convert it to ReST markup
  Documentation/VGA-softcursor.txt: convert to ReST markup
  Documentation/volatile-considered-harmful.txt: convert to ReST markup
  Documentation/parport.txt: fix table to show on LaTeX

 Documentation/BUG-HUNTING  |  162 +--
 Documentation/SecurityBugs |   12 +-
 Documentation/VGA-softcursor.txt   |   73 +-
 Documentation/adding-syscalls.txt  |  263 ++---
 Documentation/applying-patches.txt |2 +-
 Documentation/bad_memory.txt   |   26 +-
 Documentation/basic_profiling.txt  |   59 +-
 Documentation/binfmt_misc.txt  |  134 ++-
 Documentation/braille-console.txt  |   30 +-
 Documentation/conf.py  |2 +
 Documentation/development-process/Changes.rst  |1 +
 .../development-process/CodeOfConflict.rst |1 +
 Documentation/development-process/CodingStyle.rst  |1 +
 Documentation/development-process/HOWTO.rst|1 +
 .../development-process/ManagementStyle.rst|1 +
 .../development-process/SubmitChecklist.rst|1 +
 .../development-process/SubmittingDrivers.rst  |1 +
 .../development-process/SubmittingPatches.rst  |1 +
 .../development-process/adding-syscalls.rst|1 +
 .../development-process/applying-patches.rst   |1 +
 .../development-process/email-clients.rst  |1 +
 Documentation/development-process/index.rst|   23 +
 Documentation/development-process/kernel-docs.rst  |1 +
 Documentation/development-process/magic-number.rst |1 +
 .../development-process/stable_api_nonsense.rst|1 +
 .../development-process/stable_kernel_rules.rst|1 +
 .../volatile-considered-harmful.rst 

[PATCH 00/32] Create an User's manual and improve development-process book

[Mauro Carvalho Chehab]

This patch series continues the efforts of converting the Linux Kernel
documentation to Sphinx.

It contains text to ReST conversion of several files under Documentation,
and a few ones under the main dir (README, REPORTING-BUGS).

As several of the files that document the user's book and the development
process have a very known name and location, this series opts to keep them
in the same location, adding a symbolic link under Documentation/user and
Documentation/development-process.

The advantage of this approach is that people should not learn that those
files got moved, and sites/git history pointing to those files will still be
pointing to the real thing. The disadvantage is that it is more complex to
see what files were already added to a ReST book and on what book those
files were grouped. 

When compared with the patches I sent to ML before the merge window, I 
removed the patch adding MAINTAINERS to the User's manual, and added 
several other files to both books.

All patches on this series can be found on my development tree:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=lkml-books

and are all based on Kernel 4.9-rc1.

The Kernel docs html output after this series can be seen at:
https://mchehab.fedorapeople.org/kernel_docs/

NOTE:


In my opinion, it would be better to move the converted files to be inside
a Sphinx build directory, but Jon seems reluctant to that, so, this series
use symlinks, as it is easy to move the files in the future with a very simple
patch, if we decide to do so.

Mauro Carvalho Chehab (32):
  Documentation/applying-patches.txt: fix a bad external link
  REPORTING-BUGS: convert to ReST markup
  README: convert it to ReST markup
  Documentation/kernel-parameters.txt: convert to ReST markup
  docs-rst: add documents to development-process
  docs-rst: create an user's manual book
  Documentation/adding-syscalls.txt: convert it to ReST markup
  Documentation/bad_memory.txt: convert it to ReST markup
  Documentation/basic_profiling.rst: convert to ReST markup
  Documentation/binfmt_misc.txt: convert it to ReST markup
  Documentation/serial-console.txt: convert it to ReST markup
  Documentation/braille-console: convert it to ReST markup
  Documentation/BUG-HUNTING: convert to ReST markup
  Documentation/CodeOfConflict: add it to the development-process book
  Documentation/devices.rst: convert it to ReST markup
  Documentation/dynamic-debug-howto.txt: convert it to ReST markup
  Documentation/initrd.txt: convert to ReST markup
  Documentation/init.txt: convert to ReST markup
  Documentation/magic-number.txt: convert it to ReST markup
  Documentation/md.txt: Convert to ReST markup
  Documentation/module-signing.txt: convert to ReST markup
  Documentation/mono.txt: convert to ReST markup
  Documentation/java.txt: convert to ReST markup
  Documentation/oops-tracing.txt: convert to ReST markup
  Documentation/parport.txt: convert to ReST markup
  Documentation/ramoops.txt: convert it to ReST format
  Documentation/sysfs-rules.txt: convert it to ReST markup
  Documentation/sysrq.txt: convert to ReST markup
  Documentation/unicode.txt: convert it to ReST markup
  Documentation/VGA-softcursor.txt: convert to ReST markup
  Documentation/volatile-considered-harmful.txt: convert to ReST markup
  Documentation/parport.txt: fix table to show on LaTeX

 Documentation/BUG-HUNTING  |  162 +--
 Documentation/SecurityBugs |   12 +-
 Documentation/VGA-softcursor.txt   |   73 +-
 Documentation/adding-syscalls.txt  |  263 ++---
 Documentation/applying-patches.txt |2 +-
 Documentation/bad_memory.txt   |   26 +-
 Documentation/basic_profiling.txt  |   59 +-
 Documentation/binfmt_misc.txt  |  134 ++-
 Documentation/braille-console.txt  |   30 +-
 Documentation/conf.py  |2 +
 Documentation/development-process/Changes.rst  |1 +
 .../development-process/CodeOfConflict.rst |1 +
 Documentation/development-process/CodingStyle.rst  |1 +
 Documentation/development-process/HOWTO.rst|1 +
 .../development-process/ManagementStyle.rst|1 +
 .../development-process/SubmitChecklist.rst|1 +
 .../development-process/SubmittingDrivers.rst  |1 +
 .../development-process/SubmittingPatches.rst  |1 +
 .../development-process/adding-syscalls.rst|1 +
 .../development-process/applying-patches.rst   |1 +
 .../development-process/email-clients.rst  |1 +
 Documentation/development-process/index.rst|   23 +
 Documentation/development-process/kernel-docs.rst  |1 +
 Documentation/development-process/magic-number.rst |1 +
 .../development-process/stable_api_nonsense.rst|1 +
 .../development-process/stable_kernel_rules.rst|1 +
 .../volatile-considered-harmful.rst