README 3.4 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283
  1. The manpages are generated by processing *.m4 files using m4.
  2. Manpages are written in "roff", which is an ancient text formatting/markup system and language
  3. with a lot of peculiarities. For the Dinit manpages we try to stick to the subset documented here.
  4. Roff formatting guide:
  5. Inline formatting ("escapes"):
  6. \fB - set bold
  7. \fI - set italic (shows as underlined when output on console)
  8. \fR - set regular (i.e. unset bold & italic)
  9. Special characters:
  10. '\ ' - (backslash followed by space) - non-breaking space
  11. \& - zero-width space
  12. \- - non-breaking dash (avoid automatic line-splitting due to hyphen)
  13. \(em - em-dash (GNU groff accepts "\[em]" as well but it may not be portable)
  14. \(en - en-dash
  15. \(bu - bullet point
  16. Line commands ("requests"):
  17. .\" - begins a comment line (may be used for spacing in source document without the effect that having a
  18. line would)
  19. .sp - vertical space (i.e. blank line without breaking paragraph); not really necessary since you can get
  20. the same effect with a blank line in the source document.
  21. .in - set or adjust indent (if given an argument). Argument should be "7m" for example (m = em's,
  22. i = inches) i.e. ".in 7m"; "+7m" increases, "-7m" decreases current indent by specified amount.
  23. Without argument is supposed to restore indent from before previous .in, but mandoc gets this wrong
  24. and always just restores initial indent value. See also .RS/.RE which should normally be used in
  25. preference.
  26. ... and macros (which behave like requests). Arguments can be quoted ("...") if they contain
  27. spaces.
  28. .TH <title> <section> [<up to three extras>] - title macro. See "structure" notes below.
  29. .SH <name> - section heading for <name> (name usually capitalised). If name is omitted the
  30. next line is used.
  31. .LP - begin a new normal paragraph
  32. .HP - begin a hanging paragraph (lines after the first are indented)
  33. .TP - begin an indented paragraph with unindented label (label is on the next line)
  34. .IP \(bu - indented paragraph with bullet point
  35. .RS - increase left margin by one level (and reset indentation). Should typically be used instead of ".in".
  36. .RE - decrease left margin by one level
  37. .EX - begin example (monospace font, line ends as they appear in source)
  38. .EE - end example
  39. Structure:
  40. Documents should start with a .TH header line ("8" is the man section):
  41. .TH DINIT "8" "October 2022" "Dinit 0.16.1" "Dinit - service management system"
  42. This should be followed by a NAME section:
  43. .SH NAME
  44. dinit \- supervise processes and manage services
  45. Gotchas:
  46. * Sentences should always end at the end of a line (this affects spacing in output).
  47. * hyphens which are actually part of a word (part of a setting name for example) should be
  48. preceded by a backslash ("\-") which will prevent the literal from being split over multiple lines.
  49. * A blank line doesn't technically start a new paragraph (but does produce a blank line in the output).
  50. It's probably better to use .LP/.HP/.TP for example to start a paragraph.
  51. * There are effectively two ways to indent text: one is to set the indent (.in), another is to set the
  52. left margin (.RS/.RE). The latter is usually preferred.
  53. For synopsis:
  54. .PD 0 -- no space between paragraphs
  55. .nh -- disable hyphenation
  56. .HP -- begin hanging paragraph
  57. (command goes here)
  58. .HP
  59. (next command variant)
  60. .PD -- default paragraph spacing
  61. .hy -- default hyphenation