nordic-dev.net/nixpkgs
nordic-dev.net/nixpkgs
2
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2025-01-14 17:04:42 +00:00
Code Issues Packages Projects Releases Wiki Activity
0c601b12bf
nixpkgs/nixos/doc/manual/manpages/README.md
pennae 0c601b12bf nixos/manual: translate manpages to mdoc 
since we want to move away from docbook and having docbook manpages
around is going to block further progress we have to translate the
current nixos manpages from docbook it *something* else. mdoc seems the
most appropriate choice since markdown can't represent all the things
manpages can differentiate with even more extensions. if we ever need
html manpages we can render them using troff, like many of the online
manpage viewers, or rewrite them again. since we haven't had html
manpages for any of these in many years that seems unlikely to happen.

unlike most of the recent markdown conversions this comes with a lot of
minor rendering changes, mostly in spacing. docbook-xslt creates manual
pages in a very different dialect than mdoc (which is used here).
2023-02-03 02:23:07 +01:00

2.7 KiB
Raw Blame History

NixOS manpages

This is the collection of NixOS manpages, excluding configuration.nix(5).

Man pages are written in mdoc(7) format and should be portable between mandoc and groff for rendering (though minor differences may occur, mandoc and groff seem to have slightly different spacing rules.)

Being written in mdoc these manpages use semantic markup. This file provides a guideline on where to apply which of the semantic elements of mdoc.

Command lines and arguments

In any manpage, commands, flags and arguments to the current executable should be marked according to their semantics. Commands, flags and arguments passed to other executables should not be marked like this and should instead be considered as code examples and marked with Ql.

  • Use Fl to mark flag arguments, Ar for their arguments.
  • Repeating arguments should be marked by adding ellipses (...).
  • Use Cm to mark literal string arguments, e.g. the boot command argument passed to nixos-rebuild.
  • Optional flags or arguments should be marked with Op. This includes optional repeating arguments.
  • Required flags or arguments should not be marked.
  • Mutually exclusive groups of arguments should be enclosed in curly brackets, preferrably created with Bro/Brc blocks.

When an argument is used in an example it should be marked up with Ar again to differentiate it from a constant. For example, a command with a --host name flag that calls ssh to retrieve the host's local time would signify this thusly:

This will run
.Ic ssh Ar name Ic time
to retrieve the remote time.

Paths, NixOS options, environment variables

Constant paths should be marked with Pa, NixOS options with Va, and environment variables with Ev.

Generated paths, e.g. result/bin/run-hostname-vm (where hostname is a variable or arguments) should be marked as Ql inline literals with their variable components marked appropriately.

  • Taking hostname from an argument become .Ql result/bin/run- Ns Ar hostname Ns -vm
  • Taking hostname from a variable otherwise defined becomes .Ql result/bin/run- Ns Va hostname Ns -vm

Code examples and other commands

In free text names and complete invocations of other commands (e.g. ssh or tar -xvf src.tar) should be marked with Ic, fragments of command lines should be marked with Ql.

Larger code blocks or those that cannot be shown inline should use indented literal display block markup for their contents, i.e.

.Bd -literal -offset indent
...
.Ed

Contents of code blocks may be marked up further, e.g. if they refer to arguments that will be subsituted into them:

.Bd -literal -offset indent
{
  options.hostname = "\c
.Ar hostname Ns \c
";
}
.Ed