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]