mirror of https://github.com/digint/btrbk
a6dbd60e5a
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) |
||
|---|---|---|
| .. | ||
| .gitignore | ||
| FAQ.md | ||
| Makefile | ||
| btrbk.1 | ||
| btrbk.1.asciidoc | ||
| btrbk.conf.5 | ||
| btrbk.conf.5.asciidoc | ||
| install.md | ||
| ssh_filter_btrbk.1 | ||
| ssh_filter_btrbk.1.asciidoc | ||
| upgrade_to_v0.23.0.md | ||