1 |
commit: 9164549006068637d060a23a9a24f657982bfbaf |
2 |
Author: Fabian Groffen <grobian <AT> gentoo <DOT> org> |
3 |
AuthorDate: Mon Apr 2 17:26:35 2018 +0000 |
4 |
Commit: Fabian Groffen <grobian <AT> gentoo <DOT> org> |
5 |
CommitDate: Mon Apr 2 17:26:35 2018 +0000 |
6 |
URL: https://gitweb.gentoo.org/proj/portage-utils.git/commit/?id=91645490 |
7 |
|
8 |
qatom: improve manpage |
9 |
|
10 |
Bug: https://bugs.gentoo.org/645554 |
11 |
|
12 |
man/include/qatom.desc | 15 +++++++++ |
13 |
man/include/qatom.optdesc.yaml | 43 ++++++++++++++++++++++++ |
14 |
man/qatom.1 | 74 ++++++++++++++++++++++++++++++++++++------ |
15 |
3 files changed, 122 insertions(+), 10 deletions(-) |
16 |
|
17 |
diff --git a/man/include/qatom.desc b/man/include/qatom.desc |
18 |
new file mode 100644 |
19 |
index 0000000..10f0c1c |
20 |
--- /dev/null |
21 |
+++ b/man/include/qatom.desc |
22 |
@@ -0,0 +1,15 @@ |
23 |
+\fIqatom\fR parses strings into atoms and optionally compares them. The |
24 |
+parsing into atoms results in CATEGORY, PN (package name), PV (package |
25 |
+version), PR (package revision), SLOT and REPO. Next to these version |
26 |
+qualifiers (e.g.\ >, <, or =) and optional * suffix are extracted. All |
27 |
+but PN are optional. |
28 |
+ |
29 |
+Comparison of atoms returns the relationship between two parsed atoms. |
30 |
+\fIqatom\fR does not allow to test conditions. It is possible to |
31 |
+perform multiple comparisons by simply adding more arguments. |
32 |
+Comparisons are, however, always performed two by two, so there must be |
33 |
+an even count of arguments to the compare function. |
34 |
+ |
35 |
+The \fIqatom\fR applet is a direct wrapper around the atom parsing |
36 |
+functionalities used by various other applets. As such this applet |
37 |
+allows easy testing or atom parsing and comparison behaviour. |
38 |
|
39 |
diff --git a/man/include/qatom.optdesc.yaml b/man/include/qatom.optdesc.yaml |
40 |
new file mode 100644 |
41 |
index 0000000..e71dfb7 |
42 |
--- /dev/null |
43 |
+++ b/man/include/qatom.optdesc.yaml |
44 |
@@ -0,0 +1,43 @@ |
45 |
+format: | |
46 |
+ Specify a custom output format. The default format is |
47 |
+ .nf |
48 |
+ %{CATEGORY} %{PN} %{PV} %[PR] %[SLOT] %[pfx] %[sfx] |
49 |
+ .fi |
50 |
+ Conversion specifiers start with a \fI%\fR symbol and are followed |
51 |
+ by either \fI{\fR or \fI[\fR. Next is the name of the field to |
52 |
+ expand, followed by a matching \fI}\fR or \fI]\fR. The difference |
53 |
+ between \fI{\fR and \fI[\fR is that the latter is only printed if |
54 |
+ the field referred is set, while the former prints \fI<unset>\fR in |
55 |
+ that case. |
56 |
+ |
57 |
+ The following fields are supported, which are inline with the |
58 |
+ variables from \fBebuild\fR(5). |
59 |
+ .RS |
60 |
+ .IP CATEGORY |
61 |
+ The category of the package. |
62 |
+ .IP P |
63 |
+ The package name and version without the ebuild revision. |
64 |
+ .IP PN |
65 |
+ The package name. |
66 |
+ .IP PV |
67 |
+ The package version without the ebuild revision. |
68 |
+ .IP PVR |
69 |
+ The package version including ebuild revision, which is also printed |
70 |
+ when zero, unlike for \fIPF\fR. |
71 |
+ .IP PF |
72 |
+ The package name, version and revision when not zero. Thus, a zero |
73 |
+ revision \fI\-r0\fR is not printed. |
74 |
+ .IP PR |
75 |
+ The ebuild revision, when force printed, outputs \fI\-r0\fR when unset. |
76 |
+ .IP SLOT |
77 |
+ The package slot, when force printed, outputs \fI\-\fR when unset. |
78 |
+ .IP REPO |
79 |
+ The package repository. |
80 |
+ .IP pfx |
81 |
+ The package prefixes, that is version specifiers. |
82 |
+ .IP sfx |
83 |
+ The package suffices, currently that is just the asterisk. |
84 |
+ .RE |
85 |
+verbose: Force all expansions, basically treat all \fI[\fR like \fI{\fR. |
86 |
+quiet: Ignored for compatibility with other qapplets. |
87 |
+nocolor: Ignored for compatibility with other qapplets. |
88 |
|
89 |
diff --git a/man/qatom.1 b/man/qatom.1 |
90 |
index 4a30343..aeb9629 100644 |
91 |
--- a/man/qatom.1 |
92 |
+++ b/man/qatom.1 |
93 |
@@ -1,41 +1,95 @@ |
94 |
-.TH qatom "1" "Mar 2016" "Gentoo Foundation" "qatom" |
95 |
+.\" generated by mkman.py, please do NOT edit! |
96 |
+.TH qatom "1" "Apr 2018" "Gentoo Foundation" "qatom" |
97 |
.SH NAME |
98 |
qatom \- split atom strings |
99 |
.SH SYNOPSIS |
100 |
.B qatom |
101 |
\fI[opts] <pkg>\fR |
102 |
.SH DESCRIPTION |
103 |
+\fIqatom\fR parses strings into atoms and optionally compares them. The |
104 |
+parsing into atoms results in CATEGORY, PN (package name), PV (package |
105 |
+version), PR (package revision), SLOT and REPO. Next to these version |
106 |
+qualifiers (e.g.\ >, <, or =) and optional * suffix are extracted. All |
107 |
+but PN are optional. |
108 |
|
109 |
+Comparison of atoms returns the relationship between two parsed atoms. |
110 |
+\fIqatom\fR does not allow to test conditions. It is possible to |
111 |
+perform multiple comparisons by simply adding more arguments. |
112 |
+Comparisons are, however, always performed two by two, so there must be |
113 |
+an even count of arguments to the compare function. |
114 |
+ |
115 |
+The \fIqatom\fR applet is a direct wrapper around the atom parsing |
116 |
+functionalities used by various other applets. As such this applet |
117 |
+allows easy testing or atom parsing and comparison behaviour. |
118 |
.SH OPTIONS |
119 |
.TP |
120 |
\fB\-F\fR \fI<arg>\fR, \fB\-\-format\fR \fI<arg>\fR |
121 |
-Custom output format (default: %{CATEGORY} %{PN} %{PV} %[PR] %[SLOT] %[pfx] %[sfx]) |
122 |
+Specify a custom output format. The default format is |
123 |
+.nf |
124 |
+%{CATEGORY} %{PN} %{PV} %[PR] %[SLOT] %[pfx] %[sfx] |
125 |
+.fi |
126 |
+Conversion specifiers start with a \fI%\fR symbol and are followed |
127 |
+by either \fI{\fR or \fI[\fR. Next is the name of the field to |
128 |
+expand, followed by a matching \fI}\fR or \fI]\fR. The difference |
129 |
+between \fI{\fR and \fI[\fR is that the latter is only printed if |
130 |
+the field referred is set, while the former prints \fI<unset>\fR in |
131 |
+that case. |
132 |
+ |
133 |
+The following fields are supported, which are inline with the |
134 |
+variables from \fBebuild\fR(5). |
135 |
+.RS |
136 |
+.IP CATEGORY |
137 |
+The category of the package. |
138 |
+.IP P |
139 |
+The package name and version without the ebuild revision. |
140 |
+.IP PN |
141 |
+The package name. |
142 |
+.IP PV |
143 |
+The package version without the ebuild revision. |
144 |
+.IP PVR |
145 |
+The package version including ebuild revision, which is also printed |
146 |
+when zero, unlike for \fIPF\fR. |
147 |
+.IP PF |
148 |
+The package name, version and revision when not zero. Thus, a zero |
149 |
+revision \fI\-r0\fR is not printed. |
150 |
+.IP PR |
151 |
+The ebuild revision, when force printed, outputs \fI\-r0\fR when unset. |
152 |
+.IP SLOT |
153 |
+The package slot, when force printed, outputs \fI\-\fR when unset. |
154 |
+.IP REPO |
155 |
+The package repository. |
156 |
+.IP pfx |
157 |
+The package prefixes, that is version specifiers. |
158 |
+.IP sfx |
159 |
+The package suffices, currently that is just the asterisk. |
160 |
+.RE |
161 |
.TP |
162 |
\fB\-c\fR, \fB\-\-compare\fR |
163 |
-Compare two atoms |
164 |
+Compare two atoms. |
165 |
.TP |
166 |
\fB\-\-root\fR \fI<arg>\fR |
167 |
-Set the ROOT env var |
168 |
+Set the ROOT env var. |
169 |
.TP |
170 |
\fB\-v\fR, \fB\-\-verbose\fR |
171 |
-Make a lot of noise |
172 |
+Force all expansions, basically treat all \fI[\fR like \fI{\fR. |
173 |
.TP |
174 |
\fB\-q\fR, \fB\-\-quiet\fR |
175 |
-Tighter output; suppress warnings |
176 |
+Ignored for compatibility with other qapplets. |
177 |
.TP |
178 |
\fB\-C\fR, \fB\-\-nocolor\fR |
179 |
-Don't output color |
180 |
+Ignored for compatibility with other qapplets. |
181 |
.TP |
182 |
\fB\-h\fR, \fB\-\-help\fR |
183 |
-Print this help and exit |
184 |
+Print this help and exit. |
185 |
.TP |
186 |
\fB\-V\fR, \fB\-\-version\fR |
187 |
-Print version and exit |
188 |
+Print version and exit. |
189 |
|
190 |
.SH "REPORTING BUGS" |
191 |
Please report bugs via http://bugs.gentoo.org/ |
192 |
.br |
193 |
-Product: Portage Development; Component: Tools |
194 |
+Product: Portage Development; Component: Tools, Assignee: |
195 |
+portage-utils@g.o |
196 |
.SH AUTHORS |
197 |
.nf |
198 |
Ned Ludd <solar@g.o> |