qatom: improve manpage

Bug: https://bugs.gentoo.org/645554

3 files changed, 122 insertions, 10 deletions

diff --git a/man/include/qatom.desc b/man/include/qatom.desc
new file mode 100644
index 0000000..10f0c1c
--- /dev/null
+++ b/man/include/qatom.desc
@@ -0,0 +1,15 @@
+\fIqatom\fR parses strings into atoms and optionally compares them.  The
+parsing into atoms results in CATEGORY, PN (package name), PV (package
+version), PR (package revision), SLOT and REPO.  Next to these version
+qualifiers (e.g.\ >, <, or =) and optional * suffix are extracted.  All
+but PN are optional.
+
+Comparison of atoms returns the relationship between two parsed atoms.
+\fIqatom\fR does not allow to test conditions.  It is possible to
+perform multiple comparisons by simply adding more arguments.
+Comparisons are, however, always performed two by two, so there must be
+an even count of arguments to the compare function.
+
+The \fIqatom\fR applet is a direct wrapper around the atom parsing
+functionalities used by various other applets.  As such this applet
+allows easy testing or atom parsing and comparison behaviour.
diff --git a/man/include/qatom.optdesc.yaml b/man/include/qatom.optdesc.yaml
new file mode 100644
index 0000000..e71dfb7
--- /dev/null
+++ b/man/include/qatom.optdesc.yaml
@@ -0,0 +1,43 @@
+format: |
+    Specify a custom  output  format.  The default format is
+    .nf
+    %{CATEGORY} %{PN} %{PV} %[PR] %[SLOT] %[pfx] %[sfx]
+    .fi
+    Conversion specifiers start with a \fI%\fR symbol and are followed
+    by either \fI{\fR or \fI[\fR.  Next is the name of the field to
+    expand, followed by a matching \fI}\fR or \fI]\fR.  The difference
+    between \fI{\fR and \fI[\fR is that the latter is only printed if
+    the field referred is set, while the former prints \fI<unset>\fR in
+    that case.
+
+    The following fields are supported, which are inline with the
+    variables from \fBebuild\fR(5).
+    .RS
+    .IP CATEGORY
+    The category of the package.
+    .IP P
+    The package name and version without the ebuild revision.
+    .IP PN
+    The package name.
+    .IP PV
+    The package version without the ebuild revision.
+    .IP PVR
+    The package version including ebuild revision, which is also printed
+    when zero, unlike for \fIPF\fR.
+    .IP PF
+    The package name, version and revision when not zero.  Thus, a zero
+    revision \fI\-r0\fR is not printed.
+    .IP PR
+    The ebuild revision, when force printed, outputs \fI\-r0\fR when unset.
+    .IP SLOT
+    The package slot, when force printed, outputs \fI\-\fR when unset.
+    .IP REPO
+    The package repository.
+    .IP pfx
+    The package prefixes, that is version specifiers.
+    .IP sfx
+    The package suffices, currently that is just the asterisk.
+    .RE
+verbose: Force all expansions, basically treat all \fI[\fR like \fI{\fR.
+quiet: Ignored for compatibility with other qapplets.
+nocolor: Ignored for compatibility with other qapplets.
diff --git a/man/qatom.1 b/man/qatom.1
index 4a30343..aeb9629 100644
--- a/man/qatom.1
+++ b/man/qatom.1
@@ -1,41 +1,95 @@
-.TH qatom "1" "Mar 2016" "Gentoo Foundation" "qatom"
+.\" generated by mkman.py, please do NOT edit!
+.TH qatom "1" "Apr 2018" "Gentoo Foundation" "qatom"
 .SH NAME
 qatom \- split atom strings
 .SH SYNOPSIS
 .B qatom
 \fI[opts] <pkg>\fR
 .SH DESCRIPTION
+\fIqatom\fR parses strings into atoms and optionally compares them.  The
+parsing into atoms results in CATEGORY, PN (package name), PV (package
+version), PR (package revision), SLOT and REPO.  Next to these version
+qualifiers (e.g.\ >, <, or =) and optional * suffix are extracted.  All
+but PN are optional.
 
+Comparison of atoms returns the relationship between two parsed atoms.
+\fIqatom\fR does not allow to test conditions.  It is possible to
+perform multiple comparisons by simply adding more arguments.
+Comparisons are, however, always performed two by two, so there must be
+an even count of arguments to the compare function.
+
+The \fIqatom\fR applet is a direct wrapper around the atom parsing
+functionalities used by various other applets.  As such this applet
+allows easy testing or atom parsing and comparison behaviour.
 .SH OPTIONS
 .TP
 \fB\-F\fR \fI<arg>\fR, \fB\-\-format\fR \fI<arg>\fR
-Custom output format (default: %{CATEGORY} %{PN} %{PV} %[PR] %[SLOT] %[pfx] %[sfx])
+Specify a custom  output  format.  The default format is
+.nf
+%{CATEGORY} %{PN} %{PV} %[PR] %[SLOT] %[pfx] %[sfx]
+.fi
+Conversion specifiers start with a \fI%\fR symbol and are followed
+by either \fI{\fR or \fI[\fR.  Next is the name of the field to
+expand, followed by a matching \fI}\fR or \fI]\fR.  The difference
+between \fI{\fR and \fI[\fR is that the latter is only printed if
+the field referred is set, while the former prints \fI<unset>\fR in
+that case.
+
+The following fields are supported, which are inline with the
+variables from \fBebuild\fR(5).
+.RS
+.IP CATEGORY
+The category of the package.
+.IP P
+The package name and version without the ebuild revision.
+.IP PN
+The package name.
+.IP PV
+The package version without the ebuild revision.
+.IP PVR
+The package version including ebuild revision, which is also printed
+when zero, unlike for \fIPF\fR.
+.IP PF
+The package name, version and revision when not zero.  Thus, a zero
+revision \fI\-r0\fR is not printed.
+.IP PR
+The ebuild revision, when force printed, outputs \fI\-r0\fR when unset.
+.IP SLOT
+The package slot, when force printed, outputs \fI\-\fR when unset.
+.IP REPO
+The package repository.
+.IP pfx
+The package prefixes, that is version specifiers.
+.IP sfx
+The package suffices, currently that is just the asterisk.
+.RE
 .TP
 \fB\-c\fR, \fB\-\-compare\fR
-Compare two atoms
+Compare two atoms.
 .TP
 \fB\-\-root\fR \fI<arg>\fR
-Set the ROOT env var
+Set the ROOT env var.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Make a lot of noise
+Force all expansions, basically treat all \fI[\fR like \fI{\fR.
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Tighter output; suppress warnings
+Ignored for compatibility with other qapplets.
 .TP
 \fB\-C\fR, \fB\-\-nocolor\fR
-Don't output color
+Ignored for compatibility with other qapplets.
 .TP
 \fB\-h\fR, \fB\-\-help\fR
-Print this help and exit
+Print this help and exit.
 .TP
 \fB\-V\fR, \fB\-\-version\fR
-Print version and exit
+Print version and exit.
 
 .SH "REPORTING BUGS"
 Please report bugs via http://bugs.gentoo.org/
 .br
-Product: Portage Development; Component: Tools
+Product: Portage Development; Component: Tools, Assignee:
+portage-utils@gentoo.org
 .SH AUTHORS
 .nf
 Ned Ludd <solar@gentoo.org>