Merge pull request #1 from erkin/master

get up to date

1 files changed, 320 insertions, 12 deletions

diff --git a/manuals/ponysay.texinfo b/manuals/ponysay.texinfo
index d25cfdf..c90cd4c 100644
--- a/manuals/ponysay.texinfo
+++ b/manuals/ponysay.texinfo
@@ -21,8 +21,8 @@ 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''.
+Texts. A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
 @end quotation
 @end copying
 
@@ -49,15 +49,24 @@ Free Documentation License''.
 @menu
 * Overview::                            Brief overview of @command{ponysay}.
 * Invoking ponysay::                    How to run @command{ponysay}.
+* Advanced usage::                      Advanced usage of @command{ponysay}.
 * Environment::                         Environment variables.
-@c Extensions
 * Limitations::                         Limitations.
 * Problems and requests::               Reports and requests.
+* Dependencies::                        Dependencies.
+* Installing::                          Installing.
+@c Extensions
+@c Inner workings->Pony anatomy
+* Contributing::                        Contributing.
+* Ponysay constributors::               Ponysay constributors.
+* Ponysay license::                     Ponysay license.
 * GNU Free Documentation License::      Copying and sharing this manual.
 * Concept index::                       Concept index.
 @end menu
 
 
+
+
 @node Overview
 @chapter Overview
 @cindex overview
@@ -70,6 +79,8 @@ is printed on standard output.
 @command{ponythink} is to @command{ponysay} as @command{cowthink} is to @command{cowsay}.
 
 
+
+
 @node Invoking ponysay
 @chapter Invoking @command{ponysay}
 @cindex invoking
@@ -138,6 +149,46 @@ If you want to use @command{ponysay} without arguments and enter the message
 by hand, you can run @code{cat | ponysay}.
 
 
+
+@node Advanced usage
+@chapter Advanced usage of @command{ponysay}.
+@cindex advanced usage
+
+@cindex fortune
+If you have @command{fortune} installed -- this program may be named
+@command{fortune-mod} in your GNU/Linux distributions package reposity --
+you can run @code{fortune | ponysay} to get a random pony reading a
+random fortune cookie.
+
+@cindex on startup
+By adding @code{fortune | ponysay} to the end [easiest way] of your
+@code{~/.bashrc} -- or equivalent for your shell if use do not use GNU Bash
+(standard shell for most distributions now adays) -- you will get the
+effect described in the previous paragraph every time you open a terminal.
+
+@cindex tty
+@cindex linux vt
+If you use TTY and have a custom colour palette, you should also add to your
+@code{~/.bashrc}, before @code{fortune | ponysay}:
+@example
+[[ "$TERM" = "linux" ]] &&
+    function ponysay
+    @{   exec ponysay "$@@"
+        #RESET PALETTE HERE
+    @}
+@end example
+
+@cindex ponification
+@cindex ponypipe
+You can ponify text (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 use 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}.
+Their is also a large sed script, similar to @command{ponypipe}: @url{http://www.reddit.com/r/mylittlelinux/comments/srixi/using_ponysay_with_a_ponified_fortune_warning/}
+
+
 @node Environment
 @chapter Environment variables
 @cindex environment variables
@@ -176,30 +227,63 @@ are not running @command{ponysay} under TTY.
 
 
 
+
 @node Limitations
 @chapter Limitations
 @cindex limitations
 
 @menu
 * Terminals::           Limitations on terminals.
-@c Cowsay
+* Cowsay::              Limitations on cowsay,
 @end menu
 
+
 @node Terminals
 @section Terminals
 
-
 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}.
 
