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: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
parent
43fb67a525
commit
34fed7e7e0
|
@ -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
|
||||||
|
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue