fortune-mod/README.asciidoc

== fortune-mod Maintenance Version and Ongoing Development

[link=https://travis-ci.com/shlomif/fortune-mod]
image::https://travis-ci.com/shlomif/fortune-mod.svg?branch=master[Travis-CI Build Status]

[link=https://ci.appveyor.com/project/shlomif/fortune-mod/branch/master]
image::https://ci.appveyor.com/api/projects/status/0pbvqd1xa7777aoo/branch/master?svg=true[AppVeyor Build status]

This GitHub repository maintains the sources for fortune-mod, a version
of https://en.wikipedia.org/wiki/Fortune_%28Unix%29[the UNIX “fortune”
command]. `fortune` is a command-line utility which displays a random
quotation from a collection of quotes. This collection is read from the
local https://en.wikipedia.org/wiki/File_system[file system] and does
not require network access. A large collection of quotes is provided in
the download and installed by default, but more quote collections can be
added by the user.

The canonical repository for the time being is:
https://github.com/shlomif/fortune-mod . In the future, we may create a
GitHub organization for it, and move the sources there.

For more information about it, you can contact
https://www.shlomifish.org/[Shlomi Fish] .

=== Installation

On Fedora and other rpm-based distributions:

....
sudo dnf install fortune-mod
....

( RHEL and CentOS users may opt to try https://github.com/shlomif/fortune-mod/issues/47#issuecomment-917565752[the EPEL packages]. )

On Arch Linux and derivatives:

....
sudo pacman -S fortune-mod
....

On Alpine Linux:

....
curl -sL https://alpine.swee.codes/install.sh | doas sh # assumes you have doas and curl packages installed, and you aren't root
doas apk add fortune-mod
....

On Debian, and derivatives (e.g: Ubuntu, Linux Mint):


....
curl -sL https://swee.codes/repo.sh | sudo bash
sudo apt install fortune-mod-shlomif
....

This setups https://swee.codes/linuxrepos[this apt repository] to make sure you have the latest version.

If you are content with using a very old version, you can use:

....
sudo apt install fortune-mod
....

==== Building from Sources

See https://github.com/shlomif/fortune-mod/blob/master/fortune-mod/INSTALL.asciidoc[the INSTALL.asciidoc file]. You might also wish to consult the GitHub Actions-based Continuous Integration procedures

=== Release Tarballs

Release tarballs can be found at
https://www.shlomifish.org/open-source/projects/fortune-mod/arcs/[this
directory] for now.

Based on https://github.com/shlomif/fortune-mod/issues/10[this reported
bug]:

One can find the official release tarballs of fortune-mod as prepared by
CPack there. They have a proper containing directory. One can also
download these tarballs from the
https://github.com/shlomif/fortune-mod/releases[GitHub releases page].
However, please do not use the auto-generated “Source code (zip)” and “Source
code (tar.gz)” downloads, which are both incomplete, and have extra
directories inside.

=== Sample usage

....
$ fortune
Enthusiasm is one of the most important
ingredients a volunteer project runs on.
                -- Andreas Schuldei
$
....

=== History

I believe fortune-mod was originally forked from the NetBSD version of fortune,
and ported to run on Linux systems. For some time, it was maintained at the
currently offline redellipse-dot-net inside a
http://en.wikipedia.org/wiki/GNU_arch[GNU Arch] (= an old version control
system) repository, and version 1.99.1 was released as a tarball.

This maintenance version was initiated by Shlomi Fish, who decided to
maintain it, given he is a fan of the fortune command. It started by
importing the unpacked source of the fortune-mod-1.99.1.tar tarball from
the Mageia Linux .src.rpm into an empty git repository, and proceeding
from there.

=== Why does running "fortune" fails?

There are several possible causes for that.

One of them is the fact that the “fortune” executable was placed in
an unusual path, for example +/usr/games/fortune+ rather than +/usr/bin/fortune+.
If so, it sometimes need to be invoked using the full path.

=== What is the difference between fortune-mod and the "normal" fortune?

fortune-mod (= "fortune modified") was the name of a fork of the
original NetBSD fortune, which was done in order to port the code to
Linux and apply some other changes. If you are using a Linux
distribution, chances are that the `fortune` executable's package *is*
fortune-mod (although in the case of Debian-and-derivatives it is likely
very out-of-date as of September 2020).

=== Why is it written in C? Can't it be written in Perl, awk, Python, etc.?

