Ponysay: ponies for your terminal
*********************************

This manual is for ponysay (version 2.3),

Copyright © 2012 Mattias Andrée

     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''.

Overview
********

ponysay displays an image of a My Little Pony pony saying some text provided by the user in a terminal, or a quote from the series. It is was wrapper for cowsay, but since version 2.1 it reimplementation cowsay. If message is not provided, e.g. by piping, it accepts standard input. The pony saying the given message is printed on standard output.

ponythink is to ponysay as cowthink is to cowsay.

ponysay is generally used to decorate your terminal with a random pony, when you start the terminal. But if you known anypony how does like ponies [fat chance] you can always make screen-shots of ponysay -q runs and communication that way over e-mail.

Invoking ponysay
****************

The format for running the ponysay program is:

     ponysay [OPTION...] [--] [MESSAGE]
     ponythink [OPTION...] [--] [MESSAGE]

Running ponysay will print a speech balloon, ponythink will print a thought balloon. Otherwise ponysay and ponythink is the same thing.

ponysay supports the following options:

--
     Parse the following arguments as parts of MESSAGE.

-h
--help
     Show summary of options.

-v

--verion
     Show version of program.

-f PONY
--file PONY
--pony PONY
     Specify the pony that should printed, this can either be a file name or a pony name printed by 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.

     If you have 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 `/'. This is not longer required and any existing pony name supersedes file names.

-F
++file PONY
++pony PONY
     Just as -F, but it uses extra (non-MLP:FiM) ponies instead of standard (MLP:FiM) ponies

-b STYLE
--bubble STYLE
--balloon STYLE
     Specify the balloon style that should used, this can either be a file name or a balloon name printed by 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.

-q [PONY...]
--quote [PONY...]
     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 after -q. If one or more ponies are added after -q, the pony will be selected randomly from that set of ponies. This option requires the extension ponyquotes4ponysay, which is included by default since version 1.2.

     The argument can be a file name, but pony if it ends with .pony.

-W COLUMN
--wrap COLUMN
     Specify the screen column where the message should be wrapped, this is by default 40, which is inherited from cowsay.

-c
--compress
     Compress the message in the same way cowsay does, that is basically without multiple spaces, one only paragraphs seperations.

-l
--list
     Lists all installed ponies. If the extension ponyquotes4ponysay is installed the ponies which have quotes, i.e. can be used with the -q option, will be mark by being printed in bold or bright (depending on the terminal.)

-L
--altlist
     Lists all installed ponies. If the extension ponyquotes4ponysay is installed the ponies which have quotes, i.e. can be used with the -q option, will be mark by being printed in bold or bright (depending on the terminal.) This options differs from -l by printing alternative names (symbolic links) inside brackets after their target ponies.

+l
++list
     Just as -l, but it lists extra (non-MLP:FiM) ponies instead of standard (MLP:FiM) ponies

+L
++altlist
     Just as -L, but it lists extra (non-MLP:FiM) ponies instead of standard (MLP:FiM) ponies

-B
--balloonlist
     Prints a list of all balloon styles.

If neither -q is used nor any MESSAGE is specified, ponysay will read the message from stdin (standard input); however, if no arguments are used that nothing is piped to stdin, a help message will be printed. If you want to use ponysay without arguments and enter the message by hand, you can run cat | ponysay.

If no pony is selected, ponysay will look for a best.pony file, this should be a symbolic link to the pony you want as a default. If it is not a symbolic link, -q cannot determine which quotes to use.

Advanced usage of ponysay.
**************************

Fortune cookies
===============

If you have fortune installed -- this program may be named fortune-mod in your GNU/Linux distributions package repository -- you can run fortune | ponysay to get a random pony reading a random fortune cookie.

By adding fortune | ponysay to the end [easiest way] of your ~/.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.

Ponification
============

You can ponify text (i.e. replaces words search as `everyone' with `everypony') by using fortune | ponypipe instead of using fortune. ponypipe can be downloaded from https://github.com/maandree/ponypipe. Alternatively you can use pinkie (or pinkiepie), which can be downloaded from https://github.com/maandree/pinkie-pie, which is just fortune | ponypipe. There is also a large sed script, similar to ponypipe: http://www.reddit.com/r/mylittlelinux/comments/srixi/using_ponysay_with_a_ponified_fortune_warning/ However I think ponypipe as better at replacing words than the sed script, but I haven't used the script so I wouldn't know for sure.

