tfortune.suite.m4

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