Update README for manpages

doc/manpages/README

@@ -1,6 +1,12 @@
 The manpages are generated by processing *.m4 files using m4.
 
-Roff cheatsheet:
+Manpages are written in "roff", which is an ancient text formatting/markup system and language
+with a lot of peculiarities. For the Dinit manpages we try to stick to the subset documented here.
+
+
+
+Roff formatting guide:
+
 
 Inline formatting ("escapes"):
 
@@ -9,23 +15,58 @@ Inline formatting ("escapes"):
 \fR - set regular (i.e. unset bold & italic)
 
 
+Special characters:
+'\ ' - (backslash followed by space) - non-breaking space
+\& - zero-width space
+\- - non-breaking dash (avoid automatic line-splitting due to hyphen)
+\(em - em-dash (GNU groff accepts "\[em]" as well but it may not be portable)
+\(en - en-dash
+\(bu - bullet point
 
 Line commands ("requests"):
 
-.\" - begins a comment line (may be used for spacing in source document)
+.\" - begins a comment line (may be used for spacing in source document without the effect that having a
+      line would)
+.sp - vertical space (i.e. blank line without breaking paragraph); not really necessary since you can get
+      the same effect with a blank line in the source document.
+.in - set or adjust indent (if given an argument). Argument should be "7m" for example (m = em's,
+      i = inches) i.e. ".in 7m"; "+7m" increases, "-7m" decreases current indent by specified amount.
+      Without argument is supposed to restore indent from before previous .in, but mandoc gets this wrong
+      and always just restores initial indent value. 
+
+... and macros (which behave like requests). Arguments can be quoted ("...") if they contain
+spaces.
+
+.TH <title> <section> [<up to three extras>] - title macro. See "structure" notes below.
+.SH <name> - section heading for <name> (name usually capitalised). If name is omitted the
+             next line is used.
 .LP - begin a new normal paragraph
-.HP - begin a hanging paragraph
-.TP - begin an indented paragraph with unindented label (first line)
+.HP - begin a hanging paragraph (lines after the first are indented)
+.TP - begin an indented paragraph with unindented label (label is on the next line)
 .IP \(bu - indented paragraph with bullet point
-.sp - vertical space (i.e. blank line without breaking paragraph)
+.RS - increase left margin by one level (and reset indentation). Should typically used instead of ".in".
+.RE - decrease left margin by one level
+
+Structure:
+Documents should start with a .TH header line ("8" is the man section):
+
+   .TH DINIT "8" "October 2022" "Dinit 0.16.1" "Dinit - service management system"
+     
+This should be followed by a NAME section:
+
+   .SH NAME
+   dinit \- supervise processes and manage services
+
 
 Gotchas:
 
 * Sentences should always end at the end of a line (this affects spacing in output).
-* hyphens which are actually dashes (part of a setting name for example) should be
-  preceded by a backslash ("\-").
+* hyphens which are actually part of a word (part of a setting name for example) should be
+  preceded by a backslash ("\-") which will prevent the literal from being split over multiple lines.
 * A blank line doesn't technically start a new paragraph (but does produce a blank line in the output).
-  It's probably better to use ".sp" instead. Use .LP/.HP/.TP for example to start a paragraph.
+  It's probably better to use .LP/.HP/.TP for example to start a paragraph.
+* There are effectively two ways to indent text: one is to set the indent (.in), another is to set the
+  left margin (.RS/.RE). The latter is usually preferred.
 
 For synopsis: