diff options
| -rw-r--r-- | manuals/ponysay.texinfo | 89 |
1 files changed, 88 insertions, 1 deletions
diff --git a/manuals/ponysay.texinfo b/manuals/ponysay.texinfo index 5033ca7..18f6814 100644 --- a/manuals/ponysay.texinfo +++ b/manuals/ponysay.texinfo @@ -56,7 +56,7 @@ Texts. A copy of the license is included in the section entitled * Dependencies:: Dependencies. * Installing:: Installing. * Extensions:: Extensions. -@c Inner workings->Pony anatomy +* Inner workings:: Inner workings. * Contributing:: Contributing. * Ponysay constributors:: Ponysay constributors. * Ponysay license:: Ponysay license. @@ -300,6 +300,10 @@ you run @command{ponythink}. @node Terminals @section Terminals +@cindex kms +@cindex kernel mode settings +@cindex 9term +@cindex 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 @@ -508,8 +512,88 @@ displayed with the associated ponies. See @ref{Invoking ponysay} for more inform +@node Inner workings +@chapter Inner workings +@cindex inner workings +@cindex hacking + +@menu +* Pony anatomy:: Anatomy of pony files. +* Truncation:: Output truncation. +* Languages:: Selection of languages. +@end menu + + +@node Pony anatomy +@section Pony anatomy +@cindex pony anatomy +@cindex anatomy of pony files + +The pony files are cow files used by @command{cowsay}, they are partial Perl-scripts +that assign a value to a scalar variable named @code{$the_cow}. The files use a +predefined scalar named variable named @code{$thoughts}, these are used to create +a link between the message and the pony. The message (and the balloon) it self is +printed by @command{cowsay} and is not definied in the pony files. + +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). + + +@node Truncation +@section Truncation +@cindex truncation +@cindex output trunction +@cindex kms +@cindex kernel mode settings + +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 @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 required on 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. + +For truncation the width, we have a custom program, named @command{ponysaytruncater}, +that is installed to @code{/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 eigth coloumn 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 [ (OSI) +or ] (CSI). For support UTF-8, to handles all bytes that do not match @code{10xxxxxx} as +beginning of a character. + + +@node Languages +@section Languages +@cindex languages +@cindex script languages +@cindex programming languages + +Ponysay is written primarily in GNU Bash shell script (POSIX compliant); the truncater +is 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 [that exist today] Perl is used; Perl +is already required by cowsay, is similar to shell, but also supports hash tables. +[maandree: I actually learned Perl just for this.] + + + @node Contributing @chapter Contributing +@cindex contributing @menu * Providing ponies:: Providing ponies @@ -526,6 +610,9 @@ desktop ponies, implementing it in JavaScript. Browser ponies are available at 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} + +There is a checklist named @code{"pony-checklist"} at the top level of the project +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 |