documentation: disable hyphenation and justification in man-pages; use .PP and .RS 4 instead of .TP, which creates more predictable output

doc/btrbk.1

@@ -1,8 +1,14 @@
 .TH "btrbk" "1" "2015-09-02" "btrbk v0.20.0" ""
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
 .SH NAME
 btrbk \- backup tool for btrfs volumes
 .SH SYNOPSIS
+.nf
 \fBbtrbk\fR [\-\-version] [\-\-help] [\-c <file>] [\-p] [\-v] [\-q] [\-l <level>] <command> [<args>]
+.fi
 .SH DESCRIPTION
 \fBbtrbk\fR is a backup tool for btrfs subvolumes, taking advantage of
 btrfs specific capabilities to create atomic snapshots and transfer
@@ -10,45 +16,65 @@ them incrementally to target volumes. It is able to perform backups
 from one source to multiple destinations.
 .PP
 Snapshots as well as backup subvolume names are created in form:
-.IP
+.PP
+.RS 4
 <source_name>.YYYYMMDD[_N]
+.RE
 .PP
 Where YYYY is the year, MM is the month, and DD is the day of
 creation, and, if multiple backups are created on the same day, N will
 be incremented on each backup, starting at 1.
 .SH OPTIONS
-.TP
+.PP
 \-\-version
+.RS 4
 Prints the btrbk version.
-.TP
+.RE
+.PP
 \-h, \-\-help
+.RS 4
 Prints the synopsis and a list of the commands.
-.TP
+.RE
+.PP
 \-c, \-\-config <file>
+.RS 4
 Read the configuration from <file>.
-.TP
+.RE
+.PP
 \-p, \-\-preserve
+.RS 4
 Preserve all backups. Skips deletion of old backups, even if specified
 in the configuration file.
-.TP
+.RE
+.PP
 \-r, \-\-resume-only
+.RS 4
 Resume only. Skips snapshot creation, only resumes missing
 backups. This only makes sense if the \fIresume_missing\fR option is
 set to \[lq]yes\[rq] in the configuration file.
-.TP
+.RE
+.PP
 \-v, \-\-verbose
+.RS 4
 Verbose output. Identical to: \-l info.
-.TP
+.RE
+.PP
 \-q, \-\-quiet
+.RS 4
 Quiet operation. If set, btrbk does not print the summary after
 executing the "run" command.
-.TP
+.RE
+.PP
 \-l, \-\-loglevel <level>
+.RS 4
 Set the level of verbosity. Accepted levels are warn, info, debug,
 and trace.
-.TP
+.RE
+.PP
 \-\-progress
+.RS 4
 Show progress bar on send-receive operation.
+.RE
 .SH COMMANDS
 .PP
 .B run
@@ -119,14 +145,15 @@ parent-child relationship as well as the received-from information.
 Print new files since subvolume <from> for subvolume <to>.
 .RE
 .SH FILES
-.TP
+.PP
 /etc/btrbk.conf
-.PD 0
+.br
-.TP
 /etc/btrbk/btrbk.conf
+.RS 4
 Default configuration file. The file format and configuration options
 are described in
 .BR btrbk.conf (5).
+.RE
 .PD
 .SH EXIT STATUS
 .sp

doc/btrbk.conf.5

@@ -1,4 +1,8 @@
 .TH "btrbk.conf" "5" "2015-09-02" "btrbk v0.20.0" ""
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
 .SH NAME
 btrbk.conf \- btrbk configuration file
 .SH SYNOPSIS
@@ -17,18 +21,23 @@ superseding the values set in upper-level sections. This means that
 global options must be set before any sections are defined.
 .PP
 The sections are:
-.TP
+.PP
 \fBvolume\fR  <volume-directory>|<url>
+.RS 4
 Directory of a btrfs volume containing the source subvolume(s) to be
 backed up. \fI<volume-directory>\fR must be an absolute path and point
 to a btrfs volume (or subvolume). Usually the mount point of a btrfs
 filesystem mounted with the \fIsubvolid=0\fR option.
-.TP
+.RE
+.PP
 \fBsubvolume\fR  <subvolume-name>
+.RS 4
 Subvolume to be backed up, relative to the \fI<volume-directory>\fR
 specified in the \fIvolume\fR section.
-.TP
+.RE
+.PP
 \fBtarget\fR  <type> <volume-directory>|<url>
+.RS 4
 Target type and directory where the backup subvolumes are to be
 created. \fI<volume-directory>\fR must be an absolute path and point
 to a btrfs volume (or subvolume). Currently the the only valid
@@ -36,26 +45,36 @@ to a btrfs volume (or subvolume). Currently the the only valid
 .PP
 For the \fIvolume\fR and \fItarget\fR sections, you can also specify a
 ssh-url instead of a local directory. The syntax for \fI<url>\fR is:
-.IP
+.PP
+.RS 4
+.nf
 ssh://host.xz/path/to/volume
+.fi
+.RE
 .PP
 Note that btrfs is very picky on file names (mainly for security
 reasons), only the characters [0-9] [a-z] [A-Z] and "._+-@" are
 allowed.
+.RE
 .PP
 The configuration options are:
