Commit 9aca8fee authored by Ximin Luo's avatar Ximin Luo

Auto-generate manpage using help2man, so it's no longer out-of-date.

parent 9d5690e2
......@@ -5,6 +5,8 @@
/.cache
/diffoscope.egg-info/
/dist/
/doc/diffoscope.1
/doc/diffoscope.h2m
.coverage
/htmlcov/
favicon.png
......
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@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
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@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>`
diffoscope (89) UNRELEASED; urgency=medium
* Auto-generate manpage using help2man, so it's no longer out-of-date.
-- Ximin Luo <infinity0@debian.org> Tue, 28 Nov 2017 18:09:33 +0100
diffoscope (88) unstable; urgency=medium
[ Holger Levsen ]
......
......@@ -27,6 +27,7 @@ Build-Depends:
ghc <!nocheck>,
ghostscript <!nocheck>,
giflib-tools <!nocheck>,
help2man,
imagemagick <!nocheck>,
jsbeautifier <!nocheck>,
libarchive-tools <!nocheck>,
......
============
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>`
debian/diffoscope.1
doc/diffoscope.1
......@@ -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:
......
......@@ -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"
#!/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
#!/bin/sh
# dummy program wrapper for help2man
cd ..
exec python3 -m diffoscope.main "$@"
[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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment