Merge pull request #524 from fwilhe/rework-section-titles

Rework Text on Section Titles

docs/asciidoc-recommended-practices.adoc

@@ -60,23 +60,15 @@ In the Setext-style, the section title is defined on two lines. The second line
  First Section
  -------------
 
-Since the length of the line is determined by the number of characters in the section title, another dimension must be introduced to determine the level. That dimension is the character used for the underline. The mapping is as follows:
-
-[cols="1m,1", width="25%", options="header"]
-|===
-|Character | Heading level
-|=         | 1 (title)
-|-         | 2
-|~         | 3
-|^         | 4
-|+         | 5
-|===
+Since the length of the line is determined by the number of characters in the section title, another dimension must be introduced to determine the level. That dimension is the character used for the underline.
+The characters used are (sorted from document title to level 5 section) `=`, `-`, `~`, `^`, and `+`.
 
 I _strongly_ recommend against using the Setext style for section titles. Keeping the length of the underline in sync with the title length is an unnecessary task and time waster. A more substantial reason is that the mapping between character and heading level is *very* difficult to remember and not obvious to new AsciiDoc adopters. All in all, using Setext section titles is a _bad practice_. *Don't use them!*
 
-TIP: Use the asymmetric Atx-style to define your section titles.
+TIP: The recommendation is to use the asymmetric Atx-style for section titles.
+It's the most simple and intuitive method for writing, as well as for reading in the plain text (source) file.
 
-.Document title
+=== Document title
 
 Since the document title occurs only once in a document, I consider it acceptable to use the Setext style in this instance.