Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1486381

[PATCH v4 24/29] Documentation/HOWTO: improve some markups to make it visually better

Show all headers | View raw

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>
---
 Documentation/HOWTO | 36 ++++++++++++++++--------------------
 1 file changed, 16 insertions(+), 20 deletions(-)

diff --git a/Documentation/HOWTO b/Documentation/HOWTO
index f297d5512885..784724aa4f34 100644
--- a/Documentation/HOWTO
+++ b/Documentation/HOWTO
@@ -292,11 +292,9 @@ process is as follows:
 It is worth mentioning what Andrew Morton wrote on the linux-kernel
 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
-	preconceived timeline."
+	preconceived timeline."*
 
 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.
 
 If you add patches to your mail, make sure they are plain readable text
-as stated in Documentation/SubmittingPatches. Kernel developers don't
-want to deal with attachments or compressed patches; they may want
-to comment on individual lines of your patch, which works only that way.
-Make sure you use a mail program that does not mangle spaces and tab
-characters. A good first test is to send the mail to yourself and try
-to apply your own patch by yourself. If that doesn't work, get your
-mail program fixed or change it until it works.
+as stated in Documentation/SubmittingPatches.
+Kernel developers don't want to deal with
+attachments or compressed patches; they may want to comment on
+individual lines of your patch, which works only that way. Make sure you
+use a mail program that does not mangle spaces and tab characters. A
+good first test is to send the mail to yourself and try to apply your
+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.
 
@@ -496,8 +495,8 @@ Remember, being wrong is acceptable as long as you are willing to work
 toward a solution that is right.
 
 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
-patch will not be accepted, and it is _not_ meant against you
+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
 personally.  Simply correct all issues raised against your patch and
 resend it.
 
@@ -582,19 +581,17 @@ The reasons for breaking things up are the following:
 
 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
 	before they came up with the solution. They want to see the
 	cleanest, most elegant answer.  A good student knows this, and
 	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
 	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
 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:
 
   "The Perfect Patch"
-
       http://www.ozlabs.org/~akpm/stuff/tpp.txt
 
 
-- 
2.7.4

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[PATCH v4 00/29] Create a book for Kernel development Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 09/29] Documentation/Changes: add minimal requirements for documentation build Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 01/29] doc-rst: add CSS styles for :kbd: and :menuselection: Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 08/29] Documentation/Changes: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 03/29] doc: development-process: rename files to rst Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 04/29] docs-rst: create a book for the development process Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 05/29] Documentation/HOWTO: convert to ReST notation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 06/29] Documentation/applying-patches.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 28/29] Documentation/email-clients.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 25/29] Documentation/HOWTO: adjust external link references Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 11/29] Documentation/CodingStyle: use the proper tag for verbatim font Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 14/29] Documentation/ManagementStyle: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
    Re: [PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert  it to ReST markup Greg KH <greg@kroah.com> - 2016-09-20 09:10 +0200
  [PATCH v4 12/29] Documentation/CodingStyle: replace underline markups Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 27/29] Documentation/SubmitChecklist: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 02/29] doc: development-process: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 16/29] Documentation/stable_api_nonsense.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 20/29] Documentation/SubmittingPatches: enrich the Sphinx output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 07/29] Documentation/applying-patches.txt: Update the information there Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 10/29] Documentation/CodingStyle: Convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 24/29] Documentation/HOWTO: improve some markups to make it visually better Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 13/29] Documentation/CodingStyle: use the .. note:: markup where needed Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 23/29] Documentation/HOWTO: update information about generating documentation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 22/29] Documentation/HOWTO: add cross-references to other documents Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
    Re: [PATCH v4 22/29] Documentation/HOWTO: add cross-references to  other documents Greg KH <greg@kroah.com> - 2016-09-20 09:10 +0200
  [PATCH v4 26/29] Documentation/SubmitChecklist: update kernel-doc task Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 15/29] Documentation/SecurityBugs: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 19/29] Documentation/SubmittingPatches: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 18/29] Documentation/SubmittingDrivers: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  Re: [PATCH v4 00/29] Create a book for Kernel development Jonathan Corbet <corbet@lwn.net> - 2016-09-21 02:50 +0200
    Re: [PATCH v4 00/29] Create a book for Kernel development Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-21 11:30 +0200

csiph-web