dinit/doc/manpages/README

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:


Inline formatting ("escapes"):

\fB - set bold
\fI - set italic (shows as underlined when output on console)
\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 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. See also .RS/.RE which should normally be used in
      preference.

... 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 (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
.RS - increase left margin by one level (and reset indentation). Should typically be used instead of ".in".
.RE - decrease left margin by one level
.EX - begin example (monospace font, line ends as they appear in source)
.EE - end example

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 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 .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:

.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