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 (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
\& - zero-width space
\- - literal hyphen (also suppresses line breaking through dash)
\(em - em-dash (GNU groff accepts "\[em]" as well but it may not be portable)
\(en - en-dash
\(bu - bullet point

` and ' (backtick / apostrophe) - use for opening/closing single quotes


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.
.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); .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

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 (with a period) 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.
* 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.

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