From 82780016431fb3d495bca70d3182dd8ebe5c31a9 Mon Sep 17 00:00:00 2001
From: bill-auger <mr.j.spam.me@gmail.com>
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 <COW_NAME> moo ;
+.PP
+\... where `-f <COW_NAME>` may be a cow name (per `cowsay -l`), a .cow filename,
+or an animation directory name - <COW_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

