granicus.if.org Git - fortune-mod/blob - README.asciidoc

   1 == fortune-mod Maintenance Version and Ongoing Development
   2
   3 [link=https://travis-ci.com/shlomif/fortune-mod]
   4 image::https://travis-ci.com/shlomif/fortune-mod.svg?branch=master[Travis-CI Build Status]
   5
   6 [link=https://ci.appveyor.com/project/shlomif/fortune-mod/branch/master]
   7 image::https://ci.appveyor.com/api/projects/status/0pbvqd1xa7777aoo/branch/master?svg=true[AppVeyor Build status]
   8
   9 This GitHub repository maintains the sources for fortune-mod, a version
  10 of https://en.wikipedia.org/wiki/Fortune_%28Unix%29[the UNIX fortune
  11 command]. `fortune` is a command-line utility which displays a random
  12 quotation from a collection of quotes. This collection is read from the
  13 local https://en.wikipedia.org/wiki/File_system[file system] and does
  14 not require network access. A large collection of quotes is provided in
  15 the download and installed by default, but more quote collections can be
  16 added by the user.
  17
  18 The canonical repository for the time being is:
  19 https://github.com/shlomif/fortune-mod . In the future, we may create a
  20 GitHub organization for it and move the sources there.
  21
  22 For more information about it, you can contact
  23 https://www.shlomifish.org/[Shlomi Fish] .
  24
  25 === Installation
  26
  27 On Fedora and other rpm-based distributions:
  28
  29 ....
  30 sudo dnf install fortune-mod
  31 ....
  32
  33 ( RHEL and CentOS users may opt to try https://github.com/shlomif/fortune-mod/issues/47#issuecomment-917565752[the EPEL packages]. )
  34
  35 On Arch Linux and derivatives:
  36
  37 ....
  38 sudo pacman -S fortune-mod
  39 ....
  40
  41 On Debian, and derivatives (e.g: Ubuntu, Linux Mint):
  42
  43 ....
  44 sudo apt install fortune-mod
  45 ....
  46
  47 (Warning: may be an old version.)
  48
  49 === Release Tarballs
  50
  51 Release tarballs can be found at
  52 https://www.shlomifish.org/open-source/projects/fortune-mod/arcs/[this
  53 directory] for now.
  54
  55 Based on https://github.com/shlomif/fortune-mod/issues/10[this reported
  56 bug]:
  57
  58 One can find the official release tarballs of fortune-mod as prepared by
  59 CPack there. They have a proper containing directory. One can also
  60 download these tarballs from the
  61 https://github.com/shlomif/fortune-mod/releases[GitHub releases page]
  62 but please do not use the auto generated “Source code (zip)” and “Source
  63 code (tar.gz)” downloads which are both incomplete and have extra
  64 directories inside.
  65
  66 === Sample usage
  67
  68 ....
  69 $ fortune
  70 Enthusiasm is one of the most important
  71 ingredients a volunteer project runs on.
  72                 -- Andreas Schuldei
  73 $
  74 ....
  75
  76 === History
  77
  78 I believe fortune-mod was originally forked from the NetBSD version of
  79 fortune, and ported to run on Linux systems. For some time it was
  80 maintained at the currently offline redellipse-dot-net inside a
  81 http://en.wikipedia.org/wiki/GNU_arch[GNU Arch] (= an old and now mostly
  82 unused version control system) repository, and version 1.99.1 was
  83 released as a tarball.
  84
  85 This maintenance version was initiated by Shlomi Fish, who decided to
  86 maintain it out of being a fan of the fortune command. It started by
  87 importing the unpacked source of the fortune-mod-1.99.1.tar tarball from
  88 the Mageia Linux .src.rpm into an empty git repository and continuing
  89 from there.
  90
  91 === What is the difference between fortune-mod and the "normal" fortune?
  92
  93 fortune-mod (= "fortune modified") was the name of a fork of the
  94 original NetBSD fortune, which was done in order to port the code to
  95 Linux and apply some other changes. If you are using a Linux
  96 distribution chances are that the `fortune` executable's package *is*
  97 fortune-mod (although in the case of Debian-and-derivatives it is likely
  98 very out-of-date as of September 2020).
  99
 100 === Why is it written in C? Can't it be written in Perl, awk, Python, etc.?
 101
 102 The answer has several parts:
 103
 104 First of all note that according to
 105 https://en.wikipedia.org/wiki/Fortune_%28Unix%29[the wikipedia page] the
 106 original fortune was created in 1979, before the first version of perl
 107 was released in 1987, or python, ruby or Lua which were released later,
 108 and when UNIX-running computers were more underpowered than they are
 109 today.
 110
 111 Secondly, you can find some reimplementations of fortune here:
 112
 113 * https://metacpan.org/pod/distribution/PerlPowerTools/bin/fortune[perl]
 114 * https://github.com/bmc/fortune[python]
 115
 116 You may be able to get them to work with the data files of fortune-mod
 117 and other fortune collections, but note that we have not closely
 118 reviewed their source codes.
 119
 120 Thirdly, most of the value (and relative data size) of the tarball is in
 121 the quotes collection.
 122
 123 Fourthly, a native executable may still give a
 124 https://tonsky.me/blog/disenchantment/[better user experience] (I have
 125 yet to perform a stresstest benchmark though, and I doubt it will matter
 126 too much for fortune's common use case.)
 127
 128 Finally note that the runtime algorithm is not as straightforward as one
 129 may believe, making use of dat files that contain counts and offsets of
 130 the fortune "cookies".
 131
 132 === Why did you convert the buildsystem to CMake?
 133
 134 See:
 135
 136 * https://github.com/shlomif/fortune-mod/pull/54
 137 * https://twitter.com/shlomif/status/1330457762191511554
 138
 139 == What was already done.
 140
 141 . fortune-mod-1.99.1 was imported into the repository from the Mageia
 142 tarball as the tag `fortune-mod-1.99.1`.
 143 . Converted the build system to
 144 https://en.wikipedia.org/wiki/CMake[CMake] .
 145 . Converted the source files to UTF-8.
 146 . Added some tests.
 147 . Removed trailing whitespace.
 148 . Reformatted long (> 80 chars) lines.
 149 . Fixed some typos.
 150 . Added https://travis-ci.org/[Travis-CI] testing.
 151 . Added valgrind tests and fixed some memory leaks.
 152 . Released fortune-mod-1.99.3, fortune-mod-1.99.4, v2.0.0 and up to
 153 version 2.26.0
 154 . Fixed some C compiler warnings encountered with the GCC compiler flags
 155 of
 156 https://bitbucket.org/shlomif/shlomif-cmake-modules/overview[Shlomif_Common].
 157 . Added a build-time option to remove the “-o” (= “offensive”) flag,
 158 inspired by a set of patches on the Fedora package.
 159 . Applied some downstream patches.
 160 . Fixed as many “clang -Weverything” warnings as possible.
 161 . lib-recode became maintained again at
 162 https://github.com/rrthomas/recode (thanks to @rrthomas ) thus
 163 preventing a switch to something else.
 164 . Got the build and tests to pass on
 165 https://ci.appveyor.com/project/shlomif/fortune-mod[AppVeyor/MS Windows]
 166 (with some appreciated help).
 167 . Found and fixed some security issues:
 168 * Seem to have affected some Linux distributions as well as FreeBSD and
 169 NetBSD.
 170 ** Was already fixed in OpenBSD
 171 * https://bugs.mageia.org/show_bug.cgi?id=26567
 172 * https://advisories.mageia.org/MGASA-2020-0199.html
 173 * https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=246050
 174 * https://github.com/shlomif/fortune-mod/commit/fe182a25663261be6e632a2824f6fd653d1d8f45
 175 * https://github.com/shlomif/fortune-mod/commit/540c495f57e441b745038061a3cfa59e3a97bf33
 176 * https://github.com/shlomif/fortune-mod/commit/acd338098071bddfa1d21f87e1813727031428ea
 177 . Reformatted the C code using
 178 https://clang.llvm.org/docs/ClangFormat.html[clang-format].
 179
 180 == What remains to be done.
 181
 182 . Fix more typos (issue reports and pull-requests are welcome.)
 183 . Add more quotes / fortune cookies (issue reports and pull-requests are welcome.).
 184 . Prepare packages for the new releases for
 185 https://pkgs.org/download/fortune-mod[downstream distributions/Operating
 186 Systems].
 187
 188 == Links
 189
 190 * https://www.shlomifish.org/humour/fortunes/[Shlomi Fish’s Fortune
 191 Cookie Files] - on his site, containing links to many other collections
 192 of fortune cookies.
 193 * https://web-cpan.shlomifish.org/modules/XML-Grammar-Fortune/[XML-Grammar-Fortune]
 194 - an XML grammar for collections of quotes, allowing one to generate
 195 XHTML or plaintext.
 196 * http://www.anvari.org/fortune/[Anvari.org’s web interface to fortune]
 197 - with many collections.