-.TP
+.PP
 \fBsnapshot_dir\fR  <directory>
+.RS 4
 Directory in which the btrfs snapshots are created, relative to
 \fI<volume-directory>\fR of the \fIvolume\fR section. Note that btrbk
 does not autmatically create this directory, and the snapshot creation
 will fail if it is not present.
-.TP
+.RE
-\fBsnapshot_name\fR <basename> Base name of the created snapshot (and
+.PP
-backup). This option is only valid in the \fItarget\fR
+\fBsnapshot_name\fR <basename>
-section. Defaults to \fI<subvolume-name>\fR.
+.RS 4
-.TP
+Base name of the created snapshot (and backup). This option is only
+valid in the \fItarget\fR section. Defaults to \fI<subvolume-name>\fR.
+.RE
+.PP
 \fBsnapshot_create\fR  always|ondemand|onchange|no
+.RS 4
 If set to \[lq]ondemand\[rq], snapshots are only created if the target
 subvolume is reachable (useful if you are tight on disk space and you
 only need btrbk for backups to an external disk which is not always
@@ -67,74 +86,101 @@ created. If set to \[lq]no\[rq], the snapshots are never created
 (useful in conjunction with the \fIresume_missing\fR option if another
 instance of btrbk is taking care of snapshot creation). Defaults to
 \[lq]always\[rq].
-.TP
+.RE
+.PP
 \fBincremental\fR  yes|no|strict
+.RS 4
 If set, incremental backups are created. If set to \[lq]strict\[rq],
 non-incremental (initial) backups are never created. Defaults to
 \[lq]yes\[rq].
-.TP
+.RE
+.PP
 \fBresume_missing\fR  yes|no
+.RS 4
 If set, the backups in the target directory are compared to the source
 snapshots, and missing backups are created if needed (complying to the
 target preserve matrix). Defaults to \[lq]yes\[rq].
-.TP
+.RE
+.PP
 \fBtarget_preserve_daily\fR  all|<number>
+.RS 4
 How many days of backups should be preserved. Defaults to \[lq]all\[rq].
-.TP
+.RE
+.PP
 \fBtarget_preserve_weekly\fR  all|<number>
+.RS 4
 Defines for how many weeks back weekly backups should be
 preserved. Every backup created at \fIpreserve_day_of_week\fR (or
 the next backup in this week if none was made on the exact day) is
 considered as a weekly backup. Defaults to \[lq]0\[rq].
-.TP
+.RE
+.PP
 \fBtarget_preserve_monthly\fR  all|<number>
+.RS 4
 Defines for how many months back monthly backups should be
 preserved. Every last weekly backup in a month is considered a
 monthly backup. Defaults to \[lq]all\[rq].
-.TP
+.RE
+.PP
 \fBsnapshot_preserve_daily\fR
 .PD 0
-.TP
+.PP
 \fBsnapshot_preserve_weekly\fR
-.TP
+.PP
 \fBsnapshot_preserve_monthly\fR
+.RS 4
 Defines retention policy for the snapshots, with same semantics as the
 \fItarget_preserve_*\fR options.
+.RE
 .PD
-.TP
+.PP
 \fBpreserve_day_of_week\fR  monday|tuesday|...|sunday
+.RS 4
 Defines on what day a backup/snapshot is considered as a weekly
 backup. Defaults to \[lq]sunday\[rq].
-.TP
+.RE
+.PP
 \fBssh_identity\fR  <file>
+.RS 4
 Absolute path to a ssh identity file (private key). Note that if the
 private key is password protected, btrbk will prompt for user input,
 which is usually not desired.
-.TP
+.RE
+.PP
 \fBssh_user\fR  <username>
+.RS 4
 Remote username for ssh. Defaults to \[lq]root\[rq]. Note that you will
 have to make sure that the remote user is able to run /sbin/btrfs
 (which needs root privileges).
-.TP
+.RE
+.PP
 \fBssh_port\fR  <port>
+.RS 4
 Port to connect to on the remote host. Defaults to \[lq]default\[rq]
 (the port specified in \fIssh_config\fR, which defaults to 22).
-.TP
+.RE
+.PP
 \fBssh_compression\fR  yes|no
+.RS 4
 Enables or disables the compression of ssh connections. Defaults to
 \[lq]no\[rq].
-.TP
+.RE
+.PP
 \fBbtrfs_commit_delete\fR  after|each|no
+.RS 4
 If set, make sure the deletion of snapshot and backup subvolumes are
 committed to disk when btrbk terminates. Defaults to \[lq]no\[rq].
-.TP
+.RE
+.PP
 \fBbtrfs_progs_compat\fR  yes|no \fI*experimental*\fR
+.RS 4
 Enable compatibility mode for btrfs-progs < 3.17 (\fIbtrfs
 --version\fR). This option can be set either globally or within a
 \fItarget\fR section.  If enabled, the latest common snapshots are
 determined by subvolume names instead of \fIreceived_uuid\fR, which
 can lead to false guesses if the snapshot or target subvolumes are
 manipulated by hand (moved, deleted).
+.RE
 .PP
 Lines that contain a hash character (#) in the first column are
 treated as comments.