ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/walnut-creek-CDROM/CPM/PROGRAMS/WSTAR/FTNOTE14.LBR/FTNOTE14.DQC/FTNOTE14.DOC

Text File | 2000-06-30 | 26KB | 472 lines

                 FTNOTE.DOC
                 ----------
            Documentation for FTNOTE.COM
            (C)1984,  Eric Meyer
              (Version 1.4 - 84/08/27)

       Requires: CP/M operating system and WordStar(tm)

This program and its documentation are released to the public domain.
They may be used, copied, and distributed by all as long as NO charge
      is involved, and NO unauthorized changes are made.
---------------------------------------------------------------------

              I. INTRODUCTION

     FTNOTE.COM is a formatting utility for WordStar files.  Its main
function is to allow the printing of WordStar documents with page-bottom
footnotes, but it does internal page referencing and improved block
formatting as well.
     FTNOTE will automatically move your footnotes into and out of your
text file; number them for use as end notes; or produce a printable file
with them at page bottom.
     FTNOTE is an effective but simple program.  It does NOT attempt to
duplicate the existing capabilities of WordStar: editing, justification,
or printing.  It is a utility to be used in conjunction with WordStar.

FEATURES:   * simple, natural file format
        * automatic separation of text and notes
        * will produce end notes or footnotes as desired
        * automatic footnote numbering
        * numbering can match up across multiple files
        * page-mode or continuous footnote numbers
        * long notes will continue on next page
        * many formatting options allow flexible results
        * automatic internal page reference numbering
        * useful improved figure-block formatting
        * can be run FROM WORDSTAR with Main Menu "R" command

TYPICAL USE SEQUENCE:
 (1) Create the source file (text with notes)  WHATEVER.DOC
 (2) Extract notes to separate file WHATEVER.NOT: run FTNOTE WHATEVER -E
 (3) Combine the DOC and NOT files for printing:  run FTNOTE WHATEVER
 (4) Print or Mergeprint the output file  WHATEVER.PRN

---------------------------------------------------------------------

       II. THE COMMAND LINE: MODES, OPTIONS, FILES

SYNTAX:     FTNOTE [D:]FILENAME -mode         (utility modes)
     or FTNOTE [D:]FILENAME [options]    (formatting)

Do not include the filetype on the FTNOTE command line.  FTNOTE
will look for files (of filename FILENAME) with the filetypes DOC,
NOT, D#C, N#T, and PRN as appropriate.    (See FILE USAGE.)

EXAMPLES:
   ftnote dissert -e     extracts DISSERT.NOT from DISSERT.DOC
   ftnote art1 #an^     combines ART1.DOC and ART1.NOT into
            ART1.PRN for printing (see options below)

In the following instructions, the phrase "the DOC file" means the
file with your specified name, and filetype DOC, i.e. ART1.DOC.  "The
NOT file" is then ART1.NOT, etc.

UTILITY MODES:
     If you wish to create the needed NOT file by extracting footnote
text from your DOC file, use the "-e" mode.
     If you later wish to replace the footnotes into the DOC file,
which makes major editing of the document a lot easier, use "-r" mode.
     If you wish to have end notes instead of footnotes, once you
have the DOC and NOT files separate, the "-n" mode will simply number
the notes in each sequentially, producing files D#C and N#T.  This
mode does NO other formatting.
     The default mode is formatting mode, which combines the DOC and
NOT files into a PRN output file with notes at page bottom, etc.  Most
of the following instructions apply to the preparations for or use of
this format mode.

FORMATTING OPTIONS:
     If you are ready to format (combine the DOC and NOT files into a
PRN file ready to print), the option string may contain any of the
following:    (1) the character "#".
          (2) the character "^".
          (3) any ONE of characters =, ~, _, @.
          (4) any PAIR of characters A, N, Q, W, E, R, Y.
These allow you to choose the following optional features.
     (1) By default, footnote numbers run continuously from 1 to 99