Running on TTY
==============

If you use TTY and have a custom colour palette, you should also add to your ~/.bashrc, before fortune | ponysay:

     [ "$TERM" = "linux" ] &&
         function ponysay
         {   exec ponysay "$@"
             #RESET PALETTE HERE
         }

Running on screen
=================

screen will adapt ANSI colour escape sequences to your terminal's capabilities. This means that if your terminal reports itself as xterm in $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 xterm and mate-terminal reports themselves as xterm in $TERM, and some reports their actual name in $COLORTERM. So before opening screen you use set $TERM to xterm-256color, if you are using a terminal with support for xterm's 256 colours; this can be done by adding to your ~/.bashrc:

     [ "$TERM" = "xterm" ] &&
         function screen
         {   export TERM="xterm-256color"
             exec screen "$@"
         }

Environment variables
*********************

ponysay supports the follow environment variables:

PONYSAY_BOTTOM
     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 PONYSAY_BOTTOM with the value yes, y or 1.

PONYSAY_SHELL_LINES
     Under TTY (Linux VT), if the output is larger the the screen's height, two lines are left blank. If you want more, or less, blank lines you can export PONYSAY_SHELL_LINES with the value of how many blank lines you want. Naturally this takes effect if the output is not actually larger than the screen.

PONYSAY_FULL_WIDTH
     You can export PONYSAY_FULL_WIDTH with the value yes, y or 1, if you do not want the output to be truncated on the width to fit the terminal.

PONYSAY_TRUNCATE_HEIGHT
     Export PONYSAY_TRUNCATE_HEIGHT with the value yes, y or 1, if you want to truncate the output on the height even if you are not running ponysay under TTY.

PONYSAY_UCS_ME
     Export PONYSAY_UCS_ME with the value yes, y or 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 PONYSAY_UCS_ME with the value harder, h or 2 instead.

     If you have not enabled this, UCS names are not usable, suggested or listed. If you use yes UCS names will be usable, suggested or listed. If you use harder ASCII:ised names will not be suggested or listed, but they will still be usable.

PONYSAY_COWSAY
PONYSAY_COWTHINK
     Since version 2.1 this is no longer used as cowsay has been reimplemented inside ponysay, but it is possible we will add a way to replace that back-end.

     If you want to use another program than cowsay (the first cowsay found in $PATH), you can export PONYSAY_COWSAY with the value of that program. In earlier versions than version 2.0: If, and only if, PONYSAY_COWSAY does not have any value, cowsay is patch with use utf8; to the beginning. The use utf8; patch is introduced to make it easier to customise cowsay.

     PONYSAY_COWTHINK will be used instead of PONYSAY_COWSAY if you run ponythink.

See kmsponies4ponysay for additional environment variables used by the extension kmsponies4ponysay.

Limitations
***********

Terminals
=========

Ponysay works perfectly on xterm, xterm like terminals including 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 mate-terminal.

On Linux's native terminal Linux VT (TTY) it works less well, and not good at all with Kernel Mode Settings (KMS) support. See https://github.com/erkin/ponysay/issues/1 for more information. 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 (except for 2^24 + full transparency.)

ponysay works perfectly on xterm, urxvt and putty, but rxvt, mrxvt and Eterm do not have UTF-8 support and are currently not supported. Additionally aterm have neither UTF-8 support nor 256 colour support, and is therefore not yet support.

Due to extreme limitations in 9term ponysay will never be able to run on it.

Cowsay
======

This section describes the limitation of cowsay, but since version 2.1 cowsay is no longer used because of it. So none of the following limitations are present anymore.

When 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, cowsay does not recognise ANSI escape sequences, therefore, using colours and text styling in messages will also malformat the balloon with the message.

cowsay does not support balloon, including the link between the message and the pony, customisation, other than using cowthink. However you can modify cowsay (written Perl, so you can edit the installed files) to make the balloon look different, maybe using box drawing characters.

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.

cowsay's word wrapping handles single line breaks as normal blank spaces, this messes up messages created with programs such as figlet and TOIlet.

Problems and requests
*********************

Reporting bugs
==============

If you find a bug in ponysay, install the last version from https://github.com/erkin/ponysay, and if it is still present, please report it at https://github.com/erkin/ponysay/issues. Please be as descriptive as possible, as it will help us verify it solve it faster.

Requesting ponies
=================

If you want I specific pony added, ask us at 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.

Dependencies
************

