From 82780016431fb3d495bca70d3182dd8ebe5c31a9 Mon Sep 17 00:00:00 2001 From: bill-auger Date: Tue, 21 Mar 2023 18:21:19 -0400 Subject: [PATCH 4/5] document animated cows and the `-a` option --- cowsay.1 | 44 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/cowsay.1 b/cowsay.1 index e522c01..84760b4 100644 --- a/cowsay.1 +++ b/cowsay.1 @@ -24,7 +24,7 @@ cowsay .IR tongue_string ] .RB [ \-W .IR column ] -.RB [ \-bdgpstwy ] +.RB [ \-abdgpstwy ] .SH DESCRIPTION .I Cowsay generates an ASCII picture of a cow saying something provided by the @@ -56,7 +56,7 @@ accept standard input for a message in this case. There are several provided modes which change the appearance of the cow depending on its particular emotional/physical state. The .B \-b -option initiates Borg mode; +option initiates Borg mode; .B \-d causes the cow to appear dead; .B \-g @@ -108,7 +108,15 @@ with the .B \-l switch. .PP -If the program is invoked as +The +.B \-a +option initiates animation single-stepping mode. This allows stepping forwards +and backwards through an animation sequence, frame-by-frame, at your own pace. +This helps greatly while creating and fine-tuning the animated .cow files. In +this way, you can watch closely, to see how the picture changes from one frame +to the next. +.PP +If the program is invoked as .B cowthink then the cow will think its message instead of saying it. .PP @@ -131,6 +139,36 @@ interpolation. The name of a cowfile should end with otherwise it is assumed not to be a cowfile. Also, at-signs (``@'') must be backslashed because that is what Perl 5 expects. .PP +.SH ANIMATED COWS +.PP +Animations are simply multiple normal .cow files, which will be shown, one after +the other. To create new animated cows (or any other critters), make a new +directory and add all of the animation files to the directory. The name of the +directory will be the name given by `cowsay -l`. The names of the files within +are arbitrary; but note that they will be shown in alpha-numeric order. +.PP +By passing the `-a` option, you can to step through an animation sequence, +frame-by-frame. Press the 'period' key to step forward by one frame. Press the +'comma' key to step backward by one frame. Press the 'q' key to quit. +.PP +For creating new cows and experimenting with a source-code distribution, +(aka: "in-tree", without installing the program), run cowsay like this: + $ export COWPATH=./cows ; perl ./cowsay -f moo ; +.PP +\... where `-f ` may be a cow name (per `cowsay -l`), a .cow filename, +or an animation directory name - may also be a file-system path, +in which case, the `export` command may be omitted. See EXAMPLES below. +.PP +EXAMPLES: + For a single cow: + $ perl ./cowsay -f ./cows/default.cow moo + Or for a single animation frame: + $ perl ./cowsay -f ./cows/backflip-cow/backflip-cow_1.cow moo + To run a complete animation sequence: + $ COWPATH=./cows perl ./cowsay -f backflip-cow moo + To step through an animation sequence: + $ COWPATH=./cows perl ./cowsay -f backflip-cow -a moo +.PP .SH COMPATIBILITY WITH OLDER VERSIONS .PP What older versions? :-) -- 2.40.0