-On Linux's native terminal Linux VT (or TTY) it works less well, and not good at all
-with Kernal Mode Settings (KMS) support. See @url{https://github.com/erkin/ponysay/issues/1}
-for more information.
+On Linux's native terminal Linux VT (TTY) it works less well, and not good at all with
+Kernal Mode Settings (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.
+
+Due to extreme limitations in @command{9term} @command{ponysay} will never be able to
+run on it.
+
+Most terminals have support for 256 colours, we do however only use the top 240 colours;
+this is because the lower 16 colours are usally, 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 @math{2^{24}} + full transparency.)
+
+
+@node Cowsay
+@section Cowsay
+
+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.
 
-Due to extreme limitations in @command{9term} @command{ponysay} will never be able
-to run on it.
+@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 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.
+
+@cindex figlet
+@cindex tiolet
+@command{cowsay}'s word wrapping handles single line breaks as normal blankspaces,
+this messes up messaged created with programs seach as @command{figlet} and @command{TOIlet}.
 
 
 
@@ -208,9 +292,10 @@ to run on it.
 
 @menu
 * Problems::           Reporting bugs.
-* Requests::           Requestig ponies.
+* Requests::           Requesting ponies.
 @end menu
 
+
 @node Problems
 @section Reporting bugs
 @cindex bugs
@@ -221,8 +306,9 @@ 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 Requests
-@section Requestig ponies
+@section Requesting ponies
 @cindex pony requests
 
 If you want I specific pony added, ask us at @url{https://github.com/erkin/ponysay/issues}
@@ -230,6 +316,227 @@ 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
+
+@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 @option
+@item bash
+Required for the main script [file: @command{ponysay}].
+@item cowsay
+This is a wrapper for @command{cowsay}.
+@item coreutils
+The main script [file: @command{ponysay}] uses @command{stty}, @command{cut},
+@command{ls}, @command{cat}, @command{sort}, @command{readlink}, @command{pwd},
+@command{head} and @command{tail}.
+@item sed
+Used to remove @code{.pony} from pony names when running @command{ponysay -l}
+and @command{ponysay -L}.
+@item perl
+Required to run @command{ponysay -l} and @command{ponysay -L}.
+@end table
+
+@node Optional runtime dependencies
+@section Optional runtime dependencies
+@cindex extensions
+@cindex ponyquotes4ponysay
+
+@table @option
+@item ponyquotes4ponysay
+For support of My Little Pony quotes with associated pony: the @code{-q} option.
+It can be downloaded at @url{https://github.com/maandree/ponyquotes4ponysay}.
+@end table
+
+
+@node Package building dependencies
+@section Package building dependencies
+
+@table @option
+@item gcc
+Used for compiling @command{ponysaytruncater.c}.
+@item gzip
+Used for compressing manpages.
+@item make
+Required to run the make script.
+@item coreutils
+The make script uses @command{install}, @command{unlink}, @command{rm}, @command{ln},
+@command{mkdir} and @command{cp}.
+@end table
+
+
+@node Dependencies for pony providers
+@section Dependencies for pony providers
+@cindex contributing
+
+@table @option
+@item make
+Required to run @command{make -B ttyponies`}.
+@item coreutils
+@command{ln} and @command{readlink} are used in the @command{ttyponies} subscript.
+@item bash
+Used in the ttyponies subscript.
+@item util-say
+Used by @command{make 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
+@cindex make
+
+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 @command{clone} the project URL
+@url{https://github.com/erkin/ponysay.git}.
+
+In the terminal,@command{cd} into the ponysay directory and execute
+@command{make && make install}. This will install @command{ponysay} into the
+@code{/usr}, meaning you may need to run @command{make install} as root,
+e.g. by running @command{sudo make install}.
+
+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!~"}.
+
+@command{ponysay} comes with a manpage in section 6, @command{man 6 ponysay}
+(or just @command{man ponysay}). The man page is also available in Spanish:
+@command{man -L es 6 ponysay}. 
+
+
+
+@node Contributing
+@chapter Contributing
+
+@menu
+* Providing ponies::            Providing ponies
+@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:
+@url{https://github.com/maandree/unisay/tree/develop/dev/newponies}
+@*
+
+New ponies can be created from regular images by using util-say, which is available
+at @url{https://github.com/maandree/util-say}.
+@command{img2xterm} (@url{https://github.com/rossy2401/img2xterm}) was used earlier,
+but util-say tries do 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.)
+      
+Using util-say:
+@example
+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:
+@url{https://github.com/maandree/util-say/wiki/img2ponysay}
+@end example
+
+@*
+@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{make -B ttyponies} after adding the ponies
+to @code{ponies/}, running @command{make -B ttyponies} will build (or rebuild) all
+ttyponies with a pony present in @code{ponies/}, and creates all needed symlinks.
+
+To be able to run @command{make -B ttyponies} you must have the packages listed under
+@ref{Dependencies for pony providers}.
+
+
+
+
+@node Ponysay constributors
+@appendix Ponysay constributors
+
+Active developers of ponysay:
+@itemize @bullet
+@item Erkin Batu Altunbaş
+@item Mattias Andrée
+@item Sven-Hendrik Haase
+@item Pablo Lezaeta
+@item Jan Alexander Steffens
+@end itemize
+@*
+Patchers and other contributors of ponysay:
+@itemize @bullet
+@item Elis Axelsson
+@item Duane Bekaert
+@item Kyah Rindlisbacher
+@item James Ross-Gowan
+@item Louis Taylor
+@item Jannis
+@end itemize
+
+
+@node Ponysay license
+@appendix 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 Licese (WTFPL) version 2.
+
+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 neighbor (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
+
+@*
+
+@center DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+@center Version 2, December 2004
+
+Copyright @copyright{} 2012 Erkin Batu Altunbaş
+
+@quotation
+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.
+@end quotation
+
+
+
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
 @include fdl.texinfo
@@ -238,5 +545,6 @@ properties that makes a picture good.
 @appendix Concept index
 @printindex cp
 
+
 @bye