It would be nice to have the complete documentation available locally, not only the manual pages. Thank you!
Upstream dev here. Please let me know if there's anything I can do to make this easier. (Ideally in the form of a borgmatic ticket.) Today, the online documentation is "packaged" and served as a container image, but I realize that's not the most convenient way to consume offline documentation in Debian. Dan
Hi Dan I had a look but the current build is to complex to have documentation built from source with the package. Ideally, with python project, we have a sphinx documentation which integrate nicely. But this is quite some work to migrate the current doc to something else I guess. An alternative would be to release the documentation already built for the tag being released. For instance as an extra tarbal in the release page. What do you think? Cheers k
I'd prefer not to migrate to Sphinx, but what I did was put a tarball of the generated HTML for the docs into the packages repository of borgmatic. You can find it here: https://projects.torsion.org/borgmatic-collective/borgmatic/packages If you click on borgmatic-docs, you'll see that the URL has the version number in it, so you should be able to fetch it programmatically for a particular version. I hope that helps. Please let me know if you have any feedback on this. Thanks, Dan
Hi Kaliko, I agree that it's complex, and a time-sink, but is it really too complex? I took a quick look at the Dockerfile and these two things stood out as blockers: 1. 11ty-* eleventy-* isn't part of Debian. I have a decade-old RFP for an unrelated node/libjs thing, so I feel like to address this on a realistic timeline someone will need to learn nodejs Debian packaging. 2. fetch-contributors >> /contributors.html. Network access is forbidden for Debian package builds. What did I miss? Best, Nicholas
Hi, This approach appears to make it impossible for uscan to find the documentation tarball. Kaliko requested that the documentation tarball is published on the same page as the borgmatic release tarball (similarly to how gpg signature are published for a release), because this uses Gitea's release tracking interface. To be fair, maybe I was unsuccessful at defeating what appears to be an anti-scraping feature, or alternatively I was unsuccessful at storing in a variable the version scraped from the Gitea API for the source code, and then using that to write a URL to target a specifically correlated documentation tarball. Regards, Nicholas
Hi Nicholas, Thanks for taking care of borgmatic in Debian :) Same here, I came to the conclusion it was not worth trying to build doc from source, as an alternative I was considering shipping a script to download documentation built upstream [0], thanks Dan for providing it :) But in the mean time I failed to resume my work on the package. [0] https://projects.torsion.org/borgmatic-collective/borgmatic/packages Cheers k.
I can't speak to 11ty packaging, but the contributors script could be skipped for packaging purposes; it's just a "nice to have" for the documentation that produces this section: https://torsion.org/borgmatic/#recent-contributors Dan
https://projects.torsion.org/borgmatic-collective/borgmatic/releases ... See borgmatic-docs.tar.gz Dan
Dan Helfman <witten@torsion.org> writes: It took a while to figure out a method to infer a version for this unversioned tarball, but it's working now. Resolving a bunch of nonDFSG issues comes next. Ie: I'm sure BenchNine is a great font, but in Debian we don't provide fonts that haven't been compiled on our infrastructure. This needs a solution. I haven't yet investigated if there's any JS (ie for the search function), but bundled, vendored, and especially minified copies of these are also prohibited. In some cases it's sufficient to provide the source alongside the compiled copy. For example, that's what we're doing with the documentation source (borgmatic-$version/docs) alongside the additional tarball component (unpackaged to borgmatic-$version/documentation). Best, Nicholas
Okay, let me know if you'd like me to change it to put the version number in the filename. Done. (In main. This will be in the next docs release tarball.) It's definitely minified, but not vendored in the source. As far as I know, this is just how Pagefind <https://pagefind.app/> works, and there's not an option to skip the minification. I don't know what the constraints are on your side, but here's the Pagefind source for the most recent version <https://github.com/Pagefind/pagefind/archive/refs/tags/v1.4.0.tar.gz>. (Side note: Here's the ITP <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1111971> for it.) Alternatively, it /may/ be possible to strip out the search functionality from the borgmatic docs tarball. Let me know your thoughts. Dan
Hi Dan, Sorry for the delay. Reply follows inline: Dan Helfman <witten@torsion.org> writes: Maybe later? Let's get the significant blocker[s] out of the way first :) Sorry at the time I wrote "resolving a bunch of nonDFSG issues comes next" I hadn't yet looked into this more and thus hadn't yet learned that BenchNine is licensed "SIL v1.1 with Reserved Font Name 'BenchNine'". If I understand the discussion correctly, resolving this requires a nontrivial amount of Debian-side work to package BenchNine source, build it, compare the results to the upstream-distributed font, but then distribute the upstream provided copy. https://lists.debian.org/debian-legal/2026/01/msg00003.html https://lists.debian.org/debian-legal/2026/02/msg00004.html So it's possible with font-building-specific work. Excellent to hear that this isn't a vendored copy. Oh, nice, thank you for finding this! I'll ping Jonas momentarily. After Pagefind is packaged the nascent borgmatic-docs package will load the locally-installed copy. This is what we do for things like jquery-ui, which is installed in and loaded from /usr/share/javascript/jquery-ui. I agree that that wouldn't be ideal. Also, one or more users would report a bug asking to restore it. ;) Cheers, Nicholas P.S. Sorry for falling behind with importing new releases. I had hoped to make more fast progress with the docs, and have also been starved for free time, energy, and reliable hardware.
Got it. In the meantime, the existing tarball without the font should work. That sounds like it'll be fine as long as the locally installed copy can consume the borgmatic-specific Pagefind indices from the tarball. No worries.. There's only so much of those to go around. Dan