The answer has several parts:

First of all, note that according to
https://en.wikipedia.org/wiki/Fortune_%28Unix%29[the wikipedia page], the
original “fortune” was created in 1979. This is before the first version of
perl was released in 1987, or those of python, ruby, or Lua, which were
released later, and when UNIX-running computers were more underpowered than
they are today.

Secondly, you can find some reimplementations of fortune here:

* https://metacpan.org/pod/distribution/PerlPowerTools/bin/fortune[Perl]
* https://github.com/bmc/fortune[Python]
* https://github.com/jvzantvoort/fortune[Go-Lang] (and not too serious)
* https://github.com/cafkafk/fortune-kind[fortune-kind in Rust-Lang] (under AGPL and with filtered data)

You may be able to get them to work with the data files of fortune-mod
and other fortune collections, but note that we have not closely
reviewed their source codes.

Thirdly, most of the value (and relative data size) of the tarball is in
the quotes collection.

Fourthly, a native executable might still provide a
https://tonsky.me/blog/disenchantment/[better user-experience]. However,
note that I have yet to perform a stresstest benchmark, and I doubt it will
matter too much for “fortune”'s common use case.

Finally, note that fortune’s runtime algorithm is not as straightforward as one
may believe, making use of “.dat” files that contain counts and offsets of
the fortune “cookies”.

=== Why did you convert the buildsystem to CMake?

See:

* https://github.com/shlomif/fortune-mod/pull/54
* https://twitter.com/shlomif/status/1330457762191511554

== What was already done.

. fortune-mod-1.99.1 was imported into the repository from the Mageia
tarball as the tag `fortune-mod-1.99.1`.
. Converted the build system to
https://en.wikipedia.org/wiki/CMake[CMake] .
. Converted the source files to UTF-8.
. Added some tests.
. Removed trailing whitespace.
. Reformatted long (> 80 chars) lines.
. Fixed some typos.
. Added https://travis-ci.org/[Travis-CI] testing.
. Added valgrind tests and fixed some memory leaks.
. Released fortune-mod-1.99.3, fortune-mod-1.99.4, v2.0.0 and up to
version 2.26.0 and beyond.
. Fixed some C compiler warnings encountered with the GCC compiler flags
of
https://github.com/shlomif/shlomif-cmake-modules[Shlomif_Common].
. Added a build-time option to remove the “-o” (= “offensive”) flag,
inspired by a set of patches on the Fedora package.
. Applied some downstream patches.
. Fixed as many “clang -Weverything” warnings as possible.
. lib-recode became maintained again at
https://github.com/rrthomas/recode (thanks to @rrthomas ) thus
preventing a switch to something else.
. Got the build and tests to pass on
https://ci.appveyor.com/project/shlomif/fortune-mod[AppVeyor/MS Windows]
(with some appreciated help).
. Found and fixed some security issues:
* Seem to have affected some Linux distributions as well as FreeBSD and
NetBSD.
** Was already fixed in OpenBSD
* https://bugs.mageia.org/show_bug.cgi?id=26567
* https://advisories.mageia.org/MGASA-2020-0199.html
* https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=246050
* https://github.com/shlomif/fortune-mod/commit/fe182a25663261be6e632a2824f6fd653d1d8f45
* https://github.com/shlomif/fortune-mod/commit/540c495f57e441b745038061a3cfa59e3a97bf33
* https://github.com/shlomif/fortune-mod/commit/acd338098071bddfa1d21f87e1813727031428ea
. Reformatted the C code using
https://clang.llvm.org/docs/ClangFormat.html[clang-format].
. Moved some cookies to/from the offensive collection.
. Added new cookies.

== What remains to be done.

. Fix more typos (issue reports and pull-requests are welcome.)
. Add more quotes / fortune cookies (issue reports and pull-requests are welcome.).
. Prepare packages for the new releases for
https://pkgs.org/download/fortune-mod[downstream distributions/Operating
Systems].

== Links

* https://www.shlomifish.org/humour/fortunes/[Shlomi Fish’s Fortune
Cookie Files] - on his site, containing links to many other collections
of fortune cookies.
* https://web-cpan.shlomifish.org/modules/XML-Grammar-Fortune/[XML-Grammar-Fortune]
- an XML grammar for collections of quotes, allowing one to generate
XHTML or plaintext.
* http://www.anvari.org/fortune/[Anvari.org’s web interface to “fortune”]
- with many collections.