CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / lambda / soundpot / p / wsnot134.lbr / WSNOTE.DZC / WSNOTE.DOC

Wrap

Text File | 1993-10-25 | 29.1 KB | 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)