commit: 9164549006068637d060a23a9a24f657982bfbaf Author: Fabian Groffen <grobian <AT> gentoo <DOT> org> AuthorDate: Mon Apr 2 17:26:35 2018 +0000 Commit: Fabian Groffen <grobian <AT> gentoo <DOT> org> CommitDate: Mon Apr 2 17:26:35 2018 +0000 URL: https://gitweb.gentoo.org/proj/portage-utils.git/commit/?id=91645490
qatom: improve manpage Bug: https://bugs.gentoo.org/645554 man/include/qatom.desc | 15 +++++++++ man/include/qatom.optdesc.yaml | 43 ++++++++++++++++++++++++ man/qatom.1 | 74 ++++++++++++++++++++++++++++++++++++------ 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: [email protected] .SH AUTHORS .nf Ned Ludd <[email protected]>
