initialinitial

1 files changed, 103 insertions, 0 deletions

diff --git a/tfortune.suite b/tfortune.suite
new file mode 100644
index 0000000..6545865
--- /dev/null
+++ b/tfortune.suite
@@ -0,0 +1,103 @@
+# 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]