inc/test-eom-align: Cut down on the flicker by re-ordering tests.

[nmh] / docs / README.manpages

diff --git a/docs/README.manpages b/docs/README.manpages
index 42bd6a35a9057bd0b05c0b5d5da6f5d5a2426ddd..f5a802afa47857ab8715c3572ae2678fe94a659e 100644 (file)
--- 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