secret-tool: Add a manual page

https://bugzilla.gnome.org/show_bug.cgi?id=681434

diff --git a/.gitignore b/.gitignore
index 4cdb0ba..90c3a85 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -46,6 +46,7 @@ stamp*
 !/build/m4/vapigen.m4
 /build/valgrind-suppressions
 
+/docs/man/secret-tool.1
 /docs/reference/libsecret/version.xml
 /docs/reference/libsecret/version-major.xml
 /docs/reference/libsecret/libsecret-decl-list.txt

diff --git a/configure.ac b/configure.ac
index 138149e..82bc86f 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -72,6 +72,20 @@ GOBJECT_INTROSPECTION_CHECK([1.29])
 AC_PATH_PROG(GLIB_MKENUMS, glib-mkenums)
 
 # --------------------------------------------------------------------
+# Manual pages
+
+AC_ARG_ENABLE(manpages,
+              AC_HELP_STRING([--disable-man-pages], [Build manual pages]))
+if test "$enable_manpages" != "no"; then
+       enable_manpages="yes"
+       AC_PATH_PROG([XSLTPROC], [xsltproc])
+       if test x$XSLTPROC = x; then
+               AC_MSG_ERROR([xsltproc is required to build manual pages])
+       fi
+fi
+AM_CONDITIONAL(WITH_MANPAGES, test x$enable_manpages = xyes)
+
+# --------------------------------------------------------------------
 # Vala
 
 VALA_REQUIRED=0.17.2.12
