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