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
It's not uncommon to have a large intact parent-chain on targets
(e.g. target_preserve_min=all).
If this is the case, performance drops a bit on "btrbk archive".
Note that we could limit the search depth in get_best_parent() for
some performance improvements, as this only affects extra clones.
Perl hates recursions, and dies if recursion depth = 100:
Deep recursion on subroutine "main::_push_related_children"
Unfortunately this happens before the implemented abort condition
(distance=256).
Fixed by re-implementing get_related_readonly_nodes() non-recursive.
Refs: https://github.com/digint/btrbk/issues/279
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.
With this, previous snapshots (far relations) are still listed when
restoring a snapshot.
Example (S = source subvolume, readwrite):
After 3 snapshots:
A->S, B->S, C->S
Restore B: `btrfs subvol delete S; btrfs subvol snapshot B S'`
A->S, B->S, C->S, S'->B
Previous implementation would show now snapshots for S', as no
snapshot has parent_uuid=S'.
New implementation shows A, B, C as snapshots for S', as orphaned
siblings (A, B, C pointing to deleted S) are also related.
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.
Preferences for parent (and required clone sources):
1. closest older in snapdir (by btrbk timestamp), related
2. closest older related (by cgen)
3. closest newer related (by cgen)
4. closest older in snapdir (by btrbk timestamp)
5. closest newer in snapdir (by btrbk timestamp)
Note: prefering 1 over 2 helps keeping parent-chain within droot on
target (assuming that btrfs always uses correlated parent on
btrfs-receive).
This will e.g. add a clone source on "btrbk resume", if both older AND
newer snapshot/backup pairs exists.
Also makes sure that the closest older btrbk snapshot is always added
as clone source, even if another related subvolume has newer cgen.
Old implementation was missing last readonly parent in chain, as well
as orphaned siblings.
Also sort all by cgen, not by distance, then cgen.
Also skip self.
Axel Burri