(or 999).  However, if you use the "#" option, you can instead have the
numbers start over at 1 on each page.
     (2) By default, footnotes are printed at the bottom of the
page even when the text ends higher up.  Use the "^" option if you
would prefer the notes to be right under the text regardless.
     (3) By default, page bottom notes are preceded by a blank line
followed by a short line of dashes (-).  The length of this line can
be changed via a user patch, below.  You can change this to a line of
=, ~, or _ if you prefer.  (For _, this line will precede the blank
line, so it doesn't collide with footnote superscripts.)  If you want
no visible line, use @, and you will simply get two blank lines.
     (4) You may choose to have footnotes print out in a different
print style than the body of the text.    If you have a set of ^P codes
installed in WordStar to use such a feature of your printer (for
example, compressed print mode on a matrix printer), put the appro-
priate pair of letters in the option string.  For example, if you
have set up ^PA to enter compressed mode and ^PN to return to normal
print, use "AN" in the option string.  (Remember to format the note
file accordingly; use wider margins for smaller print, so the text
and notes will have the same physical line width in the PRN file.)

FILE USAGE:
Be sure to give your original source file the filetype "DOC".
     All files to be used by FTNOTE must be on the same drive: the
one you specified on the command line (or the logged drive).
     Here is a summary of FTNOTE's file usage.    Note that in order
not to fill up your disk, it does not create BAK files.
       MODE      INPUT FILE(S)   KEPT?      OUTPUT FILE(S)
       ----      -------------   -----      --------------
    -n        .DOC, .NOT       yes           .D#C, .N#T
    -e           .DOC       NO           .DOC, .NOT
    -r        .DOC, .NOT       NO         .DOC
     (format)        .DOC, .NOT       yes         .PRN
Always keep a backup copy of your document and notes, in case something
goes wrong.  Note that in the "-e" and "-r" modes, FTNOTE replaces or
erases the existing DOC and NOT files when it is finished.  (Unless it
aborts, in which case it will merely leave a ".$$$" file behind.)  To
protect your existing notes, the "-e" mode will refuse to run if a NOT
file already exists.
     Make sure you always have enough space on the disk to hold another
full copy of your entire document, whatever mode you are using.
     When using format or "-n" modes, every DOC file must have its
corresponding NOT file, even if it makes no footnote calls!  Running
"-e" on a DOC file with no footnotes will produce an empty (0 K) NOT
file, which must exist for format or "-n" mode to work.
     You can print the PRN file with WordStar or MailMerge, but be
cautious about editing it.  Don't insert or delete lines, or the page
breaks will get misplaced.  If you want to revise the document, edit
the DOC file, and run FTNOTE again.
     Very large files are best broken up into manageable pieces (this
is true even when not using FTNOTE).  Output can be recombined using
the .FI dot command, or page and footnote numbers can be made to mesh
using the .PN and .FN commands to start each piece with the appropriate
numberings.

-------------------------------------------------------------------

             III. USING FOOTNOTES

FILE FORMAT:
     Unlike some commercial programs, FTNOTE does not use non-Wordstar
type imbedded commands that disturb the appearance of your text file.
You can create your text just as you have in the past.
     Whenever you need to insert a footnote, a place is held for its
number with two "##" characters.  (When you want to start again with
note 1, use "#1".)  These must be enclosed within a pair of characters
of your choice, called "delimiters".  Typical delimiters are pairs of
brackets "[##]" or WordStar superscript codes "^T##^T", or a leading
space and a following period " ##.".  You must use the same delimiters
consistently throughout your text, but you may use a different set in
the notes.
     The footnotes must be entered into the file following a <CR> (hard
carriage return), typically (but not necessarily) the one that ends the
paragraph in which they were called; and in the proper order.  Each
note must begin with another delimited "##" (or "#1") flush left.  At
the end of the block of notes, enter a "]" followed by a <CR>, and then
continue with the text.
     You might write the file ART1.DOC like this (each "<" flag in
Wordstar indicates a hard carriage return):

          |  ...seafood derivatives in the native  population
   (text)     |  as a whole. [##]  This result agrees with recent
          |  findings, as well as the classic  study [##]  of
          |  Jenkins and Namabi.                   <
------------- |   ##. This does, of course, vary greatly with the
 (block of    |  season.  See Hirsch (1944), chapter XII.       <
   notes)     |   ##. B. Jenkin and S. Namabi (1961), "Seafood in
------------- |  the Native Population", JGH 7:156-78. ]       <
 (more text)  |       On the other hand, fairly little is known...

Note the use of brackets as delimiters in the text; a space and a
period as delimeters in the notes; and the "]" ending the note block.
     Running FTNOTE in the "-e" (extract) mode will then remove all
these footnotes into a separate file.  (Alternatively, if you find it
convenient, you may write them in a separate file yourself to begin with,
as version 1.0 required.  No closing "]"s are needed in the NOT file.)
     Now you have a file ART1.DOC which looks in part like this:

    |  ...seafood derivatives in the  native population
    |  as a whole. [##]  This result agrees with recent
    |  findings, as well as the classic  study [##]  of
    |  Jenkins and Namabi.                     <
    |    On the other hand, fairly little is known...

and you have a file ART1.NOT which looks in part like this:

    |   ##. This does, of course, vary greatly with the
    |  season.  See Hirsch (1944), chapter XII.         <
    |   ##. B. Jenkin and S. Namabi (1961), "Seafood in
    |  the Native Population", JGH 7:156-78.         <

Finally, running FTNOTE in "format" mode will produce the output
file ART1.PRN, a non-document file looking something like this:

    |...found to be far greater than the average intake  |
    |  of seafood derivatives in the  native population  |
    |  as a whole. [19]  This result agrees with recent  |
    |  findings, as well as the classic  study [20]  of  |
    |  Jenkins and Namabi.                     |
    |    On the other hand, fairly  little is  known  |
    |  of possibly similar practices in the neighboring  |
    |                             |
    |  ------------------------                 |
    |   19. This does, of course, vary greatly with the  |
    |  season.  See Hirsch (1944), chapter XII.         |
    |   20. B. Jenkin and S. Namabi (1961), "Seafood in  |
    |  the Native Population", JGH 7:156-78.         |

Observe that the text will remain formatted exactly as it was in the
DOC file, and the notes as they were in the NOT file.

     Note: if you are going to use "-n" mode for end notes, you MUST
use "#1" in the corresponding footnote each time you use it in the
text, or your end notes will be misnumbered.  Use of "#1" in the notes
is not required for format mode, but is recommended for consistency.

THREE-DIGIT FOOTNOTES:
     With larger documents, you may find that you need the footnote
numbering to continue past 99.    It is now possible to use FTNOTE with
footnotes up to 999: instead of using "##" (or "#1") as shown in the
examples above, simply use "###" (or "##1").  If you do not need the
larger note numbers, you will find that the two-digit form above will
produce more attractive results.  Note that whether you choose two- or
three-digit footnotes, you must be consistent throughout your document
and notes.

ADVANCED TECHNIQUES:
     With a little ingenuity, you can get FTNOTE to handle a variety
of format requirements that I didn't have in mind when I wrote it.
Here are some problems people have had in the past.
     Example 1:  FTNOTE requires footnote text to begin in column 1,
but you want your whole document (text and notes) to print out with
a ten-space left margin.  Solution: write your file without the
margin (all those extra spaces waste disk space anyway).  Use a dot
command, either .LM or .PO, to create the margin at print time.
     Example 2:  MLA footnote style requires the first line of each
footnote to be indented, and the number superscripted.    Solution:
use a fixed tab (^PI) and a superscript as your delimiters in the
notes (e.g. ^I##^T).  Then after formatting, edit the PRN file and
change all ^I##^T to ^I^T##^T, completing the superscript toggles.
     Example 3:  You want to take advantage of Figure Blocks, page
referencing, etc, but you want end notes, not footnotes.  Solution:
Run "-n" mode first.  (This produces a D#C file which has no "##"
footnote calls, and a N#T file.)  Then rename the D#C file to NEW.DOC,
the N#T file to NEW.NOT, and format these with FTNOTE NEW.  The NEW.PRN
file will then be your final text, and NEW.NOT is the endnotes for it.

--------------------------------------------------------------------

              IV. PAGE REFERENCING

     The automatic internal page referencing feature available in format
mode allows you to refer in the course of your text to a number of other
locations in your text by page number.    The two most common uses for
this are in constructing a table of contents, and referring to figures
and other references.  FTNOTE allows 52 separate locations to be marked
for this use; references may be made either earlier or later in the text.
(This feature cannot be used to build an index; the number of markers is
too small, and each should be set at only one location.)
     Page references are delimited by the control character ^P, placed in
your WordStar text like any other control-P code, by typing ^P, then P.
Referencing will not be invoked if no ^P is found in your DOC file.  It
is a two-pass operation, so it will double the formatting time for your
document, if used.  You will get a message "Scanning ahead..." when page
referencing begins, and "Scan complete" at the end of the first pass.

SUMMARY:  To set reference marker A:   ^PA^P     (no adjacent spaces)
      To call for its value:       ^PAAA^P     (spaced normally)

     Page reference markers run from "A" to "Z", and from "a" to "z".  To
set marker "A", identifying a location for further reference, you enter
the sequence "^PA^P" in your text between an appropriate pair of words,
with NO intervening spaces: for example, "CHAPTER^PA^PIV. ASTRONOMY."
You can now refer to the page on which "CHAPTER IV" occurred by asking
for the value of marker "A", by entering the sequence "^PAAA^P" where you
want the page number: for example, "Chapter IV...........page ^PAAA^P."
In formatting, the marker setting "^PA^P" will be replaced by a space " ",
and any marker references "^PAAA^P" will be replaced by that page number,
giving for example "Chapter IV............page 29.", assuming the heading
"CHAPTER IV. ASTRONOMY." winds up on page 29.
     Page references may be in a different file from the corresponding
marker setting, only if the files are chained with the .FI command.
Otherwise the attempt to reference a nonexistent marker gives an error.

--------------------------------------------------------------------

             V. TECHNICAL DETAILS

DOT COMMANDS:
     You should be aware that certain WordStar/Mailmerge dot commands
work in a nonstandard manner with FTNOTE, and a few are not allowed.
The nonstandard group are interpreted by FTNOTE, and often are removed
from the PRN output file.  These include:
    .PL will change the page length.  (See PRINTER FORMAT.)  It may
occur only once, at the top of your DOC file.
    .HE, .PA, and .PNnnn,  all have their normal effects, except that
the default header is a blank line with page number at column 74.
    .CPnn will work as intended unless the text it covers includes
footnotes, which may cause a page break earlier than expected.
    .LSnn will change the line spacing of the text in the formatted
output, but will leave footnotes and Figure Blocks single spaced.  When
entering consecutive blank lines, remember that each one will be multi-
plied by the current LS spacing.
    .FI NEWNAME.DOC, as the last line of the DOC file, will chain to
a new pair of input files, NEWNAME.DOC and NEWNAME.NOT, while still using
the same output file(s).  Thus you can break a large document up into
small pieces, and have the output combined properly upon formatting or
numbering.  The alternative would be to use the .PN and .FN commands at
the beginning of each piece to match up the page and footnote numbers,
and process and print each separately.    .FI works in "-n" mode also; it
is ignored by "-e" and "-r".  Do not specify a drive; all files will be
sought on the same drive as the original ones.
     (.LS and .FI are MailMerge commands, but you don't have to use
Mailmerge for them to work, because FTNOTE is processing them itself.)

     The dot commands that are not allowed are those that would upset
the vertical page formatting FTNOTE is doing.  These are .FM, .FO, .HM,
.LH, .MB, and .MT.  (Note: the formfeed character ^PL should not be used
either.)  Upon encountering any of these commands, FTNOTE will issue
a warning message, and suppress the command.  (If you really know better,
you can edit the PRN file: you will find the offending dot command with
".IG" stuck in front of it, which you can remove.  But the result will
probably be misplaced page breaks.)

     FTNOTE also offers two dot commands of its own:
    .FB (Figure Block) provides another formatting capability WordStar
lacks.    ".FB nn" will force the next 'nn' lines of text to print as a
contiguous block at the top of the next new page; the current page con-
tinues until full, in contrast to the .CP command.  This block may, for
example, contain the text of a table, or blank lines for a figure to be
pasted in.  At most a whole page can be reserved (Page Length - 1 - Header
Margin - Bottom Margin, by default 66 - 1 - 3 - 8 = 54), so any larger value
of 'nn' will default to one page.
    .FN (Footnote Number): ".FN nnn" sets the next footnote number to
'nnn'.    This is most useful in combination with .PN at the beginning of a DOC
file.  (.FN works in "-n" mode also, IF it is the first line of the file.)
     WordStar itself ignores these two FTNOTE dot commands.

PRINTER FORMAT:
     The default page format for FTNOTE is intended for standard
11" paper at 6 lines per inch, giving 66 lines per page.  In this
case FTNOTE actually prints 54 lines per page.
     You can vary the placement of text on the page by moving the
platen and resetting top-of-form on your printer.  If you want to
use different forms, such as legal paper, the page length may be
changed via the .PL command or user patch.  If you have installed
WordStar with a default page length other than 66, you should change
the .PL user patch to get FTNOTE's page length to agree.  When
printing the PRN file, instruct WordStar to use formfeeds, if that
is not your default.
     The size of the top and bottom margins may also be changed by user
patches.  These changes cannot be made merely by editing the dot commands
that begin an existing PRN file: they affect the page length, and page
breaks would be misplaced.

CAVEATS:
     Don't try to put footnotes, dot commands, or ^P page references in
the text of a Figure Block or a footnote.  FTNOTE won't recognize them.
Don't use the page reference code (^P) for any other purpose.
     Be sure to follow the instructions on FILE FORMAT above exactly.
A small error could cause a note to be ignored, or a portion of your
text to be misplaced.  In particular, be careful not to misuse the "#"
or "]" characters.   If you see a problem in your output, a little
experimentation should lead you to a solution.
     You must be in single spacing (^OS1) before entering footnote
text.  This should be no problem: since .LS can control line spacing,
you should never need to use the ^OS command anyway.
     Be careful while using alternate print modes (including underline,
italics, etc) in your document.  If a page break occurs while the text
is in such a mode, for example, any footnotes on that page, along with
the next page header, will also appear in that alternate print mode.
You may have to edit the PRN file and insert extra print codes.
     Proofread your output carefully!

----------------------------------------------------------------------

          VI. FURTHER TECHNICAL NOTES

USER CUSTOMIZATION:
     You can change several default parameters in FTNOTE.COM, if you
wish, by using DDT, SID or equivalent to patch the following bytes:
ADDRESS  DEFAULT  LEGAL RANGE    DESCRIPTION
-------  -------  -----------    ------------------------------------
 08D8H     23H (#)   20H - 7FH    Footnote number character
 08D9H     5DH (])   20H - 7FH    Character marking end of note block
 08DAH     03H (3)   00H - 08H    Lines between header and text (.HM)
 08DBH     08H (8)   00H - 08H    Lines left blank at page end (.MB)
 08DCH     42H (66)  08H - 7FH    Physical page length in lines (.PL)
 08DDH     4AH (74)  01H - 7FH    Column number for page number
 08DEH     10H (^P)  01H - 1DH    Control code for page referencing
 08DFH     14H (20)  01H - 7FH    Length of dashed line for footnotes
Thus you can, for example, avoid complications in a text that contains
many "#" signs by changing to "@" for your number marker character; or
get more lines on the same size page by decreasing the .MB number.
     You can also change the filetypes used by FTNOTE, if for example
you prefer "TXT" to "DOC".  The default filetypes DOC, NOT, PRN, D#C,
and N#T appear from address 08E0H to 08F3H.
     NO changes to the object code of FTNOTE.COM by the user are auth-
orized outside the address range 08D8-08F3 provided for this purpose.

ERROR MESSAGES:
     These are immediate error messages:
! no file          (no file name specified)
! bad option X          (illegal or contradictory format option specified)
! NOT file exists     ("-e" won't run if there's already a NOT file)
! bad user patch      (an illegal default value has been patched in)
     These are non-fatal warning messages; be aware that something may
not be working as you intended.  Abort with ^C if you wish.
? ignored .XX           (unacceptable dot command)
? ignored .XX; bad argt    (bad number in .CP, .FN, .FB, .LS, or .PN)
? extra notes           (better check for missing references in text)
     These errors will cause formatting to abort; the PRN file will
end abruptly where the error was detected.
! missing notes       (there's no note body for a footnote call in text)
! buffer full          (you probably forgot to terminate a footnote)
! duplicate ref X     (you tried to set this marker a second time)
! not set: ref X      (you tried to reference a marker that wasn't set)
! bad ref ^P$          (invalid page marker reference attempt)
! can't open MY.DOC   (can't find (or write to?) the specified file)

VERSION HISTORY:
     This program was developed on an Osborne Executive computer with
CP/M 3.0 and WordStar 3.3, using the Software Toolworks C/80 compiler.
It has been much improved since, largely in response to user feedback.
Note: files created with earlier versions should be upward compatible,
but not necessarily vice versa.  [Exception: page referencing codes
from versions 1.3x are not compatible with version 1.4.]
  84/03/29    FTNOTE 1.0   8K
     The basic program, with "formatting" mode only.  Options allow
    numbering and print mode control.  Requires the user to write a
    separate file of notes.  Offers .FB figure block command.
  84/04/09    FTNOTE 1.1   10K
     Added "-e" and "-r" modes: note texts can be entered in the
    document, immediately following the "[##]" call, making writing (and
    editing) easier.  Added the .FN dot command.
  84/04/25    FTNOTE 1.2   12K
     Notes can be entered en bloc at paragraph bottom.  Added "-n"
     mode for folks who want end notes.  Allowed dot commands .LS and .PL.
     Options: vary line character; print notes up with text on short pages.
     NOTE --->    Version 1.21 corrected a bug in the page header.
  84/06/14    FTNOTE 1.3   16K
     Better algorithm allows more flexible options for delimiters,
     fewer recognition errors.    Added page referencing feature, .FI dot
     command.  Several default parameters made user-patchable.
     NOTE --->    Versions 1.31-33 corrected minor bugs: more dot commands
     are now "acceptable"; last-line note calls no longer cause trouble.
  84/08/27    FTNOTE 1.4   17K
     Allows larger page and (optionally) footnote numbers.    Page ref-
     erence codes modified for larger numbers (no longer compatible with
     versions 1.3x).  Footnote separator line options improved.  Minor
     bugs associated with use of ".FI" and "#1" fixed.

FEEDBACK:
     If you think you have found a bug in this program, or have some
suggestions for improving it, please contact:
      Eric Meyer, 427 N. Washington, Bloomington, IN 47401.
      Phone [phone], CompuServe [74415,1305].
As said above, this program is free, and I hope you find it useful.
However, if you would like to express your support for it, you may send
a check for $10 to become a registered user: you will be notified of
future revisions, and can order copies of the latest version in most
common minifloppy formats for $5 each.

-----------------------------------------------------------------------