[kde-doc-english] [kwallet] /: Adding manpage

Valentin Rusu kde at rusu.info
Sun Jun 14 07:01:15 UTC 2015 

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>

More information about the kde-doc-english mailing list