Required runtime dependencies
=============================

cowsay
     This is a wrapper for cowsay.

coreutils
     stty is used to determine the size of the terminal.

python
     ponysay is written in pure Python 3.

Optional runtime dependencies
=============================

util-say>=2
     For improved TTY support for user with custom colour palette and KMS support. It can be downloaded at https://github.com/maandree/util-say.

     For the purpose of simplifying for pony contributors, ponysay supports using .png-images (note that the file must not miss the .png in the file) in addition of .pony-files or pony names.

Package building dependencies
=============================

gzip
     Used for compressing manuals.

texinfo
info
     texinfo and info are required if you want this info manual.

make
     Required to run the make script.

coreutils
     The make script uses install, unlink, rm, ln, mkdir and cp and cut.

sed
     Used by the make script for PREFIX customisation.

Dependencies for pony providers
===============================

make
     Required to run make -B ttyponies`.

coreutils
     ln and readlink are used in the ttyponies subscript.

bash
     Used in the ttyponies subscript.

util-say>=2
     Used by make ttyponies to build ttyponies from xterm ponies. It can be downloaded at https://github.com/maandree/util-say.

Installing
**********

From upstream
=============

Installations basics
--------------------

Before installing ponysay, make sure your system have the packages listed under Required runtime dependencies and Package building dependencies installed.

Tarballs can be downloaded at https://github.com/erkin/ponysay/tarball/master for bleeding edge, or from https://github.com/erkin/ponysay/tags for releases.

If you have git you clone the project URL https://github.com/erkin/ponysay.git.

In the terminal, cd into the ponysay directory and execute ./configure && make install. This will install ponysay into the /usr, meaning you may need to run make install as root, e.g. by running sudo make install.

Now you will be to use ponysay, run: ponysay "I am just the cutest pony!", or if have a specific pony in your mind: ponysay -f pinkie "Partay!~".

ponysay comes with this info manual and a manpage in section 6, man 6 ponysay (or just man ponysay). The manpage is also available in Spanish: man -L es 6 ponysay. The install the Spanish manual add the option --with-man-es when running ./configure.

Custom installations
--------------------

A basic installation will install everything ponysay has to offer, except the prebuilt PDF manual and translated manpages. If you want to install exactly everything add the option --everything when running ./configure.

After --everything it is possible to remove unwanted parts, this can of cause be done without --everything. If you want to install the PDF manual to /usr/doc/ponysay.pdf add the option --with-pdf when running ./configure. To install a manpage translation add --with-man-LANG and substitute the the language code for LANG. Currently the only translation is Spanish with the language code es. If you do not want the English manpage add the option --without-man. If you do not want the info manual add the option --without-info. If you are installing the info manual but are not privileged to execute install-info add the option --without-info-install.

The following argumentless options are also recognised:

  * --without-bash will skip installation of auto-completion for ponysay and the GNU Bourne-again shell, bash.

  * --without-fish will skip installation of auto-completion for ponysay and the Friendly interactive shell, fish.

  * --without-zsh will skip installation of auto-completion for ponysay and the shell zsh.

  * --without-shared-cache will skip installing a shared cache for KMS support, when there is no shared cache, private one will be used at ~/.cache/ponysay.

The program is by default installed in /usr, if you want another target directory, you can add --prefix=TARGET when running ./configure. For example to install ponysay in /usr/games you build the program by running ./configure --prefix=/usr/games, and alike for installation and uninstallation. Notice the = cannot be substituted with white space.

If you are not using --without-info you can add --info-desc=DESCRIPTION to specify the description info which provide when listing commands.

By default bash is in the make file, if you want to use another shell add the option --shell=SHELL.

Arch Linux
==========

The official Arch Linux package repositories contains ponysay as community/ponysay. The Arch Linux User Repository (AUR) contains a bleeding edge git version of ponysay as ponysay-git.

Gentoo Linux
============

Gentoo users can use the overlay https://github.com/etu/aidstu-overlay, which contains ponysay as games-misc/ponysay.

Debian GNU/Linux and Ubuntu
===========================

A .deb file is available at http://roryholland.co.uk/misc.html#ponysay, and a PPA can be found at https://launchpad.net/~blazemore/+archive/ponysay.

Uninstallation
==============

If you did not install ponysay with a package manager, but rather manually from the upstream, you can uninstall it by running 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 Makefile. To perform the uninstallation of old filed run make uninstall-old.

Extensions
**********

Ponysay does not support extensions, per se, but rather have optional features that are enabled when other packages are installed.

ponyquotes4ponysay
==================

ponyquotes4ponysay is a package that adds support for MLP:FiM quotes that are displayed with the associated ponies. See Invoking ponysay for more information.

As of version 1.2 ponyquotes4ponysay is included in ponysay, but is still available at https://github.com/maandree/ponyquotes4ponysay.

kmsponies4ponysay
=================

kmsponies4ponysay is an extension for TTY users that have a custom TTY colour palette and KMS support. KMS is supported on most computers, but due to lack of published specifications Nvidea drivers does not support KMS. kmsponies4ponysay can be downloaded at https://github.com/maandree/kmsponies4ponysay.

To use this extension your ~/.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 $PONYSAY_KMS_PALETTE or you should export a command to can get the palette string to $PONYSAY_KMS_PALETTE_CMD. The palette string should be the stream which sets the colour palette to the terminal when 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 ~/.bashrc, to reset the colour palette to what you set it to last time in the terminal, named reset-palette, your ~/.bashrc should, for example, contain:

     [ "$TERM" = "linux" ] &&
         function ponysay
         {   export PONYSAY_KMS_PALETTE="`reset-palette`"
             exec ponysay "$@"
         }

kmsponies4ponysay uses /var/cache/kmsponies4ponysay/ for cache space.

As of version 2.0 kmsponies4ponysay is included in ponysay, but is still available at https://github.com/maandree/kmsponies4ponysay.

Inner workings
**************

Pony anatomy
============

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 ($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 ($var=value$). Variable names cannot include equality signs, but the value can; dollar signs can be used by placin an ESC character before the dollar sign.

There are three predefinied variables: $$ (empty variable name), $\$ and $/$. $$ has a dollar sign ($) as its value, while $\$ and $/$ contains the characters for the link to the balloon directed in the same direction as the variable name's slash.

Variables those name begin with balloon are parsed as balloon inserts, it can be either balloon, balloonX, balloon,Y or balloonX,Y, whether X is the minimum width of the balloon and Y is the minimum height of the balloon.

Prior to version 2.1 the pony files were cow files used by cowsay, they are partial Perl-scripts that assign a value to a scalar variable named $the_cow. Cow files use a predefined scalar variable named $thoughts, these are used to create a link between the message and the pony. The message (and the balloon) itself was printed by cowsay and is not defined in the cow files.

Pony quote infrastructure
=========================

When compiles pony quotes are built to quotes, the file names are lists of ponies joined with plus signs (+) -- the pony names are the same as the pony files, except they do not end with .pony -- with a index at the end, and a full stop (.) before the index.

The source files are located in ponyquotes, where their is a file named ponies. This file is called the pony map, is the basis for how the compiled files are named. In the ponymap ponies with the same quotes are on the same line join togather with plus signs (+), if the lines because too long for file names the line is split into multiple lines with the first pony in common.

In ponyquotes there are also quote files, each contain just one quote, just as when compiled to quotes. The source quote files are indentical to the compiled quote files, except that there name contains just the first pony.

Balloon style files
===================

Balloon style files are located in the directory balloons, the ones ending with .say applies to ponysay and the ones ending with .think applies to ponythink.

Balloon style consists of 20 strings. Each string is definied on separate lines, by their name and their value seperated with a colon (name:value), if the name is empty it continues the last one new line in the value. Only 10 of the strings may be multilined: nw, nnw, n, nne, ne, sw, ssw, s sse and se.

The following strings are used, and must be definied in the files:

\
     The character for the link to the balloon directed as \.

/
     The character for the link to the balloon directed as /.

ww
     The beginning of the balloon's line where the message is located if and only if the message contains only one line.

ee
     The end of the balloon's line where the message is located if and only if the message contains only one line.

nw
     The top left corner of the balloon.

nnw
     If both this string and the 'nne' string fits between the top corners, this is printed directly to the right of the top left corner.

n
     The top edge of the balloon.

nne
     If both this string and the 'nnw' string fits between the top corners, this is printed directly to the right of the top top corner.

ne
     The top right corner of the balloon.

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.

e
     The right edge of the balloon.

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.

se
     The bottom right corner of the balloon.

sse
     If both this string and the 'ssw' string fits between the bottom corners, this is printed directly to the left of the bottom right corner.

s
     The bottom edge of the balloon.

ssw
     If both this string and the 'sse' string fits between the bottom corners, this is printed directly to the right of the bottom left corner.

sw
     The bottom left corner of the balloon.

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.

w
     The left edge of the balloon.

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.

Printing in TTY with KMS
========================

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 ``\e[H\e[2J'' (\e is ESC) in at beginning. ``\e[H'' places the cursor at the beginning of the screen, and ``\e[2J'' clears everything on the screen after, and including at, the cursor. If we would use ``\ec'' (that is a reset), we would also turn off num. lock and caps. lock.

Truncation
==========

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 Settings (KMS) support to keep the colours from being messed up ad the ponies is moved in the screen during print; this done either by piping to head (keeps the top) or by piping to tail (keeps the bottom.) head and tail takes as argument the number of lines to keep at most.

The size of the terminal, measured in characters, is fetched from stty size, which returns HEIGHT WIDTH, and cut it the used to get either the height or the width. This required on GNU Coreutils; earlier tput rows and tput cols were used, this however required, the only de facto standard, package ncurses, some shells have environment variables for this.

For truncation the width, we have a custom program, named ponysaytruncater, that is installed to /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 ([a-zA-Z]), but also stops escape sequences after the first character after the initial escape if it is not either [ (CSI) or ] (OSI). For support UTF-8, to handles all bytes that do not match 10xxxxxx as beginning of a character.

Languages
=========

Before version 2.0 ponysay was written primarily in GNU Bash script (POSIX compliant); 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 cowsay, is 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.

Shell auto-completion
=====================

To make it easier to write auto-completion for shells, ponysay supports the two options --onelist, ++onelist and --quoters, which has nt short versions.

Executing 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 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.

ponysay --quoters work just as 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.

Contributing
************

Providing ponies
================

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 https://github.com/panzi/Browser-Ponies. Desktop ponies are available at http://desktop-pony-team.deviantart.com/.

There is also a collection of ponies that are not yet pixelated in a Java reimplementation: https://github.com/maandree/unisay/tree/develop/dev/newponies

There is a checklist named "pony-checklist" at the "dev/" directory. You can use the check which ponies are added and which are not.

New ponies can be created from regular images by using util-say, which is available at https://github.com/maandree/util-say. Prior to version 2.1 of ponysay, img2xterm could be used, by since version 2.1 ponysay is using a new format that only util-say supports. img2xterm (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:

     img2ponysay -2 -- SOURCE_IMAGE > PONY_FILE

     PONY_FILE should end with .pony and be localed in ponies/

     Omit -2 if the source image does not use double pixel size.

     For more information see:
     https://github.com/maandree/util-say/wiki/img2ponysay

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 make -B ttyponies after adding the ponies to ponies/, running make -B ttyponies will build (or rebuild) all ttyponies with a pony present in ponies/, and creates all needed symlinks.

To be able to run make -B ttyponies you must have the packages listed under Dependencies for pony providers.

Also when adding new ponies, please map them up in the file "ponyquotes/ponies". If the pony is a new pony without any other alternative image just add it to a new line, without .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 (+) without any white space. When a line is too long for a file name (this has happened to Pinkie Pie [pinkie],) it must be split into multiple lines, this line should have their first pony file in common.

Change log
**********

Version 2.3
===========

  * Support for best.pony file.

  * -q accepts file names.

  * Improved Unicode support: treats combining characters as invisible.

  * Optional support for UCS pony names.

  * Pony files and balloon style files can be pipes (as well as sockets, doors and as always regular files.)

  * Support cowsay style message compression.

  * Pony symlink added:

       * pinkieoink → oinkoinkoink

  * Support for non-MLP:FiM ponies (known as extraponies), although the directory is currently empty. This is implemented with the options -F, +l, and +L corresponding to -f, -l, and -L.

Version 2.2
===========

  * Full support for arbitrary positioning of balloon in pony files.

  * ANSI colour sequences in pony files are applied only to the pony image, not the balloon link or the balloon itself.

  * Support for colours in the message.

  * Support custom balloon styles using the option -b, -B will list all available. This list depends on whether you are invoking ponysay

Version 2.1.1
=============

Nothing worth mention.

Version 2.1
===========

  * applebumkin is renamed to applebumpkin.

  * New ponies: purplehaze, owlowiscious

  * Cowsay has be reimplemented, and have full Unicode support and support for figlet style messages.

  * Deleted environment variables: PONYSAY_COWSAY, PONYSAY_COWTHINK

  * You will need Python 3, but not GNU Bash, Perl or Cowsay.

  * New .pony file format is used: unisay's format instead of cowsay's Perl based format. This includes arbitrary position of balloon, mirrored balloon links, and minimum size of balloon.

Version 2.0
===========

  * Makefile is generated by running ./configure.

  * All Perl scripts and almost all Bash are reimplemented in one Python 3 script.

  * kmsponies4ponysay is included.

Version 1.4.1
=============

  * Code is repaired and more portable.

Version 1.4
===========

  * Make file is improved.

Note: Identifies itself as version 1.3

Version 1.3
===========

  * New ponies: forestspirit, hollydash, raggedy, rhyme

  * sindy is renamed to powderrouge. Pony symlink added:

       * sindy → powderrouge

  * PREFIX=/some-dir can be used when invoking make, the default value is /usr

Version 1.2
===========

  * ponyquotes4ponysay is included.

  * Support for extension: kmsponies4ponysay.

  * Pony symlinks added:

       * mrsparkle → nightlight

       * elsie → prettyvision

  * New ponies: ace, blueblood, filthyrich, gingergold, hayfever, highscore, junebug, mrsparkle, persnickety, ponet, screwloose, tornadobolt.

  * elsie is renamed to prettyvision.

  * Arbitrary spaces in -f argument is not longer accepted (it causes problems with file names including spaces.)

Note: Identifies itself as version 1.1

Version 1.1
===========

  * Manpages are compressed before installation.

  * info manual added.

  * Shell completion for ponythink added, in addition to ponysay.

  * fish completion added.

  * /usr/lib/ponysay is used instead of /usr/bin for code used by the main script.

  * ~/.local/share/ponysay is used for private pony directories.

  * ncurses is no longer needed for determining the screen's size, coreutils is used instead.

  * Pony symlinks added:

       * amethyststar → sparkler

       * berrypinch → ruby

       * craftycrate → boxxy

       * magnum → raritysdad

       * pearl → raritysmom

       * powderrouge → sindy

       * royalribbo → violet

  * New ponies: blossomforth, bonvoyage, cadance, celestiasmall, changelingqueen, cherryberry, discordamused, discordpuppetmaster, fleurdelishair, fleurdelislay, owl, perrypierce, petunia, pinacolada, skyra, truffleshuffle.

  * Pony spelling removed: fillycadence.

  * Pony symlink change: perry → {pokey → perrypierce}.

  * Option -L added, lists ponies with symlink mapping.

  * Support for extension: ponyquotes4ponysay.

  * Accepts arbitrary spaces in -f argument.

Version 1.0
===========

  * Spanish translation of the manpage is added.

  * New ponies: applecore, applejackscarecrow, bonbonstand, changeling, chrysalis, cottoncloudy, diamondmint, discord, fillycadence, flam, fleurdelis, flim, fluttershyshy, fluttershystare, lyrasit, oinkoinkoink (is pinkie), philomenaphoenix, pinkiecannon, pinkiecannonfront, pinkiecannonhappy, pinkiegummy, pinkiehugfluttershy, pinkiehugsfluttershy, pinkiepartycannon, pinkieprincess, pinkiesilly, pinkietongue, pinkiewhoops, pinkiewhoopseat, pinkiewhoopsout, rainbowdrag, rainbowsalute, rainbowshine, raritydrama, shiningarmor, shiningarmorguard, snowflake, spikemustache, stevenmagnet, stevenmagnettrue, twilightcrazyfromball, twilightrage, twilightzero, wildfire.

  * Pony symlinks added:

       * djpon-3 → vinyl

       * fillycadance → fillycadence

       * horsepower → snowflake

  * Improved TTY support: ponies have low colours resolution, instead of monochrome, when the high colour resolution is not available.

Version 0.10
============

  * Manpage manual added.

  * The directories for pony directories are changed from /usr/share to /usr/share/ponysay and ~ to ~/.ponysay.

  * Pony symlinks added:

       * carrottop → carrot

       * goldenharvest → carrot

       * harpass → lyra

       * heartstrings → lyra

       * lulamoon → trixie

       * minuette → colgate

       * noteworthy → blues

       * perry → pokey

       * pokeypierce → pokey

       * timeturner → doctornohat

       * trixielulamoon → trixie

       * twilightvelvet → mrssparkle

  * Support for truncating output on height, enabled by default under TTY.

  * Environment variables added: PONYSAY_FULL_WIDTH, PONYSAY_SHELL_LINES, PONYSAY_TRUNCATE_HEIGHT, PONYSAY_BOTTOM.

Version 0.9
===========

  * Output truncated on width to fit screen.

  * Support for TTY (Linux VT).

  * bash completion added.

  * zsh completion added.

  * New ponies: allie, archer, boxxy, carecake, cupcake, daringdo, davenport, fancypants, ironwillwalk, lily, lunafly, maredowellfly, maredowellgallop, master, mjolna, orange, raritysdad, raritysmom, royalnightguard, ruby, sparkler, violet.

Version 0.8
===========

  * New ponies: aloe, angle, applebloom, applebumkin, applefritter, berrypunch, bigmac, blinkie, blues, braeburn, caesar, candymane, caramel, cheerilee, cheerilee80, clyde, colgate, colton, daisy, derpystand, derpystandwing, diamondtiara, dinky, doctornohat, elsie, fido, fillycelestia, fillydash, fillydashfly, fillyjack, fillyjacktravel, fillypinkie, fillypinkiecurly, fillyrarity, fillyshy, fluttershygala, gilda, gildastand, granny, grannychair, grannysleep, gummy, hoity, horte, inky, laflour, lightning, lintsalot, lotus, mayor, mrssparkle, nightmare, opal, parasprite, philomena, photofinish, pinkamina, pinkiebounce, pinkiechicken, pinkiegala, pipsqueak, pokey, rainbowfly, rainbowgala, rainbowsleep, raindrops, rarityfly, raritygala, rarityponder, redheart, rocky, rose, rover, royalguard, sapphire, scootaloo, screwball, shadowbolts, silverspoon, silverstar, sindy, snails, snips, soarin, soigne, spike, spikefloat, spikelove, spot, stella, strongheart, sue, suedance, tank, trixiestage, trixiestand, turnip, twist, winona.

Note: Identifies itself as version 0.7

Version 0.7
===========

  * New ponies: carrot, octavia, trixie, vinyl, zecora.

  * Support for listing ponies with -l option.

Version 0.6
===========

  * New ponies: bonbon, celestia, doctor, fillistia, spitfire, woona (not moonstuck).

  * Dropping usage of utility which, using hash instead.

Note: Identifies itself as version 0.5

Version 0.5
===========

  * Using utility which to determine existence of cowsay.

Version 0.4
===========

  * .cow files are removed.

  * Support for -W option.

  * Select random pony if not specified.

  * -f supports file names, and not only pony names.

Version 0.3
===========

  * Fixed use of .pony files.

Version 0.2
===========

  * Pony files end with .pony instead of .cow.

  * lyrasleep is renamed to lyra.

  * .cow files are kept but not used.

  * -h prints proper help.

Version 0.1
===========

First release.

  * Includes the ponies: applejack, derpy, derpysit, fluttershy, luna, lyrasleep, pinkie, rainbow, rarity, sweetie, twilight.

Ponysay contributors
********************

Active developers and major contributors of ponysay:

  * Erkin ``erkin'' Batu Altunbaş

  * Mattias ``maandree'' Andrée

  * Elis ``etu'' Axelsson

  * Sven-Hendrik ``svenstaro'' Haase

  * Pablo ``jristz'' Lezaeta

  * Jan Alexander ``heftig'' Steffens

Patchers and other contributors of ponysay:

  * Duane ``Marneus68'' Bekaert

  * Kyah ``L-four'' Rindlisbacher

  * James ``rossy2401'' Ross-Gowan

  * Louis ``kragniz'' Taylor

  * Jannis ``sycoso''

  * ``spider-mario''

Ponysay license
***************

Ponysay is Free Software (yet not Open Source) and in licensed under the terms of Do What The Fuck You Want To Public License (WTFPL) version 2.

You have the four essential freedoms:

  * The freedom to run the program, for any purpose (freedom 0).

  * 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.

  * The freedom to redistribute copies so you can help your neighbour (freedom 2).

  * 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.

DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
Version 2, December 2004

Copyright © 2012 Erkin Batu Altunbaş

     Everyone is permitted to copy and distribute verbatim or modified copies of this license document, and changing it is allowed as long as the name is changed.

     DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

     0. You just DO WHAT THE FUCK YOU WANT TO.

GNU Free Documentation License
******************************

     [file fdl.texinfo not included]