[diffoscope] 01/01: Auto-generate manpage using help2man, so it's no longer out-of-date.
Ximin Luo
infinity0 at debian.org
Tue Nov 28 18:14:53 CET 2017
This is an automated email from the git hooks/post-receive script.
infinity0 pushed a commit to branch master
in repository diffoscope.
commit 9aca8feea1629efae683569579c8da0cf660c5b2
Author: Ximin Luo <infinity0 at debian.org>
Date: Tue Nov 28 18:14:11 2017 +0100
Auto-generate manpage using help2man, so it's no longer out-of-date.
---
.gitignore | 2 +
CONTRIBUTING.rst | 70 ++++++++++++++++++++++++++
README.rst | 123 ++++++++++++++-------------------------------
debian/changelog | 6 +++
debian/control | 1 +
debian/diffoscope.1.rst | 74 ---------------------------
debian/diffoscope.manpages | 2 +-
debian/rules | 14 ++++--
diffoscope/__init__.py | 2 +-
doc/Makefile | 29 +++++++++++
doc/diffoscope | 4 ++
doc/diffoscope.h2m.0 | 9 ++++
12 files changed, 171 insertions(+), 165 deletions(-)
diff --git a/.gitignore b/.gitignore
index eb4cf19..1fd6a65 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,8 @@
/.cache
/diffoscope.egg-info/
/dist/
+/doc/diffoscope.1
+/doc/diffoscope.h2m
.coverage
/htmlcov/
favicon.png
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
new file mode 100644
index 0000000..019a8d0
--- /dev/null
+++ b/CONTRIBUTING.rst
@@ -0,0 +1,70 @@
+Contributing
+============
+
+The preferred way to report bugs about diffoscope, as well as suggest fixes and
+requests for improvements, is to submit reports to the Debian bug tracker for
+the ``diffoscope`` package. You can do this over e-mail, simply write an email
+as follows:
+
+::
+
+ To: submit at bugs.debian.org
+ Subject: <subject>
+
+ Source: diffoscope
+ Version: <version>
+ Severity: <grave|serious|important|normal|minor|wishlist>
+
+
+There are `more detailed instructions available
+<https://www.debian.org/Bugs/Reporting>`__ about reporting a bug in the Debian bug tracker.
+
+If you're on a Debian-based system, you can install and use the ``reportbug``
+package to help walk you through the process.
+
+You can also submit patches to the Debian bug tracker. Start by cloning the `Git
+repository <https://anonscm.debian.org/git/reproducible/diffoscope.git/>`__,
+make your changes and commit them as you normally would. You can then use
+Git's ``format-patch`` command to save your changes as a series of patches that
+can be attached to the report you submit. For example:
+
+::
+
+ git clone git://anonscm.debian.org/reproducible/diffoscope.git
+ cd diffoscope
+ git checkout origin/master -b <topicname>
+ # <edits>
+ git commit -a
+ git format-patch -M origin/master
+
+The ``format-patch`` command will create a series of ``.patch`` files in your
+checkout. Attach these files to your submission in your e-mail client or
+reportbug.
+
+Uploading the package
+=====================
+
+When uploading diffoscope to the Debian archive, please take extra care to make
+sure the uploaded source package is correct, that is it includes the files
+tests/data/test(1|2).(a|o) which in some cases are removed by dpkg-dev when
+building the package. See `#834315 <https://bugs.debian.org/834315>`__ for an example
+FTBFS bug caused by this. (See `#735377
+<https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=735377#44>`__ and followups
+to learn how this happened and how to prevent it)
+
+Please also release a signed tarball::
+
+ $ VERSION=FIXME
+ $ git archive --format=tar --prefix=diffoscope-${VERSION}/ ${VERSION} | bzip2 -9 > diffoscope-${VERSION}.tar.bz2
+ $ gpg --detach-sig --armor --output=diffoscope-${VERSION}.tar.bz2.asc < diffoscope-${VERSION}.tar.bz2
+ $ scp diffoscope-${VERSION}* alioth.debian.org:/home/groups/reproducible/htdocs/releases/diffoscope
+
+After uploading, please also update the version on PyPI using::
+
+ $ python3 setup.py sdist upload --sign
+
+Once the tracker.debian.org entry appears, consider tweeting the release on
+``#reproducible-builds`` with::
+
+ %twitter diffoscope $VERSION has been released. Check out the changelog here: $URL
+
diff --git a/README.rst b/README.rst
index 9f95507..7cad16f 100644
--- a/README.rst
+++ b/README.rst
@@ -1,11 +1,13 @@
-diffoscope
-==========
+Description
+===========
-.. image:: https://badge.fury.io/py/diffoscope.svg
- :target: http://badge.fury.io/py/diffoscope
+.. only:: not manpage
-.. image:: https://jenkins.debian.net/buildStatus/icon?job=reproducible_diffoscope_from_git_master&plastic=true
- :target: https://jenkins.debian.net/job/reproducible_diffoscope_from_git_master
+ .. image:: https://badge.fury.io/py/diffoscope.svg
+ :target: http://badge.fury.io/py/diffoscope
+
+ .. image:: https://jenkins.debian.net/buildStatus/icon?job=reproducible_diffoscope_from_git_master&plastic=true
+ :target: https://jenkins.debian.net/job/reproducible_diffoscope_from_git_master
diffoscope will try to get to the bottom of what makes files or
directories different. It will recursively unpack archives of many kinds
@@ -24,8 +26,25 @@ Builds” initiative <https://reproducible-builds.org>`_. It is meant
to be able to quickly understand why two builds of the same package
produce different outputs. diffoscope was previously named debbindiff.
-Example
--------
+See the ``COMMAND-LINE EXAMPLES`` section further below to get you
+started, as well as more detailed explanations of all the command-line
+options. The same information is also available in
+``/usr/share/doc/diffoscope/README.rst`` or similar.
+
+.. raw:: manpage
+
+ .\" the below hack gets rid of the python "usage" message in favour of the
+ .\" the synopsis we manually defined in doc/$(PACKAGE).h2m.0
+ .SS positional arguments:
+ .\" end_of_description_header
+
+Exit status
+===========
+
+Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
+
+Command-line examples
+=====================
To compare two files in-depth and produce an HTML report, run something like::
@@ -53,7 +72,7 @@ By default this allowed to use up half of RAM; for more add something like::
to your ``/etc/fstab``; see ``man mount`` for details.
External dependencies
----------------------
+=====================
diffoscope requires Python 3 and the following modules available on PyPI:
`libarchive-c <https://pypi.python.org/pypi/libarchive-c>`_,
@@ -64,79 +83,8 @@ get a list of them, please run::
$ bin/diffoscope --list-tools
-Contributing
-------------
-
-The preferred way to report bugs about diffoscope, as well as suggest fixes and
-requests for improvements, is to submit reports to the Debian bug tracker for
-the ``diffoscope`` package. You can do this over e-mail, simply write an email
-as follows:
-
-::
-
- To: submit at bugs.debian.org
- Subject: <subject>
-
- Source: diffoscope
- Version: <version>
- Severity: <grave|serious|important|normal|minor|wishlist>
-
-
-There are `more detailed instructions available
-<https://www.debian.org/Bugs/Reporting>`__ about reporting a bug in the Debian bug tracker.
-
-If you're on a Debian-based system, you can install and use the ``reportbug``
-package to help walk you through the process.
-
-You can also submit patches to the Debian bug tracker. Start by cloning the `Git
-repository <https://anonscm.debian.org/git/reproducible/diffoscope.git/>`__,
-make your changes and commit them as you normally would. You can then use
-Git's ``format-patch`` command to save your changes as a series of patches that
-can be attached to the report you submit. For example:
-
-::
-
- git clone git://anonscm.debian.org/reproducible/diffoscope.git
- cd diffoscope
- git checkout origin/master -b <topicname>
- # <edits>
- git commit -a
- git format-patch -M origin/master
-
-The ``format-patch`` command will create a series of ``.patch`` files in your
-checkout. Attach these files to your submission in your e-mail client or
-reportbug.
-
-Uploading the package
-----------------------
-
-When uploading diffoscope to the Debian archive, please take extra care to make
-sure the uploaded source package is correct, that is it includes the files
-tests/data/test(1|2).(a|o) which in some cases are removed by dpkg-dev when
-building the package. See `#834315 <https://bugs.debian.org/834315>`__ for an example
-FTBFS bug caused by this. (See `#735377
-<https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=735377#44>`__ and followups
-to learn how this happened and how to prevent it)
-
-Please also release a signed tarball::
-
- $ VERSION=FIXME
- $ git archive --format=tar --prefix=diffoscope-${VERSION}/ ${VERSION} | bzip2 -9 > diffoscope-${VERSION}.tar.bz2
- $ gpg --detach-sig --armor --output=diffoscope-${VERSION}.tar.bz2.asc < diffoscope-${VERSION}.tar.bz2
- $ scp diffoscope-${VERSION}* alioth.debian.org:/home/groups/reproducible/htdocs/releases/diffoscope
-
-After uploading, please also update the version on PyPI using::
-
- $ python3 setup.py sdist upload --sign
-
-Once the tracker.debian.org entry appears, consider tweeting the release on
-``#reproducible-builds`` with::
-
- %twitter diffoscope $VERSION has been released. Check out the changelog here: $URL
-
-
Contributors
-------------
+============
Lunar, Reiner Herrmann, Chris Lamb, Mattia Rizzolo, Ximin Luo, Helmut Grohne,
Holger Levsen, Daniel Kahn Gillmor, Paul Gevers, Peter De Wachter, Yasushi
@@ -144,20 +92,21 @@ SHOJI, Clemens Lang, Ed Maste, Joachim Breitner, Mike McQuaid. Baptiste
Daroussin, Levente Polyak.
Contact
--------
+=======
Please report bugs and send patches through the Debian bug tracking
system against the diffoscope package:
<https://bugs.debian.org/src:diffoscope>
+For more instructions, see ``CONTRIBUTING.rst`` in this directory.
+
Join the users and developers mailing-list:
<https://lists.reproducible-builds.org/listinfo/diffoscope>
diffoscope website is at <https://diffoscope.org/>
-
License
--------
+=======
diffoscope is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
@@ -171,3 +120,9 @@ GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with diffoscope. If not, see <https://www.gnu.org/licenses/>.
+
+See also
+========
+
+* `<https://diffoscope.org/>`
+* `<https://wiki.debian.org/ReproducibleBuilds>`
diff --git a/debian/changelog b/debian/changelog
index 6677ce2..1e23db8 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,9 @@
+diffoscope (89) UNRELEASED; urgency=medium
+
+ * Auto-generate manpage using help2man, so it's no longer out-of-date.
+
+ -- Ximin Luo <infinity0 at debian.org> Tue, 28 Nov 2017 18:09:33 +0100
+
diffoscope (88) unstable; urgency=medium
[ Holger Levsen ]
diff --git a/debian/control b/debian/control
index 4fe24cc..b09328d 100644
--- a/debian/control
+++ b/debian/control
@@ -27,6 +27,7 @@ Build-Depends:
ghc <!nocheck>,
ghostscript <!nocheck>,
giflib-tools <!nocheck>,
+ help2man,
imagemagick <!nocheck>,
jsbeautifier <!nocheck>,
libarchive-tools <!nocheck>,
diff --git a/debian/diffoscope.1.rst b/debian/diffoscope.1.rst
deleted file mode 100644
index 041fa10..0000000
--- a/debian/diffoscope.1.rst
+++ /dev/null
@@ -1,74 +0,0 @@
-============
- diffoscope
-============
-
--------------------------------------------------------
-in-depth comparison of files, archives, and directories
--------------------------------------------------------
-
-:Author: Debian “Reproducible Builds” Team
-:Copyright: GPL-3+
-:Manual section: 1
-:Manual group: Debian
-
-SYNOPSIS
-========
-
- diffoscope [-h] [--json output] [OPTIONS] file1 file2
-
- diffoscope [-h] [OPTIONS] diff_file
-
- diffoscope [-h] [OPTIONS] < diff_file
-
-DESCRIPTION
-===========
-
-diffoscope will try to get to the bottom of what makes files or
-directories different. It will recursively unpack archives of many kinds
-and transform various binary formats into more human readable form to
-compare them. It can compare two tarballs, ISO images, or PDF just as
-easily.
-
-It can be scripted through error codes, and a report can be produced
-with the detected differences. The report can be text or HTML.
-When no type of report has been selected, diffoscope defaults
-to write a text report on the standard output.
-
-diffoscope is developed as part of the “reproducible builds” Debian
-project and was formerly known as “debbindiff”.
-
-OPTIONS
-=======
-
--h, --help show a detailed help message and exit
---version show program's version number and exit
---debug display debug messages
---json output write JSON report to given file
- (use - for standard output)
---text output write plain text report to given file
- (use - for standard output)
---html output write HTML report to given file
- (use - for standard output)
---html-dir output write multi-HTML report to given directory
---max-report-size BYTES
- maximum bytes written in report (default: 2048000)
---max-diff-block-lines MAX_DIFF_BLOCK_LINES
- maximum number of lines per diff block (default: 50)
---max-diff-input-lines MAX_DIFF_INPUT_LINES
- maximum number of lines fed to diff (default: 100000)
---fuzzy-threshold FUZZY_THRESHOLD
- threshold for fuzzy-matching (0 to disable, 60 is
- default, 400 is high fuzziness)
---new-file treat absent files as empty
---css url link to an extra CSS for the HTML report
-
-EXIT STATUS
-===========
-
-Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
-
-SEE ALSO
-========
-
-* `<https://diffoscope.org/>`
-* `<https://wiki.debian.org/ReproducibleBuilds>`
diff --git a/debian/diffoscope.manpages b/debian/diffoscope.manpages
index 3a8e1e1..ec29c63 100644
--- a/debian/diffoscope.manpages
+++ b/debian/diffoscope.manpages
@@ -1 +1 @@
-debian/diffoscope.1
+doc/diffoscope.1
diff --git a/debian/rules b/debian/rules
index f293b64..361184e 100755
--- a/debian/rules
+++ b/debian/rules
@@ -2,7 +2,6 @@
include /usr/share/dpkg/pkg-info.mk
-MANPAGES = $(patsubst %.1.rst,%.1,$(wildcard debian/*.1.rst))
PY_VERSION := $(shell awk '/^VERSION = / {gsub(/"/, "", $$3); print $$3}' diffoscope/__init__.py )
ifneq ($(DEB_VERSION),$(PY_VERSION))
@@ -35,14 +34,19 @@ endif
%:
dh $@ --with python3 --with bash-completion --buildsystem=pybuild
-debian/%.1: debian/%.1.rst
- rst2man $< $@
+doc/%.1:
+ $(MAKE) -C doc $*.1
debian/diffoscope.bash-completion:
register-python-argcomplete diffoscope > $@
-override_dh_auto_build: debian/diffoscope.bash-completion $(MANPAGES)
+override_dh_auto_build: debian/diffoscope.bash-completion
dh_auto_build -O--buildsystem=pybuild
+ dh_auto_build -O--buildsystem=makefile -Ddoc
+
+override_dh_auto_clean:
+ dh_auto_clean -O--buildsystem=pybuild
+ dh_auto_clean -O--buildsystem=makefile -Ddoc
override_dh_auto_test:
# Let's avoid plonking everything in the "DOS/MBR" category, this is really not
@@ -50,7 +54,7 @@ override_dh_auto_test:
! grep 'DOS/MBR' -R diffoscope
dh_auto_test
-override_dh_installman: $(MANPAGES)
+override_dh_installman:
dh_installman -O--buildsystem=pybuild
override_dh_python3:
diff --git a/diffoscope/__init__.py b/diffoscope/__init__.py
index 2f61afd..b272466 100644
--- a/diffoscope/__init__.py
+++ b/diffoscope/__init__.py
@@ -17,4 +17,4 @@
# You should have received a copy of the GNU General Public License
# along with diffoscope. If not, see <https://www.gnu.org/licenses/>.
-VERSION = "88"
+VERSION = "89"
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100755
index 0000000..4fffb95
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,29 @@
+#!/usr/bin/make -f
+# This file is also present in reprotest, please update that as well if you
+# make fixes here.
+
+PACKAGE = diffoscope
+VERSION = $$(cd .. && python3 setup.py -V)
+SED_fix_package_quirks = -e 's,bin/diffoscope,diffoscope,g'
+
+SED_rm_python_usage_msg = -e '/end_of_description_header/,/positional arguments/{d}'
+SED_fix_rst2man_quirks = \
+ -e 's,^ \\- ,,' \
+ -e 's,^\[,\\[char91],g' \
+ -e 's,\.TH *"" "" "",,g'
+
+all: $(PACKAGE).1
+
+$(PACKAGE).1: $(PACKAGE).h2m ../$(PACKAGE)/__init__.py
+ help2man --version-string=$(VERSION) ./$(PACKAGE) -N --include="$<" | \
+ sed $(SED_rm_python_usage_msg) > "$@"
+
+$(PACKAGE).h2m: $(PACKAGE).h2m.0 ../README.rst Makefile
+ { cat $(PACKAGE).h2m.0; cat ../README.rst | \
+ rst2man -q --no-doc-title | \
+ sed $(SED_fix_rst2man_quirks) $(SED_fix_package_quirks) \
+ -e 's,\.SH \(.*\),[\1],g'; } > "$@"
+
+.PHONY: clean
+clean:
+ $(RM) $(PACKAGE).1 $(PACKAGE).h2m
diff --git a/doc/diffoscope b/doc/diffoscope
new file mode 100755
index 0000000..a91bd10
--- /dev/null
+++ b/doc/diffoscope
@@ -0,0 +1,4 @@
+#!/bin/sh
+# dummy program wrapper for help2man
+cd ..
+exec python3 -m diffoscope.main "$@"
diff --git a/doc/diffoscope.h2m.0 b/doc/diffoscope.h2m.0
new file mode 100644
index 0000000..72b333b
--- /dev/null
+++ b/doc/diffoscope.h2m.0
@@ -0,0 +1,9 @@
+[NAME]
+diffoscope \- in-depth comparison of files, archives, and directories
+[SYNOPSIS]
+.nf
+\fBdiffoscope\fR \-\-help
+\fBdiffoscope\fR [OPTIONS] [\-\-json \fIoutput_diff\fR] \fIpath1\fR \fIpath2\fR
+\fBdiffoscope\fR [OPTIONS] \fIdiff\fR
+\fBdiffoscope\fR [OPTIONS] < \fIdiff\fR
+.fi
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/reproducible/diffoscope.git
More information about the diffoscope
mailing list