@@ -246,6 +260,7 @@ AC_CONFIG_FILES([
        Makefile
        build/Makefile
        docs/Makefile
+       docs/man/Makefile
        docs/reference/Makefile
        docs/reference/libsecret/Makefile
        docs/reference/libsecret/version.xml
@@ -266,7 +281,8 @@ echo
 echo "CFLAGS: $CFLAGS"
 echo
 echo "OPTIONS:"
-echo "  libgcrypt:            $gcrypt_status"
-echo "  Debug:                $debug_status"
-echo "  Coverage:             $enable_coverage"
+echo "  libgcrypt:     $gcrypt_status"
+echo "  Debug:         $debug_status"
+echo "  Coverage:      $enable_coverage"
+echo "  Manual Page:   $enable_manpages"
 echo

diff --git a/docs/Makefile.am b/docs/Makefile.am
index cac25f2..19f6265 100644 (file)
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -1,2 +1,6 @@
 
 SUBDIRS = reference
+
+if WITH_MANPAGES
+SUBDIRS += man
+endif

diff --git a/docs/man/Makefile.am b/docs/man/Makefile.am
new file mode 100644 (file)
index 0000000..66bcfd5
--- /dev/null
+++ b/docs/man/Makefile.am
@@ -0,0 +1,19 @@
+XSLTPROC_FLAGS = \
+        --nonet \
+        --stringparam man.output.quietly 1 \
+        --stringparam funcsynopsis.style ansi \
+        --stringparam man.th.extra1.suppress 1 \
+        --stringparam man.authors.section.enabled 0 \
+        --stringparam man.copyright.section.enabled 0
+
+.xml.1:
+       $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+
+man_MANS = \
+       secret-tool.1
+
+xml_files = $(man_MANS:.1=.xml)
+
+EXTRA_DIST = $(xml_files)
+
+DISTCLEANFILES = $(man_MANS)

diff --git a/docs/man/secret-tool.xml b/docs/man/secret-tool.xml
new file mode 100644 (file)
index 0000000..452db63
--- /dev/null
+++ b/docs/man/secret-tool.xml
@@ -0,0 +1,132 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="secret-tool">
+
+       <refentryinfo>
+               <title>secret-tool</title>
+               <productname>XDG</productname>
+
+               <authorgroup>
+                       <author>
+                               <contrib>Maintainer</contrib>
+                               <firstname>Stef</firstname>
+                               <surname>Walter</surname>
+                               <email>stefw@gnome.org</email>
+                       </author>
+               </authorgroup>
+       </refentryinfo>
+
+       <refmeta>
+               <refentrytitle>secret-tool</refentrytitle>
+               <manvolnum>1</manvolnum>
+               <refmiscinfo class="manual">User Commands</refmiscinfo>
+       </refmeta>
+
+       <refnamediv>
+               <refname>secret-tool</refname>
+               <refpurpose>Store and retrieve passwords</refpurpose>
+       </refnamediv>
+
+       <refsynopsisdiv>
+               <cmdsynopsis>
+                       <command>secret-tool store <arg choice="plain">--label='Label'</arg> <arg choice="req">attribute</arg> <arg choice="req">value</arg> ...</command>
+               </cmdsynopsis>
+               <cmdsynopsis>
+                       <command>secret-tool lookup <arg choice="req">attribute</arg> <arg choice="req">value</arg> ...</command>
+               </cmdsynopsis>
+               <cmdsynopsis>
+                       <command>secret-tool clear <arg choice="req">attribute</arg> <arg choice="req">value</arg> ...</command>
+               </cmdsynopsis>
+       </refsynopsisdiv>
+
+       <refsect1>
+               <title>Description</title>
+
+               <para><command>secret-tool</command> is a command line tool that
+               can be used to store and retrieve passwords.</para>
+
+               <para>Each password is stored in an item. Items are uniquely
+               identified by a set of attribute keys and values. When storing
+               a password you must specify unique pairs of attributes names
+               and values, and when looking up a password you provide the same
+               attribute name and value pairs.</para>
+
+       </refsect1>
+
+       <refsect1>
+               <title>Store</title>
+
+               <para>To store a password run <command>secret-tool</command>
+               with the <arg choice="plain">store</arg> argument. You must
+               also specify a label for the passward with the
+               <arg choice="plain">--label</arg> argument. This label will be
+               displayed in the password manager.</para>
+
+               <para>Make sure to pass a unique set of attributes names and
+               values when storing a password. If the attributes match an
+               already existing item, it will be updated instead of creating
+               a new item.</para>
+
+               <para>If invoked from a terminal or tty, then the password to store
+               will be prompted for and only one line will be accepted.</para>
+
+               <para>A password to store can also be piped in via stdin. The
+               password will be the contents of stdin until EOF. If you provide
+               a newline via stdin it will be stored as part of the password.</para>
+       </refsect1>
+
+       <refsect1>
+               <title>Lookup</title>
+
+               <para>To lookup a password run <command>secret-tool</command>
+               with the <arg choice="plain">lookup</arg> argument. Specify the
+               same same attribute names and value pairs that you passed when
+               storing the password.</para>
+
+               <para>If multiple items match the attribute provided, then the
+               first password that is already unlocked will be returned. If
+               necessary an item will be unlocked.</para>
+
+               <para>When printing the password to a terminal or tty, an extra
+               newline will be added after the password.</para>
+       </refsect1>
+
+       <refsect1>
+               <title>Clear</title>
+
+               <para>To remove a password run <command>secret-tool</command>
+               with the <arg choice="plain">clear</arg> argument. Specify the
+               same attirbute name and value pairs that you passed when
+               storing the password.</para>
+
+               <para>All unlocked items that match the attributes will be
+               removed.</para>
+       </refsect1>
+
+       <refsect1>
+               <title>Exit status</title>
+
+               <para>On success 0 is returned, a non-zero failure code otherwise.</para>
+       </refsect1>
+
+       <refsect1>
+               <title>Examples</title>
+               <example>
+                       <title>Storing, retrieving, and clearing a password</title>
+<programlisting>
+$ secret-tool store --label='My password' key1 value1 key2 value2
+Password: My password
+</programlisting>
+<programlisting>
+$ secret-tool lookup key1 value1 key2 value2
+My password
+</programlisting>
+<programlisting>
+$ secret-tool clear key1 value1 key2 value2
+</programlisting>
+               </example>
+       </refsect1>
+
+</refentry>