h/rcvmail.h: Delete. Contained just a couple of pointless macros.

[nmh] / docs / README.manpages

diff --git a/docs/README.manpages b/docs/README.manpages
index 0976d6c439d7e92c399b42dae58ad1fa418ce12e..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
@@ -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