Git commit 97db9e5db93023acc6cd70c7e49571e003f9b3a1 by Valentin Rusu. Committed on 25/04/2015 at 15:32. Pushed by vrusu into branch 'master'.
Adding manpage The manpage was written in asciidoc, then converted to docbook format with asciidocs's a2x utility, via the included gendocbook.sh script M +1 -0 CMakeLists.txt A +12 -0 doc/CMakeLists.txt A +6 -0 doc/gendocbook.sh A +67 -0 doc/kwallet-query.adoc A +161 -0 doc/man-kwallet-query.1.docbook http://commits.kde.org/kwallet-framework/97db9e5db93023acc6cd70c7e49571e003f9b3a1 diff --git a/CMakeLists.txt b/CMakeLists.txt index dd96ebd..6c46998 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -18,6 +18,7 @@ include(FeatureSummary) ADD_SUBDIRECTORY(src) +ADD_SUBDIRECTORY(doc) #if("${CMAKE_BINARY_DIR}" STREQUAL "{CMAKE_CURRENT_BINARY_DIR}") feature_summary(WHAT ALL FATAL_ON_MISSING_REQUIRED_PACKAGES) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 0000000..7c108f8 --- /dev/null +++ b/doc/CMakeLists.txt @@ -0,0 +1,12 @@ +# +# The main documentation is written using asciidoc +# So, the files *.adoc are the documentation sources +# These are converted to docbook format using the a2x +# tool that commes with the asciidoc package +# +FIND_PACKAGE(KF5 ${KF5_VERSION} REQUIRED DocTools) + +set(m kwallet-query) +kdoctools_create_manpage(man-${m}.1.docbook 1) +install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${m}.1 DESTINATION ${MAN_INSTALL_DIR}) + diff --git a/doc/gendocbook.sh b/doc/gendocbook.sh new file mode 100755 index 0000000..80a1139 --- /dev/null +++ b/doc/gendocbook.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +# this script converts the adoc file to docbook +# it uses asciidoc tool a2x +a2x -v -d manpage -f docbook kwallet-query.adoc +tr -d '\015' <kwallet-query.xml >man-kwallet-query.1.docbook +rm kwallet-query.xml diff --git a/doc/kwallet-query.adoc b/doc/kwallet-query.adoc new file mode 100644 index 0000000..a468605 --- /dev/null +++ b/doc/kwallet-query.adoc @@ -0,0 +1,67 @@ +kwallet-query(1) +================ +:doctype: manpage + +NAME +---- +kwallet-query - KDE Wallet command-line manipulation tool + +SYNOPSIS +-------- +*kwallet-query* 'OPTIONS' 'wallet' + +DESCRIPTION +----------- +kwallet-query comes in handy when shell scripts need to read or update the KDE +Wallet. It works by manipulating the entries under the *Passwords* section, as +displayed in the *KDE Wallet Manager* utility. It's only parameter is the +'wallet' name the tool should read or update. The operation mode is specified +by the options. + +OPTIONS +------- +*-h,--help*:: + Display a short help message +*-l,--list-entries*:: + List password entries. These are the folder names under the *Passwords* + section when the 'wallet' is displayed in the *KDE Wallet Manager* utility. +*-r,--read-password* 'Entry':: + Read the contents of the given 'Entry' from the *Passwords* section of the + 'wallet' and output it on the standard output. +*-w,--write-password* 'Entry':: + Write secrets to the given 'Entry' under the *Passwords* section of the given + 'wallet'. The secrets are read from the standard input. + *IMPORTANT* previous wallet entry value will be overwritten by this option, so + be careful when using it! +*-v,--verbose*:: + Output more information when performing the operation, to help debugging. + +EXIT STATUS +----------- +*0*:: + Success +*1*:: + The wallet 'wallet' was not found +*2*:: + The wallet 'wallet' could not be opened. For example, that would be an indication + of a bad password entry or some other problem with the KDE Wallet system +*3*:: + The *Passwords* section was not found inside the wallet 'wallet'. Perhaps the + wallet file is corrupt? +*4*:: + The read or write operation has failed for some reason. + +BUGS +---- +Please report all bugs on the KDE bug reporting website: bugs.kde.org. Be sure to +select kwallet-query when submitting your bug-report. + +AUTHOR +------ +kwallet-query was originally written by Valentin Rusu and is part of KDE. + +COPYING +------- +Copyright \(C) 2015 Valentin Rusu. Free use of this software is +granted under the terms of the GNU General Public License (GPL). + diff --git a/doc/man-kwallet-query.1.docbook b/doc/man-kwallet-query.1.docbook new file mode 100644 index 0000000..9cddd13 --- /dev/null +++ b/doc/man-kwallet-query.1.docbook @@ -0,0 +1,161 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd";> +<?asciidoc-toc?> +<?asciidoc-numbered?> +<refentry lang="en"> +<refentryinfo> + <title>kwallet-query(1)</title> +</refentryinfo> +<refmeta> +<refentrytitle>kwallet-query</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="source"> </refmiscinfo> +<refmiscinfo class="manual"> </refmiscinfo> +</refmeta> +<refnamediv> + <refname>kwallet-query</refname> + <refpurpose>KDE Wallet command-line manipulation tool</refpurpose> +</refnamediv> +<refsynopsisdiv id="_synopsis"> +<simpara><emphasis role="strong">kwallet-query</emphasis> <emphasis>OPTIONS</emphasis> <emphasis>wallet</emphasis></simpara> +</refsynopsisdiv> +<refsect1 id="_description"> +<title>DESCRIPTION</title> +<simpara>kwallet-query comes in handy when shell scripts need to read or update the KDE +Wallet. It works by manipulating the entries under the <emphasis role="strong">Passwords</emphasis> section, as +displayed in the <emphasis role="strong">KDE Wallet Manager</emphasis> utility. It’s only parameter is the +<emphasis>wallet</emphasis> name the tool should read or update. The operation mode is specified +by the options.</simpara> +</refsect1> +<refsect1 id="_options"> +<title>OPTIONS</title> +<variablelist> +<varlistentry> +<term> +<emphasis role="strong">-h,--help</emphasis> +</term> +<listitem> +<simpara> + Display a short help message +</simpara> +</listitem> +</varlistentry> +<varlistentry> +<term> +<emphasis role="strong">-l,--list-entries</emphasis> +</term> +<listitem> +<simpara> + List password entries. These are the folder names under the <emphasis role="strong">Passwords</emphasis> + section when the <emphasis>wallet</emphasis> is displayed in the <emphasis role="strong">KDE Wallet Manager</emphasis> utility. +</simpara> +</listitem> +</varlistentry> +<varlistentry> +<term> +<emphasis role="strong">-r,--read-password</emphasis> <emphasis>Entry</emphasis> +</term> +<listitem> +<simpara> + Read the contents of the given <emphasis>Entry</emphasis> from the <emphasis role="strong">Passwords</emphasis> section of the + <emphasis>wallet</emphasis> and output it on the standard output. +</simpara> +</listitem> +</varlistentry> +<varlistentry> +<term> +<emphasis role="strong">-w,--write-password</emphasis> <emphasis>Entry</emphasis> +</term> +<listitem> +<simpara> + Write secrets to the given <emphasis>Entry</emphasis> under the <emphasis role="strong">Passwords</emphasis> section of the given + <emphasis>wallet</emphasis>. The secrets are read from the standard input. + <emphasis role="strong">IMPORTANT</emphasis> previous wallet entry value will be overwritten by this option, so + be careful when using it! +</simpara> +</listitem> +</varlistentry> +<varlistentry> +<term> +<emphasis role="strong">-v,--verbose</emphasis> +</term> +<listitem> +<simpara> + Output more information when performing the operation, to help debugging. +</simpara> +</listitem> +</varlistentry> +</variablelist> +</refsect1> +<refsect1 id="_exit_status"> +<title>EXIT STATUS</title> +<variablelist> +<varlistentry> +<term> +<emphasis role="strong">0</emphasis> +</term> +<listitem> +<simpara> + Success +</simpara> +</listitem> +</varlistentry> +<varlistentry> +<term> +<emphasis role="strong">1</emphasis> +</term> +<listitem> +<simpara> + The wallet <emphasis>wallet</emphasis> was not found +</simpara> +</listitem> +</varlistentry> +<varlistentry> +<term> +<emphasis role="strong">2</emphasis> +</term> +<listitem> +<simpara> + The wallet <emphasis>wallet</emphasis> could not be opened. For example, that would be an indication + of a bad password entry or some other problem with the KDE Wallet system +</simpara> +</listitem> +</varlistentry> +<varlistentry> +<term> +<emphasis role="strong">3</emphasis> +</term> +<listitem> +<simpara> + The <emphasis role="strong">Passwords</emphasis> section was not found inside the wallet <emphasis>wallet</emphasis>. Perhaps the + wallet file is corrupt? +</simpara> +</listitem> +</varlistentry> +<varlistentry> +<term> +<emphasis role="strong">4</emphasis> +</term> +<listitem> +<simpara> + The read or write operation has failed for some reason. +</simpara> +</listitem> +</varlistentry> +</variablelist> +</refsect1> +<refsect1 id="_bugs"> +<title>BUGS</title> +<simpara>Please report all bugs on the KDE bug reporting website: bugs.kde.org. Be sure to +select kwallet-query when submitting your bug-report.</simpara> +</refsect1> +<refsect1 id="_author"> +<title>AUTHOR</title> +<simpara>kwallet-query was originally written by Valentin Rusu and is part of KDE.</simpara> +</refsect1> +<refsect1 id="_copying"> +<title>COPYING</title> +<simpara>Copyright (C) 2015 Valentin Rusu. Free use of this software is +granted under the terms of the GNU General Public License (GPL).</simpara> +</refsect1> +</refentry>
