  IPAGE - INTERACTIVE FILE PAGINATOR, VERSION 2.1, NOV 14, 1994
  -------------------------------------------------------------

  IPAGE provides general utility in paginating text files. It allows the
  user to select the precise place in a document at which to add a page
  break and header, and provides additional functions to remove page
  breaks and headers, check paginated files for excessively long or
  short pages, and create a table of contents for a paginated file. Most
  importantly, IPAGE is a script which can easily be modified to provide
  extra functions, or special document headers.

  INTRODUCTION
  ------------

  The problem with AUTOMATIC file paginators is that they insert page
  breaks at inappropriate locations, such as right after a main section
  header. The result can actually make a document HARDER to follow. In
  contrast, IPAGE is an interactive file paginator. It lets you select
  where the page break will occur, so that you can place page breaks
  between paragraphs, before section headers, and in the middle of long
  paragraphs. This results in a cleaner, more professional looking
  document which is easier for users to read and print out.

  IPAGE is very easy to use and install. This file contains details on
  installation and usage, as well as detailed notes related to customizing
  the IPAGE.S script for specific sites.

  INSTALLATION PROCEDURE
  ----------------------

  IPAGE.S is a CIEX script. It requires the CIEX interpreter to execute.
  You can download CIEX from America Online by doing a file search for
  CIEX235.EXE in the Development Forum. CIEX is supplied free of charge
  by New Line Software, Inc. (If you are not yet familiar with CIEX,
  please take a close look!) The CIEX235.EXE archive contains documentation
  on how to write CIEX scripts, and also provides several useful example
  scripts including calculator, calendar, and address/dialer scripts.

  Once CIEX235.EXE is acquired, execute it to extract the CIEX.EXE program,
  then place CIEX.EXE, IPAGE.EXE, and IPAGE.S in a directory somewhere your
  path.  Note that the IPAGE.S script must reside in the same directory as
  IPAGE.EXE for proper operation.

  This distribution also includes the file IPAGE.PIF, which can be used to
  install IPAGE in a MS-DOS Windows environment. Instructions on how to
  use PIF files with CIEX can be found in the CIEX235.EXE documentation.

  GENERAL USAGE
  -------------

  Once IPAGE is installed, type IPAGE at a DOS prompt to run the program.
  The program will prompt you for a file name. At the prompt, type the
  full or brief path to a text file, or type DIR to list the current

  README.TXT                     11-14-1994                     Page: 2

  directory. You can also specify the file to paginate on the command
  line when launching IPAGE, such as "IPAGE filename". When a file has
  been specified, IPAGE displays a menu of options, where each option is
  accessed with a function key, as described below:

  [ F1 ] BEGIN Interactive File Pagination.

     The "F1" function key begins the interactive pagination of the file.
     The IPAGE script displays the last 20 lines of a page, and then
     allows the user to add a page break in the file by tapping the ENTER
     key. A different location for the page break can be selected using
     the up and down arrow keys. (You cannot, however, enter a page break
     which would cause the page to exceed the maximum number of lines per
     page, or cause an excessively short page.) Note that a page header is
     never added to page 1 of the file.

  [ F2 ] CHECK / ANALYZE Current File Pagination.

     The "F2" function key scans the file for page breaks, checks for
     pages which exceed the maximum allowed page length, and then plots a
     bar chart showing the number of lines on each page. This function is
     useful for verifying that page lengths of the file are roughly
     uniform. This is especially helpful after editing a file which has
     already been paginated, to insure that the length of any given page
     has not been inadvertently exceeded.

  [ F3 ] REMOVE Existing Page Breaks and Headers.

     The "F3" function scans the file for page breaks, and removes these
     page breaks along with any headers which are detected. This function
     works best when a file has been paginated with IPAGE (since it
     expects each page header to include one leading and trailing blank
     line). This allows a previously paginated file to be edited and
     repaginated. IPAGE can be used to remove the page breaks from other
     files, however it is possible that IPAGE will remove some blank
     lines from the file. (IPAGE never removes lines containing text.)

  [ F4 ] CREATE Table Of Contents For File.

     The "F4" function scans the paginated file for section titles, and
     constructs a Table of Contents (TOC) for the file. IPAGE defines a
     section title rather narrowly, as any line under 65 characters
     preceded by a blank line and followed by a row of dashes (as are the
     section titles in this document.) The table of contents is written to
     the file TOC.TXT in the local directory, and the target file is never
     modified. (Afterwards, the TOC.TXT file can be manually edited, and
     inserted at the top of the target file.)

  Once any of the above functions are selected, the function can be
  prematurely terminated by entering the Escape Key while the function is
  executing. If a function is prematurely terminated, no modifications to
  the target file are retained.


  README.TXT                     11-14-1994                     Page: 3

  CUSTOMIZING THE IPAGE.S SCRIPT
  ------------------------------

  One of the nice things about IPAGE.S is, since it is a script, it can
  easily be customized. Useful parameters include: the maximum page size,
  header, and screen colors. These parameters can be found at the top of
  the script. Modification to these parameters should be straightforward.

  Users will probably want to adjust the value of the "$header" assignment
  in the file (around line 33 in the script) such as by adding in a
  company name, or eliminating the "DATE" field. The value of the
  "$max_lines_per_page" parameter can be increased or decreased by a user,
  (although setting the value to be greater than 55 may make the page
  size too large to fit on some printers). The value of "$start_page" can
  be modified to indicate a number other than 1 for the first page of the
  file, useful for paginating a document that resides in separate text
  files. (In this special case, a header will be printed on the first page
  of the document.)

  Users can modify the IPAGE.S script to query one or all of these values
  (in addition to a file name) using a program segment such as the
  following, inserted into the script after the above default assignments
  are made.

     # # # # # # # # # # # # # # # #

     echo -fmt 'START PAGE NUMBER?  > ' ; read $start_page
     echo -fmt 'MAX LINES PER PAGE? > ' ; read $max_lines_per_page

     # # # # # # # # # # # # # # # #

  The above program segment can be copied from this file, and pasted into
  the IPAGE.S script immediately prior to the "display_main_menu"
  callpoint, around line 105. The above statements cause the program to
  prompt for the start page number and maximum lines per page, and then
  use these values when repaginating the file.

  CUSTOMIZING THE INSTALLATION
  ----------------------------

  IPAGE.EXE is a simple launcher for IPAGE.S, and is provided only to make
  installation easier. IPAGE.EXE derives the pathname to the IPAGE.S
  script (using its own location on the disk), verifies that both IPAGE.S
  and CIEX are installed, and then executes CIEX, passing the script
  location and command line arguments to the program. Its action is
  identical to that of executing IPAGE.S by typing "CIEX IPAGE.S", or
  invoking CIEX, and interactively executing the "source IPAGE.S" command
  at the interactive prompt. The program source code for IPAGE.EXE is
  included in this release in the file IPAGE, possibly of interest to
  C-language programmers. (IPAGE.C can be deleted without affecting the
  execution of IPAGE.)

  As an alternative, the IPAGE.S script can be tucked into a directory
  (other than the local directory) and accessed by CIEX using the DOS
  "APPEND" command in the user's AUTOEXEC.BAT file. Or, users can set the

  README.TXT                     11-14-1994                     Page: 4

  environmental variable "SOURCE" to the name of a directory containing
  scripts, and CIEX will automatically search this directory whenever a
  script is referenced. (This feature is documented only in the full
  blown CIEX documentation, and not in the briefer README.TXT file
  provided with CIEX235.EXE.)

  Users can also bind the IPAGE.S script to the CIEX interpreter by
  typing the command "CIEX -bind IPAGE.S". (Careful! The "-bind" option
  must be typed in lower case letters.) This command will create an
  executable file directly from the IPAGE.S script, called IPAGE.EXE.
  Users can then place this executable somewhere in their path, and remove
  CIEX.EXE, the original IPAGE.EXE, and IPAGE.S scripts from their system.

  AUTOMATIC FILE PAGINATION
  -------------------------

  A limitation of IPAGE.S is that it will not automatically paginate a
  file. This is a draw back for users who wish to paginate long files
  where the location of page breaks is not important. However, such a
  program is trivial to implement using CIEX. An example of one such
  program is below included in its entirety:

     # # # # # # # # # # # # # # # #

     # Script: AUTOPAGE.S  - Automatically paginate a file.
     # Usage: CIEX AUTOPAGE.S (filename) > (newfile)

     set $page_number = 1              # Starting page number.
     set $line_number = 1              # Starting line number.

     loop for -file $line = $arg:1

        echo $line
        set $line_number + 1

        if $line_number gt 55

           echo                         # Add a blank line.
           echo -ascii 12               # Add a form feed
           echo "PAGE: $page_number"    # Add a header.
           echo                         # Add a blank line.
           set $page_number + 1
           set $line_number = 1

        endif

     endloop

     # # # # # # # # # # # # # # # #

  The above listing is a complete CIEX script. It can be copied and
  pasted into a file and executed with CIEX to add a page break every 55
  lines. The script accepts a single command line argument specifying the
  file to be paginated. The paginated file is written to the console,

  README.TXT                     11-14-1994                     Page: 5

  which can be redirected to a new file. (Note that the new file name
  should be different from the existing file to preclude the existing
  file from being clobbered.)

  AUTOMATIC GENERATION OF A TABLE OF CONTENTS
  -------------------------------------------

  The biggest difficulty associated with a table of contents generator is
  determining what precisely qualifies as a title to be placed in the
  table. This is especially true with generating the table of contents for
  a plain text file, which necessarily requires some sort of convention
  (or markup code) to be followed by the writer.

  IPAGE takes a moderate approach, where section titles are distinguished
  from regular text by a previous blank line and a subsequent line of
  dashes, as used in this file. Each title must be under 65 characters to
  qualify. Alternate algorithms can be developed; one obvious approach is
  to preface titles with a keyword, such as "SECTION:" or "CHAPTER:". In
  this case, the algorithm can be implemented as follows:

     # # # # # # # # # # # # # # # #

     # Script: GENTOC.S  - Generate a table of contents.
     # Usage: CIEX GENTOC.S (filename) > (newfile)

     set $page_number = 1               # Starting page number.
     set -inlin $ff = echo -ascii 12    # Formfeed character.

     loop for -file $line = $arg:1

        if '^ +SECTION: ' in $line or '^ +CHAPTER: ' in $line

           echo -fmt-70 $line           # Echo the title.
           echo " ... $page_number"     # Echo the page number.

        else if $ff in $line

           set $page_number + 1         # Increment page number.

        endif

     endloop

     # # # # # # # # # # # # # # # #

  The above listing can be cut and pasted into a file and executed by
  CIEX to create a table of contents, where titles are distinguished from
  other text by lines beginning with keywords "SECTION:" or "CHAPTER:".
  The script accepts a single command line argument specifying the file
  to be paginated, and outputs the paginated file to the console, which
  can be redirected to a new file, as in the previous example.


  README.TXT                     11-14-1994                     Page: 6

  CREDITS
  -------

  Special thanks to Kent and Roberta Widdle for conceiving of IPAGE, and
  creating Version 1.0. Kent makes several forceful comments regarding
  file pagination, which we include here:

  "I personally like to see page breaks at the end of paragraphs. That
  way, I can flip the page at the end of a complete thought. Also, I like
  to see page breaks with at least three lines on the previous and next
  pages. My opinion only: I think it looks nicer. What I definitely DON'T
  like to see are a lot of pages which are only half-full of text. Yeah --
  I know paper is cheap, but it indicates to me a casual regard. You know
  what I mean -- an extra page here or there, an extra hunk of memory the
  programmer didn't bother to deallocate...  An extra 20 megabyte hidden
  file the programmer created and didn't delete.... I like to see a more
  polished exactness. Note that IPAGE.S forces the user to include at
  least 45 lines of text on each page. Some people may regard this as a
  limitation, but I consider it to be a feature."

  OTHER NOTES
  -----------

  New Line Software is a member of the Association of Shareware
  Professionals (ASP). ASP wants to make sure that the shareware principle
  works for you. If you are unable to resolve a shareware-related problem
  with an ASP member by contacting the member directly, ASP may be able to
  help. The ASP Ombudsman can help you resolve a dispute or problem with
  an ASP member, but does not provide technical support for members'
  products. Please write to the ASP Ombudsman at 545 Grover Road,
  Muskegon, MI USA 49442-9427, Fax 616-788-2765, or send a CompuServe
  message via CompuServe Mail to ASP Ombudsman 70007,3536.

  This program is distributed WITHOUT ANY WARRANTY of ANY KIND, including
  (but not limited to) the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE.

  Windows, and MS-DOS are registered trademarks of Microsoft Corporation.
  For more information, please call or write New Line Software, Inc.

  NLS, Inc. New Line Software
  P.O. Box 3433
  Englewood, CO 80155

  OFFICES AT:
  7348 S. Alton Way, Unit I
  Englewood, CO 80112

  PHONE:
  1-800-441-2931, FAX: 1-303-771-0836
  In Denver, and outside of USA: 1-303-741-6594
