util-say.texinfo

\input texinfo   @c -*-texinfo-*-

@c %**start of header
@setfilename util-say.info
@settitle util-say
@afourpaper
@documentencoding UTF-8
@documentlanguage en
@finalout
@c %**end of header
@set VERSION 3.0

@defindex op


@copying
This manual is for util-say
(version @value{VERSION}).

Copyright @copyright{} 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 util-say: Tools for creating ponies for ponysay and ponysay-like programs
@insertcopying
@end ifnottex

@titlepage
@title util-say
@subtitle Tools for creating ponies for ponysay and ponysay-like programs
@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
@end titlepage

@contents


@menu
* Overview::                            Brief overview of util-say.
* Background::                          Brief background.
* Using the converter::                 Using the converter, @command{ponytool}.
* Usage examples::                      Examples of basic commands.
* GNU Free Documentation License::      Copying and sharing this manual.
* Concept index::                       Concept index.
* Option index::                        Option index.
@end menu




@node Overview
@chapter Overview
@cindex overview

util-say was historically collection of utilities for creating images for ponysay,
cowsay and similiar programs, hence its name. Nowadays however, it is basically
one utility with a set of modules, called @command{ponytool}, but more utilities
will be added over time.

@command{ponytool} is used convert an image into another format or change the image's
configurations. Theses images are images be simply rendered in a terminal, and
naturally normal images formats are supported so normal images can be made into
terminal renderable.



@node Background
@chapter Background
@cindex background
@cindex terminal images
@cindex images, terminal

@cindex glyphs
@cindex Unicode
@cindex UCS
@cindex monospaced fonts
@cindex fonts, monospaces
@cindex block elements
Unicode defines glyphs made for drawing, specifically it defines block elements,
these include glyphs that splits the glyph area vertically in half and definied
all for combinations for filling or keeping empty each half. The empty glyphs
beginng the blankspace character. In monospaced fonts theses are definied to
be of same size.

@cindex font dimensions
@cindex dimensions, font
@cindex pixel perfect
@cindex mosiac, structure
A font that precisly adheres to the previous paragraph and have the total font
exactly height twice of the width is called pixel perfect to the extend of the
our usage. This lets or use just four, or even only three, glyphs to build
mosiac pictures of characters representing two pixels each, vertically stacked.

@cindex colour
An essential part of letting one glyph represent two pixels is that terminals
support both foreground and background colours, as well as 240 well definied
colours as well as full transparency.

This is the foundation that lets use print nice looking images in the terminal,
and it can be done in @command{cat}:able text files, for details on the formats
please refer to the documentation for that specific program.



@node Using the converter
@chapter Using the converter
@cindex converter
@cindex @command{ponytool}

@cindex importing
@cindex exporting
The command @command{ponytool} is used to convert images between formats and
configurations, it has the capability of importing one file and exporting
multiple files. As you may notice, @command{ponytool} does not support short
options, only long options, and all options takes exactly one argument.

@cindex invoking
@cindex selecting file
@cindex file, select
@opindex @option{import}
@opindex @option{export}
@opindex @option{in}
@opindex @option{out}
@opindex @option{file}
To use the converter, run command
@command{ponytool --import module [parameters...] @{--export module [parameters...]@}}.
Note that parameters must be added after their @option{--import} or
@option{--export}. Alternatively you can use @option{--in} instead of
@option{--import} or @option{--out} instead of @option{--export}.
Associated with @option{--import} and @option{--export} is a module take
must follow directly. All modules, before for export and import, honors
@option{--file} that takes the file to read to or write from and defaults
to stdin or stdout, @code{-} begin the explicit value for those, and will
note be listed in the module's documention's. If you want your file to
start with @code{--} you will either need to prepend @code{./} or make
@option{--file} and the file name one argument seperated with @code{=},
the latter works for all options.

@cindex modules
Supported modules are @code{ponysay}, @code{unisay}, @code{cowsay} and
@code{image}, all being case insensitive and support both import and export.


