--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/pwm.1.xml	Fri Feb 03 16:11:58 2017 +0100
@@ -0,0 +1,473 @@
+<?xml version="1.0"?>
+<!--
+
+Copyright (C) 2017 Guido Berhoerster <guido+pwm@berhoerster.name>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+<refentry xmlns="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
+  <info>
+    <author>
+      <personname>
+        <firstname>Guido</firstname>
+        <surname>Berhoerster</surname>
+      </personname>
+      <email>guido+pwm@berhoerster.name</email>
+      <personblurb/>
+    </author>
+    <date>3 February, 2017</date>
+  </info>
+  <refmeta>
+    <refentrytitle>pwm</refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo class="source"/>
+    <refmiscinfo class="version"/>
+    <refmiscinfo class="manual">User Commands</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refname>pwm</refname>
+    <refpurpose>password manager</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>pwm</command>
+      <arg choice="opt">
+        <option>-P</option>
+        <replaceable>password_file</replaceable>
+      </arg>
+      <arg choice="opt">
+        <replaceable>database_file</replaceable>
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>Description</title>
+    <para>The <command>pwm</command> utility is a password manager which
+    stores passwords and associated metadata in an encrypted database protected
+    by a master password.  It offers both a text-based user interface for
+    interactive use as well as a non-interactive mode.  The database uses the
+    PasswordSafe database version 3 file format and thus provides
+    interoperabity with other password managers using the same format.</para>
+    <para>After opening an existing database or creating a new one,
+    <command>pwm</command> provides commands to create, modify, delete, and
+    display password database entries which may be organized in groups.  The
+    contents of a field of a given entry can also be piped to an external
+    command, e.g. in order to copy the content of the username or password
+    field of an entry to the clipboard.</para>
+    <para>If specified, <command>pwm</command> will open or create
+    <replaceable>database_file</replaceable> instead of the user's default
+    database.</para>
+    <para><command>pwm</command> must be run with a locale which uses the UTF-8
+    character encoding.</para>
+    <refsect2>
+      <title>Output format</title>
+      <para>The <command>show</command> command displays selected fields by
+      printing the field name followed by a colon, one or more space characters
+      and the field's verbatim content to the standard output stream. Field
+      values may contain newlines, non-printable and/or control
+      characters.</para>
+      <para>The <command>pipe</command> prints the verbatim field content to the
+      standard input stream of the given command.</para>
+      <para>Error messages are printed to the standard error stream.</para>
+    </refsect2>
+  </refsect1>
+  <refsect1>
+    <title>Options</title>
+    <para>The following options are supported:</para>
+    <variablelist>
+      <varlistentry>
+        <term>
+          <option>-P</option>
+          <replaceable>password_file</replaceable>
+        </term>
+        <listitem>
+          <para>Read the master password from the first line of
+          <replaceable>password_file</replaceable>.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>Usage</title>
+    <para>If stdin is connected to a terminal pwm will run in interactive mode
+    and prompt the user for the master password unless
+    <replaceable>password_file</replaceable> is specified via the
+    <option>-P</option> option. After successfully opening the password
+    database the user will be prompted for a command.</para>
+    <para>When running in non-interactive mode a file containing the master
+    pasword must be specified via the <option>-P</option> option and after
+    successfully opening the password database, pwm will execute commands read
+    from stdin until either an error occurrs or end-of-file is reached.</para>
+    <para><command>pwm</command> operates on a copy of the password database
+    in memory, any changes must be explicitly written back to the database
+    using the write command.</para>
+    <refsect2>
+      <title>IDs</title>
+      <para>Database entries are referred to by an ID value which is a
+      positive integer value that is guaranteed to be unqiue during the run
+      time of the pwm utility.</para>
+    </refsect2>
+    <refsect2>
+      <title>Fields</title>
+      <para>The following entry fields are supported:
+      <simplelist type="vert">
+        <member>group</member>
+        <member>title</member>
+        <member>username</member>
+        <member>password</member>
+        <member>notes</member>
+        <member>url</member>
+      </simplelist>
+      </para>
+      <para>Other, existing fields specified by the PasswordSafe file format
+      will be preserved but cannot be displayed or modified.</para>
+    </refsect2>
+    <refsect2>
+      <title>Commands</title>
+      <para>Each command must appear on a seperate line terminated by a newline
+      character.  The command and its arguments are seperated by whitespace,
+      i.e. one or more space or tab characters.  If an argument contains
+      whitespace characters it must either be quoted by encosing it in single
+      or double quote characters or each whitespace character must be preceded
+      by a backslash character.  Arguments quoted with a single or double quote
+      character preserve the literal values of all characters with the
+      exception of the backslash character which can be used to escape the
+      respective quoting character.  Two consecutive backslash characters yield
+      a literal backslash within both quoted and unquoted arguments. A line
+      must not end in a single backslash character, any other backslash
+      characters are ignored.</para>
+      <para>If an error occurrs while parsing or executing a command,
+      <command>pwm</command> will terminate when running in non-interactive
+      mode.  In interactive mode it will print an error message and prompt the
+      user for the next command.  The following commands are supported:</para>
+      <variablelist>
+        <varlistentry>
+          <term>List entries</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>list</command>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>ls</command>
+              <sbr/>
+            </cmdsynopsis>
+            <para>List all password database entries.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Create entry</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>create</command>
+              <arg choice="opt" rep="repeat">
+                <replaceable>field</replaceable>=<replaceable>value</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>c</command>
+              <arg choice="opt" rep="repeat">
+                <replaceable>field</replaceable>=<replaceable>value</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Create a new entry assigning each given
+            <replaceable>field</replaceable> to the corresponsing
+            <replaceable>value</replaceable>.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Modify entry</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>modify</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <arg choice="opt" rep="repeat">
+                <replaceable>field</replaceable>=<replaceable>value</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>m</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <arg choice="opt" rep="repeat">
+                <replaceable>field</replaceable>=<replaceable>value</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Modify an existing entry identified by
+            <replaceable>id</replaceable> assigning each given
+            <replaceable>field</replaceable> to the corresponsing
+            <replaceable>value</replaceable>.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Remove entry</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>remove</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>rm</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Remove an existing entry identified by
+            <replaceable>id</replaceable>.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Display entry fields</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>show</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <arg choice="opt" rep="repeat">
+                <replaceable>field</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>s</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <arg choice="opt" rep="repeat">
+                <replaceable>field</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Display each <replaceable>field</replaceable> of the entry
+            identified by <replaceable>id</replaceable>.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Pipe entry fields to an external command</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>pipe</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <arg choice="plain" rep="repeat">
+                <replaceable>field</replaceable>
+              </arg>
+              <arg choice="plain">
+                <replaceable>command</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>p</command>
+              <arg choice="plain">
+                <replaceable>id</replaceable>
+              </arg>
+              <arg choice="plain" rep="repeat">
+                <replaceable>field</replaceable>
+              </arg>
+              <arg choice="plain">
+                <replaceable>command</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Pipe the content of each given
+            <replaceable>field</replaceable> of the entry identified by id to
+            command which must be a single argument. The command is executed by
+            invoking the <command>sh</command> utility with the <arg>-c</arg>
+            option and <replaceable>command</replaceable> as its option
+            argument, thus special care should be applied to quoting command.
+            See the <citerefentry><refentrytitle>sh</refentrytitle>
+            <manvolnum>1</manvolnum></citerefentry> manual page for
+            details.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Create empty group</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>creategroup</command>
+              <arg choice="plain">
+                <replaceable>name</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>cg</command>
+              <arg choice="plain">
+                <replaceable>name</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Create a new empty group named
+            <replaceable>name</replaceable>.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Remove empty group</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>removegroup</command>
+              <arg choice="plain">
+                <replaceable>name</replaceable>
+              </arg>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>rg</command>
+              <arg choice="plain">
+                <replaceable>name</replaceable>
+              </arg>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Remove the empty group named
+            <replaceable>name</replaceable>.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Change the master password</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>changepassword</command>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>ch</command>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Change the master password.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Display help text</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>help</command>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>h</command>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Display a list of all commands and a short help text.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Write database</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>write</command>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>w</command>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Write all changes back to the password database.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Quit</term>
+          <listitem>
+            <cmdsynopsis>
+              <command>quit</command>
+            </cmdsynopsis>
+            <cmdsynopsis>
+              <command>q</command>
+              <sbr/>
+            </cmdsynopsis>
+            <para>Quit <command>pwm</command>.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+  </refsect1>
+  <refsect1>
+    <title>File Format</title>
+    <para>The canonical description of the file format is included with the
+    distribution of the <citerefentry><refentrytitle>pwsafe</refentrytitle>
+    <manvolnum>1</manvolnum></citerefentry> utility.</para>
+  </refsect1>
+  <refsect1>
+    <title>Environment Variables</title>
+    <variablelist>
+      <varlistentry>
+        <term>
+          <literal>LANG</literal>
+        </term>
+        <term>
+          <literal>LC_ALL</literal>
+        </term>
+        <listitem>
+          <para>See <citerefentry><refentrytitle>locale</refentrytitle>
+          <manvolnum>5</manvolnum></citerefentry></para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>Exit Status</title>
+    <para>The following exit values are returned:</para>
+    <variablelist>
+      <varlistentry>
+        <term>0</term>
+        <listitem>
+          <para>Command successfully executed.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>1</term>
+        <listitem>
+          <para>An unspecified error has occured.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>2</term>
+        <listitem>
+          <para>Invalid command line options were specified.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>Files</title>
+    <variablelist>
+      <varlistentry>
+        <term><filename>~/.pwm/pwm.psafe3</filename></term>
+        <listitem>
+          <para>default password database</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>See Also</title>
+    <para><citerefentry><refentrytitle>pwsafe</refentrytitle>
+      <manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sh</refentrytitle>
+      <manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>locale</refentrytitle>
+      <manvolnum>5</manvolnum></citerefentry>,
+      <link xlink:href="https://pwsafe.org/"/></para>
+  </refsect1>
+</refentry>