borgbackup for Debian
---------------------

After discussion at #792096, it was agreed that we should rebuild
the cython *.c files during build. This is currently done in
debian/rules clean.

When updating the package, please check whether files have been added
or removed from the set and update CYTHON_FILES accordingly.


When upating the package, please also check whether the explicitly
given versioned runtime dependency on python3-msgpack is still
necessary; On my tests python3:Depends only picked up a non-versioned
dependency.

 -- Danny Edel <mail@danny-edel.de>  Fri, 16 Oct 2015 10:30:00 +0200


TL;DR: when updating this package, please update debian/attic.1
manually. The date and version number need to be updated, and any new
commands or global options must also be added.

Packaging, manpage, and even this file was used from the attic package
by Caitlin Matos.

This package is not intended to be uploaded to Debian until a
maintainer team of at least two active persons has formed

 -- Marc Haber <mh+debian-packages@zugschlus.de>  Sat, 11 Jul 2015 12:00:00 +0200

DETAILS:

This Debian version of this package includes a manpage under debian/attic.1. This manpage was originally created for attic version 0.13-1. Because of the many complexities of auto-generating manpages, the included file is specific to version 0.13, and must be manually altered for each upgrade of attic. What follows is the minutia of what I have done to create this manpage, as well as other alternatives I tried and the rationale for why I eventually chose this particular format.

I will be submitting all of this upstream, so there's a possibility that this file will disappear. :)

Attic does not include a manpage. The Sphinx documentation available under docs/ is able to generate a manpage using the included Makefile (cd docs && make man). However, while the generated file is technically a manpage (groff syntax), it is really a website forced into a manpage. It is not a traditional manpage, and actually quite confusing when laid out in this manner.

My next recourse was the GNU utility help2man, generating the manpage under the override_dh_installman target. Here I encountered several problems. First and foremost, lintian was not happy with the generated output, giving a "manpage-has-errors-from-man" warning. Specifically, man was unable to format the page properly because of a very very long list of commands without spaces. Additionally, it did not follow some manpage conventions, and was rather awkward. Also, because attic does not have a --version option and help2man requires it, I had to wrangle the version out of debian/changelog. While I could have entered the version number manually, it seemed senseless--if this had to be updated manually for each release, the primary advantage of using help2man instead of a manually generated manpage was lost. I also could have created a patch for the generated file attic.1, but because the placement of the added/removed lines were in proximity of version-specific information (i.e., lines that said "0.13" in them), the patch would not have been usable for future releases, and again seemed pointless.

I looked at several options, including using another Sphinx page, or creating attic.1.in and having it update various variables (date, version, etc.) via debian/rules. In doing this, however, I would lose the benefit of the automated help documentation from Python's ArgParser, and would have to manually update the page whenever a new option or command was implemented. Again, if manual manipulation is required, auto-generation seemed senseless.

I finally settled on what I have done here. I created the included attic.1 using help2man, then manually edited it. Specifically, I used:
	help2man --version-string=0.13 \
		--name='deduplicating backups' \
		--no-info \
		--include=debian/attic.h2m \
		debian/attic/usr/bin/attic >| ./debian/attic.1
where attic.h2m was the SEE ALSO section. I then made several manipulations to the generated page. Listing all these changes is just confusing; if you really want to know, use the help2man command above and compare it to the included manpage.

When this package is updated in the future, the following should be done for attic.1:
    - change the date
    - change the version
    - add any new commands or global options

Nice and simple. I hope.

 -- Caitlin Matos <caitlin.matos@zoho.com>  Fri, 11 Jul 2014 16:09:28 -0400
