mirror of
https://github.com/erkin/ponysay
synced 2024-11-27 22:00:29 +00:00
3757 lines
137 KiB
Text
3757 lines
137 KiB
Text
\input texinfo @c -*-texinfo-*-
|
||
|
||
@c %**start of header
|
||
@setfilename ponysay.info
|
||
@settitle Ponysay
|
||
@afourpaper
|
||
@documentencoding UTF-8
|
||
@documentlanguage en
|
||
@finalout
|
||
@c %**end of header
|
||
@set VERSION 3.0.2
|
||
|
||
@defindex op
|
||
@synindex op vr
|
||
@synindex cp pg
|
||
|
||
@dircategory Miscellaneous
|
||
@direntry
|
||
* ponysay: (ponysay). Ponies for your terminal
|
||
@end direntry
|
||
|
||
@copying
|
||
This manual is for ponysay
|
||
(version @value{VERSION}).
|
||
|
||
Copyright @copyright{} 2012, 2013 Mattias Andrée
|
||
|
||
@quotation
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
any later version published by the Free Software Foundation; with no
|
||
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
||
Texts. A copy of the license is included in the section entitled
|
||
``GNU Free Documentation License''.
|
||
@end quotation
|
||
@end copying
|
||
|
||
@ifnottex
|
||
@node Top
|
||
@top Ponysay: ponies for your terminal
|
||
@insertcopying
|
||
@end ifnottex
|
||
|
||
@titlepage
|
||
@title Ponysay
|
||
@c@subtitle Cowsay reimplementation for ponies.
|
||
@c@subtitle Ponies for your terminal.
|
||
@c@subtitle Infesting your terminal with ponies.
|
||
@c@subtitle Surviving the zombiepony takeover.
|
||
@subtitle Making your terminal about 20 % cooler.
|
||
@subtitle Covers ponysay version @value{VERSION}.
|
||
@c ** start of front page image **
|
||
@c If print make a pdf or hard copy with the front cover
|
||
@c you may or may not want to remove this.
|
||
@c @image{infoimage,423.5px}
|
||
@c ** end of front page image **
|
||
@author by Mattias Andrée (maandree)
|
||
|
||
@page
|
||
@vskip 0pt plus 1filll
|
||
@insertcopying
|
||
@page
|
||
@*@*
|
||
@center `For me! For my friends! @b{For EQUESTRIA!}'
|
||
@end titlepage
|
||
|
||
@contents
|
||
|
||
|
||
@menu
|
||
* Overview:: Brief overview of @command{ponysay}.
|
||
* Invoking ponysay:: How to run @command{ponysay}.
|
||
* Advanced usage:: Advanced usage of @command{ponysay}.
|
||
* Environment variables:: Getting more from @command{ponysay} with environment variables.
|
||
* Optional features:: Get the most out of @command{ponysay} with optional features.
|
||
* Pony metadata:: Metadata tags in the pony files.
|
||
* The tool chest:: Extra Ponysay commands for other stuff than printing ponies.
|
||
* Limitations:: Known limitations that may not be that easy to overcome.
|
||
* Problems and requests:: External bugs, report issues and making requests.
|
||
* Dependencies:: Ponysay's dependencies.
|
||
* Installing:: How to install @command{ponysay}.
|
||
* Inner workings:: Useful information for those whom want to help hack @command{ponysay}.
|
||
* Contributing:: Useful information for those whom want to help improve the world.
|
||
* Distributing:: Useful information for OS package repository package maintainers.
|
||
* Terminology:: Terminology.
|
||
* Change log:: Differences between the version of @command{ponysay}.
|
||
* Ponysay contributors:: Ponysay contributors.
|
||
* Ponysay license:: Copying and sharing ponysay.
|
||
* GNU General Public License:: Ponysay's license.
|
||
* GNU Free Documentation License:: Copying and sharing this manual.
|
||
* Concept and program index:: Concept and program index.
|
||
* Variable and option index:: Variable and option index.
|
||
@end menu
|
||
|
||
|
||
|
||
|
||
@node Overview
|
||
@chapter Overview
|
||
@cindex overview
|
||
|
||
@command{ponysay} displays an image of a My Little Pony pony saying a message provided
|
||
by the user in a terminal, or a quote from the show My Little Pony: Friendship is Magic
|
||
(MLP:FiM). Historically @command{ponysay} was a wrapper for cowsay, but has since
|
||
version 2.1 become an independent reimplementation of @command{cowsay}.
|
||
|
||
If a message is not provided, e.g. by piping, it accepts standard input. The pony
|
||
quoting the given message is printed on standard output.
|
||
|
||
@command{ponythink} is to @command{ponysay} as @command{cowthink} is to
|
||
@command{cowsay}.
|
||
|
||
@command{ponysay} is generally used to decorate your terminal with a random pony, when
|
||
you start the terminal. But if you know anypony how does like ponies [fat chance] you
|
||
can always make screen-shots of @command{ponysay --q} executions and communication that
|
||
way over e-mail.
|
||
|
||
|
||
|
||
|
||
@node Invoking ponysay
|
||
@chapter Invoking @command{ponysay}
|
||
@cindex invoking
|
||
@cindex options
|
||
@cindex arguments
|
||
@pindex @command{ponythink}
|
||
|
||
The format for running the @command{ponysay} program is:
|
||
|
||
@example
|
||
ponysay [@var{option}...] [--] [@var{message}]
|
||
ponythink [@var{option}...] [--] [@var{message}]
|
||
@end example
|
||
|
||
Running @command{ponysay} will print a speech balloon, @command{ponythink} will
|
||
print a thought balloon. Otherwise @command{ponysay} and @command{ponythink} is
|
||
the same thing.
|
||
|
||
@command{ponysay} supports the following options:
|
||
|
||
@table @option
|
||
|
||
@item --
|
||
@opindex @option{--}
|
||
Parse the following arguments as parts of @code{@var{message}}.
|
||
|
||
@item -h
|
||
@itemx --help
|
||
@opindex @option{-h}
|
||
@opindex @option{--help}
|
||
Show summary of options.
|
||
|
||
@item -v
|
||
@itemx --verion
|
||
@opindex @option{-v}
|
||
@opindex @option{--version}
|
||
Show version of program.
|
||
|
||
@item -f PONY
|
||
@itemx --file PONY
|
||
@itemx --pony PONY
|
||
@opindex @option{-f}
|
||
@opindex @option{--file}
|
||
@opindex @option{--pony}
|
||
Specify the pony that should printed, this can either be a file name or a pony
|
||
name printed by @command{ponysay -l}. This option can be used multiple times to
|
||
specify a set of ponies from which one will be selected randomly. If no pony is
|
||
specified one will be selected randomly.
|
||
|
||
@cindex @command{util-say}
|
||
@cindex .png
|
||
@cindex PNG images
|
||
@cindex images, PNG
|
||
@cindex Portable Network Graphics
|
||
If you have @command{util-say} installed, you can use .png-files as the arguments
|
||
for this options.
|
||
|
||
In versions earlier than version 2.0, the if the pony were a file name it had to
|
||
include a `@code{/}'. This is not longer required and any existing pony name
|
||
supersedes file names.
|
||
|
||
@item +f PONY
|
||
@itemx ++file PONY
|
||
@itemx ++pony PONY
|
||
@opindex @option{+f}
|
||
@opindex @option{++file}
|
||
@opindex @option{++pony}
|
||
Just as @option{+f}, but it uses extra (non-MLP:FiM) ponies instead of standard
|
||
(MLP:FiM) ponies
|
||
|
||
@item -F PONY
|
||
@itemx --any-file PONY
|
||
@itemx --anyfile PONY
|
||
@itemx --any-pony PONY
|
||
@itemx --anypony PONY
|
||
@opindex @option{-F}
|
||
@opindex @option{--any-file}
|
||
@opindex @option{--anyfile}
|
||
@opindex @option{--any-pony}
|
||
@opindex @option{--anypony}
|
||
This option combines @option{-f} and @option{+f}.
|
||
|
||
@item -q PONY
|
||
@itemx --quote PONY
|
||
@opindex @option{-q}
|
||
@opindex @option{--quote}
|
||
@cindex quotes
|
||
@cindex pony quotes
|
||
By using this option, a pony will be printed with quotes from her in My Little Pony:
|
||
Friendship is Magic. The pony will be selected randomly, unless at least one pony
|
||
is added as an argument to @option{-q}. If one or more ponies are added as an argument
|
||
to @option{-q}, the pony will be selected randomly from that set of ponies.
|
||
This option requires the extension @command{ponyquotes4ponysay}, which is included
|
||
by default since version 1.2.
|
||
|
||
The argument can be a file name, but only if it ends with @file{.pony}.
|
||
|
||
@item --f [PONY...]
|
||
@itemx --files [PONY...]
|
||
@itemx --ponies [PONY...]
|
||
@opindex @option{--f}
|
||
@opindex @option{--files}
|
||
@opindex @option{--ponies}
|
||
Variadic variant of @option{-f}, meaning that all arguments added after this one
|
||
will parsed as an argument to this option. Additionally, those options are added
|
||
to @option{-f}.
|
||
|
||
@item ++f [PONY...]
|
||
@itemx ++files [PONY...]
|
||
@itemx ++ponies [PONY...]
|
||
@opindex @option{++f}
|
||
@opindex @option{++files}
|
||
@opindex @option{++ponies}
|
||
Variadic variant of @option{+f}, meaning that all arguments added after this one
|
||
will parsed as an argument to this option. Additionally, those options are added
|
||
to @option{+f}.
|
||
|
||
An important feature of this options, is that you can but it in the end of the
|
||
command line, without any argument to get a random non-MLP:FiM pony. However,
|
||
altough it is not nice, since version 3.0, @option{+f} can also be unargumented
|
||
if at the end of the command line.
|
||
|
||
@item --F [PONY...]
|
||
@itemx --any-files [PONY...]
|
||
@itemx --anyfiles [PONY...]
|
||
@itemx --any-ponies [PONY...]
|
||
@itemx --anyponies [PONY...]
|
||
@opindex @option{--F}
|
||
@opindex @option{--any-file}
|
||
@opindex @option{--anyfile}
|
||
@opindex @option{--any-pony}
|
||
@opindex @option{--anypony}
|
||
This option combines @option{--f} and @option{++f}.
|
||
|
||
@item --q [PONY...]
|
||
@itemx --quotes [PONY...]
|
||
@opindex @option{--q}
|
||
@opindex @option{--quotes}
|
||
@cindex quotes
|
||
@cindex pony quotes
|
||
Variadic variant of @option{-q}, meaning that all arguments added after this one
|
||
will parsed as an argument to this option. Additionally, those options are added
|
||
to @option{-q}.
|
||
|
||
An important feature of this options, is that you can but it in the end of the
|
||
command line, without any argument to get a quote from any pony with a quote.
|
||
However, altough it is not nice, since version 3.0, @option{-q} can also be
|
||
unargumented if at the end of the command line.
|
||
|
||
@item -b STYLE
|
||
@itemx --bubble STYLE
|
||
@itemx --balloon STYLE
|
||
@opindex @option{-b}
|
||
@opindex @option{--bubble}
|
||
@opindex @option{--balloon}
|
||
Specify the balloon style that should used, this can either be a file name or a
|
||
balloon name printed by @option{ponysay -B}. This option can be used multiple
|
||
times to specify a set of styles from which one will be selected randomly. If no
|
||
balloon style is specified a fallback style will be used.
|
||
|
||
@item -W COLUMN
|
||
@itemx --wrap COLUMN
|
||
@opindex @option{-W}
|
||
@opindex @option{--wrap}
|
||
Specify the screen column where the message should be wrapped, this is by default 60,
|
||
as with @command{cowsay}. The balloon's extra width is taken into consideration.
|
||
|
||
If the argument is not a number, but starts instead with @code{n} (for ‘none’ or
|
||
‘no’), no wrapping is done, and if it starts with @code{i} (for ‘inherit’) the width
|
||
of the terminal is used.
|
||
|
||
@code{n} and @code{i} is case insensitive, so you may use @code{N} and @code{I}
|
||
instead. Additionally, typo correction is for QWERTY (and QWERTZ) and Dvorak is
|
||
built in to @command{ponysay}; the nearest key, either to the left or to the
|
||
right, depending on which hand is used to press the key, is also allowed.
|
||
|
||
@item -c
|
||
@itemx --compress
|
||
@itemx --compact
|
||
@opindex @option{-c}
|
||
@opindex @option{--compress}
|
||
@opindex @option{--compact}
|
||
@pindex @command{figlet}
|
||
@pindex @command{TOIlet}
|
||
Compress the message in the same way @command{cowsay} does, that is basically
|
||
without multiple spaces, and only paragraphs separations. Using this options
|
||
will mean that you cannot display @command{figlet} and @command{TOIlet} style
|
||
messages.
|
||
|
||
@item -l
|
||
@itemx --list
|
||
@opindex @option{-l}
|
||
@opindex @option{--list}
|
||
Lists all installed ponies. The ponies which have quotes, i.e. can be used with
|
||
the @option{-q} option, will be marked by being printed in bold or bright (depending
|
||
on the terminal.)
|
||
|
||
@item -L
|
||
@itemx --altlist
|
||
@itemx --symlist
|
||
@opindex @option{-L}
|
||
@opindex @option{--symlist}
|
||
@opindex @option{--altlist}
|
||
Lists all installed ponies. The ponies which have quotes, i.e. can be used with
|
||
the @option{-q} option, will be marked by being printed in bold or bright (depending
|
||
on the terminal.) This options differs from @option{-l} by printing alternative
|
||
names (symbolic links) inside brackets after their target ponies.
|
||
|
||
@item +l
|
||
@itemx ++list
|
||
@opindex @option{+l}
|
||
@opindex @option{++list}
|
||
Just as @option{-l}, except it lists extra (non-MLP:FiM) ponies instead of standard
|
||
(MLP:FiM) ponies.
|
||
|
||
@item +L
|
||
@itemx ++symlist
|
||
@itemx ++altlist
|
||
@opindex @option{+L}
|
||
@opindex @option{++symlist}
|
||
@opindex @option{++altlist}
|
||
Just as @option{-L}, except it lists extra (non-MLP:FiM) ponies instead of standard
|
||
(MLP:FiM) ponies.
|
||
|
||
@item -B
|
||
@itemx --bubblelist
|
||
@itemx --balloonlist
|
||
@opindex @option{-B}
|
||
@opindex @option{--bubblelist}
|
||
@opindex @option{--balloonlist}
|
||
Prints a list of all balloon styles.
|
||
|
||
@item -A
|
||
@itemx --all
|
||
@opindex @option{-A}
|
||
@opindex @option{--all}
|
||
List all ponies, MLP:FiM and non-MLP:FiM, in this case the first list are MLP:FiM
|
||
and the second are non-MLP:FiM.
|
||
|
||
@item +A
|
||
@itemx ++all
|
||
@itemx --symall
|
||
@itemx --altall
|
||
@opindex @option{+A}
|
||
@opindex @option{++all}
|
||
@opindex @option{--symall}
|
||
@opindex @option{--altall}
|
||
List all ponies names, including alternatives, these from MLP:FiM and non-MLP:FiM.
|
||
The first list are the MLP:FiM and the second one are non-MLP:FiM.
|
||
|
||
@item -o
|
||
@itemx --pony-only
|
||
@itemx --ponyonly
|
||
@opindex @option{-o}
|
||
@opindex @option{--pony-only}
|
||
@opindex @option{--ponyonly}
|
||
Print just the pony, nothing else like the speech balloon. Naturally the
|
||
@command{ponysay} will not wait for a message from stdin.
|
||
|
||
@item -i
|
||
@itemx --info
|
||
@opindex @option{-i}
|
||
@opindex @option{--info}
|
||
By adding this flag you will get a metadata for a pony printed, rather than the pony
|
||
itself. The output will beformated with bold tag names. The output will be wrapped
|
||
according to the @option{-W} option.
|
||
|
||
@item +i
|
||
@itemx ++info
|
||
@opindex @option{+i}
|
||
@opindex @option{++info}
|
||
This works just like the @option{-i} option, except the pony will use the output
|
||
has her message rather that just print that information.
|
||
|
||
@item -r RESTRICTION
|
||
@itemx --restrict RESTRICTION
|
||
@opindex @option{-r}
|
||
@opindex @option{--restrict}
|
||
This option is used to restrict which ponies can be randomly select based one their
|
||
metadata. The restrict is given is disjunctive normal form, and can hence express any
|
||
logical combination, however only for tags with one entry. For tags with multiple
|
||
values all values are tested and of one of them passes a test passes.
|
||
|
||
The argument for @option{--restrict} is a @code{+} separated list of values that all
|
||
must be satisfied for a pony to be qualified for random selection. The option
|
||
@option{--restrict} can be used multiply times, only one of them need to be satisfied
|
||
for a pony to qualified for random selection.
|
||
|
||
A value in the argument is a combination of the tag name and tag value on the form
|
||
@code{NAME=VALUE}. Additionally if the tag names ends with a question mark (@code{?})
|
||
the tag is satsified if the tag is missing; if the value starts with a bang (@code{!})
|
||
the test is inverted. Using just a bang means that the test passes for and only for
|
||
all ponies with the tag definied; using the question mark and a empty value means
|
||
that the test passes for all ponies; finally, using the question mark and just a bang
|
||
for the value means that the test passes for and only for all ponies without the tag
|
||
definied.
|
||
|
||
For most shells, if not all, trick to not need to use disjunctive normal form is to
|
||
use @code{@{ @}}. For example if you use
|
||
@option{--restrict=@{eye=@{blue,green,cyan@}+coat=@{black,grey@},coat=white@}}
|
||
(note that there is no whitespaces) means that only ponies with white coat will be
|
||
randomly selected as will as ponies with black or grey coat provided that they
|
||
have either blue, green or cyan eyes.
|
||
|
||
@item -X
|
||
@itemx --256-colours
|
||
@itemx --256colours
|
||
@itemx --x-colours
|
||
@opindex @option{-X}
|
||
@opindex @option{--256-colours}
|
||
@opindex @option{--256colours}
|
||
@opindex @option{--x-colours}
|
||
Use @command{xterm}'s 256-colour support (supported by most X11 terminals), despite
|
||
your terminal's actual compatibilies.
|
||
|
||
@item -V
|
||
@itemx --tty-colours
|
||
@itemx --ttycolours
|
||
@itemx --vt-colours
|
||
@opindex @option{-V}
|
||
@opindex @option{--tty-colours}
|
||
@opindex @option{--ttycolours}
|
||
@opindex @option{--vt-colours}
|
||
Use Linux VT's compatbilies without KMS utilisation, despite your terminal's actual
|
||
compatibilies.
|
||
|
||
@item -K
|
||
@itemx --kms-colours
|
||
@itemx --kmscolours
|
||
@opindex @option{-K}
|
||
@opindex @option{--kms-colours}
|
||
@opindex @option{--kmscolours}
|
||
Use Linux VT's compatbilies with KMS utilisation, despite your terminal's actual
|
||
compatibilies.
|
||
|
||
@item +c
|
||
@itemx --colour ANSI-COLOUR
|
||
@opindex @option{+c}
|
||
@opindex @option{--colour}
|
||
Colour the balloon, including link and message (the parts that are not individually
|
||
specified.) The argument, should be a ANSI colour sequence without leading CSI and
|
||
without a tailing ‘m’, for example @code{1;31} will make it in red and bold (or bright
|
||
depending on the terminal.)
|
||
|
||
@item --colour-bubble
|
||
@itemx --colour-balloon ANSI-COLOUR
|
||
@opindex @option{--colour-bubble}
|
||
@opindex @option{--colour-balloon}
|
||
Just like @option{--colour}, but it only colours the balloon, without the message
|
||
or link.
|
||
|
||
@item --colour-link ANSI-COLOUR
|
||
@opindex @option{--colour-link}
|
||
Just like @option{--colour}, but it only colours the balloon link.
|
||
|
||
@item --colour-msg
|
||
@itemx --colour-message ANSI-COLOUR
|
||
@opindex @option{--colour-msg}
|
||
@opindex @option{--colour-message}
|
||
Just like @option{--colour}, but it only colours the message.
|
||
|
||
@item --colour-pony ANSI-COLOUR
|
||
@opindex @option{--colour-pony}
|
||
Just like @option{--colour}, but it colours the pony. This colouring has no
|
||
effect ony regular pony files, as it has its own colouring.
|
||
|
||
@item --colour-wrap
|
||
@itemx --colour-hyphen ANSI-COLOUR
|
||
@opindex @option{--colour-wrap}
|
||
@opindex @option{--colour-hyphen}
|
||
Just like @option{--colour}, but it colours hyphen added by the word wrapping.
|
||
By default this is red (@code{31}), if you want uncoloured use @code{0},
|
||
without @code{0} or @code{39}, the default @code{31} is presistent.
|
||
|
||
@end table
|
||
|
||
@opindex @var{message}
|
||
If neither @option{-q} is used nor any @var{message} is specified, @command{ponysay}
|
||
will read the message from stdin (standard input); however, if no arguments are used
|
||
and nothing is piped to stdin, a help message will be printed. If you want to use
|
||
@command{ponysay} without arguments and enter the message by hand, you can run
|
||
@code{cat | ponysay}.
|
||
|
||
@cindex @file{best.pony}
|
||
If no pony is selected, @command{ponysay} will look for a @file{best.pony} file,
|
||
this file should be a symbolic link to the pony you want as a default. If it is not
|
||
a symbolic link, @option{-q} cannot determine which quotes to use.
|
||
|
||
|
||
|
||
@node Advanced usage
|
||
@chapter Advanced usage of @command{ponysay}.
|
||
@cindex advanced usage
|
||
|
||
@menu
|
||
* Extra information:: Displaying extra information.
|
||
* Fortune cookies:: Displaying with fortune cookies.
|
||
* Ponification:: Ponify your fortune cookies.
|
||
* Running on TTY:: Running on TTY (Linux VT).
|
||
* Running on screen:: Running on @command{screen}.
|
||
* ~/.ponysayrc:: Using the @file{~/.ponysayrc} file.
|
||
* Narcissistic ponies:: Getting ponies to think of themself.
|
||
@end menu
|
||
|
||
|
||
|
||
@node Extra information
|
||
@section Extra information
|
||
@cindex file descriptor 3
|
||
@cindex extra information
|
||
@cindex verbose mode
|
||
@pindex @command{tee}
|
||
If file descriptor 3 is definied when @command{ponysay} is executed, extra information
|
||
is printed to it. The printed information includes the name of the pony file, the name
|
||
of the balloon style file, and if definied in the pony file, file meta data and comment.
|
||
|
||
In most shells, a file descriptor 3 can defined using @command{3> FILE}, and linked to
|
||
stderr using @command{3>&2}. For example, you can print the information to @file{~/info}
|
||
by running @command{ponysay I\'m just the cutest pony! 3> ~/info}.
|
||
|
||
The message is not stored this way, for that you can use @command{tee}. However, if you
|
||
use @option{-q} the quote file is printed to file descriptor 3.
|
||
|
||
|
||
@node Fortune cookies
|
||
@section Fortune cookies
|
||
@pindex @command{fortune}
|
||
@cindex startup
|
||
@cindex on startup
|
||
@cindex @file{.bashrc}
|
||
@cindex @file{~/.bashrc}
|
||
|
||
If you have @command{fortune} installed -- this program may be named
|
||
@command{fortune-mod} in your GNU/Linux distributions package repository -- you can
|
||
run @code{fortune | ponysay} to get a random pony reading a random fortune cookie.
|
||
|
||
By adding @code{fortune | ponysay} to the end [easiest way] of your
|
||
@file{~/.bashrc} -- or equivalent for your shell if you do not use GNU Bash
|
||
(standard shell for most distributions now a days) -- you will get the effect
|
||
described in the previous paragraph every time you open a terminal.
|
||
|
||
|
||
@node Ponification
|
||
@section Ponification
|
||
@cindex ponification
|
||
@cindex text ponification
|
||
@pindex @command{ponypipe}
|
||
|
||
You can ponify messages (i.e. replaces words search as `everyone' with `everypony') by
|
||
using @code{fortune | ponypipe} instead of using @command{fortune}. @command{ponypipe}
|
||
can be downloaded from @url{https://github.com/maandree/ponypipe}.
|
||
Alternatively you can use @command{pinkie} (or @command{pinkiepie}), which can be
|
||
downloaded from @url{https://github.com/maandree/pinkie-pie}, which is just
|
||
@code{fortune | ponypipe}. There is also a large @command{sed} script, similar to
|
||
@command{ponypipe}: @url{http://www.reddit.com/r/mylittlelinux/comments/srixi/using_ponysay_with_a_ponified_fortune_warning/}
|
||
However I think @command{ponypipe} as better at replacing words than the @command{sed}
|
||
script, but I haven't used the script so I wouldn't know for sure.
|
||
|
||
|
||
@node Running on TTY
|
||
@section Running on TTY
|
||
@cindex TTY
|
||
@pindex Linux VT
|
||
@cindex @file{.bashrc}
|
||
@cindex @file{~/.bashrc}
|
||
|
||
If you use TTY and have a custom colour palette, you should also add to your
|
||
@file{~/.bashrc}, before @code{fortune | ponysay}:
|
||
@cartouche
|
||
@example
|
||
[ "$TERM" = "linux" ] &&
|
||
function ponysay
|
||
@{ exec ponysay "$@@"
|
||
#RESET PALETTE HERE
|
||
@}
|
||
@end example
|
||
@end cartouche
|
||
|
||
You should read more about this in @ref{KMS ponies}.
|
||
|
||
|
||
@node Running on screen
|
||
@section Running on @command{screen}
|
||
@pindex @command{screen}
|
||
@cindex @file{.bashrc}
|
||
@cindex @file{~/.bashrc}
|
||
|
||
@command{screen} will adapt ANSI colour escape sequences to your terminal's
|
||
capabilities. This means that if your terminal reports itself as @code{xterm}
|
||
in @env{$TERM} ponies will lose their colours; they will only use the lower 16
|
||
colours instead of the top 240 colours. By default, almost all X terminals,
|
||
including @command{xterm} and @command{mate-terminal} reports themselves as
|
||
@code{xterm} in @env{$TERM}, and some reports their actual name in @env{$COLORTERM}.
|
||
So before opening @command{screen} you use set @env{$TERM} to @code{xterm-256color},
|
||
if you are using a terminal with support for @code{xterm}'s 256 colours; this
|
||
can be done by adding to your @file{~/.bashrc}:
|
||
@cartouche
|
||
@example
|
||
[ "$TERM" = "xterm" ] &&
|
||
function screen
|
||
@{ export TERM="xterm-256color"
|
||
exec screen "$@@"
|
||
@}
|
||
@end example
|
||
@end cartouche
|
||
|
||
|
||
@node ~/.ponysayrc
|
||
@section @file{~/.ponysayrc}
|
||
@cindex @file{~/.ponysayrc}
|
||
@cindex environment variables
|
||
|
||
If you have the file @file{~/.ponysayrc} (@file{.ponysayrc} in your home directory,
|
||
the home directory can be spoofed by changing the system environment @env{HOME},)
|
||
the first thing @command{ponysay} does is running that file. This can be used for
|
||
modifing environment variables (see @ref{Environment variables}). For your convience
|
||
this can be done by modifing the map @code{env}. The code in @file{~/.ponysayrc} must
|
||
be written in Python 3.
|
||
|
||
For example if you want to set the @env{PONYSAY_SHELL_LINES} to 5, but only 1 if you
|
||
are using Linux VT (TTY), your @file{~/.ponysayrc} may look like this:
|
||
@cartouche
|
||
@example
|
||
if env[TERM] == 'linux':
|
||
env[PONYSAY_SHELL_LINES] = 1
|
||
else:
|
||
env[PONYSAY_SHELL_LINES] = 5
|
||
@end example
|
||
@end cartouche
|
||
|
||
You can examine the source code of @command{ponysay} to figure out some nice hacking
|
||
you may want to do, everything in the source code can be used directly as long as it
|
||
is defined before @file{~/.ponysayrc} is interpreted.
|
||
|
||
@file{~/.ponysayrc} is a fallback for @file{~/.config/ponysay/ponysayrc}, which in
|
||
turn is a fallback for @file{$@{XDG_CONFIG_HOME@}/ponysay/ponysayrc}. If neither of
|
||
those exist, @file{/etc/ponysayrc} is used if that exists.
|
||
|
||
|
||
@node Narcissistic ponies
|
||
@section Narcissistic ponies
|
||
@cindex narcissistic ponies
|
||
|
||
The following will not work if you have line breaks in you file names, but if you do
|
||
have that, you may want to rethink that as it will usually cause problems for programs,
|
||
especially for shell scripts.
|
||
|
||
The command @command{__pony=$(ponysay -o 3>&1 1>/dev/null | grep ^pony\ file: |
|
||
sed -e s/^pony\ file:\ //g) && (ponysay -of "$__pony" | ponythink -Wn -f "$__pony")}
|
||
will give you a pony thinking of herself. The command works on GNU Bash, but may
|
||
not work on less POSIX compatible shells. It works by first getting a random pony and
|
||
use the extra information printed the file descriptor 3 (see @ref{Extra information}),
|
||
and fetchs the file name with help of @command{grep} and @command{sed}. The file
|
||
name is stored in a shell variable. It the pipes one an execute of ponysay into
|
||
another executing, using the stored file anme in both executions. This does not
|
||
work on FISH shell because os POSIX incompatibility.
|
||
|
||
Ponysay can use just about anything as a message because it quarantines the message's
|
||
ANSI escape sequences, including colour. And is Unicode aware (including combining
|
||
characters) and ANSI escape sequence aware.
|
||
|
||
Naturally this means that you can also make ponies think of eachother,
|
||
for example: @command{ponysay -f rarity -b round 'My little Spiky-wiky' |
|
||
ponythink -f spikefloat -b unicode -W n}
|
||
|
||
|
||
|
||
@node Environment variables
|
||
@chapter Environment variables
|
||
@cindex environment variables
|
||
@cindex truncation
|
||
|
||
@command{ponysay} supports the follow environment variables:
|
||
|
||
@table @env
|
||
@item PONYSAY_BOTTOM
|
||
@vindex @env{PONYSAY_BOTTOM}
|
||
@cindex TTY
|
||
@cindex Linux VT
|
||
Under TTY (Linux VT), if the output is larger the the screen's height, only
|
||
the beginning is printed, leaving two blank lines. If you want the bottom
|
||
to be printed rather the the beginning you can export @env{PONYSAY_BOTTOM}
|
||
with the value @code{yes}, @code{y} or @code{1}.
|
||
|
||
@item PONYSAY_SHELL_LINES
|
||
@vindex @env{PONYSAY_SHELL_LINES}
|
||
@cindex TTY
|
||
@cindex Linux VT
|
||
Under TTY (Linux VT), if the output is larger than the screen's height, two
|
||
lines are left blank. If you want more, or less, blank lines you can export
|
||
@env{PONYSAY_SHELL_LINES} with the value of how many blank lines you want.
|
||
Naturally this takes effect eve n if the output is not actually larger than
|
||
the screen.
|
||
|
||
@item PONYSAY_FULL_WIDTH
|
||
@vindex @env{PONYSAY_FULL_WIDTH}
|
||
You can export @env{PONYSAY_FULL_WIDTH} with the value @code{yes}, @code{y}
|
||
or @code{1}, if you do not want the output to be truncated on the width to
|
||
fit the terminal.
|
||
|
||
@item PONYSAY_TRUNCATE_HEIGHT
|
||
@vindex @env{PONYSAY_TRUNCATE_HEIGHT}
|
||
Export @env{PONYSAY_TRUNCATE_HEIGHT} with the value @code{yes}, @code{y}
|
||
or @code{1}, if you want to truncate the output on the height even if you
|
||
are not running @command{ponysay} under TTY.
|
||
|
||
@item PONYSAY_UCS_ME
|
||
@vindex @env{PONYSAY_UCS_ME}
|
||
@cindex UCS
|
||
@cindex Universal Character Set
|
||
@cindex Unicode
|
||
@cindex ASCII
|
||
Export @env{PONYSAY_UCS_ME} with the value @code{yes}, @code{y} or @code{1},
|
||
if you want [simulated] symlink to pony files using Universal Character Set
|
||
in their names. Otherwise pony files uses only ASCII. If you want to remove
|
||
the ASCII:ised names export @env{PONYSAY_UCS_ME} with the value @code{harder},
|
||
@code{h} or @code{2} instead.
|
||
|
||
If you have not enabled this, UCS names are not usable, suggested or listed.
|
||
If you use @code{yes} UCS names will be usable, suggested and listed. If you
|
||
use @code{harder} ASCII:ised names will not be suggested or listed, but they
|
||
will still be usable.
|
||
|
||
@item @env{PONYSAY_KMS_PALETTE}
|
||
@itemx @env{PONYSAY_KMS_PALETTE_CMD}
|
||
@vindex @env{PONYSAY_KMS_PALETTE}
|
||
@vindex @env{PONYSAY_KMS_PALETTE_CMD}
|
||
@cindex TTY
|
||
@pindex Linux VT
|
||
@cindex kmsponies
|
||
@cindex KMS
|
||
@cindex kernel mode setting
|
||
|
||
@env{PONYSAY_KMS_PALETTE} or @env{PONYSAY_KMS_PALETTE_CMD} is used to tell
|
||
ponysay how your TTY palette looks, this feature lets you get the best images
|
||
in TTY if you have Kernel Mode Setting (KMS) support.
|
||
|
||
See @ref{KMS ponies} for information on how to use this.
|
||
|
||
@item @env{PONYSAY_TYPO_LIMIT}
|
||
@vindex @env{PONYSAY_TYPO_LIMIT}
|
||
@cindex auto correction
|
||
@cindex typo correction
|
||
@cindex spello correction
|
||
|
||
ponysay is able to auto correct misspelled pony names and balloon style name.
|
||
Without consideration for transpositioning, the distance between two words are
|
||
measured in the number of edits needed to get from one word to the other, with
|
||
weighting on some character changes used to favour spellos over typos.
|
||
|
||
By default if the weighted distance is greater than 5 for the closest words,
|
||
auto correction ignored. This limit can be changed by exporting the limit to
|
||
@env{PONYSAY_TYPO_LIMIT}; setting the limit to zero will disable auto correction.
|
||
|
||
@item @env{PONYSAY_WRAP_HYPHEN}
|
||
@vindex @env{PONYSAY_WRAP_HYPHEN}
|
||
@cindex wrapping
|
||
|
||
You can export what ponysay should use instead of a hyphen when wrapping messages.
|
||
The hythen is red by default, if you want to change the colour or other formating,
|
||
should should do so using the option @option{--colour-hyphen} (@option{--colour-wrap}).
|
||
|
||
@item @env{PONYSAY_WRAP_LIMIT}
|
||
@vindex @env{PONYSAY_WRAP_LIMIT}
|
||
@cindex wrapping
|
||
|
||
Defines how long a word mush be to be hyphenated. This is used for to wrap words that
|
||
are long so the output gets as pretty as possible. This s not the only condition under
|
||
which a word can be hyphenated, it can also be hyphenated if the word cannot fit
|
||
otherwise. The default value is 8.
|
||
|
||
@item @env{PONYSAY_WRAP_EXCEED}
|
||
@vindex @env{PONYSAY_WRAP_EXCEED}
|
||
@cindex wrapping
|
||
|
||
Defines how much a word must exceed the wrapping point to be hyphenated. This setting
|
||
is used togather with @env{PONYSAY_WRAP_LIMIT}. The default value is 5.
|
||
@end table
|
||
|
||
|
||
|
||
@node Optional features
|
||
@chapter Optional features
|
||
@cindex features, optional
|
||
@cindex optional features
|
||
@cindex optional dependencies
|
||
|
||
@menu
|
||
* KMS ponies:: Improved TTY support under KMS support.
|
||
@end menu
|
||
|
||
|
||
@node KMS ponies
|
||
@section KMS ponies
|
||
@cindex kmsponies
|
||
@cindex TTY
|
||
@pindex Linux VT
|
||
@cindex KMS
|
||
@cindex kernel mode setting
|
||
@cindex environment variables
|
||
@vindex @env{PONYSAY_KMS_PALETTE}
|
||
@vindex @env{PONYSAY_KMS_PALETTE_CMD}
|
||
@cindex @file{.bashrc}
|
||
@cindex @file{~/.bashrc}
|
||
@cindex cache
|
||
@cindex @file{/var/cache/ponysay}
|
||
@cindex @file{~/.cache/ponysay}
|
||
|
||
KMS ponies is an optional feature that required that you have @command{util-say>=3}
|
||
(@command{util-say<2} for @command{ponysay<2.1} and @command{util-say<3} for
|
||
@command{ponysay<3}) installed. It lets TTY users that
|
||
have a custom TTY colour palette and KMS support get best TTY images that can be
|
||
display at the current state of the art. KMS is supported on most computers, but due
|
||
to lack of published specifications Nvidia drivers does not support KMS.
|
||
@command{util-say} can be downloaded at @url{https://github.com/maandree/util-say}.
|
||
|
||
To use this feature your @file{~/.bashrc} (or equivalent for your shell) must keep
|
||
track of your colour palette; it is not possible for a program to ask to terminal.
|
||
Either the shell should export a palette string to @env{$PONYSAY_KMS_PALETTE} or you
|
||
should export a command to can get the palette string to
|
||
@env{$PONYSAY_KMS_PALETTE_CMD}. The palette string should be the stream which sets
|
||
the colour palette to the terminal when @command{echo}:ed; preferably, to increase
|
||
speed and reduce cache usage, it should be consistent every time it is exported for
|
||
every colours palette. So you may want to keep it sorted, always be in either upper
|
||
case or lower case, and not contain an character that is not used to set the colour
|
||
palette.
|
||
|
||
Assuming you have a function in your @file{~/.bashrc}, to reset the colour palette
|
||
to what you set it to last time in the terminal, named @command{reset-palette},
|
||
your @file{~/.bashrc} should, for example, contain:
|
||
@cartouche
|
||
@example
|
||
[ "$TERM" = "linux" ] &&
|
||
function ponysay
|
||
@{ export PONYSAY_KMS_PALETTE="$(reset-palette)"
|
||
exec ponysay "$@@"
|
||
@}
|
||
@end example
|
||
@end cartouche
|
||
|
||
KMS ponies uses @file{/var/cache/ponysay/} or, if missing, @file{~/.cache/ponysay/}
|
||
for cache space.
|
||
|
||
You may also want to read @ref{Fill KMS cache}.
|
||
|
||
|
||
|
||
@node Pony metadata
|
||
@chapter Pony metadata
|
||
@cindex pony metadata
|
||
@cindex metadata
|
||
@cindex tags, metadata
|
||
@cindex comments, metadata
|
||
@cindex pony tags, metadata
|
||
@cindex pony comments, metadata
|
||
|
||
Pony files can contain metadata tags and a multiline comment.
|
||
The following are the standard tags (comma separated lists may
|
||
have whitespace surrounding the comma [@code{,}]):
|
||
|
||
@table @var
|
||
@item GROUP NAME
|
||
@vindex @var{GROUP NAME}
|
||
If a pony file contains multiple ponies, it @emph{should} have a @var{GROUP NAME}
|
||
tag. The tag is a comma seperated list of the recognised names of the ponies as a
|
||
groups, if the list is empty the tag value must be @code{(none)}. An officiallity
|
||
tag should be added to each name.
|
||
|
||
@item NAME
|
||
@vindex @var{NAME}
|
||
Every pony file should have this tag, one entry for each pony on the file.
|
||
The value of the tag @emph{must} be the pony's most common name as used on
|
||
the TV show (or other source). If the pony's name have not been mentioned
|
||
the value must be @code{(not mentioned)}.
|
||
|
||
@item OTHER NAMES
|
||
@vindex @var{OTHER NAMES}
|
||
If a pony in the pony file has other names then the one in @var{NAME} it @emph{should}
|
||
have this take for this pony. Any pony in the file (in case of multiple ponies) that
|
||
do not need this tag should use the value @code{(none)}.
|
||
|
||
The tag is a comma seperated list of alternative (to @var{NAME} names for the pony,
|
||
each name should have an officiallity tag.
|
||
|
||
@item APPEARANCE
|
||
@vindex @var{APPEARANCE}
|
||
This tag specifies in which episode the pony first appeared. It reasonable to specify
|
||
it even for ponies that appears in every episode.
|
||
|
||
For uniformity the format @code{S%sE%e %t[ %P]} is recommended; @code{[ ]} denotes
|
||
and optional part, optional in the sence that it does not apply the every episode,
|
||
but it @emph{should} be used if applyable. @code{%s} is the series (season) number
|
||
in two digits, @code{%e} is the episode number in two digits. @code{%t} is the
|
||
episode title and should use the standardised title format for the used format
|
||
however without surrounding quotes if the used language has that, in the unlike
|
||
event that @code{[} or @code{]} is present in the title it should be backslashed
|
||
(@code{\[}, @code{\]}). @code{%P} is the part in the format @code{[Part %p]}, where
|
||
@code{[ ]} @i{does not} denote and optional part but rather is verbatim, and
|
||
@code{%p} is the part number in one digit (well, if the part number is not 10 or higher).
|
||
|
||
The standard way to format titles in American English is the same as in British English,
|
||
however it is not fully standardised. Capitalisation of the first word, and all other words,
|
||
except for articles, prepositions, conjunctions, and forms of `to be' is recommended.
|
||
|
||
Be aware that MLP:FiM episodes use American spelling which include a rather uncommon
|
||
why to write for examples abbrevations (like for example Mr. instread of Mr), this may
|
||
however not be the case for non-MLP:FiM episodes. And if there are not series (season)
|
||
the series number defaults to 1, however other numbers and tags (which the part number
|
||
is) may be added if required.
|
||
|
||
@item KIND
|
||
@vindex @var{KIND}
|
||
This tag decribes what kind of pony a pony is, it is a comma seperated lower case list,
|
||
and it cannot be empty, by it can be (but shouldn't) skipped for every pony in the image.
|
||
|
||
Every fitting value should be used, however an alicorn (also known as alacorn, winged
|
||
unicorn, acorn, pegasus unicorn, unipeg, unisus, horned pegasus, wing-horn, allacorn,
|
||
cerapter pterippus, aquillacorn, pegasos aithiopikos alate unicorns, or pegacorn)
|
||
should have the values @code{alicorn} and@code{pony}, but neither @code{pegasus} nor
|
||
@code{unicorn} or another of the possible therms mentioned. Earth ponies should have
|
||
the value @code{pony} and @code{earth} (not @code{earth pony}.)
|
||
|
||
The standard values are (you may use other ones if fitting): @code{unicorn}, @code{pegasus},
|
||
@code{alicorn}, @code{earth}, @code{pony}, @code{changeling}, @code{crystal}, @code{seapony},
|
||
@code{animal} (applies to Spike) and @code{item} (applies to Tom and Pinkamina's imaginare friends.)
|
||
|
||
@item GROUP
|
||
@vindex @var{GROUP}
|
||
|
||
This tag decribes which groups a pony classifies under, it is a comma seperated lower case
|
||
list, and it cannot be empty, by it can be (but shouldn't) skipped for every pony in the
|
||
image.
|
||
|
||
The standard values are (you may use other ones if fitting):
|
||
@itemize @bullet
|
||
@item @code{mare}
|
||
Adult female pony
|
||
@item @code{stallion}
|
||
Adult male pony
|
||
@item @code{filly}
|
||
Female pony child
|
||
@item @code{colt}
|
||
Male pony child
|
||
@item @code{dragon}
|
||
Dragon (Spike and the other dragons)
|
||
@item @code{mane}
|
||
The mane characters (also known as main characters [unponified] or protagonists)
|
||
@item @code{wildlife}
|
||
Wildlife, for example timberwolfs
|
||
@item @code{pet}
|
||
A pony's pet, Spike does not count because Twilight does not play with him during
|
||
pony–pet play dates.
|
||
@item @code{royal}
|
||
Royal pony, either by birth, marriage, or conquer (i.e. the old school style).
|
||
Shining Armour is royal by marriage, but is biological family does become royal by this.
|
||
@item @code{villain}
|
||
Villains, normally minions to antagonists or recurring ponies. Applies to changelings.
|
||
@item @code{antagonist} (applies to: nightmare moon, gilda, discord, chrysalis)
|
||
Antagonists are also known as archvillians or archenemies.
|
||
Nightmare Moon, Discord and Chrysalis are such, but Gilda also counts as one.
|
||
@item @code{deuteragonist} (applies to: the cutiemark cruisers)
|
||
Deuteragonists are secondary characters, these are (as of series 2) only the Cutiemark
|
||
Cruisers. The requirement is that thay are somewhat regular characters with dedicated
|
||
episodes, but are not protagonists.
|
||
@item @code{tritagonist} (applies to: celestia, luna, cadance, shining armor, spike)
|
||
Important characters (excluding Derpy Hooves) that are neither protagonists,
|
||
deuteragonists nor antagonists.
|
||
@item @code{background}
|
||
Background characters are not characters that are neither protagonists, deuteragonist,
|
||
tritagonist, antagonist nor pets. They do not need to be strictly background characters,
|
||
for example Big Mac and Cheerilee classifies under this group, as they are not too
|
||
important to be considered tritagonists (as of series 2).
|
||
@item @code{voiced} (only used together with background)
|
||
Only @code{background} characters can be @code{voiced}. The additional requirement is
|
||
that they have said something (ponies comics can also be voiced).
|
||
@item @code{imaginary}
|
||
Imaginary ponies (or other animal).
|
||
@end itemize
|
||
|
||
@item BALLOON
|
||
@vindex @var{BALLOON}
|
||
For each balloon in the file (a pony file can have more than one balloon, but
|
||
that is not common) their should one tag entry. There are four values that
|
||
can be used: @code{top} (the common setup, the balloon is at the top of the image),
|
||
@code{bottom} (the balloon is at the bottom of the image), @code{right} (the balloon
|
||
is neither at the top or at the bottom of the image, but is placed to the right of
|
||
the pony) and @code{inside} (the balloon is somewhere as inside the image.)
|
||
|
||
@item LINK ON
|
||
@vindex @var{LINK ON}
|
||
Files with only one pony @emph{should not} use this tag. Specifies to which pony
|
||
the link is connected, it is a number, starting from 1.
|
||
|
||
If a file contains Fluttershy and Pinkie (in that order, i.e. Pinkie is to the
|
||
right of or below Fluttershy) and the link is connected to Pinkie, than the value
|
||
should be 2.
|
||
|
||
In the rare case that the file contains multiple links (and multi ponies), the
|
||
metadata should contains multiple entries of this tag, one entry for each link
|
||
sorted in the order of the linkes placement in the image, in the same way
|
||
ponies are ordered.
|
||
|
||
@item LINK
|
||
@vindex @var{LINK}
|
||
In the rare case that the file contains multiple links the metadata should contains
|
||
multiple entries of this tag, one entry for each link sorted in the order of the
|
||
linkes placement in the image, in the same way ponies are ordered.
|
||
|
||
The value for this tag must be either @code{regular} or @code{mirrored}. @code{regular}
|
||
applies to linkes with NNE–SSW (@code{\}) direction. @code{mirrored} applies to linkes
|
||
with NNW–SSE (@code{/}) direction, in version 2.9.1 only @file{rainbowdrag} uses this.
|
||
|
||
@item COAT
|
||
@vindex @var{COAT}
|
||
The name of the colour (as best estimated by you), in lowercase, that the pony's coat
|
||
have. If the creature is (for example) a dragon, the colour of the scales is used.
|
||
Common colour names are preferable. Only one colour should be named, but the name may
|
||
describe a colour combination.
|
||
|
||
@item MANE
|
||
@vindex @var{MANE}
|
||
The name of the colour (as best estimated by you), in lowercase, that the pony's mane
|
||
have. Common colour names are preferable. Only one colour should be named, but the name
|
||
may describe a colour combination.
|
||
|
||
@item EYE
|
||
@vindex @var{EYE}
|
||
The name of the colour (as best estimated by you), in lowercase, that the pony's eyes
|
||
have. Common colour names are preferable. Only one colour should be named, but the name
|
||
may describe a colour combination. If the eyes are closed in the picture, use
|
||
@code{close} in addition the the actual eye colour, separated by a comma.
|
||
|
||
@item AURA
|
||
@vindex @var{AURA}
|
||
The name of the colour (as best estimated by you), in lowercase, that the pony's magic
|
||
aura have. Common colour names are preferable. Only one colour should be named, but the
|
||
name may describe a colour combination.
|
||
|
||
The magic aura is the colourisation around items that are affected by magic.
|
||
|
||
If the pony file have multiple ponies, some with magicial abilities and some without,
|
||
the ponies without magicial abilies should use the value @code{(no magic)}. If the pony
|
||
has magicial abilies but without an aura, use the value @code{(invisible)}.
|
||
|
||
Only humans [here we must call ourself humnas rather than ponies, otherwise the sentance
|
||
does not make sense) can se the magic aura, describe the colour that we humans see, not
|
||
ponies and other creatures in the TV Show [proof, see S01E11 Winter Wrap Up and S02E25-26
|
||
A Canterlot Wedding].
|
||
|
||
@item DISPLAY
|
||
@vindex @var{DISPLAY}
|
||
This tag describes how a pony is places in the image. The standard values are: @code{full}
|
||
(full body), @code{head} (just the head), @code{down} (upside down), @code{left} (pony is
|
||
looking to our left), @code{right} (pony is looking to our right), @code{front} (pony is
|
||
looking at us). @code{front} can be combined with @code{left} and @code{right}, but
|
||
@code{left} and @code{right} nor @code{full} and @code{head} cannot be combined.
|
||
|
||
@item WIDTH
|
||
@vindex @var{WIDTH}
|
||
The width of the pony image measured in text columns.
|
||
|
||
@item HEIGHT
|
||
@vindex @var{HEIGHT}
|
||
The height of the pony image measured in text lines, this include the balloon
|
||
(occupies one line) even if it the first line with nothing else on that line.
|
||
|
||
@item BALLOON TOP
|
||
@vindex @var{BALLOON TOP}
|
||
The number of lines at the beginning of the pony image that should be skipped
|
||
if the balloon is not printed.
|
||
|
||
@item BALLOON BOTTOM
|
||
@vindex @var{BALLOON BOTTOM}
|
||
The number of lines at the end of the pony image that should be skipped if the
|
||
balloon is not printed.
|
||
|
||
@item POSE
|
||
@vindex @var{POSE}
|
||
@cindex master file
|
||
@cindex slave file
|
||
@cindex extras
|
||
One word (preferably) to distinguish the pony files from other pony files with the
|
||
same @var{MASTER}. It is preferable that this is written in bare infinitive.
|
||
Master files should try to specify this tag but are not required
|
||
to, however, non-master files (slave files) are required to specify this tag.
|
||
@b{This tag is important for the extras feature to function.}
|
||
|
||
@item BASED ON
|
||
@vindex @var{BASED ON}
|
||
Either the name of a pony that the pony is based. If the original pony is not
|
||
from MLP:FiM, the name a value that pony's MEDIA tag can used inside brackets,
|
||
for example @code{(Tumblr)}, after the original pony's name. If the pony is not
|
||
based on any pony the value @code{(original)} can be used. If the ponies is
|
||
based on multiple ponies, make a comma separated list.
|
||
|
||
@item MASTER
|
||
@vindex @var{MASTER}
|
||
@cindex ponyquotes
|
||
@cindex quotes
|
||
This tag refers to the pony file that is not named with extra attributes. For example,
|
||
all files where Shining Armor is the (sole) speaking pony the this tag should be
|
||
@code{shiningarmor}, except for in @file{shiningarmor.pony} where this tag may be omitted.
|
||
@b{This tag is important for the ponyquotes feature to function.}
|
||
|
||
@item SOURCE
|
||
@vindex @var{SOURCE}
|
||
This tag specifies from where the pony image (not the file itself) originates.
|
||
If the source is unknown the value should be @code{(unknown)}, if a GitHub user
|
||
draw it the the value should be that user inside square brackets (in case of
|
||
multiple artists, the tag is comma seperated list). Otherwise the source
|
||
should be specified in any reasonable manner.
|
||
|
||
In order the claim authorship (the GitHub user value) it image must have been
|
||
written from scratch (using templates is okay) or must be a major edit of another
|
||
image. Just converting (including fixing the colours) an image (for example from
|
||
the Internet or a screenshot) with or without removing the background is not enough.
|
||
|
||
@item MEDIA
|
||
@vindex @var{MEDIA}
|
||
This tag @emph{must not} be used for MLP:FiM ponies, but only for extraponies.
|
||
It specifies the media from where the pony (not the image) originates.
|
||
|
||
@item LICENSE
|
||
@vindex @var{LICENSE}
|
||
Which licence applies to the image? Full name and version should be used.
|
||
In case of multiple license there should be one entry for each license.
|
||
Omit this tag is the license is not known.
|
||
|
||
The are two special cases here where this is no license. In which case it
|
||
either uses regular copyright, in which case use the value @code{(regular)},
|
||
or everyone is the copyright holder (for example Public Domain), in which
|
||
case use the value @code{(public)}.
|
||
|
||
@item FREE
|
||
@vindex @var{FREE}
|
||
Is the image fully free? (For example Linux-libre is fully free, but not regular Linux.)
|
||
The value @emph{must} either be @code{yes} or @code{no}, or the tag must be omitted.
|
||
|
||
@b{This is the most important tag} as it helps us build a fully free version that can
|
||
be officially distributed on GNU endorsed GNU/Linux distributions (GNU/Linux-libre).
|
||
@end table
|
||
|
||
Duplicate tags should be ordered in the order of the pony they describe from top-left
|
||
to bottom-right in the image. It is important that if there are for example three ponies
|
||
the image then all used tags that depends on the number of ponies in the image is used
|
||
three times.
|
||
|
||
@cindex officiallity tag
|
||
`Officiallity tag' refers the an annotation added to a tag value's list element.
|
||
If the value is unofficial the string @code{(unofficial)} is appended (preferable with
|
||
leading whitespace) to the element. If it is official the appended string is of the
|
||
format @code{(official, %c)} (the brackets are verbatim), where @code{%c} is a
|
||
comment. For example Chrysalis' name has not been mentioned in the show, however it
|
||
is used in the manuscript, therefore a pony file with Chrysalis should have the
|
||
(partial) metadata:
|
||
|
||
@example
|
||
NAME: (not mentioned)
|
||
OTHER NAMES: Chrysalis (official, in manuscript)
|
||
@end example
|
||
|
||
|
||
|
||
@node The tool chest
|
||
@chapter The tool chest
|
||
@cindex the tool chest
|
||
@cindex tool chest
|
||
@cindex extra commands
|
||
@pindex @command{ponysay-tool}
|
||
|
||
The tool chest is a collection of subcommands under the command @command{ponysay-tool},
|
||
its purpose is to provide tools to ponysay relevant actions that is not printing ponies
|
||
(like the commands @command{ponysay} and @command{ponythink}).
|
||
|
||
@menu
|
||
* Fill KMS cache:: Pre-generate kmsponies to your cache.
|
||
* Metadata pasting:: Copy, remove, stash and apply stashed pony metadata.
|
||
* Editing metadata:: Editing the metadata in a pony file.
|
||
* Metadata collections:: Generate pony metadata collection files.
|
||
* Dimension files:: Generate pony dimension files.
|
||
* Pony browsing:: Browse ponies or find a pony based on metadata.
|
||
@end menu
|
||
|
||
|
||
@node Fill KMS cache
|
||
@section Fill KMS cache
|
||
@cindex fill KMS cache
|
||
@cindex KMS cache, fill
|
||
@cindex kmsponies
|
||
@cindex KMS
|
||
@cindex Linux VT
|
||
@cindex TTY
|
||
|
||
Before reading this section you may want to read the earlier section @ref{KMS ponies}.
|
||
|
||
@opindex @option{--kms}
|
||
Invoking the command @command{ponysay-tool --kms} (no additional options are available)
|
||
will pre-generate all kmsponies for your current TTY palette. This is useful if your
|
||
computer is not fast enough, for you, at converting a pony to a kmspony. As the kmsponies
|
||
may change between versions (noted in the change log if it happens) you may want to
|
||
run this commmend after installing a new version of @command{ponysay}. Ponies that are
|
||
already in the cache with the current KMS version will not be re-generated.
|
||
|
||
|
||
@node Metadata pasting
|
||
@section Metadata pasting
|
||
@cindex metadata pasting
|
||
@cindex pony metadata pasting
|
||
@cindex pasting metadata
|
||
@cindex pasting pony metadata
|
||
@cindex metadata yanking
|
||
@cindex pony metadata yanking
|
||
@cindex yanking metadata
|
||
@cindex yanking pony metadata
|
||
@cindex editing metadata
|
||
|
||
@command{ponysay-tool} allows you to copy, remove, stash and apply stashed pony metadata
|
||
(but not merging, that must be done by hand.) The following commands does not support
|
||
additional options.
|
||
|
||
@cindex erase metadata
|
||
@cindex remove metadata
|
||
@opindex @option{--edit-rm}
|
||
@command{ponysay-tool --edit-rm PONY-FILE} will remove all metadata from the file
|
||
@code{PONY-FILE}. To just remove some data you must use @command{ponysay-tool --edit PONY-FILE}
|
||
or do it by hand. Note that you always use pony file, not pony names.
|
||
|
||
@cindex copy metadata
|
||
@cindex store metadata
|
||
@cindex stash metadata
|
||
@opindex @option{--edit-stash}
|
||
@command{ponysay-tool --edit-stash PONY-FILE} will print all metadata from a file to stdout.
|
||
Cherry-picking cannot be done.
|
||
|
||
@cindex paste metadata
|
||
@cindex apply metadata
|
||
@cindex yank metadata
|
||
@opindex @option{--edit-apply}
|
||
@command{ponysay-tool --edit-apply PONY-FILE} replace all metadata in a file with the metadata
|
||
used provided in stdin.
|
||
|
||
@cindex copy metadata
|
||
To copy the metadata from one pony to another (and remove the old metadata) you will have to
|
||
pipe the stashing and the applying command:
|
||
@command{ponysay-tool --edit-stash SOURCE-PONY-FILE | ponysay-tool --edit-apply TARGET-PONY-FILE}
|
||
|
||
|
||
@node Editing metadata
|
||
@section Editing metadata
|
||
@cindex editing metadata
|
||
@cindex metadata, editing
|
||
|
||
@opindex @option{--edit}
|
||
@command{ponysay-tool} allows you to edit the metadata in a pony file by running
|
||
@command{ponysay-tool --edit PONY-FILE}, where @code{PONY-FILE} is the pony file to edit,
|
||
not the pony name. No additional options are available.
|
||
|
||
@command{ponysay-tool --edit PONY-FILE} is interative and opens an editor inspired by GNU Emacs.
|
||
The tool will give you the standard tags to fill and will automatically fill in @var{HEIGHT}
|
||
and @var{WIDTH} for you without allowing you to editing those two tags. Additionally the editor
|
||
will print the pony at the right side of the terminal with the name of the file you are editing.
|
||
|
||
The commands the editor use is a small subset of the standard commands in GNU Emacs.
|
||
Currently the commands are only coded for xterm (just about all terminals except Linux VT.)
|
||
@kbd{C-x} means @kbd{x} with @kbd{control} held down.
|
||
@kbd{M-x} means @kbd{x} with @kbd{alt} (@kbd{meta}) held down.
|
||
|
||
@table @kbd
|
||
@item C-space
|
||
@itemx C-@@
|
||
Set mark; only if mark is set and is at the same position
|
||
as the point (cursor) the mark is deactivated.
|
||
A mark creates a text select, it cannot span between lines.
|
||
|
||
@item C-k
|
||
Cut out the rest of the line and add it to the kill ring.
|
||
|
||
@item C-w
|
||
Cut out selected text and add it to the kill ring.
|
||
|
||
@item M-w
|
||
Add the selected text to the kill ring and unset the mark.
|
||
|
||
@item C-y
|
||
Paste (yank) text from the kill ring.
|
||
|
||
@item M-y
|
||
Cycle in the kill ring.
|
||
|
||
@item C-o
|
||
Insert a next line below the current line and go to it.
|
||
This is useful if you want to add another entry for a tag.
|
||
|
||
@item C-j
|
||
@itemx enter
|
||
Go to next line, create a new line if at last line.
|
||
|
||
@item C-n
|
||
@itemx down
|
||
Go to next line, do not create a new line if at last line.
|
||
|
||
@item C-p
|
||
@itemx up
|
||
Go to previous line.
|
||
|
||
@item C-f
|
||
@itemx right
|
||
Go to next column.
|
||
|
||
@item C-b
|
||
@itemx left
|
||
Go to previous column.
|
||
|
||
@item home
|
||
Go to the beginning of the line.
|
||
|
||
@item end
|
||
Go to the end of the line.
|
||
|
||
@item backspace
|
||
@itemx C-h
|
||
@itemx C-?
|
||
Remove the previous character on the same line.
|
||
|
||
@item delete
|
||
Remove the current character on the same line.
|
||
|
||
@item insert
|
||
Enter or exit override mode.
|
||
|
||
@item C-x C-x
|
||
Swap the mark and the point.
|
||
|
||
@item C-x C-s
|
||
Save your changes.
|
||
|
||
@item C-x C-c
|
||
Exit the editor, do not forget to save if you have made changes.
|
||
@end table
|
||
|
||
|
||
@node Metadata collections
|
||
@section Metadata collections
|
||
@cindex metadata collection files
|
||
@cindex pony metadata collections
|
||
@opindex @option{--metadata}
|
||
@opindex @option{--restrict}
|
||
@opindex @option{-r}
|
||
|
||
Pony metadata collection files are used by @command{ponysay} to by just reading
|
||
one file per directory determine all pony files metadata and determine which
|
||
ponies will pass the @option{--restrict} option when ponies are randomly selected.
|
||
|
||
A metadata colletion file's content a list, of pony files with and their corresponding
|
||
metadata as a map from tag name to tag value set, serialised with Python's cPickle module.
|
||
|
||
Running @command{ponysay-tool --metadata PONY-DIR} will generate the file @file{metadata}
|
||
with the serialised information. For use by the installer, the files to include can be
|
||
explicity declared appending their basename to the command.
|
||
|
||
|
||
@node Dimension files
|
||
@section Dimension files
|
||
@cindex dimension files
|
||
@cindex pony dimension files
|
||
@opindex @option{--dimensions}
|
||
|
||
Pony dimension files are used by @command{ponysay} to determine the size of all
|
||
ponies and use that information to determine which ponies fit the terminal
|
||
and may be randomly selected.
|
||
|
||
Running @command{ponysay-tool --dimensions PONY-DIR} will generate three files
|
||
@file{widths}, @file{heights} and @file{onlyheights} to the directory @file{PONY-DIR},
|
||
the contain optimised information about the widths, heigths and heights with printed
|
||
without the balloon, respectively, for each pony the the directory. For use by the
|
||
installer, the files to include can be explicity declared appending their basename to
|
||
the command.
|
||
|
||
|
||
@node Pony browsing
|
||
@section Pony browsing
|
||
@cindex pony browsing
|
||
@cindex browse ponies
|
||
@opindex @option{-b}
|
||
@opindex @option{--browse}
|
||
@opindex @option{-r}
|
||
@opindex @option{--restrict}
|
||
|
||
Running @command{ponysay-tool --browse PONY-DIR}, or @command{ponysay-tool -b PONY-DIR}
|
||
will display all ponies in @file{PONY-DIR} for you. You can limit the listed ponies by
|
||
using the option @option{--restrict}, or @option{-r}, that works the same was in with
|
||
the commands @command{ponysay} and @command{ponythink}. See @ref{Invoking ponysay} for
|
||
more infomation about the @option{--restrict} option.
|
||
|
||
In this browser you will on the right side have all pony files, in your selected
|
||
directory, listed except those that does not match your @option{--restrict} settings.
|
||
In the rest of the free space, the pony select in the list is centered. You can move
|
||
the pony, in case it is too big, by using the arrows keys with @kbd{control} held down,
|
||
or using the @kbd{W}, @kbd{A}, @kbd{S}, @kbd{D} keys (for QWERTY and QWERTZ layout,)
|
||
or with the @kbd{<} (or @kbd{Ä}), @kbd{A}, @kbd{O}, @kbd{E} keys (for Dvorak and Svorak
|
||
layout.) To recenter the pony press @kbd{C-l} (@kbd{dl} with @kbd{control} held down.)
|
||
|
||
Browse between ponies using the arrow keys or with @kbd{C-n} and @kbd{C-p}, for next
|
||
pony and previous pony, respectivily. Additionally, @kbd{Q} can be used list quotes
|
||
for pony, and @kbd{I} for metadata; press the key again to return the pony browsing.
|
||
|
||
The tool can be exited using the key combinations @kbd{C-q} or @kbd{C-x C-c}.
|
||
|
||
|
||
|
||
@node Limitations
|
||
@chapter Limitations
|
||
@cindex limitations
|
||
|
||
@menu
|
||
* Terminals:: Limitations on terminals.
|
||
* GNU Hurd:: Limitations of the Hurd.
|
||
* Cowsay:: Limitations on cowsay.
|
||
@end menu
|
||
|
||
|
||
@node Terminals
|
||
@section Terminals
|
||
@cindex terminals
|
||
@cindex fonts
|
||
@cindex broken ponies
|
||
|
||
@pindex xterm
|
||
@pindex putty
|
||
Ponysay works perfectly on @command{xterm}, @command{xterm} like terminals including
|
||
@command{putty}, settings may however need to be customised for Unicode Character Set
|
||
(UCS) support, but less well, depending on font, on VTE based terminals including
|
||
@command{mate-terminal}.
|
||
|
||
@cindex KMS
|
||
@cindex kernel mode setting
|
||
@cindex TTY
|
||
@pindex Linux VT
|
||
On Linux's native terminal Linux VT (TTY) it works less well, and not good at all
|
||
without Kernel Mode Setting (KMS) support. See @url{https://github.com/erkin/ponysay/issues/1}
|
||
for more information. @command{ponysay} clears the screen before printing to TTY, this
|
||
is because if your graphics driver supports KMS, the colours will be messed by when the
|
||
ponies position moves on the screen, this is also reason why the output is truncated on
|
||
the height in TTY by default.
|
||
|
||
Most terminals have support for 256 colours, we do however only use the top 240
|
||
colours; this is because the lower 16 colours are usually, in contrast to the top 240,
|
||
customised. We assume that the top 240 colours have their standard values. In TTY with
|
||
KMS support we dot have any actual limit (except for @math{2^{24}} + full
|
||
transparency.)
|
||
|
||
@pindex xterm
|
||
@pindex urxvt
|
||
@pindex putty
|
||
@pindex rxvt
|
||
@pindex mrxvt
|
||
@pindex Eterm
|
||
@pindex aterm
|
||
@command{ponysay} works perfectly on @command{xterm}, @command{urxvt} and
|
||
@command{putty}, but @command{rxvt}, @command{mrxvt} and @command{Eterm} do not have
|
||
UTF-8 support and are currently not supported. Additionally @command{aterm} have
|
||
neither UTF-8 support nor 256 colour support, and is therefore not yet supported.
|
||
|
||
@pindex 9term
|
||
Due to extreme limitations in @command{9term} @command{ponysay} will never be able to
|
||
run on it.
|
||
|
||
|
||
@node GNU Hurd
|
||
@section GNU Hurd
|
||
@cindex Hurd
|
||
@cindex GNU Hurd
|
||
@cindex TTY
|
||
|
||
@command{ponysay} should work just fine on GNU/Hurd, except for in the native virtual
|
||
terminal (TTY). Hurd's terminal is limited to 16 colours and does not provide the capaility
|
||
of modifing
|
||
|
||
If we are lucky it may be possible draw pictures, in full resultions, as you can in linux;
|
||
which is currently not inplementedin @command{ponysay}. Another, not yet implemented
|
||
possiblity, is to use low resoltion with ACSII character for colour interpolation.
|
||
|
||
|
||
@node Cowsay
|
||
@section Cowsay
|
||
@pindex @command{cowsay}
|
||
|
||
This section describes the limitation of @command{cowsay}, but since version 2.1
|
||
@command{cowsay} is no longer used because of it. So none of the following limitations
|
||
are present anymore.
|
||
|
||
When @command{cowsay} determines the length of a word it measures in number of bytes
|
||
(in UTF-8), therefore non-ASCII words will malformat the balloon with the message.
|
||
|
||
Further, @command{cowsay} does not recognise ANSI escape sequences, therefore, using
|
||
colours and text styling in messages will also malformat the balloon with the message.
|
||
|
||
@command{cowsay} does not support balloon, including the link between the message and
|
||
the pony, customisation, other than using @command{cowthink}. However you can modify
|
||
@command{cowsay} (written Perl, so you can edit the installed files) to make the
|
||
balloon look different, maybe using box drawing characters.
|
||
|
||
@command{cowsay} does not support setting the minimum size of the balloon, both
|
||
directions on the balloon–pony links. or any other placement of the balloon than at
|
||
the top to the left.
|
||
|
||
|
||
|
||
@node Problems and requests
|
||
@chapter Problems and requests
|
||
@cindex problems
|
||
|
||
@menu
|
||
* External bugs:: Known external bugs.
|
||
* Reporting bugs:: Reporting bugs and issues in ponysay.
|
||
* Requesting ponies:: Requesting inclusion of your favourite ponies.
|
||
@end menu
|
||
|
||
|
||
@node External bugs
|
||
@section External bugs
|
||
@cindex external bugs
|
||
@cindex bugs, external
|
||
|
||
@cindex VTE-based terminals
|
||
@cindex terminals
|
||
@pindex @command{mate-terminal}
|
||
@pindex @command{gnome-terminal}
|
||
@pindex @command{terminator}
|
||
There is only one known bug that may occour that is external to ponysay,
|
||
meaning that it is a bug that can occour with ponysay, but is not actually
|
||
a bug in ponysay. This bug is common for programs that prints a lot of
|
||
colours, even with @command{cat}; it is only known to happen for VTE-based
|
||
terminals, such as @command{mate-terminal}, @command{gnome-terminal} and
|
||
@command{terminator}.
|
||
|
||
The bug, is that lines (often no more than one line) can skipped when all
|
||
lines move up one step, the next line is skipped instead, and so one; or
|
||
that an escape sequence is interpreted as pure text (this is common in GNU
|
||
Emacs, however GNU Emacs does not support programs such as @command{ponysay}.)
|
||
|
||
This bug can often be suppressed by piping the output to @command{cat}
|
||
multiple times when using a VTE-based terminal (or always if you prefer).
|
||
The use of VTE-based terminal can often be determined by checking for the
|
||
environment variable @var{COLORTERM}, to which VTE-based terminal usually
|
||
export their name (some reported another terminals name.)
|
||
|
||
If you want to do this in GNU Bash you can add this (with possible modifications
|
||
depending on what you also have done with @command{ponysay}) code sample
|
||
to your @file{~/.bashrc} file.
|
||
|
||
@cartouche
|
||
@example
|
||
[[ ! "$COLORTERM" = "" ]] &&
|
||
function ponysay
|
||
@{
|
||
exec ponysay "$@@" | cat | cat | cat | cat
|
||
@}
|
||
@end example
|
||
@end cartouche
|
||
|
||
It is important for this bug workaround that @command{cat} is unbuffered, which
|
||
is default in GNU's version of @command{cat}, but not in Unix's version.
|
||
If this does not work, test adding the option @option{-u} to @command{cat}.
|
||
|
||
|
||
|
||
@node Reporting bugs
|
||
@section Reporting bugs
|
||
@cindex bugs, reporting
|
||
@cindex report bugs
|
||
|
||
If you find a bug in @command{ponysay}, install the last version
|
||
from @url{https://github.com/erkin/ponysay}, and if it is still
|
||
present, please report it at @url{https://github.com/erkin/ponysay/issues}.
|
||
Please be as descriptive as possible, as it will help us verify it
|
||
solve it faster.
|
||
|
||
|
||
@node Requesting ponies
|
||
@section Requesting ponies
|
||
@cindex pony requests
|
||
@cindex request ponies
|
||
|
||
If you want I specific pony added, ask us at
|
||
@url{https://github.com/erkin/ponysay/issues} and we will add it.
|
||
To speed the up the process, if possible, supply good pictures. Full visibly,
|
||
transparent background, and pixelated are the properties that makes a picture good.
|
||
|
||
|
||
|
||
@node Dependencies
|
||
@chapter Dependencies
|
||
@cindex dependencies
|
||
@cindex optional dependencies
|
||
|
||
We have provided a script that should run one most, if not all shells, named
|
||
@file{./dependency-test.sh} that will help you track down any missing package.
|
||
The script works in @command{bash}, @command{dash} and @command{zsh}, but not
|
||
in @command{fish}, so case you @command{sh} links to @command{fish}, run
|
||
@command{bash dependency-test.sh} (or with one of the other compatible shells.)
|
||
|
||
@menu
|
||
* Required runtime dependencies:: Required runtime dependencies.
|
||
* Optional runtime dependencies:: Optional runtime dependencies.
|
||
* Package building dependencies:: Package building dependencies.
|
||
* Dependencies for pony providers:: Dependencies for pony providers.
|
||
@end menu
|
||
|
||
|
||
@node Required runtime dependencies
|
||
@section Required runtime dependencies
|
||
|
||
@table @command
|
||
@item coreutils
|
||
@command{stty} is used to determine the size of the terminal.
|
||
@item python>=3@footnote{Sometimes distributed as @command{python3} rather than @command{python}.}
|
||
@command{ponysay} is written in pure Python 3.
|
||
@end table
|
||
|
||
@node Optional runtime dependencies
|
||
@section Optional runtime dependencies
|
||
@cindex extensions
|
||
@cindex optional dependencies
|
||
|
||
@table @command
|
||
@item util-say>=3
|
||
@pindex @command{util-say}
|
||
@cindex KMS
|
||
@cindex TTY
|
||
@pindex Linux VT
|
||
For improved TTY support for user with custom colour palette and KMS support.
|
||
It can be downloaded at @url{https://github.com/maandree/util-say}. If this is
|
||
used @command{chmod} from @command{coreutils} is also required.
|
||
|
||
|
||
@cindex .png
|
||
@cindex PNG images
|
||
@cindex images, PNG
|
||
@cindex Portable Network Graphics
|
||
For the purpose of simplifying for pony contributors, @command{ponysay} supports
|
||
using .png-images (note that the file must not miss the @file{.png} at the end of
|
||
the file name) in addition to .pony-files or pony names.
|
||
@end table
|
||
|
||
|
||
@node Package building dependencies
|
||
@section Package building dependencies
|
||
|
||
@table @command
|
||
@item python>=3@footnote{Sometimes distributed as @command{python3} rather than @command{python}.}
|
||
@pindex @command{python}
|
||
@pindex @command{python3}
|
||
Required to run the @file{./setup.py} file, which is also invoked from the
|
||
make script.
|
||
@item gzip
|
||
@pindex @command{gzip}
|
||
Used for compressing manuals. (Optional, standard)
|
||
@item xz
|
||
@pindex @command{xz}
|
||
Used for compressing manuals. (Optional, non-standard)
|
||
@item texinfo
|
||
@pindex @command{texinfo}
|
||
@pindex @command{info}
|
||
@pindex @command{install-info}
|
||
Used to compile this @command{info} manual. (Optional, standard)
|
||
@item info@footnote{Normally a part of @command{texinfo}.}
|
||
Used to install this @command{info} manual with @command{install-info}.
|
||
(Optional, standard)
|
||
@end table
|
||
|
||
|
||
@node Dependencies for pony providers
|
||
@section Dependencies for pony providers
|
||
@cindex contributing
|
||
|
||
@table @command
|
||
@item bash
|
||
@pindex @command{bash}
|
||
Required to run @command{dev/dist.sh}.
|
||
@item coreutils
|
||
@pindex @command{coreutils}
|
||
@command{ln} and @command{readlink} are used in the @command{ttyponies} subscript
|
||
of @command{dev/dist.sh}.
|
||
@item util-say>=3
|
||
Used by @command{dev/dist.sh ttyponies} to build ttyponies from xterm ponies.
|
||
It can be downloaded at @url{https://github.com/maandree/util-say}.
|
||
@end table
|
||
|
||
|
||
|
||
@node Installing
|
||
@chapter Installing
|
||
@cindex installing
|
||
@pindex @command{make}
|
||
|
||
@menu
|
||
* From upstream:: Installing manually from upstream (GitHub repository).
|
||
* Package repositories:: Packages distributed in OS package repositories.
|
||
* Exotic operating systems:: Installing on other OS:es than GNU.
|
||
* Uninstalling:: Uninstalling when installed manually.
|
||
@end menu
|
||
|
||
|
||
@node From upstream
|
||
@section From upstream
|
||
@cindex upstream installation
|
||
|
||
@menu
|
||
* Installations basics:: The basics of installations.
|
||
* Custom installations:: Installation customisation.
|
||
@end menu
|
||
|
||
@node Installations basics
|
||
@subsection Installations basics
|
||
@cindex @file{setup.py}
|
||
@pindex @command{./setup.py}
|
||
@pindex @command{make}
|
||
@cindex basic installation
|
||
|
||
|
||
Before installing @command{ponysay}, make sure your system have the packages listed
|
||
under @ref{Required runtime dependencies} and @ref{Package building dependencies}
|
||
installed.
|
||
|
||
Tarballs can be downloaded at @url{https://github.com/erkin/ponysay/tarball/master}
|
||
for bleeding edge, or from @url{https://github.com/erkin/ponysay/tags} for releases.
|
||
|
||
If you have @command{git} you can @command{clone} the project URL
|
||
@url{https://github.com/erkin/ponysay.git}.
|
||
|
||
In the terminal, @command{cd} into the ponysay directory and execute
|
||
@command{./setup.py --freedom=parital install} or
|
||
@command{python3 setup.py --freedom=parital install}. This will install
|
||
@command{ponysay} into @file{/usr}, normally meaning you need to run as root, e.g. by
|
||
running @command{sudo ./setup.py --freedom=parital install}.
|
||
|
||
The @command{--freedom} option and manditory, if you only want completely free
|
||
ponies, use @command{--freedom=strict} instread of @command{--freedom=partial}.
|
||
|
||
Now you will be to use ponysay, run: @command{ponysay "I am just the cutest pony!"},
|
||
or if have a specific pony in your mind: @command{ponysay -f pinkie "Partay!~"}.
|
||
|
||
@cindex man page translations
|
||
@command{ponysay} comes with this @command{info} manual and a manpage in section 6,
|
||
@command{man 6 ponysay} (or just @command{man ponysay}). The manpage is also available
|
||
in Spanish: @command{man -L es 6 ponysay}. To install the Spanish manual add the
|
||
option @option{--with-man-es} when running @command{./setup.py}.
|
||
|
||
|
||
|
||
@node Custom installations
|
||
@subsection Custom installations
|
||
@cindex customised installations
|
||
@cindex installation customisation
|
||
@cindex @file{setup.py}
|
||
@pindex @command{./setup.py}
|
||
@pindex @command{./configure}
|
||
@pindex @command{make}
|
||
@cindex configure
|
||
|
||
With the exception for with @option{--with-everything} and @option{--with-nothing},
|
||
every option that starts with @option{--with-} or @option{--without-} exists in both
|
||
variants. @option{--with-} options install parts of the package. @option{--without-}
|
||
options skips installation of parts of the packages. With the same exception,
|
||
@option{--without-} options take not arguments and @option{--with-} optionally takes
|
||
an argument, if no argument is provided a default argument is implied.
|
||
|
||
The configuration script recognised the following options, the default values for
|
||
options with arguments are written after the equality sign (@code{=}) in the option:
|
||
|
||
@table @option
|
||
@item --everything
|
||
@itemx --with-everything
|
||
@opindex @option{--everything}
|
||
@opindex @option{--with-everything}
|
||
Install everything that is not explicity excluded.
|
||
|
||
@item --minimal
|
||
@opindex @option{--minimal}
|
||
Install only the essentials. Note that this can vary depending on version. Currently
|
||
this means that the commands, xterm ponies and legal documents is installed.
|
||
|
||
@item --nothing
|
||
@itemx --with-nothing
|
||
@opindex @option{--nothing}
|
||
@opindex @option{--with-nothing}
|
||
Install nothing, except legal documents, that is not explicity included.
|
||
|
||
@item --with-ponysay
|
||
@itemx --with-ponysay-command=/usr/bin/ponysay
|
||
@opindex @option{--with-ponysay}
|
||
@opindex @option{--without-ponysay}
|
||
@opindex @option{--with-ponysay-command}
|
||
@opindex @option{--without-ponysay-command}
|
||
Install the @command{ponysay} command, and set file name. (Default)
|
||
|
||
@item --with-ponythink
|
||
@itemx --with-ponythink-command=/usr/bin/ponythink
|
||
@opindex @option{--with-ponythink}
|
||
@opindex @option{--without-ponytink}
|
||
@opindex @option{--with-ponythink-command}
|
||
@opindex @option{--without-ponytink-command}
|
||
Install the @command{ponythink} command, and set file name. (Default)
|
||
|
||
@item --with-ponysay-tool
|
||
@itemx --with-ponyponysay-tool-command=/usr/bin/ponyponysay-tool
|
||
@opindex @option{--with-ponysay-tool}
|
||
@opindex @option{--without-ponysay-tool}
|
||
@opindex @option{--with-ponysay-tool-command}
|
||
@opindex @option{--without-ponysay-tool-command}
|
||
Install the @command{ponysay-tool} command, and set file name. (Default)
|
||
|
||
@item --with-shared-cache=/var/cache/ponysay
|
||
@opindex @option{--with-shared-cache}
|
||
@opindex @option{--without-shared-cache}
|
||
Install a user shared cache, this is only used by KMS ponies so far. (Default)
|
||
|
||
@item --with-bash
|
||
@item --with-bash-completion=/usr/share/bash-completion/completions/ponysay
|
||
@opindex @option{--with-bash}
|
||
@opindex @option{--without-bash}
|
||
@opindex @option{--with-bash-completion}
|
||
@opindex @option{--without-bash-completion}
|
||
Install auto-completion for installed commands in GNU Bash. Select the file name
|
||
for the installed script for the ponysay command, the other commands modifies this
|
||
file name. (Default)
|
||
|
||
@item --with-fish
|
||
@itemx --with-fish-completion=/usr/share/fish/completions/ponysay.fish
|
||
@opindex @option{--with-fish}
|
||
@opindex @option{--without-fish}
|
||
@opindex @option{--with-fish-completion}
|
||
@opindex @option{--without-fish-completion}
|
||
Install auto-completion for installed commands in Friendly interactive shell.
|
||
Select the file name for the installed script for the ponysay command, the other
|
||
commands modifies this file name. (Default)
|
||
|
||
@item --with-zsh
|
||
@itemx --with-zsh-completion=/usr/share/zsh/site-functions/_ponysay
|
||
@opindex @option{--with-zsh}
|
||
@opindex @option{--without-zsh}
|
||
@opindex @option{--with-zsh-completion}
|
||
@opindex @option{--without-zsh-completion}
|
||
Install auto-completion for installed commands in the zsh shell.
|
||
Select the file name for the installed script for the ponysay command, the other
|
||
commands modifies this file name. (Default)
|
||
|
||
@item --with-shell
|
||
@itemx --with-shell-completion=/usr/share
|
||
@opindex @option{--with-shell}
|
||
@opindex @option{--without-shell}
|
||
@opindex @option{--with-bash}
|
||
@opindex @option{--without-bash}
|
||
@opindex @option{--with-fish}
|
||
@opindex @option{--without-fish}
|
||
@opindex @option{--with-zsh}
|
||
@opindex @option{--without-zsh}
|
||
@opindex @option{--with-shell-completion}
|
||
@opindex @option{--without-shell-completion}
|
||
@opindex @option{--with-bash-completion}
|
||
@opindex @option{--without-bash-completion}
|
||
@opindex @option{--with-fish-completion}
|
||
@opindex @option{--without-fish-completion}
|
||
@opindex @option{--with-zsh-completion}
|
||
@opindex @option{--without-zsh-completion}
|
||
Macro for @option{--with-bash}, @option{--with-fish} and @option{--with-zsh}.
|
||
The argument is the used share/ directory that all shells have in common.
|
||
|
||
@item --with-pdf
|
||
@itemx --with-pdf-manual=/usr/doc
|
||
@opindex @option{--with-pdf}
|
||
@opindex @option{--without-pdf}
|
||
@opindex @option{--with-pdf-manual}
|
||
@opindex @option{--without-pdf-manual}
|
||
Install PDF manual, and select directory for it.
|
||
|
||
@item --with-pdf-compression
|
||
@itemx --with-pdf-manual-compression=gz
|
||
@opindex @option{--with-pdf}
|
||
@opindex @option{--with-pdf-manual}
|
||
@opindex @option{--with-pdf-compression}
|
||
@opindex @option{--without-pdf-compression}
|
||
@opindex @option{--with-pdf-manual-compression}
|
||
@opindex @option{--without-pdf-manual-compression}
|
||
Compress PDF manual, select compression by file name extension. This option
|
||
does not imply @option{--with-pdf}. (Default)
|
||
|
||
@item --with-info
|
||
@itemx --with-info-manual=/usr/share/info
|
||
@opindex @option{--with-info}
|
||
@opindex @option{--without-info}
|
||
@opindex @option{--with-info-manual}
|
||
@opindex @option{--without-info-manual}
|
||
Install @command{info} manual, and select directory for it. (Default)
|
||
|
||
@item --with-info-install
|
||
@itemx --with-info-manual-install=My Little Ponies for your terminal
|
||
@opindex @option{--with-info-install}
|
||
@opindex @option{--without-info-install}
|
||
@opindex @option{--with-info-manual-install}
|
||
@opindex @option{--without-info-manual-install}
|
||
Use @command{install-info} when installing @command{info} manual. Set the
|
||
description for the manual. This option does not imply @option{--with-info}. (Default)
|
||
|
||
@item --with-info-compression
|
||
@itemx --with-info-manual-compression=gz
|
||
@opindex @option{--with-info}
|
||
@opindex @option{--with-info-compression}
|
||
@opindex @option{--without-info-compression}
|
||
@opindex @option{--with-info-manual}
|
||
@opindex @option{--with-info-manual-compression}
|
||
@opindex @option{--without-info-manual-compression}
|
||
Compress @command{info} manual, select compression by file name extension.
|
||
This option does not imply @option{--with-info}. (Default)
|
||
|
||
@item --with-man-en
|
||
@itemx --with-manpage-en
|
||
@itemx --with-man-manual-en
|
||
@itemx --with-en-man
|
||
@itemx --with-en-manpage
|
||
@itemx --with-en-man-manual=/usr/share/man
|
||
@opindex @option{--with-man-en}
|
||
@opindex @option{--without-man-en}
|
||
@opindex @option{--with-manpage-en}
|
||
@opindex @option{--without-manpage-en}
|
||
@opindex @option{--with-man-manual-en}
|
||
@opindex @option{--without-man-manual-en}
|
||
@opindex @option{--with-en-man}
|
||
@opindex @option{--without-en-man}
|
||
@opindex @option{--with-en-manpage}
|
||
@opindex @option{--without-en-manpage}
|
||
@opindex @option{--with-en-man-manual}
|
||
@opindex @option{--without-en-man-manual}
|
||
Install English @command{man} manual. Set directory for @command{man} manuals.
|
||
(Default)
|
||
|
||
@item --with-man-es
|
||
@itemx --with-manpage-es
|
||
@itemx --with-man-manual-es
|
||
@itemx --with-es-man
|
||
@itemx --with-es-manpage
|
||
@itemx --with-es-man-manual=/usr/share/man
|
||
@opindex @option{--with-man-es}
|
||
@opindex @option{--without-man-es}
|
||
@opindex @option{--with-manpage-es}
|
||
@opindex @option{--without-manpage-es}
|
||
@opindex @option{--with-man-manual-es}
|
||
@opindex @option{--without-man-manual-es}
|
||
@opindex @option{--with-es-man}
|
||
@opindex @option{--without-es-man}
|
||
@opindex @option{--with-es-manpage}
|
||
@opindex @option{--without-es-manpage}
|
||
@opindex @option{--with-es-man-manual}
|
||
@opindex @option{--without-es-man-manual}
|
||
Install Spanish @command{man} manual. Set directory for @command{man} manuals.
|
||
|
||
@item --with-man
|
||
@itemx --with-manpage
|
||
@itemx --with-man-manual
|
||
@opindex @option{--with-man}
|
||
@opindex @option{--without-man}
|
||
@opindex @option{--with-manpage}
|
||
@opindex @option{--without-manpage}
|
||
@opindex @option{--with-man-manual}
|
||
@opindex @option{--without-man-manual}
|
||
Macro for all @option{--with-man-LANG}.
|
||
|
||
@item --with-man-en-compression
|
||
@itemx --with-manpage-en-compression
|
||
@itemx --with-man-manual-en-compression
|
||
@itemx --with-en-man-compression
|
||
@itemx --with-en-manpage-compression
|
||
@itemx --with-en-man-manual-compression=gz
|
||
@opindex @option{--with-man-en-compression}
|
||
@opindex @option{--without-man-en-compression}
|
||
@opindex @option{--with-manpage-en-compression}
|
||
@opindex @option{--without-manpage-en-compression}
|
||
@opindex @option{--with-man-manual-en-compression}
|
||
@opindex @option{--without-man-manual-en-compression}
|
||
@opindex @option{--with-en-man-compression}
|
||
@opindex @option{--without-en-man-compression}
|
||
@opindex @option{--with-en-manpage-compression}
|
||
@opindex @option{--without-en-manpage-compression}
|
||
@opindex @option{--with-en-man-manual-compression}
|
||
@opindex @option{--without-en-man-manual-compression}
|
||
Compress English @command{man} manual, select compression by file name extension.
|
||
This option does not imply @option{--with-man-en}. (Default)
|
||
|
||
@item --with-man-es-compression
|
||
@itemx --with-manpage-es-compression
|
||
@itemx --with-man-manual-es-compression
|
||
@itemx --with-es-man-compression
|
||
@itemx --with-es-manpage-compression
|
||
@itemx --with-es-man-manual-compression=gz
|
||
@opindex @option{--with-man-es-compression}
|
||
@opindex @option{--without-man-es-compression}
|
||
@opindex @option{--with-manpage-es-compression}
|
||
@opindex @option{--without-manpage-es-compression}
|
||
@opindex @option{--with-man-manual-es-compression}
|
||
@opindex @option{--without-man-manual-es-compression}
|
||
@opindex @option{--with-es-man-compression}
|
||
@opindex @option{--without-es-man-compression}
|
||
@opindex @option{--with-es-manpage-compression}
|
||
@opindex @option{--without-es-manpage-compression}
|
||
@opindex @option{--with-es-man-manual-compression}
|
||
@opindex @option{--without-es-man-manual-compression}
|
||
Compress Spanish @command{man} manual, select compression by file name extension.
|
||
This option does not imply @option{--with-man-es}. (Default)
|
||
|
||
@item --with-man-compression
|
||
@itemx --with-manpage-compression
|
||
@itemx --with-man-manual-compression
|
||
@opindex @option{--with-man-compression}
|
||
@opindex @option{--without-man-compression}
|
||
@opindex @option{--with-manpage-compression}
|
||
@opindex @option{--without-manpage-compression}
|
||
@opindex @option{--with-man-manual-compression}
|
||
@opindex @option{--without-man-manual-compression}
|
||
Macro for all @option{--with-man-LANG-compression}.
|
||
|
||
@item --man-section-ponysay
|
||
@itemx --man-sectionpage-ponysay
|
||
@itemx --ponysay-man-section
|
||
@itemx --ponysay-manpage-section=6
|
||
@opindex @option{--man-section-ponysay}
|
||
@opindex @option{--manpage-section-ponysay}
|
||
@opindex @option{--ponysay-man-section}
|
||
@opindex @option{--ponysay-manpage-section}
|
||
Change the section for the @command{ponysay} manpage.
|
||
|
||
@item --man-section-cowsay
|
||
@itemx --manpage-section-cowsay
|
||
@itemx --cowsay-man-section
|
||
@itemx --cowsay-manpage-section=1
|
||
@opindex @option{--man-section-cowsay}
|
||
@opindex @option{--manpage-section-cowsay}
|
||
@opindex @option{--cowsay-man-section}
|
||
@opindex @option{--cowsay-manpage-section}
|
||
Change the section for the @command{cowsay} manpage.
|
||
|
||
@item --man-section-fortune
|
||
@itemx --manpage-section-fortune
|
||
@itemx --fortune-man-section
|
||
@itemx --fortune-manpage-section=6
|
||
@opindex @option{--man-section-fortune}
|
||
@opindex @option{--manpage-section-fortune}
|
||
@opindex @option{--fortune-man-section}
|
||
@opindex @option{--fortune-manpage-section}
|
||
Change the section for the @command{fortune} manpage.
|
||
|
||
@item --with-ponies
|
||
@opindex @option{--with-ponies}
|
||
@opindex @option{--without-ponies}
|
||
Install standard xterm ponies. (Default)
|
||
|
||
@item --with-ttyponies
|
||
@opindex @option{--with-ttyponies}
|
||
@opindex @option{--without-ttyponies}
|
||
Install standard tty ponies. (Default)
|
||
|
||
@item --with-extraponies
|
||
@opindex @option{--with-extraponies}
|
||
@opindex @option{--without-extraponies}
|
||
Install extra xterm ponies. (Default)
|
||
|
||
@item --with-extrattyponies
|
||
@opindex @option{--with-extrattyponies}
|
||
@opindex @option{--without-extrattyponies}
|
||
Install extra tty ponies. (Default)
|
||
|
||
@item --with-quotes
|
||
@opindex @option{--with-quotes}
|
||
@opindex @option{--without-quotes}
|
||
Install pony quotes. (Default)
|
||
|
||
@item --with-balloons
|
||
@opindex @option{--with-balloons}
|
||
@opindex @option{--without-balloons}
|
||
Install balloon styles. (Default)
|
||
|
||
@item --with-ucs
|
||
@itemx --with-ucs-names
|
||
@opindex @option{--with-ucs}
|
||
@opindex @option{--without-ucs}
|
||
@opindex @option{--with-ucs-names}
|
||
@opindex @option{--without-ucs-names}
|
||
Install UCS pony names. (Default)
|
||
|
||
@item --without-custom-env-python
|
||
@opindex @option{--without-custom-env-python}
|
||
Let the installer set the @command{env} name for @command{python} in @file{ponysay}.
|
||
(Default)
|
||
|
||
@item --with-custom-env-python=python3
|
||
@opindex @option{--with-custom-env-python}
|
||
Set the @command{env} name for @command{python} in @file{ponysay}.
|
||
|
||
@item --prefix=/usr
|
||
@opindex @option{--prefix}
|
||
Set a prefix to all implicit directories.
|
||
|
||
@item --private
|
||
@opindex @option{--private}
|
||
Change all implicit configurations to fit local user a installation
|
||
for the current user.
|
||
|
||
@item --opt
|
||
@opindex @option{--opt}
|
||
Change all implicit directories to fit installation to @file{/opt}.
|
||
|
||
@item --bin-dir=/usr/bin
|
||
@opindex @option{--bin-dir}
|
||
Set the system's directory for command executables.
|
||
|
||
@item --lib-dir=/usr/lib/ponysay
|
||
@opindex @option{--lib-dir}
|
||
Set the system's directory for non-command executables. Currently their
|
||
is not non-executable library, so this options has no effect, but bleeding
|
||
edge distributors should specify it if it differs from prefered.
|
||
|
||
@item --libexec-dir=/usr/libexec/ponysay
|
||
@opindex @option{--libexec-dir}
|
||
Set the system's directory for non-command executables. Currently their
|
||
is not non-command executables, so this options has no effect, but bleeding
|
||
edge distributors should specify it if it differs from prefered.
|
||
|
||
@item --share-dir=/usr/share
|
||
@opindex @option{--share-dir}
|
||
Set the system's directory for resource files.
|
||
|
||
@item --sysconf-dir=/etc
|
||
@opindex @option{--sysconf-dir}
|
||
Set the system's local specific configuration directory.
|
||
|
||
@item --cache-dir=/var/cache
|
||
@opindex @option{--cache-dir}
|
||
Set the system's directory for cache directories.
|
||
|
||
@item --dest-dir=
|
||
@opindex @option{--dest-dir}
|
||
Set off environment for installation.
|
||
|
||
@item --linking=symbolic
|
||
@opindex @option{--linking}
|
||
Set how to link identical files. Directories cannot be hard linked on most
|
||
systems, therefore directories or always symbolically linked of hard linked
|
||
is specified.
|
||
Recognised arguments are @code{copy}, @code{hard} and @code{symbolic}.
|
||
@code{copy} implies that files and directories are not linked, but duplicated.
|
||
@command{ponysay -L} will give the same output as @command{ponysay -l} if @code{copy}
|
||
or @code{hard} is used. This is because it does link reading and not content or
|
||
inode comparison.
|
||
|
||
@item --freedom=MANDITORY!
|
||
@opindex @option{--freedom}
|
||
@cindex full freedom
|
||
@cindex freedom, full
|
||
Set your freedom. If you the any of the values @code{strict}, @code{full}, @code{true}
|
||
or @code{yes}, the setup will make sure that only completly free parts of the package
|
||
is installed. This should be used (@code{--freedom=strict}) on distributions for GNU
|
||
endorsed (endorsable) GNU/Linux-libre distributions.
|
||
|
||
If you do not want this, will need to explicity say so (you do also need to say if you
|
||
do want it) by using either of the values @code{sloppy}, @code{partial}, @code{false}
|
||
or @code{no}.
|
||
@end table
|
||
|
||
Recognised compressions are @option{gz} which uses @option{gzip -9}, and @option{xz}
|
||
which uses @option{xz -9e}. @option{xz} is still exotic to most programs, using
|
||
it is not recommended. Distributors are strongly disencouraged to compression for the
|
||
PDF manual and should use @option{--without-pdf-compression}.
|
||
|
||
You can run @command{./setup.py [OPTIONS] view} to make sure everything is correct
|
||
before building and installing.
|
||
|
||
|
||
@node Package repositories
|
||
@section Package repositories
|
||
@cindex package repositories
|
||
|
||
@menu
|
||
* Arch Linux:: Packages for Arch Linux.
|
||
* Arch Linux ARM:: Packages for Arch Linux ARM.
|
||
* Chakra:: Packages for Chakra.
|
||
* Debian GNU/Linux:: Packages for Debian GNU/Linux and Ubuntu.
|
||
* Gentoo Linux:: Packages for Gentoo Linux.
|
||
* Source Mage GNU/Linux:: Packages for Source Mage GNU/Linux.
|
||
@end menu
|
||
|
||
|
||
@node Arch Linux
|
||
@subsection Arch Linux
|
||
@cindex Arch Linux
|
||
|
||
The official Arch Linux package repositories contains @command{ponysay} as
|
||
@w{@code{community/ponysay}} (developer maintained). The Arch Linux User Repository
|
||
(AUR) contains a bleeding edge git version of @command{ponysay} as
|
||
@w{@code{ponysay-git}} (user maintained).
|
||
|
||
|
||
@node Arch Linux ARM
|
||
@subsection Arch Linux ARM
|
||
@cindex Arch Linux ARM
|
||
|
||
@w{@code{community/ponysay}} from Arch Linux (@ref{Arch Linux}) is also available
|
||
for Arch Linux ARM.
|
||
|
||
|
||
@node Chakra
|
||
@subsection Chakra
|
||
@cindex Chakra
|
||
|
||
Chakra users can install from (CCR) a stable version named a @code{ponysay}
|
||
(developer maintained Arch Linux mirror), additionally a git verion of ponysay is
|
||
available as @code{ponysay-git} (developer maintained Arch Linux mirror).
|
||
|
||
|
||
@node Debian GNU/Linux
|
||
@subsection Debian GNU/Linux and Ubuntu
|
||
@cindex Debian GNU/Linux
|
||
@cindex Ubuntu
|
||
|
||
A .deb file is available at @url{http://roryholland.co.uk/misc.html#ponysay}
|
||
(user maintained), and PPA:s can be found at
|
||
@url{https://launchpad.net/~vincent-c/+archive/ppa} (user maintained) and
|
||
@url{https://launchpad.net/~blazemore/+archive/ponysay} (user maintained).
|
||
|
||
|
||
@node Gentoo Linux
|
||
@subsection Gentoo Linux
|
||
@cindex Gentoo Linux
|
||
|
||
Gentoo users can use the overlay @url{https://github.com/etu/aidstu-overlay}, which
|
||
contains @command{ponysay} as @w{@code{games-misc/ponysay}} (developer maintained).
|
||
|
||
|
||
@node Source Mage GNU/Linux
|
||
@subsection Source Mage GNU/Linux
|
||
@cindex Source Mage GNU/Linux
|
||
|
||
The spell @w{@code{util/ponysay}} (user maintained) is available in Grimoire for
|
||
Source Mage @w{GNU/Linux}.
|
||
|
||
|
||
@node Exotic operating systems
|
||
@section Exotic operating systems
|
||
@cindex exotic OS:es
|
||
|
||
An "exotic operating system" as a operating system that is not GNU (GNU/Linux ("Linux")
|
||
and GNU/Hurd are GNU distor:s.)
|
||
|
||
@cindex Mac OS X
|
||
@cindex OS X
|
||
Ponysay is told to be running on Mac OS X, which is Unix-like OS meaning that probably
|
||
all future version of ponysay will be able to run without any problems.
|
||
|
||
@cindex Windows
|
||
@cindex Cygwin
|
||
Ponysay is also reported to be able to run on Windows 8 through Cygwin, provided that
|
||
@code{python3} is installed. It will probabily also run one any other version of Windows
|
||
through Cygwin. Additionally among the preinstalled fonts in Windows 8; Consolas 10pt,
|
||
and larger, can be used for almost perfect ponies (they may be just a little distorted
|
||
on the height), however Consolas is only able print the ASCII based balloons.
|
||
|
||
|
||
|
||
@node Uninstalling
|
||
@section Uninstalling
|
||
@cindex uninstalling
|
||
|
||
If you did not install @command{ponysay} with a package manager, but rather
|
||
manually from the upstream, you can uninstall it by running @command{make uninstall}.
|
||
|
||
Well written package manages will uninstall files that the package is no longer
|
||
using, i.e. if deleted, moved or renamed. To uninstall files that are not longer
|
||
used, by the currently installed version you will need that versions @file{Makefile}.
|
||
To perform an uninstallation of old files run @command{make uninstall-old}.
|
||
|
||
|
||
|
||
@node Inner workings
|
||
@chapter Inner workings
|
||
@cindex inner workings
|
||
@cindex hacking
|
||
|
||
@menu
|
||
* Pony anatomy:: Anatomy of pony files.
|
||
* Pony metadata extension:: Metadata in pony files.
|
||
* Pony quote infrastructure:: Pony quote infrastructure.
|
||
* Balloon style files:: Balloon style files.
|
||
* Printing in TTY with KMS:: Printing in TTY with KMS support.
|
||
* Truncation:: Output truncation.
|
||
* Languages:: Selection of programming languages.
|
||
* Shell auto-completion:: Things that make auto-completion simpler.
|
||
* Universal Character Set:: Something about Universal Character Set support.
|
||
@end menu
|
||
|
||
|
||
@node Pony anatomy
|
||
@section Pony anatomy
|
||
@cindex pony anatomy
|
||
@cindex anatomy of pony files
|
||
|
||
The pony files are simple raw output data that can be printed to the terminal,
|
||
except it contains scalar variables. The pony images consists of white space, lower
|
||
half blocks [U+2584], upper half blocks [U+2580] and ANSI colour sequences (CSI m),
|
||
and, in TTY, colour value change sequences (OSI P).
|
||
|
||
Variables are recalled by putting the variable's name between two dollar signs
|
||
(@code{$var$}), and are stored by putting the variable's name followed by the value
|
||
between two dollar signs and with a equality sign between the name and the value
|
||
(@code{$var=value$}). Variable names cannot include equality signs, but the value
|
||
can; dollar signs can be used by placing an ESC character before the dollar sign.
|
||
|
||
There are three predefined variables: @code{$$} (empty variable name), @code{$\$}
|
||
and @code{$/$}. @code{$$} has a dollar sign (@code{$}) as its value, while @code{$\$}
|
||
and @code{$/$} contains the characters for the link to the balloon directed in the
|
||
same direction as the variable name's slash.
|
||
|
||
Variables whose name begin with @code{balloon} are parsed as balloon inserts, it
|
||
can be either @code{balloon}, @code{balloonX}, @code{balloon,Y} or @code{balloonX,Y},
|
||
whether @code{X} is the minimum width of the balloon and @code{Y} is the minimum
|
||
height of the balloon. New in Ponysay 3.0 is that the @code{X} can also be an range
|
||
of columns, it contains of two numbers, the preferable start column, from the
|
||
column that variables is placedon, the other number is the minimum width of the
|
||
balloon. The two values are separated either by a @code{l}, a @code{r} or a @code{c}.
|
||
If @code{l} is used the the balloon is printed as normal, except that it if wrapping
|
||
is enabled and the balloon whould exceed the wrapping column, the balloon continues
|
||
to fill on its left, at most as much as the position value. If @code{r} is used, the
|
||
balloon fills the its left first and then to its right. If @code{c} is used the
|
||
balloon will try the fill on its left and right side equally.
|
||
|
||
Prior to version 2.1 the pony files were cow files used by @command{cowsay}, they
|
||
are partial Perl-scripts that assign a value to a scalar variable named
|
||
@code{$the_cow}. Cow files use a predefined scalar variable named @code{$thoughts},
|
||
these are used to create a link between the message and the pony. The message (and
|
||
the balloon) itself was printed by @command{cowsay} and is not defined in the cow
|
||
files.
|
||
|
||
|
||
@node Pony metadata extension
|
||
@section Pony metadata extension
|
||
@cindex pony metadata
|
||
@cindex metadata
|
||
@cindex tags, metadata
|
||
@cindex comments, metadata
|
||
@cindex pony tags, metadata
|
||
@cindex pony comments, metadata
|
||
|
||
New in ponysay 3.0 is pony metadata, this feature is not supported in @command{util-say}
|
||
(at least not yet). It extends the previously described@footnote{@ref{Pony anatomy}}
|
||
format of the pony files, by letting you specify details about the pony image, and
|
||
the pony itself, as well as adding comments.
|
||
|
||
The metadata entry must be at the absolute beginning of the file (UTF-8 signture
|
||
excluded), and is the file must be encoded in UNIX line breaks. The metadata entry
|
||
begins with a line with exactly 3 dollar signs and nothing else (@code{$$$}), and
|
||
end in the same way direct follow by the pony image starting from the next line.
|
||
|
||
A metadata tag consists of a tag name in upper case and a tag value, with a colon
|
||
(@code{:}), optionally with surrounding regular spaces or tab spaces, but at least
|
||
one regular space or tab space directly after the colon. The name can only consist
|
||
of A to Z (upper case ASCII letters) and regular spaces. All tab spaces in the tag
|
||
names and values are handled as regular spaces. Multiple tag names can be used
|
||
multiple times or can be completely skipped. There are only a few tags, namely
|
||
@var{BALLOON TOP}, @var{BALLOON BOTTOM}, @var{MASTER} and @var{FREE}, that absolutely
|
||
should not be used muliple tag, but nor should @var{WIDTH} and @var{HEIGHT}; a
|
||
general rule is that a tag desribing a pony should be duplicated exactly as many
|
||
times as there are ponies in the image.
|
||
|
||
Any line that does not conform to the format of a tag line is a part of the comment
|
||
field. Leading line breaks in the comment field is ignored.
|
||
|
||
|
||
@node Pony quote infrastructure
|
||
@section Pony quote infrastructure
|
||
@cindex pony quote infrastructure
|
||
@cindex quote infrastructure
|
||
|
||
When compiling, pony quotes are built to @file{quotes/}, the file names are lists
|
||
of ponies joined with plus signs (@code{+}) -- the pony names are the same as the
|
||
pony files, except they do not end with @file{.pony} -- with a index at the end,
|
||
and a full stop (@code{.}) before the index.
|
||
|
||
The source files are located in @file{ponyquotes/}, where their is a file named
|
||
@file{ponies}. This file is called the pony map, and is the basis for how the
|
||
compiled files are named. In the ponymap ponies with the same quotes are on the
|
||
same line join together with plus signs (@code{+}), if the lines because too long
|
||
for file names the line is split into multiple lines with the first pony in common.
|
||
|
||
In @file{ponyquotes/} there are also quote files, each contain just one quote, just
|
||
as when compiled to @file{quotes/}. The source quote files are identical to the
|
||
compiled quote files, except that their name contains just the first pony.
|
||
|
||
|
||
@node Balloon style files
|
||
@section Balloon style files
|
||
@cindex balloon style files
|
||
@cindex bubble style files
|
||
@pindex ponythink
|
||
|
||
Balloon style files are located in the directory @file{balloons/}, the ones ending
|
||
with @file{.say} applies to @command{ponysay} and the ones ending with @file{.think}
|
||
applies to @command{ponythink}.
|
||
|
||
Balloon style consists of 20 strings. Each string is defined on separate lines, by
|
||
their name and their value separated with a colon (@code{name:value}), if the name is
|
||
empty it continues the last one on a new line in the value. Only 10 of the strings
|
||
may be multi-lined: @var{nw}, @var{nnw}, @var{n}, @var{nne}, @var{ne}, @var{sw},
|
||
@var{ssw}, @var{s}, @var{sse} and @var{se}.
|
||
|
||
The following strings are used, and must be defined in the files:
|
||
@table @var
|
||
@item \
|
||
The character for the link to the balloon directed as @code{\}.
|
||
@item /
|
||
The character for the link to the balloon directed as @code{/}.
|
||
@item ww
|
||
The beginning of the balloon's line where the message is located if and only if the
|
||
message contains only one line.
|
||
@item ee
|
||
The end of the balloon's line where the message is located if and only if the message
|
||
contains only one line.
|
||
@item nw
|
||
The top left corner of the balloon.
|
||
@item nnw
|
||
If both this string and the @var{nne} string fits between the top corners, this is
|
||
printed directly to the right of the top left corner.
|
||
@item n
|
||
The top edge of the balloon.
|
||
@item nne
|
||
If both this string and the @var{nnw} string fits between the top corners, this is
|
||
printed directly to the right of the top left corner.
|
||
@item ne
|
||
The top right corner of the balloon.
|
||
@item nee
|
||
The end of the balloon's line where the message's first line is located if and only
|
||
if the message contains more than one line.
|
||
@item e
|
||
The right edge of the balloon.
|
||
@item see
|
||
The end of the balloon's line where the message's last line is located if and only
|
||
if the message contains more than one line.
|
||
@item se
|
||
The bottom right corner of the balloon.
|
||
@item sse
|
||
If both this string and the @var{ssw} string fits between the bottom corners, this
|
||
is printed directly to the left of the bottom right corner.
|
||
@item s
|
||
The bottom edge of the balloon.
|
||
@item ssw
|
||
If both this string and the @var{sse} string fits between the bottom corners, this
|
||
is printed directly to the right of the bottom left corner.
|
||
@item sw
|
||
The bottom left corner of the balloon.
|
||
@item sww
|
||
The beginning of the balloon's line where the message's last line is located if and
|
||
only if the message contains more than one line.
|
||
@item w
|
||
The left edge of the balloon.
|
||
@item nww
|
||
The beginning of the balloon's line where the message's first line is located if and
|
||
only if the message contains more than one line.
|
||
@end table
|
||
|
||
|
||
@node Printing in TTY with KMS
|
||
@section Printing in TTY with KMS
|
||
@cindex TTY
|
||
@pindex Linux VT
|
||
@cindex clearing TTY
|
||
@cindex KMS
|
||
@cindex kernel mode setting
|
||
|
||
Since Linux VT (TTY) does not have capabilities for returning the position of the
|
||
cursor, the screen must always be cleared before printing the ponies to make sure
|
||
the pony's colours is not lost, i.e. reduced to mare 16 colours, during print. The
|
||
colours are reduced if the pony's position on the screen is changed. This is only
|
||
relevant with KMS support. The clear the screen we print ``@code{\e[H\e[2J}''
|
||
(@code{\e} is ESC) in at beginning. ``@code{\e[H}'' places the cursor at the
|
||
beginning of the screen, and ``@code{\e[2J}'' clears everything on the screen after,
|
||
and including at, the cursor. If we would use ``@code{\ec}'' (that is a reset),
|
||
we would also turn off num. lock and caps. lock.
|
||
|
||
|
||
@node Truncation
|
||
@section Truncation
|
||
@cindex truncation
|
||
@cindex output truncation
|
||
@cindex KMS
|
||
@cindex kernel mode setting
|
||
|
||
Ponysay supports three type of output truncations, cutting away overflow on the right
|
||
and truncation the height by either keeping the bottom or keeping the top. By default
|
||
the latest is enabled under TTY, cutting away overflow on the right is always enabled
|
||
by default.
|
||
|
||
Truncating the height in TTY is required under Kernel Mode Setting (KMS) support to
|
||
keep the colours from being messed up when the ponies is moved in the screen during
|
||
print. Prior to version 2.0 this was done either by piping to @command{head} (keeps
|
||
the top) or by piping to @command{tail} (keeps the bottom.) @command{head} and
|
||
@command{tail} takes as argument the number of lines to keep at most.
|
||
|
||
The size of the terminal, measured in characters, is fetched from @command{stty size},
|
||
which returns @code{HEIGHT WIDTH}, and @command{cut} it the used to get either the
|
||
height or the width. This requires only GNU Coreutils; earlier @command{tput rows} and
|
||
@command{tput cols} were used, this however required, the only de facto standard,
|
||
package @command{ncurses}, some shells have environment variables for this.
|
||
|
||
Since version 2.1 truncation is done internally in the Python script, before that it
|
||
was done in a custom C program @command{truncater}, that was installed to
|
||
@file{/usr/lib/ponysay/truncater}. It recognised UTF-8 ANSI escape sequences,
|
||
including OSI P and CSI m, which is essential for the truncation to be correct. It
|
||
also expands tabs to every eighth column and resets the background colour when needed,
|
||
and writes ANSI escape sequences that are on the left side of the truncation. The
|
||
truncater stops CSI sequences on the first ASCII letter (@code{[a-zA-Z]}), but also
|
||
stops escape sequences after the first character after the initial escape if it is
|
||
not either @code{[} (CSI) or @code{]} (OSI). In the previous, C, program it supported
|
||
UTF-8 by assuming that bytes do not match @code{10xxxxxx} and only those bytes were
|
||
visible. This now fixed internally in Python, but has also been improved to exclude
|
||
combining characters from the set of visible characters. Another difference is that
|
||
the background colours are not reset, instead ANSI colours after the truncation point
|
||
are still printed.
|
||
|
||
|
||
@node Languages
|
||
@section Languages
|
||
@cindex languages
|
||
@cindex script languages
|
||
@cindex program languages
|
||
|
||
Before version 2.0 @command{ponysay} was written primarily in GNU Bash script; the
|
||
truncater was however written in C, because it is simple, fast, does not pose
|
||
addition dependencies, and is easy to do byte hacking in.
|
||
|
||
Sometimes shell is too slow, in these cases Perl was used; Perl was already required
|
||
by @command{cowsay}, it is also similar to shell, but also supports hash tables.
|
||
|
||
However since version 2.0 we were trying to move from all there languages and only
|
||
use Python 3, which as been accomplished in version 2.1.
|
||
|
||
|
||
@node Shell auto-completion
|
||
@section Shell auto-completion
|
||
@cindex auto-completion, inner workings
|
||
@cindex shell, auto-completion
|
||
@opindex @option{--onelist}
|
||
@opindex @option{++onelist}
|
||
@opindex @option{--Onelist}
|
||
@opindex @option{--quoters}
|
||
@pindex @command{auto-auto-complete}
|
||
|
||
To make it easier to write auto-completion for shells, @command{ponysay} supports
|
||
the options @option{--onelist}, @option{++onelist}, @option{--Onelist} and
|
||
@option{--quoters}, which has no short versions. To make it even easier we use
|
||
@command{auto-auto-complete} (@url{https://www.github.com/maandree/auto-auto-complete})
|
||
to generate auto-completion scripts, currently it supports @command{bash},
|
||
@command{fish} and @command{zsh}, the built system uses that program to generate
|
||
completion for each shell.
|
||
|
||
Executing @command{ponysay --onelist} will list every available standard (MLP:FiM)
|
||
pony, independent of where it is located, the output is a sorted and consists only
|
||
of one pony per line.
|
||
|
||
Executing @command{ponysay ++onelist} will list every available extra (non-MLP:FiM)
|
||
pony, independent of where it is located, the output is a sorted and consists only
|
||
of one pony per line.
|
||
|
||
Executing @command{ponysay --Onelist} will list every available standard pony as
|
||
well as extra pony, independent of where it is located, the output is a sorted and
|
||
consists only of one pony per line.
|
||
|
||
@command{ponysay --quoters} work just as @command{ponysay --onelist}, excepts
|
||
it limits the ponies to those that have quotes. Ponies that have quotes,
|
||
but does not exist, i.e. does not have a .pony-file, are not listed.
|
||
|
||
Auto-completion scripts should not suggest these options.
|
||
|
||
|
||
@node Universal Character Set
|
||
@section Universal Character Set
|
||
@cindex Universal Character Set
|
||
@cindex UCS
|
||
@cindex Unicode
|
||
@cindex pony names
|
||
|
||
In earlier versions of @command{ponysay} only the output truncation supported
|
||
Universal Character Set, though handcoded UTF-8 character counting. Now
|
||
@command{ponysay} lets Python decode the data, Python store all 31 bits of a
|
||
character in as one character, not in UTF-16 as some other languages does, this
|
||
means that the code is agnostic to the character encoding. However in Unicode
|
||
6.1 their are four ranges of combining characters, these do not take up any
|
||
width in proper terminal, we therefore have a class in the code named @code{UCS}
|
||
that help us take them into consideration when determine the length of a string.
|
||
|
||
Some ponies have names that contain non-ASCII characters, read about it in
|
||
@ref{Environment variables}. The UCS names are stored in the file @file{share/ucsmap},
|
||
in it lines that are not empty and does not start with a hash (@code{#}) are
|
||
parsed, and contains a UCS name and a ASCII:ised name. The UCS name comes first,
|
||
followed by the ASCII:ised name that the UCS name should replace or link towards.
|
||
The two names are separated by and simple left to right arrow character [U+2192],
|
||
optionally with surrounding white space.
|
||
|
||
It is important that the UCS names are stored in a file and not in file names,
|
||
because it can cause problems on some platforms.
|
||
|
||
|
||
|
||
@node Contributing
|
||
@chapter Contributing
|
||
@cindex contributing
|
||
|
||
@menu
|
||
* Providing ponies:: Providing ponies.
|
||
* Pony naming guildlines:: Suggestions on how to name your pony files.
|
||
@end menu
|
||
|
||
@node Providing ponies
|
||
@section Providing ponies
|
||
@cindex create pony file
|
||
|
||
Most pony images are browser ponies or desktop ponies, browser ponies is a port of
|
||
desktop ponies, implementing it in JavaScript. Browser ponies are available at
|
||
@url{https://github.com/panzi/Browser-Ponies}. Desktop ponies are available at
|
||
@url{http://desktop-pony-team.deviantart.com/}.
|
||
|
||
There is also a collection of ponies that are not yet pixelated in a Java
|
||
reimplementation of the early Ponysay:
|
||
@url{https://github.com/maandree/unisay/tree/develop/dev/newponies}
|
||
|
||
There is a checklist named @file{pony-checklist} at the @file{dev/} directory. You
|
||
can use the check which ponies are added and which are not. Please update it when fit.
|
||
@*
|
||
|
||
New ponies can be created from regular images by using util-say, which is available
|
||
at @url{https://github.com/maandree/util-say}.
|
||
Prior to version 2.1 of @command{ponysay}, @command{img2xterm} could be used, by since
|
||
version 2.1 @command{ponysay} is using a new format that only util-say supports.
|
||
@command{img2xterm} (@url{https://github.com/rossy2401/img2xterm}) was used in the
|
||
early stage, but util-say tries to optimise the images in some aspects: as good as
|
||
possible for low capability terminals, tries to place the pony–balloon link, displayed
|
||
as good as possible when marked in the terminal (somewhat compromised by the first
|
||
aspect,) and same width on all rows.
|
||
|
||
Using util-say:
|
||
@pindex util-say
|
||
@pindex @command{img2ponysay}
|
||
@cartouche
|
||
@example
|
||
@command{img2ponysay -2 -- SOURCE_IMAGE > PONY_FILE}
|
||
|
||
@code{PONY_FILE} should end with @file{.pony} and be localed in @file{ponies/},
|
||
or @file{extraponies/} if the pony is not a MLP:FiM pony.
|
||
|
||
Omit @option{-2} if the source image does not use double pixel size.
|
||
|
||
For more information is available in util-say's info manual. @command{img2ponysay}
|
||
is a legacy command that uses the default settings of @command{ponytool} for
|
||
converting a image file to a pony file.
|
||
@end example
|
||
@end cartouche
|
||
|
||
@*
|
||
@pindex util-say
|
||
@cindex .png
|
||
@cindex PNG images
|
||
@cindex images, PNG
|
||
@cindex Portable Network Graphics
|
||
If you have util-say installed, which is required to build ponies, you can use PNG
|
||
files as argument the for @command{ponysay -f}, this requires that the file is named
|
||
@file{.png} at the end.
|
||
|
||
@cindex palette
|
||
@cindex xterm palette
|
||
@cindex pony palette
|
||
@cindex colour palette
|
||
The following @command{bash} code will print the palette the ponies (the terminals)
|
||
use:
|
||
@cartouche
|
||
@example
|
||
c=16
|
||
while ((c < 256)); do
|
||
echo -en "\e[48;5;$@{c@}m \e[49m"
|
||
c=$(( $c + 1 ))
|
||
if (( $(( c % 36 )) == 16 )); then
|
||
echo
|
||
fi
|
||
done; echo
|
||
@end example
|
||
@end cartouche
|
||
|
||
@*
|
||
For the palette to be correct, which is especially important when you draw ponies, you
|
||
must not redefine the colours in the range 16 to 255 (inclusive).
|
||
|
||
@cindex ttypony
|
||
When a pony is added please also add a ttypony version, i.e. the pony files used in
|
||
TTY, but if you don't please state so in the pull request so we do not miss the
|
||
create it; the simplest way to do this is to run @command{dev/dist.sh ttyponies} after
|
||
adding the ponies to @file{ponies/}, running @command{dev/dist.sh ttyponies} will build
|
||
(or rebuild) all ttyponies with a pony present in @file{ponies/}, and creates all
|
||
needed symlinks.
|
||
|
||
To be able to run @command{dev/dist.sh ttyponies} you must have the packages listed under
|
||
@ref{Dependencies for pony providers}.
|
||
|
||
@cindex ponyquotes
|
||
@cindex quotes
|
||
Also when adding new ponies, please map them up in the file @file{ponyquotes/ponies}.
|
||
If the pony is a new pony without any other alternative image just add it to a new
|
||
line, without @file{.pony}, preferably in its alphabetical position. If the file is
|
||
a symlink add it to the same line as the target pony, and if the pony has and
|
||
alternative image add it the the same line as that pony. Ponies on the same line are
|
||
separated with a plus sign (@code{+}) without any white space. When a line is too
|
||
long for a file name (this has happened to Pinkie Pie [@file{pinkie}],) it must be
|
||
split into multiple lines, these lines should have their first pony file in common.
|
||
|
||
|
||
@node Pony naming guildlines
|
||
@section Pony naming guildlines
|
||
@cindex naming ponies
|
||
@cindex pony naming
|
||
|
||
These are not rules, this are guildlines you can use when in doubt on how you
|
||
want to name your ponies. That is, these are only suggestioned based on observion
|
||
of current practice and discussions, it is probable that these suggestions are
|
||
not optimal in complex cases.
|
||
|
||
Try to follow the MPL Wikia on @url{http://mlp.wikia.com/wiki/List_of_ponies},
|
||
if it is in conflict with an authorised game, such as Gameloft, it is more likly
|
||
that that game has make an error, especially ignore a game on palette mismatch,
|
||
and the Wikia is probabily more agreed with by fans.
|
||
|
||
Sometimes there are background ponies with the same palette and cutie mark, but
|
||
of different kinds (earth pony, unicorn, pegasus and so on). In these cases the
|
||
Wikia often list them as the same pony, they are given the same name. When this
|
||
happens you can name the pony that appears first in the show just the name and
|
||
append either `earth', `unicorn' or `pegasus' depending on the kind. If the pony
|
||
is a background alicorn, it is a princess and is titled as such, you can bet your
|
||
sweet flank the Wikia will have given her a royal name.
|
||
|
||
When there are many alternative names, but no official, use one you think is most
|
||
recognised or your personal favourite. It with short names when the names are similar.
|
||
|
||
|
||
|
||
@node Distributing
|
||
@chapter Distributing
|
||
@cindex distributing ponysay
|
||
@cindex package maintaining
|
||
@cindex OS package maintaining
|
||
@cindex maintaining OS package
|
||
@cindex FHS
|
||
@cindex filesystem hierarchy standard
|
||
|
||
If you are planning on maintaining @command{ponysay} in your favourite operating
|
||
system you should first read @ref{Required runtime dependencies} and
|
||
@ref{Optional runtime dependencies}. If your OS does not follow Filesystem Hierarchy
|
||
Standard (FHS), e.g. installing amusement binaries in @file{/usr/games} instead of
|
||
@file{/usr/bin} or only supporting @file{/opt} equivalent directories you should
|
||
read about configurations in @ref{Custom installations}.
|
||
|
||
Apart from this, you should configure @command{ponysay} before building it with the
|
||
option @option{--everything}. Otherwise only the @command{info} manual and the
|
||
English manpage will be installed for documentation.
|
||
|
||
Please inform us about your distribution so we can list it so everypony can see it.
|
||
|
||
@*
|
||
The following is a reference distribution written in Arch Linux's PKGBUILD format.
|
||
It is not complete, proper, verbose enough or well written, it just contains the
|
||
core of an stable @command{git} distribution.
|
||
|
||
@cartouche
|
||
@example
|
||
pkgname=ponysay
|
||
pkgver=3.0
|
||
pkgrel=1
|
||
arch=(any)
|
||
pkgdesc="Cowsay reimplementation for ponies"
|
||
url="https://github.com/erkin/ponysay"
|
||
license=('GPL3' 'GNU FDL v1.3')
|
||
depends=(python>=3 coreutils)
|
||
optdepends=("util-say>=3: Improved TTY support with KMS and PNG files")
|
||
makedepends=('git' 'texinfo' 'info' 'gzip' 'python>=3', 'zip')
|
||
|
||
build()
|
||
@{ cd "$srcdir"; git clone git://github.com/erkin/ponysay.git ponysay
|
||
cd ponysay ; git checkout "$pkgver"
|
||
|
||
./setup.py --everything --without-pdf-compression \
|
||
--bin-dir=/usr/bin --dest-dir="$pkgdir" \
|
||
--freedom=parital build
|
||
|
||
# CHANGE --freedom=parital to --freedom=strict
|
||
# FOR ONLY COMPLETELY FREE PONIES,
|
||
# useful for GNU/Linux-libre distributions
|
||
@}
|
||
|
||
package()
|
||
@{ cd "$srcdir/ponysay"; ./setup.py prebuilt
|
||
@}
|
||
@end example
|
||
@end cartouche
|
||
|
||
|
||
|
||
@node Terminology
|
||
@chapter Terminology
|
||
@cindex terminology
|
||
|
||
@table @i
|
||
@item MLP:FiM
|
||
@cindex MLP:FiM
|
||
The television show My Little Pony: Friendship is Magic.
|
||
|
||
@item My Little Pony
|
||
@cindex My Little Pony
|
||
The successor to My Pretty Pony, the toy not the short story by Stephen King.
|
||
|
||
@item TTY
|
||
@itemx Linux VT
|
||
@cindex TTY
|
||
@pindex Linux VT
|
||
Linux's native terminal emulator. The name TTY comes from the file names for the
|
||
devices used for terminals by Linux VT, which is @file{/dev/tty*}.
|
||
|
||
@item KMS
|
||
@itemx Kernel Mode Setting
|
||
@cindex KMS
|
||
@cindex kernel mode setting
|
||
A feature in Linux allowing mode setting in kernel-space, this gives the TTY,
|
||
for example better colour support. I would go to Wikipedia for more information.
|
||
|
||
@item ttyponies
|
||
@cindex ttyponies
|
||
Pony files used in TTY.
|
||
|
||
@item kmsponies
|
||
@cindex kmsponies
|
||
Pony files generated for use in TTY with custom TTY colour palette and KMS support.
|
||
|
||
@item extraponies
|
||
@itemx extra ponies
|
||
@cindex extraponies
|
||
@cindex extra ponies
|
||
Pony files of ponies that are not a part of MLP:FiM.
|
||
@item standard ponies
|
||
@cindex standard ponies
|
||
|
||
Pony files of ponies that are a part of MLP:FiM.
|
||
@item systemponies
|
||
@itemx sysponies
|
||
@cindex systemponies
|
||
@cindex sysponies
|
||
Pony files located in @file{/usr/share/ponysay}.
|
||
|
||
@item homeponies
|
||
@itemx usrponies
|
||
@cindex homeponies
|
||
@cindex usrponies
|
||
Pony files located in @file{$@{XDG_DATA_HOME@}/ponysay} or @file{~/.local/share/ponysay} (fallback).
|
||
|
||
@item browser ponies
|
||
@cindex browser ponies
|
||
@cindex desktop ponies
|
||
A JavaScript program which is the source for most of our ponies. It is a port of
|
||
@i{desktop ponies}.
|
||
|
||
@item ponification
|
||
@cindex ponification
|
||
The process of converting English text to Equestrian English.
|
||
|
||
@item Equestrian English
|
||
@cindex Equestrian English
|
||
The English dialect spoken by the ponies in MLP:FiM, the basic role is that it
|
||
is American English with as many words and parts of words as possible exchanged
|
||
to words having to do with ponies, including the work `pony' itself. This is
|
||
normally the language we, the developers, write in, except we may use another
|
||
English, e.g. British English, as the base language.
|
||
|
||
@item best.pony
|
||
@cindex best.pony
|
||
The pony you think is [the] best pony. It should be a symlink pony. It is a feature
|
||
affecting the @option{-f}, @option{+f}, @option{-F} and @option{-q} options.
|
||
|
||
@item pony symlink
|
||
@itemx symlink pony
|
||
@cindex pony symlink
|
||
@cindex symlink pony
|
||
A pony file that is a symbolic link to another pony file. Symbolic links can be
|
||
created with the command @command{ln -s TARGET SYMLINK}.
|
||
|
||
@item ponyquotes
|
||
@cindex ponyquotes
|
||
A feature enabling ponies to quote them self from MLP:FiM.
|
||
|
||
@item environment variables
|
||
@cindex environment variables
|
||
Variables stored to the environment with the command @command{export VARIABLE=VALUE}.
|
||
The variable name is often written with the prefix @code{$} due to have they are read
|
||
in shell, using the command @command{echo $VARIABLE}.
|
||
|
||
@item UCS
|
||
@itemx Universal Character Set
|
||
@cindex UCS
|
||
@cindex Universal Character Set
|
||
The set of of character, develop by the Unicode Consortium. It defined a partially filled
|
||
space of @math{2^{31}} characters, some of which are not glyphs.
|
||
|
||
@item combining characters
|
||
@cindex combining characters
|
||
Character that have zero width and is used to compose characters with diacritical when
|
||
there is no precomposed character to use.
|
||
|
||
@item ASCII
|
||
@itemx ASCII character
|
||
@cindex ASCII
|
||
@cindex character
|
||
American Standard Code for Information Interchange (ASCII) defines 128 characters, some
|
||
are not glyphs. It contains control characters, basic punctuation, the decimal digit,
|
||
and lower case and upper case English alphabet characters @code{a-z}.
|
||
|
||
@item short options
|
||
@cindex short options
|
||
Command line arguments starting with either exactly one hyphen (@code{-}) or exactly one
|
||
plus sign (@code{+}), and have exactly one character beyond that. They may be argumentless,
|
||
argumented, optionally argumented, or variadic (consumes all following arguments).
|
||
|
||
@item long options
|
||
@cindex long options
|
||
Command line arguments starting with either at least two hyphens (@code{-}) or at least two
|
||
plus signs (@code{+}), beyond that they have at least one character, but often at least one
|
||
work. They by be argumentless, argumented, optionally argumented, or variadic (consumes all
|
||
following arguments).
|
||
|
||
@item completion
|
||
@itemx auto-completion
|
||
@itemx shell completion
|
||
@itemx shell auto-completion
|
||
@cindex completion
|
||
@cindex auto-completion
|
||
@cindex shell completion
|
||
@cindex shell auto-completion
|
||
Provided by a shell dependent script, argument suggestion is provided of then by pressing
|
||
the tab key.
|
||
|
||
@item ANSI escape sequences
|
||
@itemx escape sequences
|
||
@cindex ANSI escape sequences
|
||
@cindex escape sequences
|
||
Character sequences starting with a ESC character, with a special interpretation for terminals
|
||
standardise by ANSI.
|
||
|
||
@item ANSI colour sequences
|
||
@itemx ANSI colours
|
||
@itemx colour sequences
|
||
@cindex ANSI colour sequences
|
||
@cindex ANSI colours
|
||
@cindex colour sequences
|
||
ANSI escape sequences defining a colour or other formatting, known as CSI m, a sequence starting
|
||
with CSI and ending with an @code{m}. This is extended to 256 colours, from 16 colours, by
|
||
@command{xterm} which is de facto standardise.
|
||
|
||
@item CSI
|
||
@cindex CSI
|
||
The character combination ESC followed by @code{[}, used in standardised ANSI escape sequences.
|
||
|
||
@item OSI
|
||
@cindex OSI
|
||
The character combination ESC followed by @code{]}, used in non-standardised ANSI escape
|
||
sequences.
|
||
@end table
|
||
|
||
|
||
|
||
@node Change log
|
||
@appendix Change log
|
||
@cindex change log
|
||
@cindex versions
|
||
@cindex previous releases
|
||
|
||
@heading Version 3.0.2
|
||
@itemize @bullet
|
||
@item
|
||
New ponies: @file{brucemane}, @file{deepblue}, @file{hairytipper}, @file{peachbottom}, @file{rainbowdrop},
|
||
@file{strawberrycream}, @file{wildflower}
|
||
@item
|
||
New extraponies: @file{milky}
|
||
@item
|
||
Default value for @option{-W}, the message wrapping column, has been changed from 40 to 60, to wrap messages better.
|
||
@end itemize
|
||
|
||
@heading Version 3.0.1
|
||
@itemize @bullet
|
||
@item
|
||
New ponies: @file{harshwhinny}
|
||
@item
|
||
All ponies has been reviewed and improved when needed.
|
||
@item
|
||
The @command{ponysay-tool} command is now installed.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 3.0
|
||
@itemize @bullet
|
||
@item
|
||
New ponies: @file{applesplit}, @file{amira}, @file{babseed}, @file{bear}, @file{beautybrass}, @file{bigmacsleep},
|
||
@file{billneiigh}, @file{cadancecrystal}, @file{cadancescruffy}, @file{cloudchaser}, @file{descent}, @file{gingersnap},
|
||
@file{haakim}, @file{hayseed}, @file{jubileena}, @file{featherweight}, @file{fiddlesticks}, @file{flitter}, @file{lighningdust},
|
||
@file{midnightstrike}, @file{mrbreezy}, @file{orangebird}, @file{orangefrog}, @file{pansyshy}, @file{pinkiecrazyface},
|
||
@file{princesserroria}, @file{poundcake}, @file{raccoon}, @file{rainbowblitz}, @file{rarity}, @file{ravenearth}, @file{ravenunicorn},
|
||
@file{royalunicornguard}, @file{rumble}, @file{shiningarmorcrystal}, @file{sombra}, @file{spikecrystal}, @file{squirrel},
|
||
@file{sweetcream} (IDW Comic Issue #1), @file{trixieamulet}, @file{twilacorn}, @file{twilightcrystal}, @file{twilightfly}, @file{twilightpricess},
|
||
@file{twilightwings}, @file{twinkleshine}
|
||
@item
|
||
New extraponies: @file{donutpony}, @file{gleamingshield}, @file{hastelle}, @file{johndelancie}, @file{jristz}, @file{maandree}, @file{orion},
|
||
@file{pipsqueak}, @file{pardise}, @file{pizzapony}, @file{snowdrop}, @file{tempo}, @file{ticket}
|
||
@item
|
||
@file{lotusbloosom} has been renamed to @file{lotusblossom} (typo)
|
||
@item
|
||
@file{maredowellgallop} has been renamed to @file{maredowellgallop} (need a version named as master)
|
||
@item
|
||
@file{ironwillwalk} has been renamed to @file{ironwillwalk} (need a version named as master)
|
||
@item
|
||
Renamed option @option{-F} to @option{+f} and option @option{--F} to @option{++f}, @option{-F} and @option{--F} has new definitions.
|
||
@item
|
||
Environment variable @env{PONYSAY_TYPO_LIMIT} has been added.
|
||
@item
|
||
Environment variable @env{PONYSAY_WRAP_HYPHEN} has been added.
|
||
@item
|
||
Environment variable @env{PONYSAY_WRAP_LIMIT} has been added.
|
||
@item
|
||
Environment variable @env{PONYSAY_WRAP_EXCEED} has been added.
|
||
@item
|
||
Added support for @file{~/.ponysayrc} with the alternatives: @file{$@{XDG_CONFIG_HOME@}/ponysay/ponysayrc}
|
||
and @file{~/.config/ponysay/ponysayrc} as well as the global fallback @file{/etc/ponysayrc}
|
||
@item
|
||
@option{-f}, @option{+f} and @option{-q} may be unargumented if that are at the end of the command line.
|
||
@item
|
||
@command{ponysay-tool} is introduced, it can be used to edit, remove and copy pony meta data, and more.
|
||
@item
|
||
@command{ponysay-tool --kms} generates all kmsponies for the current TTY palette.
|
||
@item
|
||
Pony metadata tags @var{BALLOON TOP} and @var{BALLOON BOTTOM} can be used to specify how much extra
|
||
height the balloon causes at the top and at the bottom of the pony.
|
||
@item
|
||
@file{$@{XDG_DATA_HOME@}/ponysay/*} is allowed in favour of @file{$@{HOME@}/.local/share/ponysay/*}
|
||
@item
|
||
Balloons can be have and explicit minimum column span with placement justification.
|
||
@item
|
||
Only ponies that fit the terminal will be randomly selected (for directory with pony
|
||
dimension files generated), however if no pony fits, any of the can be randomly selected.
|
||
@item
|
||
Setup option @option{--sysconf-dir} with default value @file{/etc} added,
|
||
@item
|
||
New manditory setup option @option{--freedom}.
|
||
@item
|
||
Pony metadata options added: @option{--info}, @option{++info} and @option{--restrict}.
|
||
@item
|
||
@file{fillycelestia} and @file{filliestia} has been moved to @file{extraponies}.
|
||
@item
|
||
@file{shadowbolts} has been renamed to @file{nightingale} (shadowbolts split)
|
||
@item
|
||
@file{lily} has been renamed to @file{lilyvalley} (official name)
|
||
@item
|
||
@file{sweatiesing} has been renamed to @file{sweetising} (name consistency)
|
||
@item
|
||
@file{carecake} has renamed into @file{carrotcake} (official full name)
|
||
@item
|
||
@file{peppermoon} has renamed to @file{pepermoon} (typo)
|
||
@item
|
||
@file{maria} has been renamed to @file{danger} (name given by the author)
|
||
@item
|
||
@file{maliot} renamed to @file{melilot} (typo)
|
||
@item
|
||
Pony symlink added:
|
||
@itemize @bullet
|
||
@item @file{lily} @arrow{} @file{lilyvalley}
|
||
@item @file{sweetiedrops} @arrow{} @file{bonbon}
|
||
@item @file{carecake} @arrow{} @file{carrotake}
|
||
@item @file{berrydreams} @arrow{} @file{blueberry}
|
||
@end itemize
|
||
@item
|
||
The license has been changed to the GNU General Public License version 3+, from WTFPL 2.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 2.9.1
|
||
@itemize @bullet
|
||
@item
|
||
Bug fix: correction in the -W option broke the -o option.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 2.9
|
||
@itemize @bullet
|
||
@item
|
||
New ponies: @file{pinkieumbrelahatfear}, @file{twilighttime}
|
||
@item
|
||
New extraponies: @file{molestia} (Tumblr)
|
||
@item
|
||
The option @option{-q} works like @option{-f} and @option{-F}, it takes one argument, and
|
||
may be used multiple times for more arguments.
|
||
@item
|
||
The old option @option{-q} is renamed to @option{--q}.
|
||
@item
|
||
The options @option{--f} and @option{--F} has been added.
|
||
@item
|
||
Weighted distance for autocorrection on pony names and boolean style name is set to 5, rather
|
||
than unlimited. Currently this cannot be modified (without editing the source code.)
|
||
@item
|
||
If file descriptor 3 is definied when @command{ponysay} is executed, extra information is
|
||
printed to it.
|
||
@item
|
||
Arguments starting with @code{n} or @code{i} is allowed for @option{-W}.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 2.8
|
||
@itemize @bullet
|
||
@item
|
||
New ponies: @file{airheart}, @file{bastionyorsets}, @file{gustavelegrand}, @file{milkyway},
|
||
@file{peppermoon}, @file{pinkacopter}, @file{pinkiefly}, @file{pinkieparade},
|
||
@file{pinkieumbrellahat}, @file{shiningarmorwedding}, @file{soaringofficer},
|
||
@file{starlight}, @file{sunnyrays}, @file{sweatiesing}, @file{tenderheart}, @file{tom},
|
||
@file{twilightspike}, @file{zecorabalance}
|
||
@item
|
||
New extraponies: @file{applejack} (Tumblr), @file{applejack-63}, @file{artemis}, @file{blueberry},
|
||
@file{butterscotch}, @file{drhoovesdiscorded} (Tumblr), @file{duskshine}, @file{elusive},
|
||
@file{rainbowblitz}
|
||
@item
|
||
Pony symlink added:
|
||
@itemize @bullet
|
||
@item @file{georgewashingtony} @arrow{} @file{bastionyorsets}
|
||
@end itemize
|
||
@item
|
||
Support for explicit hyphenation using soft hyphens had been added to the word wrapper.
|
||
@item
|
||
Support for explicit non-word wrapping using non-breaking space had been added to the word wrapper.
|
||
@item
|
||
The word wrapper colours the inserted hyphens in red.
|
||
@item
|
||
Support for terminal capabilities emulation with the flags @option{-X}, @option{-V} and @option{-K}.
|
||
@item
|
||
Support for printing just the pony, using the flag @option{-o}.
|
||
@item
|
||
Colouring option flags are added.
|
||
@item
|
||
Automatic correction of incorrectly spelled pony names and balloon style names added.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 2.7
|
||
@itemize @bullet
|
||
@item
|
||
New ponies: @file{basil}, @file{cloudkicker}, @file{cerberus}, @file{cow}, @file{derpysad},
|
||
@file{flowertrio}, @file{frederickhorseshoepin}, @file{horsemd}, @file{jeffletroski},
|
||
@file{jesuspezuna}, @file{joe}, @file{joetuxedo}, @file{manticore},
|
||
@file{meadownsong}, @file{meliot}, @file{pinkiegummydisguise}, @file{seaswirl},
|
||
@file{theodoredonaldkerabatsos}, @file{turf}, @file{waltercoltchak}
|
||
@item
|
||
New extraponies: @file{blueballblitz} (Varous fanfics, Shadowbolt), @file{drhooves1},
|
||
@file{drhooves2}, @file{drhooves3}, @file{drhooves4}, @file{drhooves5}, @file{drhooves6},
|
||
@file{drhooves7}, @file{drhooves8}, @file{drhooves9}, @file{drhooves10}, @file{drhooves11},
|
||
@file{nyx} (Fanfic: Past Sins), @file{nyxdisguised} (Fanfic: Past Sins),
|
||
@file{pinkaminacupcake} (Fanfic)
|
||
@item
|
||
@file{cracky} is renamed to @file{crackle}.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 2.6
|
||
|
||
@itemize @bullet
|
||
@item
|
||
New ponies: @file{applebloomdance}, @file{blueberry}, @file{blueberrycake}, @file{blueharvest},
|
||
@file{candylicious}, @file{cherrycola}, @file{cracky}, @file{cutiemarkcrusaders},
|
||
@file{derpybags}, @file{derpycloud}, @file{firestreak}, @file{hughjelly}, @file{lemonhearts},
|
||
@file{lyrabonbon}, @file{noi}, @file{pictureperfect}, @file{poppycock}, @file{quickfix},
|
||
@file{silverspeed}, @file{rainbowhurricane}, @file{rainbowshadowbolt}, @file{silverspeed},
|
||
@file{surprise} (wonderbolt), @file{thunderlane}, @file{timeturner}, @file{twilightthebearded}
|
||
@item
|
||
New extraponies: @file{faust} (alicorn), @file{maria} (Moonstuck, seapony), @file{posey} (Tumblr),
|
||
@file{slanderpony}, @file{sparkler} (Tumblr), @file{twilight} (Tumblr)
|
||
@item
|
||
Pony symlink added:
|
||
@itemize @bullet
|
||
@item @file{bonbonlyra} @arrow{} @file{lyrabonbon}
|
||
@item @file{epona} @arrow{} @file{quickfix}
|
||
@item @file{clockwork} @arrow{} @file{quickfix}
|
||
@item @file{drhooves} @arrow{} @file{timeturner}
|
||
@item @file{lotusbloosom} @arrow{} @file{lotus}
|
||
@end itemize
|
||
@item
|
||
@file{doctor} and @file{doctornohat} has become extraponies,
|
||
because their mane style is differenct from in the TV show.
|
||
And @file{timeturner} no longer links to any of them.
|
||
@item
|
||
@command{./configure} and @command{make} is no longer support.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 2.5.1
|
||
|
||
@itemize @bullet
|
||
@item
|
||
New extraponies: @file{sealyra}
|
||
@item
|
||
Build system as compatibility with standard GNU Make build system.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 2.5
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Brand new highly configurable build system.
|
||
@item
|
||
UTF-8 as I/O encoding is enforced. (Critical bug fix for ASCII locale users.)
|
||
@end itemize
|
||
|
||
|
||
@heading Version 2.4
|
||
|
||
Nothing worth mentioning.
|
||
|
||
@b{Note}: Identifies itself as version 2.3
|
||
|
||
|
||
@heading Version 2.3
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Support for @file{best.pony} file.
|
||
@item
|
||
@option{-q} accepts file names.
|
||
@item
|
||
Improved Unicode support: treats combining characters as invisible.
|
||
@item
|
||
Optional support for UCS pony names.
|
||
@item
|
||
Pony files and balloon style files can be pipes (as well as sockets, doors
|
||
and as always regular files.)
|
||
@item
|
||
Support cowsay style message compression.
|
||
@item
|
||
New ponies: @file{blaze}
|
||
@item
|
||
New extraponies: @file{fyrefly} (Tumblr), @file{surprise} (Tumblr), @file{woona}
|
||
(moonstuck), @file{woonanohat} (moonstuck)
|
||
@item
|
||
Pony symlink added:
|
||
@itemize @bullet
|
||
@item @file{pinkieoink} @arrow{} @file{oinkoinkoink}
|
||
@end itemize
|
||
@item
|
||
Support for non-MLP:FiM ponies (known as extraponies).
|
||
@c BEGIN the following is too descriptive for the plain/text change log
|
||
This is implemented with the options @option{-F}, @option{+l}, and @option{+L}
|
||
corresponding to @option{-f}, @option{-l}, and @option{-L}.
|
||
@c END
|
||
@end itemize
|
||
|
||
|
||
@heading Version 2.2
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Full support for arbitrary positioning of balloon in pony files.
|
||
@item
|
||
ANSI colour sequences in pony files are applied only to the pony image,
|
||
not the balloon link or the balloon itself.
|
||
@item
|
||
Support for colours in the message.
|
||
@item
|
||
Support custom balloon styles using the option @option{-b}, @option{-B} will list
|
||
all available. This list depends on whether you are invoking @command{ponysay}
|
||
or @command{ponythink}
|
||
@end itemize
|
||
|
||
|
||
@heading Version 2.1.1
|
||
|
||
Nothing worth mentioning.
|
||
|
||
|
||
@heading Version 2.1
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@file{applebumkin} is renamed to @file{applebumpkin}.
|
||
@item
|
||
New ponies: @file{owlowiscious}, @file{purplehaze}
|
||
@item
|
||
Cowsay has be reimplemented, and have full Unicode support and support
|
||
for @command{figlet} style messages.
|
||
@item
|
||
Deleted environment variables: @env{PONYSAY_COWSAY}, @env{PONYSAY_COWTHINK}
|
||
@item
|
||
You will need Python 3, but not GNU Bash, Perl or Cowsay.
|
||
@item
|
||
New .pony file format is used:
|
||
@c BEGIN the following is too descriptive for the plain/text change log
|
||
@command{unisay}'s format instead of @command{cowsay}'s Perl based format.
|
||
This includes arbitrary position of balloon, mirrored balloon links, and
|
||
minimum size of balloon.
|
||
@c END
|
||
@end itemize
|
||
|
||
|
||
@heading Version 2.0
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Makefile is generated by running @command{./configure}.
|
||
@item
|
||
All Perl scripts and almost all Bash are reimplemented in one Python 3 script.
|
||
@item
|
||
kmsponies4ponysay is included.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 1.4.1
|
||
@itemize @bullet
|
||
@item
|
||
Code is repaired and more portable.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 1.4
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Make file is improved.
|
||
@end itemize
|
||
|
||
@b{Note}: Identifies itself as version 1.3
|
||
|
||
|
||
@heading Version 1.3
|
||
|
||
@itemize @bullet
|
||
@item
|
||
New ponies: @file{forestspirit}, @file{hollydash}, @file{raggedy}, @file{rhyme}
|
||
@item
|
||
@file{sindy} is renamed to @file{powderrouge}.
|
||
@item
|
||
Pony symlink added:
|
||
@itemize @bullet
|
||
@item @file{sindy} @arrow{} @file{powderrouge}
|
||
@end itemize
|
||
@item
|
||
@option{PREFIX=/some-dir} can be used when invoking @command{make},
|
||
the default value is @file{/usr}
|
||
@end itemize
|
||
|
||
|
||
@heading Version 1.2
|
||
|
||
@itemize @bullet
|
||
@item
|
||
ponyquotes4ponysay is included.
|
||
@item
|
||
Support for extension: kmsponies4ponysay.
|
||
@item
|
||
Pony symlinks added:
|
||
@itemize @bullet
|
||
@item @file{mrsparkle} @arrow{} @file{nightlight}
|
||
@item @file{elsie} @arrow{} @file{prettyvision}
|
||
@end itemize
|
||
@item
|
||
New ponies: @file{ace}, @file{blueblood}, @file{filthyrich}, @file{gingergold},
|
||
@file{hayfever}, @file{highscore}, @file{junebug}, @file{mrsparkle},
|
||
@file{persnickety}, @file{ponet}, @file{screwloose}, @file{tornadobolt}.
|
||
@item
|
||
@file{elsie} is renamed to @file{prettyvision}.
|
||
@item
|
||
@opindex @option{-f}
|
||
Arbitrary spaces in @option{-f} argument is not longer accepted (it causes
|
||
problems with file names including spaces.)
|
||
@end itemize
|
||
|
||
@b{Note}: Identifies itself as version 1.1
|
||
|
||
|
||
@heading Version 1.1
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Manpages are compressed before installation.
|
||
@item
|
||
@command{info} manual added.
|
||
@item
|
||
Shell completion for @command{ponythink} added, in addition to @command{ponysay}.
|
||
@item
|
||
@command{fish} completion added.
|
||
@item
|
||
@file{/usr/lib/ponysay} is used instead of @file{/usr/bin} for code used by the
|
||
main script.
|
||
@item
|
||
@file{~/.local/share/ponysay} is used for private pony directories.
|
||
@item
|
||
@command{ncurses} is no longer needed for determining the screen's size,
|
||
@command{coreutils} is used instead.
|
||
@item
|
||
Pony symlinks added:
|
||
@itemize @bullet
|
||
@item @file{amethyststar} @arrow{} @file{sparkler}
|
||
@item @file{berrypinch} @arrow{} @file{ruby}
|
||
@item @file{craftycrate} @arrow{} @file{boxxy}
|
||
@item @file{magnum} @arrow{} @file{raritysdad}
|
||
@item @file{pearl} @arrow{} @file{raritysmom}
|
||
@item @file{powderrouge} @arrow{} @file{sindy}
|
||
@item @file{royalribbo} @arrow{} @file{violet}
|
||
@end itemize
|
||
@item
|
||
@w{New ponies:} @file{blossomforth}, @file{bonvoyage}, @file{cadance},
|
||
@file{celestiasmall}, @file{changelingqueen}, @file{cherryberry},
|
||
@file{discordamused}, @file{discordpuppetmaster}, @file{fleurdelishair},
|
||
@file{fleurdelislay}, @file{owl}, @file{perrypierce}, @file{petunia},
|
||
@file{pinacolada}, @file{skyra}, @file{truffleshuffle}.
|
||
@item
|
||
Pony spelling removed: @file{fillycadence}.
|
||
@item
|
||
Pony symlink change: @file{perry} @arrow{} @{@file{pokey} @arrow{} @file{perrypierce}@}.
|
||
@item
|
||
@opindex @option{-L}
|
||
Option @option{-L} added, lists ponies with symlink mapping.
|
||
@item
|
||
Support for extension: ponyquotes4ponysay.
|
||
@item
|
||
@opindex @option{-f}
|
||
Accepts arbitrary spaces in @option{-f} argument.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 1.0
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Spanish translation of the manpage is added.
|
||
@item
|
||
@w{New ponies:} @file{applecore}, @file{applejackscarecrow}, @file{bonbonstand},
|
||
@file{changeling}, @file{chrysalis}, @file{cottoncloudy}, @file{diamondmint},
|
||
@file{discord}, @file{fillycadence}, @file{flam}, @file{fleurdelis}, @file{flim},
|
||
@file{fluttershyshy}, @file{fluttershystare}, @file{lyrasit}, @file{oinkoinkoink}
|
||
(is pinkie), @file{philomenaphoenix}, @file{pinkiecannon}, @file{pinkiecannonfront},
|
||
@file{pinkiecannonhappy}, @file{pinkiegummy}, @file{pinkiehugfluttershy},
|
||
@file{pinkiehugsfluttershy}, @file{pinkiepartycannon}, @file{pinkieprincess},
|
||
@file{pinkiesilly}, @file{pinkietongue}, @file{pinkiewhoops}, @file{pinkiewhoopseat},
|
||
@file{pinkiewhoopsout}, @file{rainbowdrag}, @file{rainbowsalute}, @file{rainbowshine},
|
||
@file{raritydrama}, @file{shiningarmor}, @file{shiningarmorguard}, @file{snowflake},
|
||
@file{spikemustache}, @file{stevenmagnet}, @file{stevenmagnettrue},
|
||
@file{twilightcrazyfromball}, @file{twilightrage}, @file{twilightzero},
|
||
@file{wildfire}.
|
||
@item
|
||
Pony symlinks added:
|
||
@itemize @bullet
|
||
@item @file{djpon-3} @arrow{} @file{vinyl}
|
||
@item @file{fillycadance} @arrow{} @file{fillycadence}
|
||
@item @file{horsepower} @arrow{} @file{snowflake}
|
||
@end itemize
|
||
@item
|
||
Improved TTY support: ponies have low colours resolution, instead of monochrome,
|
||
when the high colour resolution is not available.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 0.10
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Manpage manual added.
|
||
@item
|
||
The directories for pony directories are changed from @file{/usr/share} to
|
||
@file{/usr/share/ponysay} and @file{~} to @file{~/.ponysay}.
|
||
@item
|
||
Pony symlinks added:
|
||
@itemize @bullet
|
||
@item @file{carrottop} @arrow{} @file{carrot}
|
||
@item @file{goldenharvest} @arrow{} @file{carrot}
|
||
@item @file{harpass} @arrow{} @file{lyra}
|
||
@item @file{heartstrings} @arrow{} @file{lyra}
|
||
@item @file{lulamoon} @arrow{} @file{trixie}
|
||
@item @file{minuette} @arrow{} @file{colgate}
|
||
@item @file{noteworthy} @arrow{} @file{blues}
|
||
@item @file{perry} @arrow{} @file{pokey}
|
||
@item @file{pokeypierce} @arrow{} @file{pokey}
|
||
@item @file{timeturner} @arrow{} @file{doctornohat}
|
||
@item @file{trixielulamoon} @arrow{} @file{trixie}
|
||
@item @file{twilightvelvet} @arrow{} @file{mrssparkle}
|
||
@end itemize
|
||
@item
|
||
Support for truncating output on height, enabled by default under TTY.
|
||
@item
|
||
Environment variables added: @env{PONYSAY_FULL_WIDTH}, @env{PONYSAY_SHELL_LINES},
|
||
@env{PONYSAY_TRUNCATE_HEIGHT}, @env{PONYSAY_BOTTOM}.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 0.9
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Output truncated on width to fit screen.
|
||
@item
|
||
Support for TTY (Linux VT).
|
||
@item
|
||
@command{bash} completion added.
|
||
@item
|
||
@command{zsh} completion added.
|
||
@item
|
||
@w{New ponies}: @file{allie}, @file{archer}, @file{boxxy}, @file{carecake},
|
||
@file{cupcake}, @file{daringdo}, @file{davenport}, @file{fancypants},
|
||
@file{ironwillwalk}, @file{lily}, @file{lunafly}, @file{maredowellfly},
|
||
@file{maredowellgallop}, @file{master}, @file{mjolna}, @file{orange},
|
||
@file{raritysdad}, @file{raritysmom}, @file{royalnightguard}, @file{ruby},
|
||
@file{sparkler}, @file{violet}.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 0.8
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@w{New ponies}: @file{aloe}, @file{angle}, @file{applebloom}, @file{applebumkin},
|
||
@file{applefritter}, @file{berrypunch}, @file{bigmac}, @file{blinkie}, @file{blues},
|
||
@file{braeburn}, @file{caesar}, @file{candymane}, @file{caramel}, @file{cheerilee},
|
||
@file{cheerilee80}, @file{clyde}, @file{colgate}, @file{colton}, @file{daisy},
|
||
@file{derpystand}, @file{derpystandwing}, @file{diamondtiara}, @file{dinky},
|
||
@file{doctornohat}, @file{elsie}, @file{fido}, @file{fillycelestia},
|
||
@file{fillydash}, @file{fillydashfly}, @file{fillyjack}, @file{fillyjacktravel},
|
||
@file{fillypinkie}, @file{fillypinkiecurly}, @file{fillyrarity}, @file{fillyshy},
|
||
@file{fluttershygala}, @file{gilda}, @file{gildastand}, @file{granny},
|
||
@file{grannychair}, @file{grannysleep}, @file{gummy}, @file{hoity}, @file{horte},
|
||
@file{inky}, @file{laflour}, @file{lightning}, @file{lintsalot}, @file{lotus},
|
||
@file{mayor}, @file{mrssparkle}, @file{nightmare}, @file{opal}, @file{parasprite},
|
||
@file{philomena}, @file{photofinish}, @file{pinkamina}, @file{pinkiebounce},
|
||
@file{pinkiechicken}, @file{pinkiegala}, @file{pipsqueak}, @file{pokey},
|
||
@file{rainbowfly}, @file{rainbowgala}, @file{rainbowsleep}, @file{raindrops},
|
||
@file{rarityfly}, @file{raritygala}, @file{rarityponder}, @file{redheart},
|
||
@file{rocky}, @file{rose}, @file{rover}, @file{royalguard}, @file{sapphire},
|
||
@file{scootaloo}, @file{screwball}, @file{shadowbolts}, @file{silverspoon},
|
||
@file{silverstar}, @file{sindy}, @file{snails}, @file{snips}, @file{soarin},
|
||
@file{soigne}, @file{spike}, @file{spikefloat}, @file{spikelove}, @file{spot},
|
||
@file{stella}, @file{strongheart}, @file{sue}, @file{suedance}, @file{tank},
|
||
@file{trixiestage}, @file{trixiestand}, @file{turnip}, @file{twist}, @file{winona}.
|
||
@end itemize
|
||
|
||
@b{Note}: Identifies itself as version 0.7
|
||
|
||
|
||
@heading Version 0.7
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@w{New ponies:} @file{carrot}, @file{octavia}, @file{trixie}, @file{vinyl},
|
||
@file{zecora}.
|
||
@item
|
||
@opindex @option{-l}
|
||
Support for listing ponies with @option{-l} option.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 0.6
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@w{New ponies:} @file{bonbon}, @file{celestia}, @file{doctor}, @file{fillistia},
|
||
@file{spitfire}, @file{woona} (not moonstuck).
|
||
@item
|
||
Dropping usage of utility @command{which}, using @command{hash} instead.
|
||
@end itemize
|
||
|
||
@b{Note}: Identifies itself as version 0.5
|
||
|
||
|
||
@heading Version 0.5
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Using utility @command{which} to determine existence of @command{cowsay}.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 0.4
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@file{.cow} files are removed.
|
||
@item
|
||
@opindex @option{-W}
|
||
Support for @option{-W} option.
|
||
@item
|
||
Select random pony if not specified.
|
||
@item
|
||
@opindex @option{-f}
|
||
@option{-f} supports file names, and not only pony names.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 0.3
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Fixed use of @file{.pony} files.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 0.2
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Pony files end with @file{.pony} instead of @file{.cow}.
|
||
@item
|
||
@file{lyrasleep} is renamed to @file{lyra}.
|
||
@item
|
||
@file{.cow} files are kept but not used.
|
||
@item
|
||
@opindex @option{-h}
|
||
@option{-h} prints proper help.
|
||
@end itemize
|
||
|
||
|
||
@heading Version 0.1
|
||
|
||
First release.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@w{Includes the ponies}: @file{applejack}, @file{derpy}, @file{derpysit},
|
||
@file{fluttershy}, @file{luna}, @file{lyrasleep}, @file{pinkie}, @file{rainbow},
|
||
@file{rarity}, @file{sweetie}, @file{twilight}.
|
||
@end itemize
|
||
|
||
|
||
|
||
@node Ponysay contributors
|
||
@appendix Ponysay contributors
|
||
|
||
Active developers and major contributors of ponysay:
|
||
@itemize @bullet
|
||
@item Erkin ``erkin'' Batu Altunbaş
|
||
@item Mattias ``maandree'' Andrée
|
||
@item Elis ``etu'' Axelsson
|
||
@item Sven-Hendrik ``svenstaro'' Haase
|
||
@item Pablo ``jristz'' Lezaeta
|
||
@item Jan Alexander ``heftig'' Steffens
|
||
@end itemize
|
||
@*
|
||
Patchers and other contributors of ponysay:
|
||
@itemize @bullet
|
||
@item Duane ``Marneus68'' Bekaert
|
||
@item Kyah ``L-four'' Rindlisbacher
|
||
@item James ``rossy2401'' Ross-Gowan
|
||
@item Louis ``kragniz'' Taylor
|
||
@item Daniel ``gtmanfred'' Wallace
|
||
@item Jannis ``sycoso''
|
||
@item ``spider-mario''
|
||
@end itemize
|
||
|
||
|
||
|
||
@node Ponysay license
|
||
@appendix Ponysay license
|
||
|
||
Ponysay is release by Erkin Batu Altunbaş et al. @*@*
|
||
Copyright @copyright{} 2012, 2013 Erkin Batu Altunbaş et al.
|
||
|
||
@*
|
||
|
||
Ponysay is Free Software (and Open Source) and in licensed under the terms
|
||
of GNU General Public License version 3, or at your option, any later version.
|
||
|
||
You have the four essential freedoms:
|
||
@itemize @bullet
|
||
@item
|
||
The freedom to run the program, for any purpose (freedom 0).
|
||
@item
|
||
The freedom to study how the program works, and change it so it does your
|
||
computing as you wish (freedom 1). Access to the source code is a precondition
|
||
for this.
|
||
@item
|
||
The freedom to redistribute copies so you can help your neighbour (freedom 2).
|
||
@item
|
||
The freedom to distribute copies of your modified versions to others (freedom 3).
|
||
By doing this you can give the whole community a chance to benefit from your
|
||
changes. Access to the source code is a precondition for this.
|
||
@end itemize
|
||
@*
|
||
|
||
If you intend to redistribute ponysay or a fork of it commercially, it contains
|
||
aggregated images, some of which may not be commercially redistribute, you would
|
||
be required to remove those. To determine whether or not you may commercially
|
||
redistribute an image make use that line @code{FREE: yes}, is included inside
|
||
the image between two @code{$$$} lines and the @code{FREE} is and upper case and
|
||
directly followed by the colon.
|
||
@*
|
||
|
||
@cartouche
|
||
ponysay is free software: you can redistribute it and/or modify
|
||
it under the terms of the GNU General Public License as published by
|
||
the Free Software Foundation, either version 3 of the License, or
|
||
(at your option) any later version.
|
||
|
||
ponysay is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
GNU General Public License for more details.
|
||
|
||
You should have received a copy of the GNU General Public License
|
||
along with ponysay, and attached to this document.
|
||
If not, see <http://www.gnu.org/licenses/>.
|
||
@end cartouche
|
||
|
||
@node GNU General Public License
|
||
@appendix GNU General Public License
|
||
@include gpl.texinfo
|
||
|
||
@node GNU Free Documentation License
|
||
@appendix GNU Free Documentation License
|
||
@include fdl.texinfo
|
||
|
||
|
||
@node Concept and program index
|
||
@appendix Concept and program index
|
||
@printindex pg
|
||
|
||
@node Variable and option index
|
||
@appendix Variable and option index
|
||
@printindex vr
|
||
|
||
|
||
@bye
|
||
|