[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