home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ftp.barnyard.co.uk
/
2015.02.ftp.barnyard.co.uk.tar
/
ftp.barnyard.co.uk
/
cpm
/
walnut-creek-CDROM
/
CPM
/
PROGRAMS
/
WSTAR
/
WSNOT134.ARK
/
WSNOTE.DOC
< prev
Wrap
Text File
|
1988-05-22
|
30KB
|
601 lines
INSTRUCTION MANUAL
tm
wsNOTE
note formatter
(c)1988 E. Meyer
427 N. Washington, #4
Bloomington, IN 47401 USA
ABOUT wsNOTE
------------
wsNOTE is a small, fast, easily used program that enables you to produce
numbered footnotes or endnotes with your WordStar program. It has some
additional formatting features as well. wsNOTE is completely independent of
WordStar, and requires no modifications to your present copy of it; yet wsNOTE
can be run without ever leaving WordStar.
Its advantages include:
* - Simple,natural file format. No strange embedded commands; no control
codes to conflict with your printer installation, or other software.
* - Fast, one-pass operation produces either footnotes or endnotes from the
same source file; notes can be typed along with text or separately.
* - Can also function as a simple numbering utility, for example, numbering
items in a bibliography.
* - Figure Block feature offers space for illustrations without interrupting
the flow of text.
* - Large documents may be split into separate files,which can be chained
together for output or processed separately.
* - You have complete flexibility in format of note numbers and text.
wsNOTE works on text files created with WordStar or compatible programs
(like NewWord), including the new WordStar 4.0. The CP/M version runs on any
CP/M or compatible (eg, ZRDOS) computer. The MSDOS version runs on any PCDOS
or MSDOS computer with at least 128K RAM.
This manual contains no special codes other than formfeeds. It can be
printed out, or examined onscreen with any editor. It was written using VDE
(Video Display Editor) 1.21, another program from the same author.
SHAREWARE POLICY
----------------
This version of wsNOTE is "shareware", user supported software. There is
no initial obligation: feel free to give wsNOTE a thorough trial, and to keep
it around for occasional use. If you find that wsNOTE meets your needs and
you will be using it regularly, please send a modest contribution of $20
(individual) or $50 (corporate) to the author:
Eric Meyer
427 N. Washington #4
Bloomington, IN 47401 USA
CompuServe [74415,1305]
Upgrades on disk, and printed manuals, are NOT available from the author.
For the latest release of wsNOTE, watch the MicroPro SIG on CompuServe (GO
MICROPRO) and other BBS systems.
****************************************************************
***** The wsNOTE utility and its documentation are *****
***** (c)1988 E. Meyer, all rights reserved. *****
***** They may not be circulated in any incomplete or *****
***** modified form, nor sold for profit, without *****
***** written permission of the author. *****
****************************************************************
DISCLAIMER: You undertake to use wsNOTE at your own risk. The author
accepts no liability for any damages resulting from its use or misuse. Direct
problem reports and suggestions to the author; include a stamped return
envelope for a reply if desired.
NOTES: Please observe in what follows that "WordStar", "NewWord", and
"Mailmerge", are trademarks of MicroPro International or NewStar Software.
The wsNOTE program was formerly sold as a commercial product; it is now
released as shareware by the author.
GETTING STARTED
---------------
The wsNOTE package should contain the following files:
WSNOTE.EXE (or COM) - the wsNOTE program
CONFIG.EXE (or COM) - a configuration utility
SAMPLE.FIL - a sample text file to practice with
In addition there may be a READ.ME file, containing last-minute updates to the
information in this Manual. If so, TYPE or PRINT this file, or edit it with
WordStar or VDE, to read it. Eventually you will want to move WSNOTE, and
possibly its CONFIG utility, onto your working WordStar disk (if there's room).
wsNOTE is a "post-processor": it reads through a text file that you
create with WordStar, and it creates a formatted file for you to print. This
means that wsNOTE consumes no memory, and will not interfere with your
existing writing process. The same input file may be processed to produce
either footnotes or endnotes, as desired. The output is a standard WordStar
document file, and any other software (like indexing utilities) may be used on
it prior to printing.
You can convert existing documents for use with wsNOTE. The easiest way
is to replace all the note numbers with "##" signs, and collect all the notes
in a separate ".XNT" file (see "EXTERNAL NOTE OPTION", below).
This Manual is short; please read it thoroughly. It covers:
1. How to create or modify text files for use with wsNOTE. (You may
want to examine the file SAMPLE.FIL as you read this.)
2. How to run the WSNOTE program itself, to format and number your
notes, and proofread and print the output.
3. How to use the CONFIG program to take advantage of the many
formatting options of wsNOTE.
You will need to be familiar with the use of WordStar itself on your
computer, including the "dot commands" used by WordStar (and Mailmerge) for
print-time formatting. If you find yourself needing to refresh your memory on
any of this, keep your WordStar manual handy as you proceed.
The following instructions apply to both the MSDOS and CP/M versions of
wsNOTE, and to the use of either WordStar or NewWord, identically.
FILE FORMAT
-----------
First, you need to know how to type a note call in your text, the place
where the note number should go. Just type it as you always have, except that
instead of an actual number like 17, type two or three "#" characters. The
number may be formatted in any way you like: in square brackets "[##]", or
superscripted "^T##^T", etc. The "#"s will be replaced by the actual note
number when you run WSNOTE. Use of two "#"s gives note numbers up to 99; use
three only if you expect you will need numbers larger than 99.
Once you make your choices of format and number of digits, every note
call in the file must be done the same way. Any call that is not done exactly
like the first will not be recognized. (There is one exception: when you want
the note number to reset to 1, as at the start of a new chapter, you may use
"#1" instead of "##", or "##1" instead of "###".)
EXAMPLE: Try the ^SwsNOTE^S^T#1^T program to format your notes.^T##^T
1 2
RESULT: Try the wsNOTE program to format your notes.
Second, you need to know how to type the actual notes. They can be put
after the end of any paragraph, either before or after their calls, though
they should be reasonably close. The natural place is at the end of the
paragraph in which the calls occurred. Keep the notes in the proper order,
and remember not to try to put them into the middle of a text paragraph; they
would not be recognized.
Each note (or group of several notes) must be enclosed as a "note block"
between the characters "{}" (curly braces), which distinguish a note block
from a paragraph of ordinary text. The "{" must be the first character on its
line, and the "}" the last on its. Neither brace will appear in the printed
output; they are markers only.
Each note within the block must have somewhere on its first line a number
"##" or "###" with the same number of digits as the calls have. They may be
formatted differently from the calls, but again all notes must be done the
same way. You can, for example, use "[##]" for the calls and "##." for the
notes. Use of "#1" and "##1" in the notes is allowed, if it helps you keep
things straight, but is not needed, and has no effect.
EXAMPLE: { ##. "wsNOTE" is a trademark of the author.
##. The program can produce either footnotes or endnotes,
depending on your preferences.}
EXTERNAL NOTE OPTION: Most users find note blocks integrated with the
text to be easiest to use and keep track of. However, if you prefer to type
your notes in a separate file (or have already done so), wsNOTE has an
"external note" option. Don't put any note blocks in your text. In the note
file, just type in the notes as desired, with "##" in place of the numbers;
don't use block markers ("{}"). Give the note file the same name as the text
file, and the type ".XNT"; for "PAPER2" or "MAGAZ.ART", use "PAPER2.XNT" or
"MAGAZ.XNT". If an ".XNT" (external note) file is present, wsNOTE will
automatically use it.
DOT COMMANDS
------------
When using wsNOTE, a few WordStar/Mailmerge dot commands should not
ordinarily be used. Others will operate somewhat differently than usual,
because wsNOTE interprets them itself at formatting time, and may or may not
pass them along to WordStar as well. Also, two new ones are available.
Dot commands that should usually not be used are: ".LH", which would
change the vertical spacing of lines; ".PF", ".LM", and ".RM", which would
cause print-time reformatting of text. If wsNOTE encounters these commands,
it will issue a warning message, but will keep going. Thus you can use them
if you really know what you're doing; but this is not encouraged, and page
misalignment may result.
(You should also avoid the formfeed character, ^PL.)
Dot commands whose usage differs under wsNOTE are:
".PL", ".MT", ".MB" can each be used only once, at the beginning of your
file, before any text, or page misalignment may result. If used, they
override any default set with CONFIG.
".CP" may not function as intended if the text it governs includes
footnote calls, since the notes cause the page to fill sooner than expected.
".LS" will affect the spacing of the output text, but not the notes. In
particular, ".LS 2" will produce double spaced text, while the notes remain
single spaced. This (rather than typing with ^OS) is the recommended method.
".FI" should be used only at the end of a file, where it will chain to a
new input file. Don't specify a drive; the file will be sought on the same
drive as the original one. This is the easiest way to break up a large
document. For example, PART1.DOC might end with the line ".FI PART2.DOC".
(Although ".LS" and ".FI" are Mailmerge commands, you don't need Mail-
merge for them to work, because wsNOTE is processing them itself.)
wsNOTE also has two new dot commands of its own:
".NN" (Note Number), sets the current note number the same way ".PN" sets
page numbers. This can be used to reset to 1 at the start of a chapter, or to
synchronize numbers across multiple files.
".FB" (Figure Block), provides an extra feature which WordStar lacks.
".FB nn" causes the next 'nn' lines of text (or blank space) to appear
together on the next page, while the surrounding text continues to flow around
normally. Thus in contrast to ".CP", no premature page break occurs. If you
can't see immediately how this is useful, try it out! This feature is used
for printing tables intact, or setting aside space for an illustration to be
pasted in, without interrupting the text in an unnatural way. Figure blocks
can be no larger than one page.
(WordStar will of course not recognize ".NN" and ".FB" as valid dot
commands; don't be disturbed by the "?" shown in the flag column.)
RUNNING wsNOTE
--------------
Once you've done the work of writing your file, actually formatting it is
easy. You can do this either from the operating system prompt, or from within
WordStar via the Opening (No-File) Menu "R" command. If you've never used the
"R" command, now is the time to discover it. It allows you to run nearly any
command or program, without exiting from WordStar. At the Opening Menu, type
"R". WordStar asks "COMMAND?", and you simply type in the name (followed by
any required arguments) and press <RETURN>. When the program is finished, the
message "Hit any key to return to WordStar" will appear; doing this brings
back the Opening Menu.
In either case, WSNOTE takes two arguments. The first is your text
filename, and is required. Include the drive, if different from the current
drive. The second is an optional flag "-e", if you want endnotes; omit it if
you want footnotes.
EXAMPLES: (from DOS, with endnotes) A>wsnote b:sample.fil -e
(from WordStar, with footnotes) COMMAND? wsnote sample.fil
There must be enough free space on the disk in use for another complete
copy of your document. Remember to add together the sizes of any files you
are chaining together, and add a few extra K just to be safe. When wsNOTE
stops, there will be a new file on the disk, with the same name as the (first)
input file, but the type ".PRN". (SAMPLE.FIL will produce SAMPLE.PRN.) This
is the formatted output, all set to print using WordStar's "P" print command.
It is wise to make a habit of proofreading the ".PRN" file before
printing it, in order to check the page layout. Edit it in "D" (document)
mode, and scroll through it at will. But remember, to make corrections you
should edit your source file, then run wsNOTE again. Make changes directly in
the ".PRN" file only when needed to get it to print the way you want; and
never do anything resulting in a net change of the number of lines. This
would cause pages to become misaligned in printing. (Make sure WordStar's
page break indicators agree with the wsNOTE "..page" markers.)
If you selected endnotes ("-e"), there will be a second output file with
the type ".NOT", containing your notes. It is also a document file, but may
be edited or reformatted as you like before printing. (You may, for example,
want to insert a ".PN" command to get the right page numbering.)
NUMBERING OPTION: It is also possible to use wsNOTE to simply number
items in a list, for example a bibliography. Just enter the usual "##" (or
"###") for the number of each item, making sure that all are formatted exactly
the same way. Then run WSNOTE on the file, with the option "-n":
EXAMPLE: COMMAND? wsnote bibliog.104 -n
The numbering will proceed sequentially from 1 (unless modified with "##1" or
the .NN command). Other wsNOTE features (such as figure blocks) also remain
active. The output file will have the type ".PRN".
USAGE TIPS
----------
Make sure that you either (1) use CONFIG to set the page length, top and
bottom margins in wsNOTE to agree with the defaults you have installed in your
copy of WordStar, or (2) always put ".PL", ".MT", and ".MB" commands at the
top of your file. Otherwise wsNOTE and WordStar won't agree on the page
format, and pages will get misaligned.
Follow the "FILE FORMAT" instructions exactly. If a note call or number
is not done correctly or consistently, wsNOTE won't recognize it, and notes
may start getting mismatched, or an error may occur. If a note block is not
correctly marked off, it will appear to be missing, or not to end, and an
error will result.
Be careful if you "block move" a note block, to be sure that it still
stands as a paragraph: begins after, and ends with, a hard carriage return.
If you use right justified text, don't use three "###" signs unless you
will need numbers over 99. The extra one will add an unnecessary space.
wsNOTE features don't "nest": you can't put dot commands, note calls, or
note blocks inside of other note blocks or figure blocks.
The .LS command is the easiest way to produce double-spaced text. The
alternative, multiple line spacing with ^OS in WordStar, can cause problems in
the spacing of notes, and is not recommended. If you must use ^OS, be sure
that only a single <RETURN> precedes and follows each note block.
If you want a blank line between each note in your output, insert an
extra <RETURN> after every note in the source file. Remember to do this for
the last note in each block, too (before the closing "}"), or some notes will
not be spaced properly.
There are two ways to handle a document consisting of multiple files.
First, you can chain the files together with a ".FI" at the end of each. This
will produce a single ".PRN" file, with the name of the first input file. (If
you are using external notes, they must also be in a single ".XNT" file with
that name.)
Alternatively, you can process each file quite separately. At the start
of each file, you can use the ".PN" and ".NN" commands to synchronize the page
and note numbers. This is best if a single output file would be unwieldy.
Problems can occur in printing the ".PRN" file, if a page ends while an
alternate print mode (underlined, compressed, etc) is in effect. For example,
the footnotes and next page header may also print in that mode, or the text
may fail to return to it on the next page. In this event you will need to
stop the printing, edit the ".PRN" file, and manually insert extra print codes
where needed to correct the problem. Then print out the offending pages
again. Be careful not to insert or delete any lines in the process, or pages
will become misaligned.
The smaller the capacity of your disk drive, the smaller you should keep
your text files. WordStar always makes temporary and backup files; this can
quickly fill up a small floppy disk. Delete ".BAK" files when you can, and
".PRN" files once they're printed.
USING CONFIG
------------
The CONFIG utility offers you a number of quick, useful ways to customize
the use of wsNOTE to suit your tastes, or the requirements of a style manual.
Most people will only need to run CONFIG once. If you often have to use
different styles, you will need to either keep CONFIG on your disk with WSNOTE
or set up several different copies of WSNOTE.
CONFIG takes a single argument, the name of your wsNOTE program. (In-
clude the drive if it's not the current drive.) Again, CONFIG may be run from
either the system prompt or the "R" command in WordStar.
EXAMPLE: COMMAND? config wsnote.exe
You will see a menu of all the parameters you can change, which are
described below, and their current values. Type the menu letter of the one
you wish to change, then enter the desired value. When you're through, hit
<RETURN> to save your changes, or type ^C to abort without saving. This copy
of WSNOTE.EXE (or COM) will be modified as you chose.
Read this list now, to familiarize yourself with the control you have
over the appearance of the printed output. The choices, in order, are:
A: note number character. The default is "#". If you want or need to
use a different character to designate note numbers, you may.
B,C: note block delimiters. The defaults are "{}". Again, if you
prefer different characters you may change these.
D,E: note line character, length. The character to use for the note
separator line between text and footnotes (D), and how long the line should
be (E). Defaults are "-", 20 characters. You may prefer "~", "_", etc, or
a longer line. If you want no line, set the length to 0.
F,G: blank lines before, after line. These are the number of lines you
want to skip before and after the note separator line. Defaults are 1 line
before (F), and 0 after (G).
H: minimum lines for note start. Setting this to "n" means that if
there is not room on the page for the first "n" lines of a footnote, the
note will be postponed to the next page. Default is 1 (no postponement).
I,J: printer codes for notes. You can get your notes to automatically
print in a different mode from the text (such as compressed), if you want.
Enter the WordStar control code you've installed to turn on the printer mode
desired for the notes (I), and the one to return to your text mode (J).
These might be, for example, ^Q and ^R; type these codes in directly.
If you use a print mode with a different character width, be sure to
format your note blocks with appropriately adjusted margins, so their prin-
ted width will match that of the text.
Defaults: no codes. (This displays as "none", and may be entered from
the keyboard by typing <RETURN> alone.)
K: physical page length. This is the number of lines on a page. Set
it to agree with whatever you have installed in WordStar. This setting is
overridden by the .PL command, if used. Default: 66 lines (for ordinary 11"
paper, 6 lines per inch).
L,M: top, bottom margins. Again, set these to agree with the defaults
you have installed in WordStar. These settings will be overridden by the
commands .MT or .MB, if used. Defaults: 0 lines top, 0 lines bottom.
N: new page resets to note 1? To change this, enter "Y" or "N". If
you set this to "Yes", the first note number on each page starts over again
at 1. Default: "No", note numbers continue to increment.
O: notes up on short pages? Enter "Y" or "N". Ordinarily "No", and
footnotes always print at the very bottom of the page. If set to "Yes", on
a partly filled page, notes (if present) print up right under the text.
P: avoid widow text lines? Enter "Y" or "N". Ordinarily "No"; if you
set this to "Yes", wsNOTE will avoid beginning a paragraph on the last line
of a page (it will begin on the next page instead).
Q: right justified text? Enter "Y" or "N". Ordinarily "Yes", and
extra (soft) spaces are inserted where necessary to preserve justification
(for example, after one-digit note numbers). Set to "No" to avoid these
extra spaces in unjustified text.
R: buffer size in K. There are four buffers in wsNOTE, each of this
size (default: 6K). The minimum is 2K. If you start getting "buffer over-
flow" error messages from wsNOTE, increase this size. If you get "buffers
exceed available RAM", decrease it.
CONFIG ERRORS
CONFIG modifies the actual WSNOTE.EXE file. This cannot be done if the
disk WSNOTE is on is write-protected, or Read/Only. In such cases, a BDOS
Error message will appear, and the changes will not be made.
Note that CONFIG will refuse to save if you have specified a buffer size
below 2K, or a page length that's too small for the margins. Correct the
offending value(s) and try again.
In addition, two error messages may appear when you try to run CONFIG:
"can't open input file" - The name you gave for your wsNOTE program doesn't
exist. Either it's misspelled or incomplete, or it's on another drive.
"can't CONFIG that file" - The file exists, but it either isn't wsNOTE, or
isn't the correct version.
ERROR MESSAGES
--------------
Every effort has been made to trap and identify errors neatly. When an
error causes wsNOTE to abort formatting, the output file(s) will of course be
incomplete. Take a look at the end of the ".PRN" file, to get an idea of
where in your source file the problem occurred. Then refer to this alpha-
betical list, for some suggestions as to the likely cause.
"bad dot command argument" - The number following a dot command appears to
be invalid or missing.
"bad figure block" - A figure block was still being read in when the end of
your file was reached. Either some of its text is missing, or you need to
decrease the number of lines in the ".FB" command.
"bad note block" - A note block was still being read in when the end of your
file was reached. This means the note block is not terminated properly
with "}", <RETURN>.
"bad option specified" - The only thing allowed on the command line after
"WSNOTE INPUT.FIL" is "-E" or "-N". You typed something else.
"buffers exceed available RAM" - Your computer doesn't have room for four
buffers of the current size. Use CONFIG to decrease your buffer size.
The maximum under CP/M will be about 10K; under MSDOS, about 15K.
"can't open file" - The file specified in a ".FI" command can't be found.
There is an error in the filename, or you tried to specify a drive.
"can't open input file" - The file you gave on the wsNOTE command line can't
be found on the current (or specified) disk. Did you misspell it, or is
it on a different disk?
"can't open output file" - wsNOTE can't write its output on the current (or
specified) disk. Either it's read-only, or its directory is full. (This
error can occur if your input file has the type ".PRN" or ".NOT", which
you should avoid.)
"figure block exceeds page" - A ".FB" command has requested a figure block
larger than the current number of free lines on a page. Decrease the
header and bottom margins, or make the figure block shorter.
"figure buffer overflow" - The text of a figure block filled the available
buffer. Decrease the amount of text in the block, or use CONFIG to
increase your buffer size.
"foot buffer overflow" - The text of footnotes already scheduled to print
has filled the available buffer. Don't call so many notes from a single
page, or make them shorter, or use CONFIG to increase your buffer size.
"missing note block" - A note block was still being searched for when the
end of your file was reached. Either some notes are missing, or there are
too many calls in the text.
"no file specified" - You didn't give wsNOTE the name of your text file, so
it couldn't even get started.
"no note in buffer" - The contents of a note block don't look like notes,
because there is no proper "##" number on the first line. There is
probably a simple error in its format. The same error in a subsequent
note in the block will cause it to become part of the preceding one.
In external note mode (with an ".XNT" file), this message indicates
that there weren't enough notes in the file for all the calls in the text.
"note buffer overflow" - Your note block appears to be too long to fit in
the note buffer. Probably, the block isn't terminated properly with "}",
<RETURN>. Possibly you've left out some calls, and so have too many
notes. If your notes are simply too large, or you've put in too many
before their calls, you need to increase your buffer size with CONFIG.
In external note mode (with an ".XNT" file), this message means that
one single note was too large to fit in the buffer.
"page align error" - This is very unlikely. It indicates that wsNOTE can't
cope with the combination of page length, header and bottom margins that
you have set with CONFIG, which must be pretty strange.
"source line too long" - There appears to be a line in the text file that
exceeds the maximum length, currently 256 characters. You probably forgot
to reformat a paragraph.
"text buffer overflow" - While looking ahead to find a note block, the text
buffer filled up. You need to put this note block closer to the point in
the text where it was called, or to increase your buffer size with CONFIG.
"[Warning: extra notes]" - This is only a warning. wsNOTE has finished, but
there still seem to be unused notes. Probably you left out a call in the
text, and the following notes may all be mismatched as a result. Proof-
read the output carefully.
In numbering ("-n") mode this error means that a note block was found.
"[Warning: found .XX]" - This is only a warning; formatting does not stop.
You have used a dot command that is not recommended, and will likely cause
misaligned pages in your printout. Abort wsNOTE with ^C if this was a
mistake. Proofread the output carefully.
"[Warning: multiple spacing]" - This is only a warning. wsNOTE has found
text that was multiple-spaced with ^OS. This may cause spacing problems
in the notes. Proofread the output carefully.
[END]
wsNOTE Manual Rev. 1.34 (05/88)