diff options
author | Stef Walter <stefw@gnome.org> | 2012-08-08 10:40:30 +0200 |
---|---|---|
committer | Stef Walter <stefw@gnome.org> | 2012-08-16 11:13:10 +0200 |
commit | 152371b3e465d31fccee125dea56f8f765616017 (patch) | |
tree | ce04170b8a53d38c7990b86f24822af6494901ac /docs | |
parent | 053ecbd8f70676c76cd0cfc5648256ccae27a1e8 (diff) | |
download | libsecret-152371b3e465d31fccee125dea56f8f765616017.tar.gz |
secret-tool: Add a manual page
https://bugzilla.gnome.org/show_bug.cgi?id=681434
Diffstat (limited to 'docs')
-rw-r--r-- | docs/Makefile.am | 4 | ||||
-rw-r--r-- | docs/man/Makefile.am | 19 | ||||
-rw-r--r-- | docs/man/secret-tool.xml | 132 |
3 files changed, 155 insertions, 0 deletions
diff --git a/docs/Makefile.am b/docs/Makefile.am index cac25f2..19f6265 100644 --- 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 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 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> |