@menu
* Ponysay module::                      Using the @code{ponysay} module.
* Unisay module::                       Using the @code{unisay} module.
* Cowsay module::                       Using the @code{cowsay} module.
* Cat module::                          Using the @code{cat} module.
* Image module::                        Using the @code{image} module.
@end menu


@node Ponysay module
@section @code{ponysay} module
@cindex @code{ponysay} module
@cindex module, @code{ponysay}

@opindex @option{version}
The @code{ponysay} module lets you import and export @command{ponysay}
ponies of any @command{ponysay} version. To select the which version of
@command{ponysay} to use, use the option @option{--version}, the value
is version string (numerals seperated by dots). The version will always
default to the latest version of @command{ponysay}, if not yet stabil.

The following version spans exists:

@table @asis
@item @bullet{} 0 @math{<=} @option{version} @math{<} 2.1
@cindex @command{cowsay}
@command{cowsay} format.
@item @bullet{} 2.1 @math{<=} @option{version} @math{<} 2.9
@cindex @command{unisay}
@command{unisay} format.
@item @bullet{} 2.9 @math{<=} @option{version} @math{<} 3
Metadata support is added.
@item @bullet{} 3 @math{<=} @option{version}
Horizontal balloon justification is added.
@end table

The additional options are supported:

@table @asis
@item @option{--ignoreballoon} (export/import)
@opindex @option{ignoreballoon}
@cindex ignore balloons
@cindex balloons, ignore
Specifies whether to remove all balloons but not links and substitute with
transparent pixels. To enable this, use a value starting with @code{y} or
@code{Y}.

@item @option{--ignorelink} (export/import)
@opindex @option{ignorelink}
@cindex ignore links
@cindex links, ignore
Specifies whether to remove all balloons links and substitute with
transparent pixels. To enable this, use a value starting with @code{y} or
@code{Y}, the value defaults to the value of @option{--ignoreballoon}.

@item @option{--even} (export)
@opindex @option{even}
@cindex right padding
@cindex padding, right
@cindex padding, even
@cindex even out
Specifies whether to pad the the lines to make all lines of same visual
lenght. To disable this, use a value starting with @code{n} or @code{N}.
This option is only available in @option{--export}.

@item @option{--fullblocks} (export)
@opindex @option{fullblocks}
@cindex block elements
@cindex full blocks
Specifies whether full block elements can be used when a pixel pair has the
same colours; in modes where the paletter is modified, this allows better
selection of colour index. To disable this, use a value starting with
@code{n} or @code{N}. This option is only available in @option{--export}.

@item @option{--spacesave} (export)
@opindex @option{spacesave}
@cindex compression
@cindex file size
Specifies whether to prefer small files over making the image look good
while marked in a terminal. To enable this, use a value starting with
@code{y} or @code{Y}. This option is only available in @option{--export}.

@item @option{--zebra} (export)
@opindex @option{zebra}
@cindex zebra effect
Specifies whether to use half block elements when the pixel's an pixel
pair has the same colours. To enable this, use a value starting with
@code{y} or @code{Y}. This option is only available in @option{--export}.

@item @option{--utf8} (export)
@opindex @option{utf8}
@cindex cowsay encoding
@cindex encoding, escaping
@cindex UTF-8
This option is only available when using the @command{cowsay} format in
@option{--export}, it is manditorly enabled when not using the
@command{cowsay} format. It specifies whether to encode the files in
UTF-8, rather then using escaped strings. To enable this, use a value
starting with @code{y} or @code{Y}.

@item @option{--escesc} (export)
@opindex @option{escesc}
@cindex cowsay encoding
@cindex encoding, escaping
This option is only available when using the @command{cowsay} format in
@option{--export}, it is manditorly disabled when not using the
@command{cowsay} format. It specifies whether to escape the escape
characters in the files. To enable this, use a value starting with
@code{y} or @code{Y}.

@item @option{--left} (export)
@opindex @option{left}
@cindex margins
Fix the number emptying columns at the left side of the pony, if the value
cannot be parsed as a non-negative integer, for example @code{-}, the margin
will not be modified from the original image. This options is import
supported in @option{--export}.
Use a value starting with a @code{y} or @code{Y} make the program use a
default value.

