[pyosmium] 06/08: Add man pages for pyosmium utilities.
Bas Couwenberg
sebastic at debian.org
Mon Mar 20 20:34:20 UTC 2017
This is an automated email from the git hooks/post-receive script.
sebastic pushed a commit to branch master
in repository pyosmium.
commit e92a30c7e44cb2511a82b6ea3ba19b9ceb3f846f
Author: Bas Couwenberg <sebastic at xs4all.nl>
Date: Mon Mar 20 21:02:11 2017 +0100
Add man pages for pyosmium utilities.
---
debian/changelog | 1 +
debian/control | 6 +-
debian/man/pyosmium-get-changes.1.xml | 160 ++++++++++++++++++++++++++++++++++
debian/man/pyosmium-up-to-date.1.xml | 158 +++++++++++++++++++++++++++++++++
debian/pyosmium.manpages | 1 +
debian/rules | 12 ++-
6 files changed, 336 insertions(+), 2 deletions(-)
diff --git a/debian/changelog b/debian/changelog
index f0e34d7..84a334e 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -3,6 +3,7 @@ pyosmium (2.12.0-1) UNRELEASED; urgency=medium
* New upstream release.
* Bump minimum required libosmium2-dev to 2.12.0.
* Add pyosmium binary package for utilities.
+ * Add man pages for pyosmium utilities.
-- Bas Couwenberg <sebastic at debian.org> Mon, 20 Mar 2017 18:30:32 +0100
diff --git a/debian/control b/debian/control
index 5ba352a..303671b 100644
--- a/debian/control
+++ b/debian/control
@@ -20,7 +20,11 @@ Build-Depends: debhelper (>= 9),
python3-setuptools,
python3-nose,
python3-sphinx,
- zlib1g-dev
+ zlib1g-dev,
+ docbook2x,
+ docbook-xsl,
+ docbook-xml,
+ xsltproc
Standards-Version: 3.9.8
Vcs-Browser: https://anonscm.debian.org/cgit/pkg-grass/pyosmium.git/
Vcs-Git: https://anonscm.debian.org/git/pkg-grass/pyosmium.git
diff --git a/debian/man/pyosmium-get-changes.1.xml b/debian/man/pyosmium-get-changes.1.xml
new file mode 100644
index 0000000..5dcecbe
--- /dev/null
+++ b/debian/man/pyosmium-get-changes.1.xml
@@ -0,0 +1,160 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<refentry id='pyosmium-get-changes'>
+
+ <refmeta>
+ <refentrytitle>pyosmium-get-changes</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>pyosmium-get-changes</refname>
+ <refpurpose>Fetch diffs from an OSM planet server</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv id='synopsis'>
+ <cmdsynopsis>
+ <command>pyosmium-get-changes</command>
+ <arg choice='opt'><replaceable>OPTIONS</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id='description'>
+ <title>DESCRIPTION</title>
+ <para>
+ <command>pyosmium-get-changes</command> fetches diffs from an OSM planet
+ server.
+ </para>
+ <para>
+ The starting point of the diff must be given either as a sequence ID or
+ a date or can be computed from an OSM file.
+ If no output file is given, the program will just print the initial
+ sequence ID it would use (or save it in a file, if requested) and exit.
+ This can be used to bootstrap the update process.
+ </para>
+ <para>
+ The program tries to download until the latest change on the server is
+ found or the maximum requested diff size is reached.
+ Note that diffs are kept in memory during download.
+ </para>
+ <para>
+ On success, the program will print a single number to stdout, the
+ sequence number where to continue updates in the next run.
+ This output can also be written to (and later read from) a file.
+ </para>
+ </refsect1>
+
+ <refsect1 id='options'>
+ <title>OPTIONS</title>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-v</option></term>
+ <listitem>
+ <para>
+ Increase verbosity.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-o</option> <replaceable>file</replaceable></term>
+ <term><option>--outfile</option> <replaceable>file</replaceable></term>
+ <listitem>
+ <para>
+ Name of diff output file.
+ If omitted, only the sequence ID will be printed where updates
+ would start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--server</option> <replaceable>url</replaceable></term>
+ <listitem>
+ <para>
+ Base URL of the replication server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-s</option> <replaceable>int</replaceable></term>
+ <term><option>--size</option> <replaceable>int</replaceable></term>
+ <listitem>
+ <para>
+ Maximum data to load in MB (default: 100MB).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-I</option> <replaceable>ID</replaceable></term>
+ <term><option>--start-id</option> <replaceable>ID</replaceable></term>
+ <listitem>
+ <para>
+ Sequence ID to start with.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-D</option> <replaceable>DATE</replaceable></term>
+ <term><option>--start-date</option> <replaceable>DATE</replaceable></term>
+ <listitem>
+ <para>
+ Date when to start updates.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-O</option> <replaceable></replaceable>OSMFILE</term>
+ <term><option>--start-osm-data</option> <replaceable>OSMFILE</replaceable></term>
+ <listitem>
+ <para>
+ Start at the date of the newest OSM object in the file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-f</option> <replaceable></replaceable>file</term>
+ <term><option>--sequence-file</option> <replaceable>file</replaceable></term>
+ <listitem>
+ <para>
+ Sequence file.
+ If the file exists, then updates will start after the id given in
+ the file.
+ At the end of the process, the last sequence ID contained in the
+ diff is written.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--ignore-osmosis-headers</option></term>
+ <listitem>
+ <para>
+ When determining the start from an OSM file, ignore potential
+ replication information in the header and search for the newest
+ OSM object.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-d</option></term>
+ <term><option>--no-deduplicate</option></term>
+ <listitem>
+ <para>
+ Do not deduplicate and sort diffs.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </refsect1>
+
+</refentry>
diff --git a/debian/man/pyosmium-up-to-date.1.xml b/debian/man/pyosmium-up-to-date.1.xml
new file mode 100644
index 0000000..75fe238
--- /dev/null
+++ b/debian/man/pyosmium-up-to-date.1.xml
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<refentry id='pyosmium-up-to-date'>
+
+ <refmeta>
+ <refentrytitle>pyosmium-up-to-date</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>pyosmium-up-to-date</refname>
+ <refpurpose>Update an OSM file with changes from a OSM replication server</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv id='synopsis'>
+ <cmdsynopsis>
+ <command>pyosmium-up-to-date</command>
+ <arg choice='opt'><replaceable>OPTIONS</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id='description'>
+ <title>DESCRIPTION</title>
+ <para>
+ <command>pyosmium-up-to-date</command> updates an OSM file with changes
+ from a OSM replication server.
+ </para>
+ <para>
+ Diffs are downloaded and kept in memory.
+ To avoid running out of memory, the maximum size of diffs that can be
+ downloaded at once is limited to 1 GB per default.
+ This corresponds to approximately 3 days of update.
+ The limit can be changed with the <option>--size</option> parameter.
+ However, you should take into account that processing the files requires
+ additional memory (about 1GB more).
+ </para>
+ <para>
+ The starting time is automatically determined from the data in the file.
+ For PBF files, it is also possible to read and write the replication
+ information from the osmosis headers.
+ That means that after the first update, subsequent calls to
+ <command>pyosmium-up-to-date</command> will continue the updates from
+ the same server exactly where they have left of.
+ </para>
+ <para>
+ The program returns 0, if updates have been successfully applied up to
+ the newest data.
+ It returns 1, if some updates have been applied but there is still data
+ available on the server (either because the size limit has been reached
+ or there was a network error which could not be resolved).
+ Any other error results in a return code larger than 1.
+ The output file is guaranteed to be unmodified in that case.
+ </para>
+ </refsect1>
+
+ <refsect1 id='options'>
+ <title>OPTIONS</title>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-v</option></term>
+ <listitem>
+ <para>
+ Increase verbosity.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--infile</option> <replaceable>file</replaceable></term>
+ <listitem>
+ <para>
+ OSM file to update.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-o</option> <replaceable>file</replaceable></term>
+ <term><option>--outfile</option> <replaceable>file</replaceable></term>
+ <listitem>
+ <para>
+ Name of output file.
+ If missing, the input file will be overwritten.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--server</option> <replaceable>url</replaceable></term>
+ <listitem>
+ <para>
+ Base URL of the replication server.
+ Default: https://planet.osm.org/replication/hour/
+ (hourly diffs from osm.org).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-s</option> <replaceable>int</replaceable></term>
+ <term><option>--size</option> <replaceable>int</replaceable></term>
+ <listitem>
+ <para>
+ Maximum size of change to apply at once in MB.
+ Default: 1GB.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--tmpdir</option> <replaceable>path</replaceable></term>
+ <listitem>
+ <para>
+ Directory to use for temporary files.
+ Default: directory of input file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--ignore-osmosis-headers</option></term>
+ <listitem>
+ <para>
+ Ignore potential replication information in the header of the
+ input file and search for the newest OSM object in the file
+ instead.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-b</option> <replaceable>int</replaceable></term>
+ <term><option>--wind-back</option> <replaceable>int</replaceable></term>
+ <listitem>
+ <para>
+ Number of minutes to start downloading before the newest addition
+ to input data.
+ (Ignored when the file contains a sequence ID)
+ Default: 60.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--force-update-of-old-planet</option></term>
+ <listitem>
+ <para>
+ Apply update even if the input data is really old.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </refsect1>
+
+</refentry>
diff --git a/debian/pyosmium.manpages b/debian/pyosmium.manpages
new file mode 100644
index 0000000..13cdaf4
--- /dev/null
+++ b/debian/pyosmium.manpages
@@ -0,0 +1 @@
+debian/man/*.1
diff --git a/debian/rules b/debian/rules
index 17269de..5c19bf3 100755
--- a/debian/rules
+++ b/debian/rules
@@ -7,6 +7,10 @@ export DEB_BUILD_MAINT_OPTIONS=hardening=+all,-pie
export PYBUILD_NAME=pyosmium
+BUILD_DATE=$(shell dpkg-parsechangelog | sed -ne 's/^Date: //p' | LC_ALL=C date -u "+%d %B %Y" -f -)
+
+MANPAGES := $(wildcard debian/man/*.*.xml)
+
%:
dh $@ \
--buildsystem pybuild \
@@ -14,11 +18,17 @@ export PYBUILD_NAME=pyosmium
--parallel
override_dh_clean:
- dh_clean
+ dh_clean debian/man/*.1
$(RM) -r doc/_build
override_dh_auto_build-indep:
+ # Create man page from DocBook XML
+ for x in $(MANPAGES) ; do \
+ docbook2x-man --string-param header-3="$(BUILD_DATE)" $$x ; \
+ mv `basename $$x | sed 's/.xml$$//'` `dirname $$x` ; \
+ done
+
dh_auto_build --indep
(cd doc && PYTHONPATH=$(CURDIR)/.pybuild/pythonX.Y_`py3versions -vd`/build make html)
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-grass/pyosmium.git
More information about the Pkg-grass-devel
mailing list