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 locate]
 169         purpose = identify epigram files which contain epigrams matching a pattern
 170         non-opts-name = <regex>
 171         [description]
 172                 This prints the names of the epigram files which contain at least one
 173                 epigram that matches the given pattern. It is similar to running the
 174                 shell command "grep -El <regex>" on all epigram files.
 175
 176                 The <regex> argument must be of the form described in section "Tag
 177                 Expressions" of tfortune(1).
 178         [/description]
 179         [option edit]
 180                 short_opt = e
 181                 summary = edit matching files
 182                 [help]
 183                         Instead of printing file names, all epigram files are opened in
 184                         the editor which contain at least one matching epigram.  See the
 185                         description of the "ede" subcommand for how the editor is invoked.
 186                 [/help]
 187
 188 [subcommand lse]
 189         purpose = list epigram files
 190         [description]
 191                 Print the list of all epigram files.
 192         [/description]
 193         [option long]
 194                 short_opt = l
 195                 summary = long listing
 196                 [help]
 197                         This is similar to the long output of the standard ls(1) command.
 198                 [/help]
 199
 200 [subcommand lst]
 201         purpose = list tags
 202         [description]
 203                 This lists all tags contained in any of the given input files.
 204         [/description]
 205         non-opts-name = <file>...
 206         [option long]
 207                 short_opt = l
 208                 summary = long listing
 209                 [help]
 210                         Also show how many times this tag appears.
 211                 [/help]
 212         [option sort-by-count]
 213                 short_opt = c
 214                 summary = sort by occurrence count rather than alphabetically.
 215         [option reverse]
 216                 short_opt = r
 217                 summary = reverse sort order
 218
 219 [subcommand lsx]
 220         purpose = list tag expressions
 221         [description]
 222                 Print the list of all named tag expressions.
 223         [/description]
 224         [option long]
 225                 short_opt = l
 226                 summary = long listing
 227                 [help]
 228                         This is similar to the long output of the standard ls(1) command.
 229                 [/help]
 230 [subcommand print]
 231         purpose = print epigram(s)
 232         [description]
 233                 Unless --all is given, this picks an epigram by random from the
 234                 given file(s) which is admissible with respect to the given named
 235                 tag expression. If no file is given, all files are taken into account.
 236         [/description]
 237         non-opts-name = [file...]
 238         [option expression]
 239                 short_opt = x
 240                 summary = name of the tag expression
 241                 arg_info = required_arg
 242                 arg_type = string
 243                 typestr = filename
 244                 default_val = /dev/null
 245                 [help]
 246                         Use the tag expression stored in the given file to define the
 247                         admissible epigrams. The special string "-" means to read the tag
 248                         expression from stdin. The default value corresponds to the empty
 249                         tag expression for which all epigrams are admissible.
 250                 [/help]
 251         [option all]
 252                 short_opt = a
 253                 summary = print all admissible epigrams, not just a random one.
 254         [option tags]
 255                 short_opt = t
 256                 summary = print also the tags of the selected epigram
 257 [subcommand stats]
 258         purpose = show statistics
 259         [description]
 260                 This prints several counts and averages about the epigrams, tags and
 261                 tag expressions.
 262         [/description]
 263         [option verbose]
 264                 short_opt = v
 265                 summary = include statistics about hash table utilization
 266
 267 [section Input file format]
 268         Input files may contain arbitrary many epigrams. The end of each
 269         epigram must be marked with a "tag" line. The tag line consists of
 270         four dashes, a space character, and a comma separated list of tags.
 271         Tags may span multiple words, but no comma is allowed. The following
 272         is an example input file for tfortune. It contains a single epigram
 273         with two tags.
 274
 275         .RS
 276         .EX
 277         Anyone who attempts to generate random numbers by deterministic means
 278         is, of course, living in a state of sin.          -- John von Neumann
 279         ---- math,religion
 280         .EE
 281         .RE
 282 [/section]
 283
 284 [section Tag Expressions]
 285         Tag expressions are based on a context-free grammar in which the
 286         following keywords are defined:
 287         .IP \(bu 4
 288         .B tag("foo")
 289         evaluates to
 290         .I true
 291         if the epigram contains a tag named
 292         .IR foo ,
 293         .I false
 294         otherwise.
 295         .IP \(bu 4
 296         .B len
 297         evaluates to the number of bytes of the epigram.
 298         .IP \(bu 4
 299         .B text
 300         evaluates to contents of the epigram. This is useful for pattern
 301         matching.
 302         .P
 303
 304         The grammar admits the following operators and relations:
 305         .IP \(bu 4
 306         .BR && ,
 307         .BR || ,
 308         .BR !:
 309         logical operators for
 310         .IR and ,
 311         .IR or ,
 312         and
 313         .IR not .
 314         .IP \(bu 4
 315         .BR + ,
 316         .BR - ,
 317         .BR * ,
 318         .BR + :
 319         arithmetic operators for addition, negation or subtraction (unary
 320         or binary minus), multiplication and division. Arithmetic is always
 321         performed on 64 bit signed integers.
 322         .IP \(bu 4
 323         .BR < ,
 324         .BR > ,
 325         .BR <=,
 326         .BR >=,
 327         .BR ==,
 328         .BR != :
 329         .BR =~ :
 330         less than, greater than, less or equal than, greater or equal than,
 331         equal to, not equal to, regular expression match.
 332         Regular expression patterns are of the form
 333         .IR /pattern/[flags] .
 334         That is, the pattern is delimited by slashes, and is followed by
 335         zero or more characters, each specifying a flag according to the
 336         following list
 337         .RS
 338         .IP \(bu 4
 339         .BR i :
 340         Ignore case in match
 341         .RI ( REG_ICASE )
 342         .IP \(bu 4
 343         .BR n :
 344         Treat newline as an ordinary character
 345         .RI ( REG_NEWLINE )
 346
 347         .RE
 348         .RS
 349         Note that only extended regular expression patterns are supported. See
 350         regex(3) for details.
 351         .RE
 352
 353         The above operators obey the usual associativity and precedence
 354         rules. Parentheses can be used to change precedence.
 355
 356         A
 357         .I tag expression
 358         is an expression in this grammar which evaluates to either
 359         .I true
 360         or
 361         .IR false .
 362         Epigrams for which the expression is
 363         .I true
 364         are called
 365         .IR admissible .
 366
 367         For example, the above epigram is admissible for the tag expression
 368
 369         .RS
 370         .EX
 371                 (tag("math") || tag("physics")) && len < 1000 && text =~ /neumann/i
 372         .EE
 373         .RE
 374
 375         It is not admissible for
 376
 377         .RS
 378         .EX
 379                 (tag("math") && tag("physics")) || len > 1000 || text =~ /neumann/
 380         .EE
 381         .RE
 382 [/section]
 383
 384 [section Examples]
 385         .IP \(bu 2
 386         Print a random epigram:
 387
 388         .RS 6
 389         .EX
 390                 tfortune print
 391         .EE
 392         .RE
 393         .IP \(bu 2
 394         Print a random short (less than 100 bytes) epigram:
 395
 396         .RS 6
 397         .EX
 398                 echo 'len < 100' | tfortune -l debug -- print -x -
 399         .EE
 400         .RE
 401         .IP \(bu 2
 402         List tags, including usage counts, sort by count in descending order:
 403
 404         .RS 6
 405         .EX
 406                 tfortune -- lst -lcr
 407         .EE
 408         .RE
 409         .IP \(bu 2
 410         Activate bash completion and define the
 411         .I tf
 412         alias:
 413
 414         .RS 6
 415         .EX
 416         eval "$(tfortune completer -a tf)"
 417         .EE
 418         .RE
 419
 420 [/section]
 421
 422 [section copyright]
 423         Written by AUTHOR()
 424         .br
 425         Copyright (C) COPYRIGHT_YEAR() AUTHOR()
 426         .br
 427         License: LICENSE()
 428         .br
 429         This is free software: you are free to change and redistribute it.
 430         .br
 431         There is NO WARRANTY, to the extent permitted by law.
 432         .P
 433         Web page:
 434         .UR PACKAGE_HOMEPAGE()
 435         .UE
 436         .br
 437         Git clone URL:
 438         .UR CLONE_URL()
 439         .UE
 440         .br
 441         Gitweb:
 442         .UR GITWEB_URL()
 443         .UE
 444         .br
 445         Author's home page:
 446         .UR HOME_URL()
 447         .UE
 448         .br
 449         Report bugs to
 450         .MT EMAIL()
 451         AUTHOR()
 452         .ME
 453 [/section]
 454 [section see also]
 455         .BR fortune (6)
 456 [/section]