Install man page in section 6.
[tfortune.git] / tfortune.suite.m4
1 # SPDX-License-Identifier: GPL-3.0-only
2
3 [suite tfortune]
4 mansect = 6
5 manual_title = Games Manual
6 caption = Subcommands
7 [supercommand tfortune]
8 purpose = SLOGAN()
9 [description]
10 DESCRIPTION1()
11
12 DESCRIPTION2()
13
14 DESCRIPTION3()
15 [/description]
16 synopsis = [global-options...] [--] [<subcommand> [subcommand-options...]]
17 [option help]
18 summary = print help and exit
19 short_opt = h
20 [option detailed-help]
21 summary = print help, including all details, and exit
22 [option version]
23 summary = print version and exit
24 short_opt = V
25 [option loglevel]
26 summary = control amount of logging
27 short_opt = l
28 arg_info = required_arg
29 arg_type = string
30 typestr = severity
31 values = {
32 LSGLL_DEBUG = "debug",
33 LSGLL_INFO = "info",
34 LSGLL_NOTICE = "notice",
35 LSGLL_WARNING = "warning",
36 LSGLL_ERROR = "error",
37 LSGLL_CRIT = "crit",
38 LSGLL_EMERG = "emerg"
39 }
40 default_val = warning
41 [help]
42 Log only messages with severity greater or equal than the given
43 value. Possible values:
44
45 debug: Produces really noisy output.
46 info: Still noisy, but won't fill up the disk quickly.
47 notice: Indicates normal, but significant event.
48 warning: Unexpected events that can be handled.
49 error: Unhandled error condition.
50 crit: System might be unreliable.
51 emerg: Last message before exit.
52 [/help]
53 [option basedir]
54 summary = where to look for input files
55 short_opt = b
56 arg_info = required_arg
57 arg_type = string
58 typestr = directory
59 default_val = "~/.tfortune"
60 [help]
61 This is used to locate epigrams and named tag expressions.
62 If any filename argument does not start with a slash, the
63 filename is interpreted as relative to this base directory.
64
65 Epigrams are expected in the "epigrams" subdirectory of the base
66 directory while tag expressions are expected to be stored below
67 "expressions".
68 [/help]
69
70 [subcommand compgen]
71 purpose = perform bash command line completion
72 non-opts-name = arg...
73 [description]
74 This subcommand is executed from the bash completer for tfortune. The
75 completer sets the non-option arguments for the subcommand to the
76 words of the current command line. It obtains these words from the
77 elements of the special COMP_WORDS array which is maintained by bash.
78
79 The compgen subcommand writes all possible completions to stdout. The
80 completer reads in the completions and builds the COMPREPLY array
81 containing the matching entries. Bash examines the elements of this
82 array and completes the command line if there is a single matching
83 completion, or prints out the list of completions in case of ambiguity.
84
85 [/description]
86 [option current-word-index]
87 short_opt = c
88 summary = index of the current word in the command line
89 typestr = num
90 arg_info = required_arg
91 arg_type = uint32
92 [help]
93 An index into the argument vector of the word containing the current
94 cursor position. See the description of the $CWORD special variable
95 in the bash manual.
96 [/help]
97
98 [subcommand completer]
99 purpose = print the bash completer to stdout
100 [description]
101 The output of this command is designed to be re-used as input for bash.
102 Specifically, bash completion for tfortune can be activated by adding
103 the following to .bashrc: eval "$(tfortune completer)".
104 [/description]
105 [option alias]
106 summary = also add an alias and a completer for it
107 short_opt = a
108 arg_info = required_arg
109 arg_type = string
110 typestr = name
111 [help]
112 Specify this to define a bash alias for tfortune along with the
113 completer. Unlike the regular tfortune program, the alias will
114 contain the double dash argument which separates the subcommand and
115 its options from the options to tfortune itself.
116 [/help]
117
118 [subcommand ede]
119 purpose = edit epigrams
120 non-opts-name = basename...
121 [description]
122 Opens the named epigram file an interactive editor. The executable
123 of the editor is determined as follows: First the contents of the
124 environment variable TFORTUNE_EDITOR is examined. If this variable
125 is empty or unset, EDITOR is tried. If EDITOR is also unset, vi
126 is executed.
127
128 The given basename is interpreted as described in the help text of the
129 --basedir option above. If --basedir is not given and the "epigrams"
130 directory does not exist, it is created.
131 [/description]
132
133 [subcommand edx]
134 purpose = edit tag expressions
135 non-opts-name = basename...
136 [description]
137 Opens the named tag expression file an interactive editor. The editor
138 to execute is determined in the same way as for the "ede" subcommand.
139 Also, a non-existing "expressions" subdirectory is handled in the same
140 way.
141 [/description]
142 [subcommand help]
143 purpose = list available subcommands or print command-specific help
144 non-opts-name = [command]
145 [description]
146 Without any arguments, help prints the list of available commands. When
147 called with a command name argument, it prints the help text of the
148 given command.
149 [/description]
150 [option long]
151 short_opt = l
152 summary = show the long help text
153 [help]
154 If the optional argument is supplied, the long help text contains the
155 synopsis, the purpose and the description of the specified command,
156 followed by the option list including summary and help text of each
157 option. Without --long, the short help is shown instead. This omits
158 the description of the command and the option help.
159
160 If no command is supplied but --long is given, the list contains the
161 purpose of each command.
162 [/help]
163
164 [subcommand lse]
165 purpose = list epigram files
166 [description]
167 Print the list of all epigram files.
168 [/description]
169 [option long]
170 short_opt = l
171 summary = long listing
172 [help]
173 This is similar to the long output of the standard ls(1) command.
174 [/help]
175
176 [subcommand lst]
177 purpose = list tags
178 [description]
179 This lists all tags contained in any of the given input files.
180 [/description]
181 non-opts-name = <file>...
182 [option long]
183 short_opt = l
184 summary = long listing
185 [help]
186 Also show how many times this tag appears.
187 [/help]
188 [option sort-by-count]
189 short_opt = c
190 summary = sort by occurrence count rather than alphabetically.
191 [option reverse]
192 short_opt = r
193 summary = reverse sort order
194
195 [subcommand lsx]
196 purpose = list tag expressions
197 [description]
198 Print the list of all named tag expressions.
199 [/description]
200 [option long]
201 short_opt = l
202 summary = long listing
203 [help]
204 This is similar to the long output of the standard ls(1) command.
205 [/help]
206 [subcommand print]
207 purpose = print epigram(s)
208 [description]
209 Unless --all is given, this picks an epigram by random from the
210 given file(s) which is admissible with respect to the given named
211 tag expression. If no file is given, all files are taken into account.
212 [/description]
213 non-opts-name = [file...]
214 [option expression]
215 short_opt = x
216 summary = name of the tag expression
217 arg_info = required_arg
218 arg_type = string
219 typestr = filename
220 default_val = /dev/null
221 [help]
222 Use the tag expression stored in the given file to define the
223 admissible epigrams. The special string "-" means to read the tag
224 expression from stdin. The default value corresponds to the empty
225 tag expression for which all epigrams are admissible.
226 [/help]
227 [option all]
228 short_opt = a
229 summary = print all admissible epigrams, not just a random one.
230 [option tags]
231 short_opt = t
232 summary = print also the tags of the selected epigram
233 [subcommand stats]
234 purpose = show statistics
235 [description]
236 This prints several counts and averages about the epigrams, tags and
237 tag expressions.
238 [/description]
239 [option verbose]
240 short_opt = v
241 summary = include statistics about hash table utilization
242
243 [section Input file format]
244 Input files may contain arbitrary many epigrams. The end of each
245 epigram must be marked with a "tag" line. The tag line consists of
246 four dashes, a space character, and a comma separated list of tags.
247 Tags may span multiple words, but no comma is allowed. The following
248 is an example input file for tfortune. It contains a single epigram
249 with two tags.
250
251 .RS
252 .EX
253 Anyone who attempts to generate random numbers by deterministic means
254 is, of course, living in a state of sin. -- John von Neumann
255 ---- math,religion
256 .EE
257 .RE
258 [/section]
259
260 [section Tag Expressions]
261 Tag expressions are based on a context-free grammar in which the
262 following keywords are defined:
263 .IP \(bu 4
264 .B tag("foo")
265 evaluates to
266 .I true
267 if the epigram contains a tag named
268 .IR foo ,
269 .I false
270 otherwise.
271 .IP \(bu 4
272 .B len
273 evaluates to the number of bytes of the epigram.
274 .IP \(bu 4
275 .B text
276 evaluates to contents of the epigram. This is useful for pattern
277 matching.
278 .P
279
280 The grammar admits the following operators and relations:
281 .IP \(bu 4
282 .BR && ,
283 .BR || ,
284 .BR !:
285 logical operators for
286 .IR and ,
287 .IR or ,
288 and
289 .IR not .
290 .IP \(bu 4
291 .BR + ,
292 .BR - ,
293 .BR * ,
294 .BR + :
295 arithmetic operators for addition, negation or subtraction (unary
296 or binary minus), multiplication and division. Arithmetic is always
297 performed on 64 bit signed integers.
298 .IP \(bu 4
299 .BR < ,
300 .BR > ,
301 .BR <=,
302 .BR >=,
303 .BR ==,
304 .BR != :
305 .BR =~ :
306 less than, greater than, less or equal than, greater or equal than,
307 equal to, not equal to, regular expression match.
308 Regular expression patterns are of the form
309 .IR /pattern/[flags] .
310 That is, the pattern is delimited by slashes, and is followed by
311 zero or more characters, each specifying a flag according to the
312 following list
313 .RS
314 .IP \(bu 4
315 .BR i :
316 Ignore case in match
317 .RI ( REG_ICASE )
318 .IP \(bu 4
319 .BR n :
320 Treat newline as an ordinary character
321 .RI ( REG_NEWLINE )
322
323 .RE
324 .RS
325 Note that only extended regular expression patterns are supported. See
326 regex(3) for details.
327 .RE
328
329 The above operators obey the usual associativity and precedence
330 rules. Parentheses can be used to change precedence.
331
332 A
333 .I tag expression
334 is an expression in this grammar which evaluates to either
335 .I true
336 or
337 .IR false .
338 Epigrams for which the expression is
339 .I true
340 are called
341 .IR admissible .
342
343 For example, the above epigram is admissible for the tag expression
344
345 .RS
346 .EX
347 (tag("math") || tag("physics")) && len < 1000 && text =~ /neumann/i
348 .EE
349 .RE
350
351 It is not admissible for
352
353 .RS
354 .EX
355 (tag("math") && tag("physics")) || len > 1000 || text =~ /neumann/
356 .EE
357 .RE
358 [/section]
359
360 [section Examples]
361 .IP \(bu 2
362 Print a random epigram:
363
364 .RS 6
365 .EX
366 tfortune print
367 .EE
368 .RE
369 .IP \(bu 2
370 Print a random short (less than 100 bytes) epigram:
371
372 .RS 6
373 .EX
374 echo 'len < 100' | tfortune -l debug -- print -x -
375 .EE
376 .RE
377 .IP \(bu 2
378 List tags, including usage counts, sort by count in descending order:
379
380 .RS 6
381 .EX
382 tfortune -- lst -lcr
383 .EE
384 .RE
385 .IP \(bu 2
386 Activate bash completion and define the
387 .I tf
388 alias:
389
390 .RS 6
391 .EX
392 eval "$(tfortune completer -a tf)"
393 .EE
394 .RE
395
396 [/section]
397
398 [section copyright]
399 Written by AUTHOR()
400 .br
401 Copyright (C) COPYRIGHT_YEAR() AUTHOR()
402 .br
403 License: LICENSE()
404 .br
405 This is free software: you are free to change and redistribute it.
406 .br
407 There is NO WARRANTY, to the extent permitted by law.
408 .P
409 Web page:
410 .UR PACKAGE_HOMEPAGE()
411 .UE
412 .br
413 Git clone URL:
414 .UR CLONE_URL()
415 .UE
416 .br
417 Gitweb:
418 .UR GITWEB_URL()
419 .UE
420 .br
421 Author's home page:
422 .UR HOME_URL()
423 .UE
424 .br
425 Report bugs to
426 .MT EMAIL()
427 AUTHOR()
428 .ME
429 [/section]
430 [section see also]
431 .BR fortune (6)
432 [/section]