From 152371b3e465d31fccee125dea56f8f765616017 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Wed, 8 Aug 2012 10:40:30 +0200 Subject: [PATCH] secret-tool: Add a manual page https://bugzilla.gnome.org/show_bug.cgi?id=681434 --- .gitignore | 1 + configure.ac | 22 ++++++- docs/Makefile.am | 4 ++ docs/man/Makefile.am | 19 ++++++ docs/man/secret-tool.xml | 132 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 175 insertions(+), 3 deletions(-) create mode 100644 docs/man/Makefile.am create mode 100644 docs/man/secret-tool.xml diff --git a/.gitignore b/.gitignore index 4cdb0ba..90c3a85 100644 --- 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 --- a/configure.ac +++ b/configure.ac @@ -71,6 +71,20 @@ GTK_DOC_CHECK(1.9) 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 @@ -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 --- 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 @@ + + + + + + + secret-tool + XDG + + + + Maintainer + Stef + Walter + stefw@gnome.org + + + + + + secret-tool + 1 + User Commands + + + + secret-tool + Store and retrieve passwords + + + + + secret-tool store --label='Label' attribute value ... + + + secret-tool lookup attribute value ... + + + secret-tool clear attribute value ... + + + + + Description + + secret-tool is a command line tool that + can be used to store and retrieve passwords. + + 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. + + + + + Store + + To store a password run secret-tool + with the store argument. You must + also specify a label for the passward with the + --label argument. This label will be + displayed in the password manager. + + 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. + + If invoked from a terminal or tty, then the password to store + will be prompted for and only one line will be accepted. + + 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. + + + + Lookup + + To lookup a password run secret-tool + with the lookup argument. Specify the + same same attribute names and value pairs that you passed when + storing the password. + + 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. + + When printing the password to a terminal or tty, an extra + newline will be added after the password. + + + + Clear + + To remove a password run secret-tool + with the clear argument. Specify the + same attirbute name and value pairs that you passed when + storing the password. + + All unlocked items that match the attributes will be + removed. + + + + Exit status + + On success 0 is returned, a non-zero failure code otherwise. + + + + Examples + + Storing, retrieving, and clearing a password + +$ secret-tool store --label='My password' key1 value1 key2 value2 +Password: My password + + +$ secret-tool lookup key1 value1 key2 value2 +My password + + +$ secret-tool clear key1 value1 key2 value2 + + + + +