The manpages are generated by processing *.m4 files using m4.

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:

Overall 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

The ".TH" and ".SH" macros are explained (a little) below.


Inline formatting ("escapes"):

\fB - set bold
\fI - set italic (may show as underlined when output on console)
\fR - set regular (i.e. unset bold & italic)


Special characters (see groff_char(7)):

'\ ' - (backslash followed by space) - non-breaking space
\e - literal backslash ('\[rs]' also works)
\& - zero-width space
\- - minus sign (also suppresses line breaking through hyphen)
\[em] - em-dash
\[en] - en-dash
\[bu] - bullet point
\[lq], \[rq] - left and right double-quote (").
` and ' (backtick and apostrophe) - use for opening/closing single quotes

(Note that '\[xy]' can be written as '\(xy', which is also portable to legacy troff
implementations, but we prefer the former). 


Line commands ("requests"):

.\" - 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)

... 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.
.SS <name> - heading for a subsection (similar to .SH, for one level down in the document structure).
.LP - begin a new normal paragraph (not required after .SH/.SS, and should be omitted).
.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); .TQ can be used
      immediately after the first label, in order to specify additional labels, each appearing on their
      own line.
.IP - indented paragraph (can be used to follow on from .TP)
.IP \(bu - indented paragraph with bullet point
.RS - increase left margin by one level (and reset indentation)
.RE - decrease left margin by one level
.EX - begin example (monospace font, line ends as they appear in source)
.EE - end example


Formatting rules for Dinit man pages:

 * Executable names (dinit, dinit-check, etc) should be in bold, eg: \fBdinit\fR
 * Keywords, setting names, environment variable names, and literal setting values should be in
   bold
 * Literal output of or input for a program should be single-quoted: `like this'
 * Placeholder names for parameter values should be italicised: \fIlike-this\fR.
 * Filenames/paths should be italicised.
 * Command line options with "hyphens" should use minus signs (i.e. as typed): \-\-like\-this
   ... and should be in bold: \fB\-\-like\-this\fR
   ... and when appearing in prose should also be single-quoted: `\fB\-\-like\-this\fR'
 * Scare quotes, used to indicate a non-standard/slang/semi-technical term, use double quotes:
   \[lq]like this[\rq].
 * To cross-reference another man page, put the page name in bold and follow it with the section
   in parentheses (in regular, not bold, text), like this: \fBdinit\fR(8)
 * To cross-reference a section, specify the section title in CAPITALS and bold,
   \fBLIKE THIS\fR.


Gotchas:

* Sentences should always end (with a period) at the end of a line (this affects spacing in
  output). I.e. a new sentence should always begin on a new line.
* 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.
* Blank lines should be avoided. Use .LP/.HP/.TP/.IP for example to start a paragraph. Use .IP for
  follow-on paragraphs after .TP. Use .sp for space within a paragraph in the rare case that is
  needed. Use '.\' (comment) to insert space in the source document in a way that does not affect
  the output.


For synopsis:

.PD 0        -- no space between paragraphs
.nh          -- disable hyphenation
.HP          -- begin hanging paragraph
(command goes here)
.HP
(next command variant)
.PD          -- default paragraph spacing
.hy          -- default hyphenation
