[osmium-tool] 13/97: Added new and improved existing man pages.
Sebastiaan Couwenberg
sebastic at moszumanska.debian.org
Tue Jul 21 20:15:29 UTC 2015
This is an automated email from the git hooks/post-receive script.
sebastic pushed a commit to tag v1.0.0
in repository osmium-tool.
commit 1a1b509d3d2657c8759149ff2f37497e311ff3d9
Author: Jochen Topf <jochen at topf.org>
Date: Thu Jul 17 17:43:23 2014 +0200
Added new and improved existing man pages.
---
doc/.gitignore | 1 +
doc/Makefile | 16 ++++++---
doc/manpage.template | 30 +++++++++++++++++
doc/osmium-apply-changes.md | 81 +++++++++++++++++++++++++++++++++++++++++++++
doc/osmium-cat.md | 65 ++++++++----------------------------
doc/osmium-file-formats.md | 70 +++++++++++++++++++++++++++++++++++++++
doc/osmium-fileinfo.md | 34 +++++++++++--------
doc/osmium-merge-changes.md | 74 +++++++++++++++++++++++++++++++++++++++++
doc/osmium-time-filter.md | 38 +++++++++------------
doc/osmium.md | 21 +++++-------
10 files changed, 324 insertions(+), 106 deletions(-)
diff --git a/doc/.gitignore b/doc/.gitignore
index f7e585b..8c7bbbe 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1 +1,2 @@
*.1
+*.5
diff --git a/doc/Makefile b/doc/Makefile
index 845a675..9a55a06 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -9,18 +9,24 @@ OSMIUM_VERSION := 0.0.1
PANDOC := pandoc
MARKDOWN_FILES := $(wildcard *.md)
-MAN_PAGES := $(MARKDOWN_FILES:.md=.1)
+MAN_PAGES_1 := osmium.1 osmium-apply-changes.1 osmium-cat.1 osmium-fileinfo.1 osmium-merge-changes.1 osmium-time-filter.1
+MAN_PAGES_5 := osmium-file-formats.5
PUBDATE := `date +%Y-%m-%d`
+PANDOC_MAN_OPTIONS := -s -t man --template manpage.template --variable "description=osmium/$(OSMIUM_VERSION)" --variable "date=$(PUBDATE)"
+PANDOC_HTML_OPTIONS := -s -t html
-all: $(MAN_PAGES)
+all: $(MAN_PAGES_1) $(MAN_PAGES_5)
%.1: %.md
- $(PANDOC) -s -t man --variable "description=osmium/$(OSMIUM_VERSION)" --variable "date=$(PUBDATE)" -o $@ $<
+ $(PANDOC) $(PANDOC_MAN_OPTIONS) -o $@ $<
+
+%.5: %.md
+ $(PANDOC) $(PANDOC_MAN_OPTIONS) -o $@ $<
%.html: %.md
- $(PANDOC) -s -t html -o $@ $<
+ $(PANDOC) $(PANDOC_HTML_OPTIONS) -o $@ $<
clean:
- rm -f *.1 *.html
+ rm -f *.1 *.5 *.html
diff --git a/doc/manpage.template b/doc/manpage.template
new file mode 100644
index 0000000..abfc756
--- /dev/null
+++ b/doc/manpage.template
@@ -0,0 +1,30 @@
+$if(has-tables)$
+.\"t
+$endif$
+.TH "$title$" "$section$" "$date$" "$footer$" "$header$"
+$for(header-includes)$
+$header-includes$
+$endfor$
+$for(include-before)$
+$include-before$
+$endfor$
+$body$
+$for(include-after)$
+$include-after$
+$endfor$
+$if(author)$
+.SH COPYRIGHT
+.PP
+Copyright (C) 2013\-2014 Jochen Topf <jochen at topf.org>.
+License GPLv3+: GNU GPL version 3 or later
+<http://gnu.org/licenses/gpl.html>.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH CONTACT
+.PP
+Developers can be contacted through the OSM dev mailinglist
+(http://lists.openstreetmap.org/cgi-bin/mailman/listinfo/dev).
+Bugs should be reported to https://github.com/osmcode/osmium-tool.
+.SH AUTHORS
+$for(author)$$author$$sep$; $endfor$.
+$endif$
diff --git a/doc/osmium-apply-changes.md b/doc/osmium-apply-changes.md
new file mode 100644
index 0000000..8cc21a2
--- /dev/null
+++ b/doc/osmium-apply-changes.md
@@ -0,0 +1,81 @@
+% OSMIUM-APPLY-CHANGES(1)
+% Jochen Topf <jochen at topf.org>
+
+# NAME
+
+osmium-apply-changes - Apply OSM change file(s) to OSM data file.
+
+
+# SYNOPSIS
+
+**osmium apply-changes** \[OPTIONS\] *INPUT-FILE* *CHANGE-FILE...*
+
+
+# DESCRIPTION
+
+Merges the content of all change files given on the command line and applies
+those changes to the INPUT-FILE.
+
+Objects in change files are sorted by type, ID, and version, so it doesn't matter
+in what order the change files are given or in what order they contain the data.
+
+**Osmium apply** keeps the contents of the change files in main memory, so the
+data has to fit in there!
+
+
+# OPTIONS
+
+--generator NAME
+: The name and version of the program generating the output file. It will be
+ added to the header of the output file. Default is "*osmium/*" and the version
+ of osmium.
+
+--input-format, -F FORMAT
+: The format of the input files. Can be used to set the input format if it
+ can't be autodetected from the file names. This will set the format for
+ all input files, there is no way to set the format for some input files
+ only. See **osmium-file-formats**(5) or the libosmium manual for details.
+
+--output, -o FILE
+: Name of the output file. Default is '-' (*stdout*).
+
+--output-format, -f FORMAT
+: The format of the output file. Can be used to set the output file format
+ if it can't be autodetected from the output file name.
+ See **osmium-file-formats**(5) or the libosmium manual for details.
+
+--overwrite, -O
+: Allow an existing output file to be overwritten. Normally **osmium** will
+ refuse to write over an existing file.
+
+--remove-deleted, -r
+: Remove deleted objects from the output. If this is not set, deleted objects
+ will be in the output with the visible flag set to false.
+
+--simplify, -s
+: Only write the last version of any object to the output.
+
+--verbose, -v
+: Set verbose mode. The program will output information about what it is
+ doing to *stderr*.
+
+
+# DIAGNOSTICS
+
+**osmium cat** exits with code 0 if everything went alright, it exits
+with code 2 if there was a problem with the command line arguments,
+and with exit code 1 if some other error occurred.
+
+
+# EXAMPLES
+
+Apply change file 362.osc.gz to planet file:
+
+ osmium apply-changes -o new.osm.pbf planet.osm.pbf 362.osc.gz
+
+
+# SEE ALSO
+
+* [Osmium website](http://osmcode.org/osmium)
+* [Libosmium manual](http://osmcode.org/libosmium/manual/libosmium-manual.html)
+
diff --git a/doc/osmium-cat.md b/doc/osmium-cat.md
index 50b7998..688a25d 100644
--- a/doc/osmium-cat.md
+++ b/doc/osmium-cat.md
@@ -22,68 +22,38 @@ can be used to convert OSM files from one format into another.
# OPTIONS
---generator
+--generator NAME
: The name and version of the program generating the output file. It will be
- added to the header of the output file. Default is *osmium/* and the version
+ added to the header of the output file. Default is "*osmium/*" and the version
of osmium.
---input-format, -F
+--input-format, -F FORMAT
: The format of the input files. Can be used to set the input format if it
can't be autodetected from the file names. This will set the format for
all input files, there is no way to set the format for some input files
- only. See the FILE FORMATS section for details.
+ only. See **osmium-file-formats**(5) or the libosmium manual for details.
---output, -o
+--output, -o FILE
: Name of the output file. Default is '-' (*stdout*).
---output-format, -f
+--output-format, -f FORMAT
: The format of the output file. Can be used to set the output file format
- if it can't be autodetected from the output file name. See the FILE FORMATS
- section for details.
+ if it can't be autodetected from the output file name.
+ **See osmium-file-formats**(5) or the libosmium manual for details.
---output-header
-: Add output header. This option can be given several times.
+--output-header OPTION
+: Add output header option. This option can be given several times. See the
+ *libosmium manual* for a list of allowed headers.
--overwrite, -O
: Allow an existing output file to be overwritten. Normally **osmium** will
refuse to write over an existing file.
---verbose,-v
+--verbose, -v
: Set verbose mode. The program will output information about what it is
doing to *stderr*.
-# FILE FORMATS
-
-**osmium** supports all file formats supported by Osmium. These are:
-
-* The classical XML format in the variants *.osm* (for data files),
- *.osh* (for data files with history) and *.osc* (for change files)
-* The PBF binary format (with the usual suffix *.osm.pbf*)
-* The OPL format (with the usual suffix *.osm.opl*)
-
-In addition XML and OPL files can be compressed using *gzip* or *bzip2*.
-(Add *.gz* or *.bz2* suffixes, respectively.)
-
-Which format a file has is usually autodetected from the file name.
-Where this doesn't work, either because you are reading from stdin
-or writing to stdout, or because you have an unusual file name, the
---input-format and --output-format options can be used to set the
-format. They take a comma-separated list of arguments, the first is
-the format, further arguments set additional options.
-
-Here are some examples:
-
-pbf
-: PBF format
-osm.bz2
-: XML format, compressed with bzip2
-osc.gz
-: OSM change file, compressed with gzip
-osm.gz,xml_change_format=true
-: OSM change file, compressed with gzip
-
-
# DIAGNOSTICS
**osmium cat** exits with code 0 if everything went alright, it exits
@@ -102,15 +72,8 @@ Concatenate all change files in the 'changes' directory into one:
osmium cat -o all-changes.osc.gz changes/*.osc.gz
-# COPYRIGHT
-
-Copyright (C) 2013 Jochen Topf <jochen at topf.org>.
-License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-
# SEE ALSO
-<http://osmcode.org/osmium>
+* [Osmium website](http://osmcode.org/osmium)
+* [Libosmium manual](http://osmcode.org/libosmium/manual/libosmium-manual.html)
diff --git a/doc/osmium-file-formats.md b/doc/osmium-file-formats.md
new file mode 100644
index 0000000..b280f81
--- /dev/null
+++ b/doc/osmium-file-formats.md
@@ -0,0 +1,70 @@
+% OSMIUM-FILE-FORMATS(5)
+% Jochen Topf <jochen at topf.org>
+
+# NAME
+
+osmium-file-formats - OSM file formats known to Osmium.
+
+# FORMATS
+
+The **osmium** command line tool supports all file formats supported by the
+Osmium library. These are:
+
+* The classical XML format in the variants *.osm* (for data files),
+ *.osh* (for data files with history) and *.osc* (for change files).
+* The PBF binary format (usually with suffix *.osm.pbf*).
+* The OPL format (usually with suffix *.osm.opl*).
+
+In addition, XML and OPL files can be compressed using *gzip* or *bzip2*.
+(Add *.gz* or *.bz2* suffixes, respectively.)
+
+# AUTODETECTION
+
+Which format a file has is usually autodetected from the file name suffix.
+
+If this doesn't work, either because you are reading from stdin or writing to
+stdout, or because you have an unusual file name, you have to set the format
+manually. You can also set the format manually if you want to set special
+format options.
+
+Most **osmium** commands support the **--input-format** and **--output-format**
+options to set the format. They take a comma-separated list of arguments, the
+first is the format, further arguments set additional options.
+
+# SPECIAL FORMAT OPTIONS
+
+The following options can be added when writing OSM files:
+
+xml_change_format=true/false
+: Enable/disable XML change format. Same as *.osc*.
+
+pbf_dense_nodes=true/false (*default: true*)
+: Enable/disable DenseNodes format for PBF files.
+
+pbf_compression=true/false (*default: true*)
+: Enable/disable compression in PBF files. Disabling this will make writing
+ files a bit faster, but the resulting files are 2 to 3 times bigger.
+
+pbf_add_metadata=true/false (*default: true*)
+: Enable/disable writing of object metadata such as changeset id, username,
+ etc. Disabling this will make files a bit smaller.
+
+# EXAMPLES
+
+Here are some examples:
+
+pbf
+: PBF format.
+osm.bz2
+: XML format, compressed with bzip2.
+osc.gz
+: OSM change file, compressed with gzip.
+osm.gz,xml_change_format=true
+: OSM change file, compressed with gzip.
+
+
+# SEE ALSO
+
+* [Osmium website](http://osmcode.org/osmium)
+* [Libosmium manual](http://osmcode.org/libosmium/manual/libosmium-manual.html)
+
diff --git a/doc/osmium-fileinfo.md b/doc/osmium-fileinfo.md
index def1d4b..d5a09fc 100644
--- a/doc/osmium-fileinfo.md
+++ b/doc/osmium-fileinfo.md
@@ -13,8 +13,8 @@ osmium-fileinfo - Show information about an OpenStreetMap file.
# DESCRIPTION
-Shows verious information about OSM files such as the file type, bounding box,
-etc.
+Shows various information about OSM files such as the file type, bounding boxes
+in the header, etc.
This command will usually only read the file header. Use the **--extended**
option to show more information.
@@ -23,16 +23,22 @@ The output is split into three sections:
File
: This section shows the information available without opening the
- file itself. It contains the file name, the format, the compression
- used and the size of the file in bytes.
+ file itself. It contains the file name, the format deduced from the
+ file name, the compression used and the size of the file in bytes.
Header
: This section shows the information available from the header of
- the file (if available, OPL files have no header).
+ the file (if available, OPL files have no header). Any available
+ bounding boxes are shown as well as header options such as the
+ generator and file format version.
Data
: This section shows the information available from reading the whole
- file. It is only shown if the **--extended** option was used.
+ file. It is only shown if the **--extended** option was used. It
+ shows the actual bounding box calculated from the nodes in the file,
+ the first and last timestamp of all objects in the file, a SHA1
+ checksum of the data in the file and the number of changesets,
+ nodes, ways, and relations found in the file.
# OPTIONS
@@ -42,19 +48,19 @@ Data
--input-format, -f
: The format of the input file. Can be used to set the input file format
- if it can't be autodetected from the file name. See the FILE FORMATS
- section of the osmium-cat man page for details.
+ if it can't be autodetected from the file name.
+ See **osmium-file-formats**(5) or the libosmium manual for details.
-# COPYRIGHT
+# DIAGNOSTICS
-Copyright (C) 2013 Jochen Topf <jochen at topf.org>.
-License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
+**osmium fileinfo** exits with code 0 if everything went alright, it exits
+with code 2 if there was a problem with the command line arguments,
+and with exit code 1 if some other error occurred.
# SEE ALSO
-<http://osmcode.org/osmium>
+* [Osmium website](http://osmcode.org/osmium)
+* [Libosmium manual](http://osmcode.org/libosmium/manual/libosmium-manual.html)
diff --git a/doc/osmium-merge-changes.md b/doc/osmium-merge-changes.md
new file mode 100644
index 0000000..4212f49
--- /dev/null
+++ b/doc/osmium-merge-changes.md
@@ -0,0 +1,74 @@
+% OSMIUM-MERGE-CHANGES(1)
+% Jochen Topf <jochen at topf.org>
+
+# NAME
+
+osmium-merge-changes - Merge several OSM change files into one.
+
+
+# SYNOPSIS
+
+**osmium merge-changes** \[OPTIONS\] *CHANGE-FILE...*
+
+
+# DESCRIPTION
+
+Merges the content of all change files given on the command line into one large
+change file. Objects are sorted by type, ID, and version, so it doesn't matter
+in what order the change files are given or in what order they contain the data.
+
+**Osmium merge** does its work in main memory, so all data has to fit in there!
+
+
+# OPTIONS
+
+--generator NAME
+: The name and version of the program generating the output file. It will be
+ added to the header of the output file. Default is "*osmium/*" and the version
+ of osmium.
+
+--input-format, -F FORMAT
+: The format of the input files. Can be used to set the input format if it
+ can't be autodetected from the file names. This will set the format for
+ all input files, there is no way to set the format for some input files
+ only. See **osmium-file-formats**(5) or the libosmium manual for details.
+
+--output, -o FILE
+: Name of the output file. Default is '-' (*stdout*).
+
+--output-format, -f FORMAT
+: The format of the output file. Can be used to set the output file format
+ if it can't be autodetected from the output file name.
+ See **osmium-file-formats**(5) or the libosmium manual for details.
+
+--overwrite, -O
+: Allow an existing output file to be overwritten. Normally **osmium** will
+ refuse to write over an existing file.
+
+--simplify, -s
+: Only write the last version of any object to the output.
+
+--verbose, -v
+: Set verbose mode. The program will output information about what it is
+ doing to *stderr*.
+
+
+# DIAGNOSTICS
+
+**osmium merge** exits with code 0 if everything went alright, it exits
+with code 2 if there was a problem with the command line arguments,
+and with exit code 1 if some other error occurred.
+
+
+# EXAMPLES
+
+Merge all changes in *changes* directory into *all.osc.gz*:
+
+ osmium merge-changes -o all.osc.gz changes/*.gz
+
+
+# SEE ALSO
+
+* [Osmium website](http://osmcode.org/osmium)
+* [Libosmium manual](http://osmcode.org/libosmium/manual/libosmium-manual.html)
+
diff --git a/doc/osmium-time-filter.md b/doc/osmium-time-filter.md
index 37a0159..a6e201c 100644
--- a/doc/osmium-time-filter.md
+++ b/doc/osmium-time-filter.md
@@ -3,57 +3,56 @@
# NAME
-osmium-time-filter - Filter OSM data from a point in time or a time span out of a history file.
+osmium-time-filter - Filter OSM data by time from a history file.
# SYNOPSIS
-**osmium time-filter** \[OPTIONS\] \[**-o** *OUTPUT-FILE*\] *INPUT-FILE* \[*TIME*\]\
-**osmium time-filter** \[OPTIONS\] \[**-o** *OUTPUT-FILE*\] *INPUT-FILE* *FROM-TIME* *TO-TIME*
+**osmium time-filter** \[OPTIONS\] *INPUT-FILE* \[*TIME*\]\
+**osmium time-filter** \[OPTIONS\] *INPUT-FILE* *FROM-TIME* *TO-TIME*
# DESCRIPTION
Copy all objects that were valid at the given *TIME* or in the time period
between *FROM-TIME* (inclusive) and *TO-TIME* (not inclusive) from the input
-file into the output file. If no time is given on the command line the current
-time is used.
+file into the output file. If no time is given, the current time is used.
Usually the *INPUT-FILE* will be an OSM data file with history. If both *FROM-TIME*
and *TO-TIME* are given, the result will also have history data, it will also
include deleted versions of objects.
-If only a single point in time was given the result will be a normal OSM file
+If only a single point in time was given, the result will be a normal OSM file
without history containing no deleted objects.
-The format for the time stamps is "yyyy-mm-ddThh:mm::ssZ".
+The format for the timestamps is "yyyy-mm-ddThh:mm::ssZ".
# OPTIONS
--generator
: The name and version of the program generating the output file. It will be
- added to the header of the output file. Default is *osmium/* and the version
+ added to the header of the output file. Default is "*osmium/*" and the version
of osmium.
--input-format, -F
-: The format of the input file. Can be used to set the input format if it
- can't be autodetected from the file name. See the FILE FORMATS section
- of the osmium-cat man page for details.
+: The format of the input file. Can be used to set the input file format
+ if it can't be autodetected from the file name.
+ **See osmium-file-formats**(5) or the libosmium manual for details.
--output-file, -o
: Name of the output file. Default is '-' (*stdout*).
--output-format, -f
: The format of the output file. Can be used to set the output file format
- if it can't be autodetected from the output file name. See the FILE FORMATS
- section of the osmium-cat man page for details.
+ if it can't be autodetected from the output file name.
+ **See osmium-file-formats**(5) or the libosmium manual for details.
--overwrite, -O
: Allow an existing output file to be overwritten. Normally **osmium** will
refuse to write over an existing file.
---verbose,-v
+--verbose, -v
: Set verbose mode. The program will output information about what it is
doing to *stderr*.
@@ -76,15 +75,8 @@ Extract planet data how it appeared on January 1 2008 from history planet:
osmium time-filter -o planet-20080101.osm.pbf history-planet.osh.pbf 2008-01-01T00:00:00Z
-# COPYRIGHT
-
-Copyright (C) 2013 Jochen Topf <jochen at topf.org>.
-License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-
# SEE ALSO
-<http://osmcode.org/osmium>
+* [Osmium website](http://osmcode.org/osmium)
+* [Libosmium manual](http://osmcode.org/libosmium/manual/libosmium-manual.html)
diff --git a/doc/osmium.md b/doc/osmium.md
index 864836b..a38fd79 100644
--- a/doc/osmium.md
+++ b/doc/osmium.md
@@ -24,7 +24,7 @@ Run **osmium help** *COMMAND* to get more information about a command.
--help, -h
: Show usage and list of commands.
---version, -v
+--version
: Show program version.
@@ -33,26 +33,21 @@ Run **osmium help** *COMMAND* to get more information about a command.
apply-changes
: Apply OSM change file(s) to OSM data file.
cat
-: Concatenate OSM files and convert OSM files between different formats.
-dump
-: Dump contents of OSM file.
+: Concatenate OSM files and convert to different formats.
fileinfo
: Show information about an OpenStreetMap file.
help
: Show help about commands.
merge-changes
: Merge several OSM change files into one.
-
-
-# COPYRIGHT
-
-Copyright (C) 2013 Jochen Topf <jochen at topf.org>.
-License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
+time-filter
+: Filter OSM data by time from a history file.
# SEE ALSO
-<http://osmcode.org/osmium>
+* **osmium-apply-changes**(1), **osmium-cat**(1), **osmium-fileinfo**(1),
+ **osmium-merge-changes**(1), **osmium-time-filter**(1), **osmium-file-formats**(5)
+* [Osmium website](http://osmcode.org/osmium)
+* [Libosmium manual](http://osmcode.org/libosmium/manual/libosmium-manual.html)
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-grass/osmium-tool.git
More information about the Pkg-grass-devel
mailing list