@item @option{--right} (export)
@opindex @option{right}
@cindex margins
Fix the number emptying columns at the right side of the pony, if the value
cannot be parsed as a non-negative integer, for example @code{-}, the margin
will not be modified from the original image. This options is import
supported in @option{--export}.

Use a value starting with a @code{y} or @code{Y} make the program use a
default value.

@item @option{--top} (export)
@opindex @option{top}
@cindex margins
Fix the number emptying lines at the top of the pony, if the value cannot
be parsed as a non-negative integer, for example @code{-}, the margin will
not be modified from the original image. This options is import supported
in @option{--export}.

Use a value starting with a @code{y} or @code{Y} make the program use a
default value.

@item @option{--bottom} (export)
@opindex @option{bottom}
@cindex margins
Fix the number emptying lines at the bottom of the pony, if the value cannot
be parsed as a non-negative integer, for example @code{-}, the margin will
not be modified from the original image. This options is import supported
in @option{--export}.

Use a value starting with a @code{y} or @code{Y} make the program use a
default value.

@item @option{--balloon} (export/import)
@opindex @option{balloon}
@cindex balloon, insert
This specifies whether to insert a balloon and its link at the top left of
the image. Specift the number of lines between the balloon and the pony or
a value starting with a @code{y} or @code{Y} for a default value.

@item @option{--platform} (export/import)
@opindex @option{platform}
@cindex platform
@cindex system
Specifies a submodule for which platform the pony is or should be encoded.
These submodules supports additional options. The platform string is case
insensitive and ignores hyphens, underscores and blankspaces and trets
@code{colours}, @code{colour}, @code{colors} and @code{color} all as the
same word.
@end table


@menu
* XTerm submodule::                     Using the @code{xterm-256color} submodule.
* Linux VT submodule::                  Using the @code{linux} submodule.
* Haiku submodule::                     Using the @code{haiku} submodule.
@end menu


@node XTerm submodule
@subsection XTerm submodule
@cindex @code{xterm}, platform
@cindex platform, @code{xterm}
@cindex system, @code{xterm}

@code{xterm}, or @code{xterm-256color}, is the default module, in @option{--import}
is reading files created with the @code{linux} submodule. @code{xterm} is used for
normal @code{xterm-256color} capable terminals.

@opindex @option{fullcolour}
@opindex @option{colourful}
@cindex 24-bit colour support
@cindex colour support, 24 bits
@code{xterm} will use the well defined colours with the indices 16 through 255
(inclusive.) If you want to enable use any colour @code{xterm} can modify the palette,
however terminals will normally not support this as the palette will be reset and
normally everything is redrawn when the palette is modified. To do this, use the
option @option{--fullcolour} with a value starting with @code{y} or @code{Y}. In this
mode only the colour indices 7 (white) and 15 (bright white) will be modified and
used, if you want 16 colour indices to be used, use the @option{--colourful} with a
value starting with @code{y} or @code{Y}.

