Package maintainers like to build everything from scratch, removing
overhead. Again, we apologize for the inconvenience.
Note that reproducible builds are still guaranteed by setting
SOURCE_DATE_EPOCH in doc/Makefile.
Reverts: a6dbd60e5a documentation: add pre-generated man pages: from groff to asciidoc and back again
This reduces build-time dependencies to zero, helping package
maintainers and providing reproducible builds.
NOTE: generated man pages will only be updated on releases. In order
to make sure the docs are correctly rebuilt, run "make clean man". We
apologize for the inconvenience.
From Groff to Asciidoc and Back Again [1]
=========================================
| Comparison | Links |
| -------------------------------------------------------------------------| -------------------------------------------------------------------------------------------------------------- |
| **Plain ROFF** | |
| +++ Best result for `man` (our main goal!) | |
| - Not supported by github | [btrbk(1) v0.25.1 in plain groff](https://github.com/digint/btrbk/blob/v0.25.1/doc/btrbk.1) |
| - No decent converters: e.g. `groff -Txhtml -mandoc` | [btrbk(1) v0.25.1 at digint.ch (official site)](https://digint.ch/btrbk/doc/archive/btrbk-0.25.1/btrbk.1.html) |
| | |
| **asciidoc** | |
| + Decent (scriptable!) html | [btrbk(1) v0.26.1 at digint.ch (official site)](https://digint.ch/btrbk/doc/archive/btrbk-0.26.1/btrbk.1.html) |
| + Supported by github (helps contributors writing decent documentation) | [btrbk.1.asciidoc v0.26.1 at github](https://github.com/digint/btrbk/blob/master/doc/btrbk.1.asciidoc) |
| | |
| **asciidoc (`xmlto`, `atx`)** | http://asciidoc.org/ |
| + Good result for `man` | |
| - EOL (why care that much? it works fine!) | [asciidoc EOL notice at github](https://github.com/asciidoc/asciidoc/releases/tag/8.6.10) |
| | |
| **asciidoc (`asciidoctor`)** | https://asciidoctor.org |
| - Pulls in tons of ruby (build depends) | https://bugs.gentoo.org/681056 |
| -- Implies to commit a pre-converted `doc/btrbk.1` | |
| + Seems more evolved than `xmlto`, still actively maintained | |
| | |
| **rst (`xrst2man.py` from docutils)** | |
| - Worse result for `man` | |
| ++ Good html converters (after having a quick look at it) | |
| - Not so well supported by github | [btrbk.1.rst v0.26.1 at github](https://github.com/digint/btrbk/blob/rst2man/doc/btrbk.1.rst) |
[1] https://github.com/digint/btrbk/pull/219 (edited)
Remove support for man page generation using asciidoc "a2x": The
project is discontinued, and depends on Python 2.7.
As we will provide pre-generated man pages as of btrbk-0.28.0, this is
not needed any more.
Makes sure that if, for whatever reason, a subvolume having correct
btrbk name scheme does NOT share any extents with previous snapshots
is never used as parent.
Note that if a related parent is found, the unrelated closest
older/newer (by btrbk timestamp) subvolumes are still added as clone
sources.
Allowed values for "incremental_resolve":
- "mountpoint" (default): Use parents in the filesystem tree below
mount points of source `<volume-directory>/<snapshot-dir>` and
target `<target-directory>`.
- "directory": Use parents strictly below source/target
directories. Useful when restricting access, e.g. when using
ssh_filter_btrbk.sh.
- "_all_accessible" (experimental): Use parents from all mount points.
Note that using "_all_accessible" causes btrfs-progs to fail:
- btrfs send -p: "ERROR: not on mount point: /path/to/mountpoint"
- btrfs receive: "ERROR: parent subvol is not reachable from inside the root subvol"
see also: https://github.com/kdave/btrfs-progs/issues/96
Common virtual machine setups have multiple volume sections with same
host, but distinct port numbers for each machine.
- make caches dependent on MACHINE_ID instead of HOST
- append port number to URL
- add MACHINE_ID to vinfo
- use MACHINE_ID where applicable
This even works if virtual machines share the same btrfs filesystems:
If a equal UUID is found on distinct machines, btr_tree() will return
the already present tree, in order to be consistent after node
injections.
Setting the ssh port directly in the "volume" / "target" config lines
adds the possibility to have a create a unique "hostname:port"
identifier (preparatory for MACHINE_ID to distinguish virtual machines
on same host with different ports.)
While on traditional UNIX the documentation (especially the man pages)
are gzip'ed, modern distros have helpers to compress it.
This patch adds an option to disable compression:
make COMPRESS=no
It is possible that the subvolume path is not accessible by the user
calling btrbk. When resolving mount points, "readlink" is used on the
path, which also needs to be wrapped with "sudo".
When using asciidoctor, backend "manpage" (-b manpage) is used, while
a2x converts asciidoc to docbook (xml), then manpage.
Asciidoctor creates ugly indentation for [literal] blocks in SYNOPSIS,
use [verse] instead.
Axel Burri