X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/f1920d78123667716f2321d37ce37628603b2700..605516b7c2e68efcd681478d40b210e6af968d58:/docs/README.manpages

diff --git a/docs/README.manpages b/docs/README.manpages
index 42bd6a35..f5a802af 100644
--- a/docs/README.manpages
+++ b/docs/README.manpages
@@ -27,10 +27,10 @@ Troff Considerations
 	When quoting, use \*(lq and \*(rq. This ensures correct
 	formatting on typesetter-like devices.
 
-	Don't use UTF-8 characters in the manpage source.  We still
-	build and run on systems that can't handle this.  And most
-	anything you would want to use has an internal troff character
-	escape sequence, anyway.
+        A man page's source is ASCII, not UTF-8.  troff has escapes for
+        non-ASCII characters, e.g. \(em for an em-dash, U+2014, that are
+        mapped onto whatever the output device supports, e.g. UTF-8 or
+        PDF.
 
 
 Section Ordering
@@ -61,18 +61,11 @@ Section Ordering
 
 Dates
 
-	The DATE in the .TH macro should reflect the most recent
-	*non-trivial* update to the *content* of the manpage;
-	formatting changes don't count.  Spell out the date (no
-	abbreviations or shortcuts):
-
-	  January 2, 1904
-
-	not the unparseable
-
-	  01/02/04
-
-	Don't abbreviate the month.
+        The DATE in the .TH macro is in `yyyy-mm-dd' format, and should
+        reflect the most recent *non-trivial* update to the *content* of
+        the manpage; formatting changes don't count, nor does expanding
+        the `SEE ALSO' list.  Ask "Would the familiar user wish to
+        re-read this page to learn of this change?"
 
 
 Program Names
@@ -99,7 +92,7 @@ SYNPOSIS Section
 
 	Set literal text (such as flags) in bold.  Set parameters
 	in italic.  Mutually exclusive options (like "-foo" and
-	"-nofoo") should be grouped together and seperated by a
+	"-nofoo") should be grouped together and separated by a
 	"|":
 
 		.RI [ +folder ]              <---- parameter
@@ -263,6 +256,35 @@ AUTHOR and HISTORY Sections
 	section might be appropriate for documenting incompatibility
 	with older versions of MH.
 
+Common errors and subjective conventions
+
+        Try to mention `nmh' in the NAME section if it's not too awkward.
+        The command-line `-foo' is an option, not a switch.
+        Describe the default behaviour, then how it can be altered,
+            e.g. an option.
+        It's `see foo(1)', not `see the foo(1) man page for more detail'.
+        Emails have `From' and `Date' headers, not `From:' and `Date:'.
+        An mbox-format file has `"From "' envelope-address headers.
+
+        A hyphen is input as an ASCII minus sign, `non-standard',
+            not as `\-' which is the input to output a minus sign.
+        Use an unbreakable space for RFCs: `RFC\ 822'.
+        Hyphenate compound adjectives, e.g. `mail-drop format'.
+        Don't SHOUT for emphasis.
+            Use `.I' for normal emphasis and `.B' for strongest.
+
+        Use `Unix', not `UNIX'.
+        Use `user ID' and `group ID', not `user-id'.
+        Use `zeroed', not `zero'd'.
+        Use `mail drop', not `maildrop' or `drop box'.
+        Use `messages', not `message(s)', ditto `folders', etc.
+        Use `e.g.', not `eg.', and `i.e.', not `ie.'.
+
+        Use a pair of commas, like this, for parenthetical asides.
+        Use `that' when the clause is essential, without a comma.
+            Use comma then `which' when it's non-essential.
+        `Hence' means `from here';  it's `thus' to introduce a conclusion.
+
 ------------------------------------------------------------------------------
 
 [ This template is a bit behind the times. I will bring it into