+---------------------------------------------------------------+
markv.lisp:
A Mark V. Shaney implementation in CLISP-flavored Common Lisp.

Version 1.0: 2006-10-22, Darren Racine <dr@racinesystems.com>
+---------------------------------------------------------------+

========
Summary:
========

Reads text or word pattern statistics on stdin until EOF, then prints
Markov-chain text or word pattern statstics on stdout.

Text output is unformatted -- words are simply output in a continuous
stream separated by spaces, suitable for input to your favorite
formatting program (or word processor). Piping the output through nroff
is an easy way to get reasonable formatting on a text terminal.

Text output continues until a word pattern is written for which there
is not a corresponding stats entry, or until interrupted (e.g. ctrl-C),
whichever occurs first.

Word pattern statistics output is formatted as markv.lisp expects to
read it on stdin.

  
======
Usage:
======

  markv.lisp [ -s ] [ -o N ]


========
Options:
========

  -s    Print word pattern statistics on stdout in a format suitable
        for use as input to markv.lisp on subsequent executions. This
        is especially useful for large input texts, as it eliminates the
        time-consuming recompilation of stats for subsequent Markov-text
        generation based on the same original text.
 

  -o N  Sets the number of words in a row for which following-word data is
        collected (a.k.a. 'order'). 'N' must be a positive integer. Higher
        values result in text output that more closely resembles
        (or duplicates) the original text. If not specified, '-o 2' is
        the default.

        Note that the '-o' option will not affect output text when the
        input to markv.lisp is pre-generated word pattern data. This 
        parameter is implicit in such data.


=========
Examples:
=========

Note the syntax shown in these examples assumes that markv.lisp resides in
a directory that's included in your command search path.

I.   The file 'a_story' contains a writing sample in plain text. The following
     invocation of markv.lisp will read the entire file while internally 
     compiling its order-2 word pattern statistics. When EOF is reached, it
     dumps a stream of markov text based on those stats to stdout:

     markv.lisp <a_story


II.  To add simple formatting and page the output:

     markv.lisp <a_story | nroff | less


III. To generate a stats file that can be used for all future Markov-text
     generation in the style of "a_story":

     markv.lisp -s <a_story >a_story.o2.stats


IV.  To generate Markov-text using the stats file as input:

     markv.lisp <a_story.o2.stats


V.   To generate order-3 stats:

     markv.lisp -o 3 -s <a_story >a_story.o3.stats


====================
System Requirements:
====================

In its current form (v1.0), markv.lisp requires GNU CLISP on some sort
of Unix-like environment. The path in the first line of markv.lisp should
match the path to the clisp binary executable on your system, and the 
'markv.lisp' file attributes should specify 'executable' (chmod +x markv.lisp).

It may work on an MS-Windows system with Cygwin and the Cygwin CLISP package,
although this has not been tested.


========
License:
========

GNU General Public License (GPL), v2.0 or later

See the LICENSE file included in markv-1.0.tar.gz, or
http://www.gnu.org/licenses/gpl.html