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]