@opindex @option{palette}
@cindex palette, custom
@cindex custom palette
@cindex @option{fullcolour}
You can specify which palette you want to use by adding it as the value of the option
@option{--palette}, the value does not need to contain the characters ESC, @code{[}
and @code{P}, and both XTerm and Linux VT palette strings are supported. When using
@option{--fullcolour} it is a good idea to use this so the palette you are using does
not get changed when displaying the image.

@opindex @option{chroma}
@cindex colour matching
@cindex colour distance
@cindex matching, colour
@cindex distance, colour
@cindex CIELAB
@cindex sRGB
@cindex standard RGB
@cindex RGB, standard RGB
The select which colour index to use, as it is limited, the best colour is choosen
by selecting the first enumerated colour with minimal distance. By default the
distances aer calculated as CIELAB distances. If you want to make the chroma more
important than distance, you can specify a non-negative floating value in the
option @option{--chroma}, which as the 1 as its default value. If you prefer
sRGB distances, you can use an invalid value for @option{--chroma}, for example,
@code{-}.


@node Linux VT submodule
@subsection Linux VT submodule
@cindex @code{linux}, platform
@cindex platform, @code{linux}
@cindex system, @code{linux}
@cindex @code{tty}, platform
@cindex platform, @code{tty}
@cindex system, @code{tty}

@code{linux}, or @code{tty}, is the submodule for parse or, primarly, create images
printable in the Linux virtual terminal. You may use @code{xterm} for parsing Linux VT
image, if but if you use @code{linux}, errors the pony will be visible.

@opindex @option{fullcolour}
@opindex @option{colourful}
@cindex 24-bit colour support
@cindex colour support, 24 bits
@cindex VT switching
@cindex switching VT
@code{linux} will use XTerm's the well defined colours with the indices 16 through 255
(inclusive.), use the option @option{--fullcolour} with a value starting with @code{y}
or @code{Y}, to support any colour. By default ony the colour indices 7 (white) and 15
(bright white) will be used and modified, if you want 16 colour indices to be used,
use the @option{--colourful} with a value starting with @code{y} or @code{Y}.

@opindex @option{palette}
@cindex palette, custom
@cindex custom palette
@cindex @option{colourful}
You can specify which palette you want to use by adding it as the value of the option
@option{--palette}, the value does not need to contain the characters ESC, @code{[} and
@code{P}. It is recommand no to use @option{--colourful} unless this option is used.


@opindex @option{chroma}
@cindex colour matching
@cindex colour distance
@cindex matching, colour
@cindex distance, colour
@cindex CIELAB
@cindex sRGB
@cindex standard RGB
@cindex RGB, standard RGB
The select which colour index to use, as it is limited, the best colour is choosen
by selecting the first enumerated colour with minimal distance. By default the
distances aer calculated as CIELAB distances. If you want to make the chroma more
important than distance, you can specify a non-negative floating value in the
option @option{--chroma}, which as the 1 as its default value. If you prefer
sRGB distances, you can use an invalid value for @option{--chroma}, for example,
@code{-}.


@node Haiku submodule
@subsection Haiku submodule
@cindex @code{haiku}, platform
@cindex platform, @code{haiku}
@cindex system, @code{haiku}

The @code{haiku} submodule works as the @code{xterm} submodule, but does not
support @code{linux} import. The difference between @code{haiku} and @code{xterm}
files is that transparency/default is encoded in conflicting escape sequences.

@code{haiku} uses @code{CSI 40m} instead of @code{CSI 49m} for transparent
backgrounds, and @code{CSI 37m} instead of @code{CSI 39m} for default
foreground colour. More precisly, colour index 0 is used for the background
colour instead of black, and colour index 7 is used for the foreground colour,
while @code{CSI 49m} and @code{CSI 39m} is not recognised.



@node Unisay module
@section @code{unisay} module
@cindex @code{unisay} module
@cindex module, @code{unisay}

The @code{unisay} module is identical to @code{ponysay} with
@option{--version=2.1}. (Which as the version of @command{ponysay}, that
dropped the use of cowsay and switch to @command{unisay}'s format.)


@node Cowsay module
@section @code{cowsay} module
@cindex @code{cowsay} module
@cindex module, @code{cowsay}

The @code{cowsay} module is an extension of the @code{ponysay} with
@option{--version=0.1}, so the same options are supported, except
@option{--version}. It can construct images usable with @code{cowsay}.
For import you will need @command{perl} installed as it is used to
parse the cow file, which is a partial @command{perl} script.


@node Cat module
@section @code{cat} module
@cindex @code{cat} module
@cindex module, @code{cat}

The @code{cat} module is identical to @code{ponysay} with
@option{--version=2.8 --balloon=- --ignoreballoon=y --ignorelink=y}.
It is designed to create pure images that are displayable by just
printing them to the terminal as is, for example with @command{cat}.
However the purity will be disrupted if the image contains stores
and recalls, which they does not do as it is not intended for
cross-format use.


@node Image module
@section @code{image} module
@cindex @code{image} module
@cindex module, @code{image}

The @code{image} module lets you import and export regular graphics images,
such as Portable Network Graphics (PNG) files. The module suports the
following options.

@table @asis
@item @option{--left} (export/import)
@opindex @option{left}
@cindex margins
Fix the number emptying columns at the left side of the pony, if the value
cannot be parsed as a non-negative integer, for example @code{-}, the margin
will not be modified from the original image.

Use a value starting with a @code{y} or @code{Y} make the program use a
default value.

@item @option{--right} (export/import)
@opindex @option{right}
@cindex margins
Fix the number emptying columns at the right side of the pony, if the value
cannot be parsed as a non-negative integer, for example @code{-}, the margin
will not be modified from the original image.

Use a value starting with a @code{y} or @code{Y} make the program use a
default value.

@item @option{--top} (export/import)
@opindex @option{top}
@cindex margins
Fix the number emptying lines at the top of the pony, if the value cannot
be parsed as a non-negative integer, for example @code{-}, the margin will
not be modified from the original image. However, in @option{--import}
this value must be a non-negative integer, and is the number of additional
lines between the pony and the balloon. Defaults to 3 in @option{--import}.

Use a value starting with a @code{y} or @code{Y} make the program use a
default value.

@item @option{--bottom} (export/import)
@opindex @option{bottom}
@cindex margins
Fix the number emptying lines at the bottom of the pony, if the value cannot
be parsed as a non-negative integer, for example @code{-}, the margin will
not be modified from the original image.

Use a value starting with a @code{y} or @code{Y} make the program use a
default value.

@item @option{--magnified} (export/import)
@opindex @option{magnified}
@cindex scale up
@cindex magnification
@cindex pixel dimension
Pixel magnification, this specifies the nearest neighbour scale up used on
the image, and default to 2. In @option{--export} this means that every
pixel in the pony be @math{M} by @math{M} pixels if the value is @math{M}.
In @option{--import} it means that the imported image has that magnification
and the avarage pixel value will be used for the created pony. The value
must be a positive integer.

Use a value starting with a @code{y} or @code{Y} make the program use a
default value.

@item @option{--encoded} (export/import)
@opindex @option{encoded}
@cindex balloon, encode
@cindex balloon link, encode
@cindex link, encode
@cindex encoded images
@cindex image, encoded
This specifies whether the balloon and balloon link is or should be encoded
into to image. Use a value starting with a @code{y} or @code{Y} to enable this.

@item @option{--balloon} (export/import)
@opindex @option{balloon}
@cindex balloon, insert
This specifies whether to insert a balloon and its link at the top left of
the image. Use a value starting with a @code{y} or @code{Y} to enable this.

@item @option{--format} (export)
@opindex @option{format}
@cindex image format
@cindex format, image
@cindex PNG
@cindex Portable Network Graphics
@cindex GIF
@cindex Graphics Interchange Format
This specified what format to export the image with, the image is automatically
select on import. If a value is not specified it will be determined from the
file name and if fall back to Portable Network Graphics (PNG) if it is not
possible to determine. Note that the program will fail if the format is not
recognised, which is a possibility even for determination by file name.
All formats support by your Java installation will be supported; you count on
PNG and Graphics Interchange Format (GIF) being supported.
@end table



@node Usage examples
@chapter Usage examples
@cindex usage examples
@cindex examples, usage

@cindex create pony file
@cindex make pony file
@cindex pony file, create
@cindex image to pony
@cindex pony from image
To create a pony file from an image, use the command
@command{ponytool --import image --file file.png --export ponysay --balloon y}.

@cindex make TTY pony
@cindex make Linux VT pony
@cindex create TTY pony
@cindex create Linux VT pony
@cindex TTY pony, create
@cindex Linux VT pony, create
To create a Linux VT pony file from and XTerm pony file, use the command
@command{ponytool --import ponysay --file file.pony --export ponysay --platform tty --left - --right - --top - --bottom - --file tty.pony}.



@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texinfo


@node Concept index
@appendix Concept index
@printindex cp

@node Option index
@appendix Option index
@printindex op


@bye