Writing style: additions, improvements

documentation/content/en/books/fdp-primer/writing-style/_index.adoc

@@ -154,12 +154,17 @@ Wrong: ... in the filename [.filename]#/etc/rc.local#...
 +
 Right: ... in [.filename]#/etc/rc.local#...
 +
-Manual page references (the second example uses `man:[]` with the man:csh[1] entity):
+Manual page references:
 +
 Wrong: See `man csh` for more information.
 +
 Right: See man:csh[1].
 
+[TIP]
+====
+`man:csh[1]` -- `man:` for the FreeBSD-defined _ManPageMacro_, `csh` names a page and `[1]` specifies the section of the manual from which the named page is taken.
+====
+
 For more information about writing style, see http://www.bartleby.com/141/[Elements of Style] by William Strunk.
 
 [[writing-style-guide]]
@@ -168,7 +173,7 @@ For more information about writing style, see http://www.bartleby.com/141/[Eleme
 To keep the source for the documentation consistent when many different people are editing it, please follow these style conventions.
 
 [[one-sentence-per-line]]
-== One sentence per line
+=== One sentence per line
 
 Use Semantic Line Breaks in the documentation, a technique called "one sentence per line".
 The idea of this technique is to help the users to write and read documentation.
@@ -187,10 +192,36 @@ All human beings are born free and equal in dignity and rights.
 They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.
 ....
 
+[[sentence-spacing]]
+=== Spaces between sentences
+
+There are two conventions.
+
+*Generally*: 
+
+* one space. 
+
+This generalization includes monospaced representation of monospaced texts that do _not_ follow the two spaces convention.
+
+Where a variable-width font will be used: the link:{one-sentence-per-line}[per-line convention] will usually negate the need to think about spacing. 
+
+If a multi-sentence list item does use a space between sentences (with the possibility of strictly replacing the space with a line break): 
+
+* consider edition, to have no more than one sentence per point
+** do not assume that nesting of points is the solution
+*** as an alternive to nesting, consider de-nesting nearby text -- for example, adjacent bullet points might be promoted to simple paragraphs.
+
+*Exceptionally*: 
+
+* two spaces in errata notices
+* two spaces in security advisories
+* two spaces in link:../manual-pages/[manual pages]
+* two spaces in other files that will normally be viewed with a monospaced font.
+
 [[writing-style-acronyms]]
-== Acronyms
+=== Acronyms
 
-Acronyms should be defined the first time they appear in a document, as in: "Network Time Protocol (NTP)".
+Acronyms should be defined the first time they appear in a document, as in: "Network Time Protocol (`NTP`)".
 After the acronym has been defined, use the acronym alone unless it makes more sense contextually to use the whole term.
 Acronyms are usually defined only once per chapter or per document.
 
@@ -321,7 +352,7 @@ This rule proposes better wording.
 
 . FreeBSD.Hyphens: Often adverbs ending with 'ly' are added with a hyphen which is wrong.
 
-. FreeBSD.Spacing: Often double spaces are hard to catch with the naked eye and this is addressed here.
+. FreeBSD.Spacing: Between a pair of sentences, it may be incorrect to have two spaces (see link:{sentence-spacing}[spacing between sentences]). 
 
 . FreeBSD.SuperfluousOptArgInLinks: Suggest to empty square brackets in `link:` macros when the displayed text coincides with the URL.