Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 34fed7e7 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

Documentation/HOWTO: improve some markups to make it visually better 



Do a series of minor improvements at the ReST output format:

- Instead of using the quote blocks (::) for quotes, use
italics. That looks nicer on epub (and html) output, as
no scroll bar will be added. Also, it will adjust line
breaks on the text automatically.

- Add a missing reference to SubmittingPatches.rst and use
**foo** instead of _foo_.

- use bold for "The Perfect Patch" by removing a newline.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 43fb67a5

Documentation/HOWTO

+16 −20
Original line number Original line Diff line number Diff line
@@ -292,11 +292,9 @@ process is as follows: 
It is worth mentioning what Andrew Morton wrote on the linux-kernel

It is worth mentioning what Andrew Morton wrote on the linux-kernel

mailing list about kernel releases:

mailing list about kernel releases:





::

	*"Nobody knows when a kernel will be released, because it's



	"Nobody knows when a kernel will be released, because it's

	released according to perceived bug status, not according to a

	released according to perceived bug status, not according to a

	preconceived timeline."

	preconceived timeline."*





4.x.y -stable kernel tree

4.x.y -stable kernel tree

-------------------------

-------------------------
@@ -449,13 +447,14 @@ add your statements between the individual quoted sections instead of 
writing at the top of the mail.

writing at the top of the mail.





If you add patches to your mail, make sure they are plain readable text

If you add patches to your mail, make sure they are plain readable text

as stated in Documentation/SubmittingPatches. Kernel developers don't

as stated in Documentation/SubmittingPatches.

want to deal with attachments or compressed patches; they may want

Kernel developers don't want to deal with

to comment on individual lines of your patch, which works only that way.

attachments or compressed patches; they may want to comment on

Make sure you use a mail program that does not mangle spaces and tab

individual lines of your patch, which works only that way. Make sure you

characters. A good first test is to send the mail to yourself and try

use a mail program that does not mangle spaces and tab characters. A

to apply your own patch by yourself. If that doesn't work, get your

good first test is to send the mail to yourself and try to apply your

mail program fixed or change it until it works.

own patch by yourself. If that doesn't work, get your mail program fixed

or change it until it works.





Above all, please remember to show respect to other subscribers.

Above all, please remember to show respect to other subscribers.
@@ -496,8 +495,8 @@ Remember, being wrong is acceptable as long as you are willing to work 
toward a solution that is right.

toward a solution that is right.





It is normal that the answers to your first patch might simply be a list

It is normal that the answers to your first patch might simply be a list

of a dozen things you should correct.  This does _not_ imply that your

of a dozen things you should correct.  This does **not** imply that your

patch will not be accepted, and it is _not_ meant against you

patch will not be accepted, and it is **not** meant against you

personally.  Simply correct all issues raised against your patch and

personally.  Simply correct all issues raised against your patch and

resend it.

resend it.
@@ -582,19 +581,17 @@ The reasons for breaking things up are the following: 




Here is an analogy from kernel developer Al Viro:

Here is an analogy from kernel developer Al Viro:





::

	*"Think of a teacher grading homework from a math student.  The



	"Think of a teacher grading homework from a math student.  The

	teacher does not want to see the student's trials and errors

	teacher does not want to see the student's trials and errors

	before they came up with the solution. They want to see the

	before they came up with the solution. They want to see the

	cleanest, most elegant answer.  A good student knows this, and

	cleanest, most elegant answer.  A good student knows this, and

	would never submit her intermediate work before the final

	would never submit her intermediate work before the final

	solution.

	solution.*





	The same is true of kernel development. The maintainers and

	*The same is true of kernel development. The maintainers and

	reviewers do not want to see the thought process behind the

	reviewers do not want to see the thought process behind the

	solution to the problem one is solving. They want to see a

	solution to the problem one is solving. They want to see a

	simple and elegant solution."

	simple and elegant solution."*





It may be challenging to keep the balance between presenting an elegant

It may be challenging to keep the balance between presenting an elegant

solution and working together with the community and discussing your

solution and working together with the community and discussing your
@@ -632,7 +629,6 @@ For more details on what this should all look like, please see the 
ChangeLog section of the document:

ChangeLog section of the document:





  "The Perfect Patch"

  "The Perfect Patch"



      http://www.ozlabs.org/~akpm/stuff/tpp.txt

      http://www.ozlabs.org/~akpm/stuff/tpp.txt