# SPDX-License-Identifier: GPL-2.0

[suite tfortune]
[supercommand tfortune]
	purpose = fortune cookies with tags
	[description]
		Like fortune(1), tfortune prints out a random epigram. However,
		the epigrams in the input files must contain additional information,
		called "tags". The program picks only epigrams which are considered
		"admissible" based on the tags and the command line options.
	[/description]
	non-opts-name = <file>...
	[option accept]
		short_opt = a
		summary = epigrams which contain this tag are admissible
		arg_info = required_arg
		arg_type = string
		typestr = tag
		flag multiple
		[help]
			This option may be given multiple times.
		[/help]
	[option reject]
		short_opt = r
		summary = epigrams which contain this tag are inadmissible
		arg_info = required_arg
		arg_type = string
		typestr = tag
		flag multiple
		[help]
			Like --accept, this may be given multiple times. See the discussion
			below how --accept and --reject interact.
		[/help]
	[option statistics]
		short_opt = s
		summary = print tags found in input files
		[help]
			If this option is specified, tfortune does not print any
			epigrams. Instead, it prints all tags found in the given input file(s),
			together with how many time each tag occurred. The list is sorted by
			occurence count.
		[/help]
	[option accept-reject]
		summary = Admissible epigrams
		flag ignored
		[help]
			tfortune picks a random epigram from the set of admissible epigrams,
			which is computed as follows. If neither --accept nor --reject are
			specified, all epigrams are considered admissible. If only --accept
			is specified, epigrams with at least one tag given as an argument to
			--accept are admissible, all others are inadmissible. Similarly, if
			only --reject is specified, epigrams with at least one tag given as an
			argument to --reject are inadmissible, all others are admissible. If
			both --accept and --reject are specified, an epigram is admissible
			if and only if it has at least one tag which is given as an argument
			to --accept but no tag which is given as an argument to --reject.
		[/help]
	[option format]
		summary = Input file format
		flag ignored
		[help]
			Input files may contain arbitrary many epigrams. The end of each
			epigram must be marked with a "tag" line. The tag line consists of
			four dashes, a space character, and a comma separated list of tags.
			Tags may span multiple words, but no comma is allowed.
		[/help]

[section example]
The following is an example input file for tfortune. It contains a single epigram
with two tags.

.RS
.EX
Anyone who attempts to generate random numbers by deterministic means
is, of course, living in a state of sin.          -- John von Neumann
---- math,religion
.EE
.RE
[/section]

[section copyright]
	Written by Andre Noll
	.br
	Copyright (C) 2016-present Andre Noll
	.br
	License: GNU GPL version 3
	.br
	This is free software: you are free to change and redistribute it.
	.br
	There is NO WARRANTY, to the extent permitted by law.
	.br
	Report bugs to
	.MT <maan@tuebingen.mpg.de>
	Andre Noll
	.ME
	.br
	Homepage:
	.UR http://people.tuebingen.mpg.de/~maan/tfortune/
	.UE
[/section]
[section see also]
	.BR fortune (6)
[/section]