# % PAGINATE.TXT -- documentation for the PAGINATE command # % Please reformat using "PAGINATE PAGINATE.TXT PAGINATE.DOC /OVERWRITE /-I" # % (There's a batch file--PAGDOCS.BAT--that does this for you) # page=60 # adjust # date="mmm dd, yyyy" # TITLE CENTER WIDTH=79 ^O%12% ^B%3% ^A # end # % The default width (WIDTH=80) is overridden here because some users # % preferred it smaller but, in general, WIDTH=80 should be wonderful! # justify width 79 # index "Column headers" "(See also HEADER)" DUMMY # index "Country settings" "(See Date displays)" DUMMY # index "END" "(See FOOTER)" DUMMY # index "END" "(See HEADER)" DUMMY # index "END" "(See MULTICOLUMN)" DUMMY # index "END" "(See TITLE)" DUMMY # index "END" "(See UNIT)" DUMMY # index "Environmental variables" "(See /ENV parameter)" DUMMY # index "Environmental variables" "(See SET PAGINATE)" DUMMY # index "Error messages" "(See also /DEBUG parameter)" DUMMY # index "Formatting commands" "LENGTH" "(See WIDTH command)" DUMMY # index "Guthrie, Bruce" "(See also Elsie)" DUMMY # index "PAGINATE.INI" "(See INI File)" DUMMY # index "PAGNOASC.INI" "(See Character-translation Table)" DUMMY # index "Printer" "(See RESET=string)" DUMMY # index "Printer" "(See SETUP=string)" DUMMY # index "Indenting" "(See also WRAPBOL=string)" DUMMY # index "Indenting" "(See also WRAPOOL=string)" DUMMY # index "INDEX" "(See INCLUDE INDEX)" DUMMY # index "Left margin" "Changing temporarily" "(See INDENT command)" DUMMY # index "Left margin" "Changing permanently" "(See MARGIN command)" DUMMY # index "Length" "Of line" "(See WIDTH command)" DUMMY # index "Length" "Of page" "(See PAGE command)" DUMMY # index "LENGTH" "(See WIDTH command)" DUMMY # index "Lines" "Across page" "(See RULE command)" DUMMY # index "Missing data values" "(See INMISS=val)" DUMMY # index "Missing data values" "(See INMISSC=val)" DUMMY # index "Missing data values" "(See OUTMISS=val)" DUMMY # index "Missing data values" "(See OUTMISSC=val)" DUMMY # index "Multicolumn text" "(See MULTICOLUMN command)" DUMMY # index "Sorting" "Case-insensitive" "(See SORTI=varspec)" DUMMY # index "Sorting" "Descending" "(See SORTD=varspec)" DUMMY # index "Source code" "Printing" "(See WRAP command)" DUMMY # index "Source code" "Printing" "(See WRAPBOL=string)" DUMMY # index "Source code" "Printing" "(See WRAPEOL=string)" DUMMY # index "Streamed output" "Printing" "(See WRAP command)" DUMMY # index "Streamed output" "Printing" "(See WRAPBOL=string)" DUMMY # index "Streamed output" "Printing" "(See WRAPEOL=string)" DUMMY # index "SPACING=1" "(See also SINGLE command)" DUMMY # index "SPACING=2" "(See also DOUBLE command)" DUMMY # index "SPACING=3" "(See also TRIPLE command)" DUMMY # index "Widow lines" "(See ADJUST command)" DUMMY # index "Windows95" # index "Windows NT" # index "Long filenames" WIN95 AND WINNT NOTICE: As with most DOS-based utilities, this program doesn't understand the weird subdirectories, long filenames, invalid characters that are possible under Windows 95 and Windows/NT. Both operating systems alias long filenames into names like MYFILE~1.TXT and you will need to specify the aliased versions of file names to process them. Under some file structure systems in NT, the program may not work at all. # index "Overview" The PAGINATE.EXE program formats text files containing embedded "marker" commands. Specifically, the program can be used to: # unit # indent 4-2 # index "Streamed text" "Example" * Align, justify, center text # indent 4 Simple sample: You have long, streamed text. You want it wrapped nicely: PAGINATE infile /WRAP /LENGTH=70 /-PAGE # indent 4-2 * Add headers and footers to pages # paragraph * Add page breaks # paragraph * Control indentation # paragraph * Control spacing # paragraph # index "Sorting" "Example" * Sort the file (alphabetically, not numerically all that well) in either ascending or descending order. # indent 4 Simple sample: You have an ASCII text file called BRUCE.DOC that you want to sort: PAGINATE bruce.doc /SORT 1-50 /-PAGE # indent 4-2 * Generate indexes # paragraph * Select fields to print # paragraph # index "dBase files" "Example" * Print out dBase and ASCII-delimited files in tabular forms # indent 4 Simple sample: You have a dBase file that you want printed out. Create an ASCII text file (call it, say, DBASEPAG.CTL) with the following: # from dbf # include sample.dbf Now, run the PAGINATE command: PAGINATE dbasepag.ctl /-PAGE # indent 4-2 * Bring ASCII-delimited and dBase files into existing text # paragraph * Translate characters # paragraph # index "Multicolumn text" "Example" * Do multi-column listings # indent 4 Simple sample: You have source code. You want it shown double-column. Create an ASCII text file (call it, say, TWOCOL.CTL) with the following: # width=133 # page=50 # title center ^N%12% ^B%2% Revised: ^A # end # wrap # wrapbol = "..>." # wrapeol = " <" # multicolumn=2 # separator = " ! " # # indent 4 Now, run the PAGINATE command: PAGINATE infile /Ctwocol.ctl # indent 4-2 * Pressing escape stops the program early. # end Despite some of the samples shown above, the power of PAGINATE is really in combining these features for a single document. You can bring dBase files into reports, you can reflow external documents and bring them into your report, you can generate indexes for documentation, etc. The documentation you're reading, for example, was created using a text editor and the PAGINATE command. # index "National Institutes of Health" The PAGINATE.EXE program is based on a document-formatting language that exists on the mainframe computers at the National Institutes of Health in Bethesda, MD. The text editor used there is called WYLBUR and it does all sorts of wonderful things like creating programs. For documentation, you use the WYLBUR text editor and insert document formatting codes. These codes determine things like margins, indentation, justification, spacing, etc. After you embed all of these formatting commands, you issue a PAGINATE command and everything's reformatted for you. PAGINATE includes many of the WYLBUR pagination commands and then adds a number or database operations. Typically, I do most of my text formatting using the PE2 text editor which I dearly love. I add PAGINATE marker commands to the regular documentation so I can do titles, footers, indexes, etc. # % Nope. Can't generate a table of contents yet using PAGINATE. # % Maybe someday! # unit verbatim # indent 8 Quick remaining contents: Introduction to marker commands...................... pg 3 Sample files......................................... pg 5 Command reference: Formatting commands................................ pg 5 Database-related functions......................... pg 14 Control codes........................................ pg 21 Varspecs............................................. pg 22 Field-definition file................................ pg 23 Specifying parameters................................ pg 25 Character-translation file........................... pg 25 Date displays........................................ pg 27 Examples............................................. pg 28 Syntax............................................... pg 29 Return codes......................................... pg 31 Author............................................... pg 31 Index................................................ pg 32 # end # # index "Marker commands" Introduction to marker commands: PAGINATE typically expects document formatting codes to be embedded in the text document itself. If you want the same formating to be used through the entire document, however, you can pass in most of the arguments (see the "Syntax" discussion below) or use a separate control file instead. The formatting codes are preceded by a "marker" character. This is a character which begins in column 1 of the text (or control) file and is typically the character "#". (When passing in the formatting codes, all codes are preceded by a "/".) For example, you might have text like this: # unit # verbatim #align width 20 This is some sample text which you have asked to align. The margins will be placed at 1 and 20. You can use an indent command to shift the left margin if desired. # end This example shows one marker statement ("#align width 20") which contains two formatting commands: "align" and "width 20". Formatting commands are keyword specific. You can put in commands on the same line which have no logical bearing to one another like "#align spacing=2". Exceptions: * Do not do this for INCLUDE statements * Do not do this for INDEX statement # index "Semi-colons" Formatting commands can be separated by semi-colons for clarity but only a space is required. The case of the marker statement is irrelevant. After the PAGINATE command is run, the above text will come out like this: # unit # verbatim This is some sample text which you have asked to align. The margins will be placed at 1 and 20. You can use an indent command to shift the left margin if desired. # end # # index "Paragraphs" In terms of alignment, justification, variable indentation, etc, the system treats each paragraph as a separate entity. A paragraph is defined as beginning with a blank line or a space. For example: # unit # verbatim #justify width 25 This is one paragraph And this is another paragraph. But this is the same paragraph. New paragraph here. # end Comes out as this: # unit # verbatim This is one paragraph And this is another paragraph. But this is the same paragraph. New paragraph here. # end # index "Range of formatting" Formatting commands cover a variety of functions. Note that formatting within titles, footers, headers, and UNIT...END blocks does not affect formatting beyond the END statement. For example, the width of the title below does not affect the width outside the title: # unit # verbatim # align width 50 This text is aligned width 50. Here comes a title. # title center width 70 This title is centered within width 70. # end This text (outside the TITLE ... END block) is still being aligned (not centered) to width 50 (not 70). # end # index "Short lines" # index "Paragraphs" "One liners" Note that JUSTIFY and ALIGN do not affect lines which are on their own and do not continue to a second line and do not exceed the given page length. As an example, note that the file names shown in the next section ("Sample files:") are not affected even though they are actually controlled by a JUSTIFY marker command. This may seem like an error at times especially if you've already indented text; remember that indentation is the system's clue that there is a new paragraph so pre-indented text won't be affected much by the program. This feature is, by the way, frequently useful in defining oddly formatted sections of text without needing to use a "# UNIT VERBATIM" statement around it; just make sure each line begins with at least one space and the program won't touch it. # # index "Sample files" Sample files: An example input file and its related components are included in this ZIP under PAGDEMO.*. You can modify this and see how features are affected. The demonstration files are as follows: # % As is documented above, the following lines don't need a VERBATIM # % marker because they are short enough to not be affected by the JUSTIFY # % marker command. PAGDEMO.BAT Batch file that actually runs the demo file PAGDEMO.#1 The primary file for the demo PAGDEMO.#1D The ASCII-delimited file brought in for the demo PAGDEMO.#1C The field-definition file used for the demo # rule=- COMMAND REFERENCE # rule=- # index "Formatting commands" Formatting commands # index "Equal signs" The following section describes the formatting commands alphabetically with some cross-referencing. The commands are case insensitive ("align" and "ALIGN" are the same). Typically, the equal signs are optional ("WIDTH=80" is the same as "WIDTH 80") except when used from the DOS command line. Remember, the text line that these commands appear in must begin with the designated marker character (typically a "#"). # index "Formatting commands" "Default values" Default initial values (format commands): FLAG=NULL INDENT=0 INDENTER=" " INDENTFLAG=NULL WIDTH=80 MARGIN=1 MARKER=# PAGE=60 PAGEEJECT=\012\013\010 SINGLE VERBATIM WRAPBOL=NULL WRAPEOL=NULL # indent 3-3 # index "Formatting commands" "% (comments)" # index "% (comments)" %: Comments. You can add comments after any marker command or you can embed them as marker commands all on their own. # index "Formatting commands" "ADJUST" # index "ADJUST" ADJUST: Tells the system to not write single lines on the bottom of a page. This is typically done to control "widow lines", cases where the first line of a paragraph prints on the bottom of one page and the remainder of the paragraph prints on the top of the next. # index "Formatting commands" "-ADJUST" # index "-ADJUST" -ADJUST: Says that "widow lines" are okay. # index "Formatting commands" "ALIGN" # index "ALIGN" ALIGN: Aligns text (uneven right margins) according to the default page width. See also: CENTER, JUSTIFY, RIGHT, VERBATIM, and WRAP. See also WIDTH. # index "Formatting commands" "-ALIGN" # index "-ALIGN" -ALIGN: Same thing as VERBATIM. # # index "Formatting commands" "CENTER" # index "CENTER" CENTER: Centers text according to the default page width. Unlike ALIGN, JUSTIFY, and RIGHT, the CENTER command does not actually reflow any text. If your line is wider than the specified width, it will not be split into multiple lines for you. Note when CENTER is in effect, leading spaces are automatically removed from text lines so centering can be recalculated correctly. See also: ALIGN, JUSTIFY, RIGHT, VERBATIM, and WRAP. See also WIDTH. # index "Formatting commands" "-CENTER" # index "-CENTER" -CENTER: Same thing as VERBATIM. # index "Formatting commands" "DATE" # index "DATE" DATE=string: Sets the date format used to fill in ^D and ^A references in the title, footer, or header sections. If no DATE specification is provided, your default country setting will be used. Note that the DATE marker must be used *before* the title, footer, or header section in order to be applied to it. The date should be enclosed in quotes. See also: "control codes" and "date displays" discussion below. See also: FOOTER, HEADER, and TITLE. Example: # unit verbatim # date="mmm dd, yyyy" # end # index "Formatting commands" "DOUBLE" # index "DOUBLE" DOUBLE: Double-spaces all text. See also: SINGLE, SPACING=n, and TRIPLE. # index "Formatting commands" "EJECT" # index "EJECT" # index "Page-eject characters" EJECT: Causes a new page to be created. A regular decimal 12 character (the female symbol) is also treated as a page eject in the input file as long as it appears by itself on a line. See also: PAGEEJECT, PAGEEJECT=string, and PAGEFILL. # index "BACK parameter" "EJECT BACK command" # index "Formatting commands" "EJECT BACK" # index "EJECT BACK" EJECT BACK: Same as EJECT but makes sure you are ejected to the next even numbered page. See EJECT FRONT discussion. # index "FRONT parameter" "EJECT FRONT command" # index "Formatting commands" "EJECT FRONT" # index "EJECT FRONT" EJECT FRONT: Same as EJECT but makes sure you are ejected to the next odd numbered page. This is mostly used in the case of a document that contains chapters. You typically want a chapter to start on an odd-numbered page. If the previous chapter ended on page 7, you wouldn't want to just eject the page because that would start on page 8. On the other hand, EJECT FRONT insures that the next page will be page 9. (EJECT FRONT is the same as EJECT if you're currently on a even numbered page.) # index "Formatting commands" "FLAG" # index "FLAG" FLAG=string: Allows you to set a character or set of characters that appears at the end of the lines that follow. The location of the flag characters is the width of the line plus a space plus whatever string you specify. For example, #flag="!" when #width=20 is in effect will result in "!" appearing at column 22 on each of the effected lines. Initially defaults to FLAG=NULL. See also: INDENTFLAG=string. # index "END" "FOOTER command" # index "Formatting commands" "FOOTER" # index "FOOTER" FOOTER ... END: Defines a footer to appear at the bottom of each page. Has same features that TITLE ... END has; see that discussion. # index "Formatting commands" "-FOOTER" # index "-FOOTER" # index "FOOTER" "Deactivating" -FOOTER: Turns off the current footer specification. See FOOTER ... END. # indent 3-3 # index "Formatting commands" "INCLUDE filename" # index "INCLUDE filename" # index "Adding files" INCLUDE filename: Adds another file to the processing. This file is processed according to whatever formatting defaults are in use at that point. # index "Formatting commands" "INDENT=n" # index "INDENT=n" INDENT=n: Indents the text which follows by "n" spaces. Essentially sets the left margin. Default value: INDENT=0. See also: INDENTFLAG=string. # # index "Formatting commands" "INDENT=n-n" # index "INDENT n-n" # index "Bulleted text" INDENT=n-n: Specifies that most of the lines of a paragraph are to be indented by "n" spaces whereas the first word of the first line is to be indented by "n-n" spaces. For example, "INDENT 5-3" will indent the first word by two spaces and the subsequent lines by 5 spaces. This is frequently used for bulleted text. See also: INDENTFLAG=string and INDENTER=string. # indent 3 # index "Bulleted text" "Tricks" Note with bulleted items that if you want single-spaced items bulleted, include a #paragraph statement before the next bullet. This is only a problem because the routine doesn't start re-indenting text until it thinks it's at another paragraph. (A blank line would have worked fine but you want it single spaced some times.) For example: # unit verbatim # indent 5-2 * This is one paragraph to be indented # paragraph * And this is another. # end Remember that the indentation rule applies to the first word of the first line of a given paragraph. That word can be a bullet (like an asterisk) but it can also be an actual word. This is useful when the first words of different paragraphs are of different widths. For example: # unit verbatim # indent 8-8 Home Takes you to the top line # indent 8-8 End Takes you to the bottom line # indent 8-8 F1 Presents help # end This ends up like this: # unit verbatim Home Takes you to the top line End Takes you to the bottom line F1 Presents help # end # index "INDENTER string" "Example" If you want, you can fake the system into thinking that multiple words are, in fact single words for indentation or word-wrapping purchases. This can be done in two ways. The first is to use the INDENTER=string marker command. This allows you to say something like this: # unit verbatim # indenter=":" # align length 30 # indent 14-14 First item: This is the first element. # paragraph Second item: And this the second. # paragraph Third item: And finally, this the last. # indenter=" " # end # This ends up like this: # unit verbatim First item: This is the first element. Second item: And this the second. Third item: And finally, this the last. # end # index "Wrapping" "Faking out" # index "Alt-255 key" The second technique is done by putting a non-printable character instead of a space character between the words. A good character to use is Alt-255 (press the Alt key, while it's down, press the digits 2, 5, 5 on the numeric keypad, then release the Alt key). This character shows up as a space but the system treats it as a regular character so it doesn't split up the words it's between. Warning: It's easy to forget you used Alt-255. If you use Alt-255 frequently, remember to check for it with a hex text viewer (like LIST) when you're wondering why text didn't wrap or otherwise behave the way you expected. Note that using INDENT=n-n causes pre-indented paragraphs to be treated differently than any other INDENT specification would. Consider the following: # unit verbatim # -indent This is some sample text # indent 3 This is some sample text # indent 3-3 This is some sample text # end In all cases, the system considers that any line that is either empty or begins with a space in fact starts a paragraph. In the first case, the system says don't change any indentation for either line. In the second case, the system figures new paragraphs for each line and additionally indents each line. In the last case, the system knows that the first word is be de-indented so it removes leading spaces. As a result, you get the following: # unit verbatim This is some sample text This is some sample text This is some sample text # end The use of #UNIT and #VERBATIM blocks is one way to insure consistency within indented sections even for single-line blocks of text. # # indent 3-3 # index "Formatting commands" "INDENT=n+n" # index "INDENT=n+n" INDENT=n+n: Specifies that most of the lines of a paragraph are to be indented by "n" spaces whereas the first line is to be indented by "n+n" spaces. For example, "INDENT 5+3" will indent the first line by eight spaces and the subsequent lines by 5 spaces. See also: INDENTFLAG=string. # index "Formatting commands" "-INDENT" # index "-INDENT" -INDENT: Same thing as INDENT=0. # index "Formatting commands" "INDENTER" # index "INDENTER=string" INDENTER=string: Specifies that the designated string is to be used when determining breaks in INDENT n-n cases. A typical example of this would be to use INDENTER=":" (see the example in the INDENT=n-n example above). The specified string can be one or more characters in length (it cannot be null). If the specified string is not found in the line to be wrapped, a space character will be looked for instead. Defaults to INDENTER=" ". # index "Formatting commands" "INDENTFLAG" # index "INDENTFLAG=string" # index "Elsie" INDENTFLAG=string: Specifies characters that are to be added to start of each indented line. Is sometimes used for highlighting text. Defaults to INDENTFLAG=NULL. See also: FLAG=string and INDENT=n. For example, # unit verbatim # indent 4 # align width 30 # indentflag="> " My cat's name is Elsie. It actually is "LC" and stands for "Lost Cat" but it's "Elsie" for short. Elsie's actually male. I thought it rude to check. # end # indent 3 Ends up as: # unit verbatim > My cat's name is Elsie. > It actually is "LC" and > stands for "Lost Cat" but > it's "Elsie" for short. > Elsie's actually male. I > thought it rude to check. # end # indent 3-3 # index "Formatting commands" "JUSTIFY" # index "JUSTIFY" JUSTIFY: Justifies text (makes right margins flush) within the default page width. See also: ALIGN, CENTER, RIGHT, VERBATIM, and WRAP. See also WIDTH. # index "Formatting commands" "-JUSTIFY" # index "-JUSTIFY" -JUSTIFY: Same thing as VERBATIM. # index "Formatting commands" "MARKER=c" # index "MARKER=c" # index "Changing marker character" MARKER=c: Defines the single-character marker indicator that will appear in column 1 of all subsequent lines. Default value: MARKER=#. # index "Formatting commands" "MARGIN=n" # index "Formatting commands" "LMARGIN=n" # index "MARGIN=n" # index "LMARGIN=n" MARGIN=n: (Or LMARGIN=n) Specifies that the left margin is to be set at a particular column. This allows you to keep standard indentation and such while shifting the entire page for punch holes or whatever. The margin is set independently of the other settings; if you have INDENT=5 and MARGIN=10, the actual text will start appearing at column 15 on the page. Default value: MARGIN=1. # index "Formatting commands" "NEXT=n" # index "NEXT=n" NEXT=n: Specifies which page number will appear the next time ^B appears in a title, footer, or header. You can specify "-NEXT" or "NEXT=0" to start at 0. Starts at NEXT=1 typically. # # index "Formatting commands" "-PAGE" # index "-PAGE" -PAGE: Same as "PAGE=0". # index "Formatting commands" "PAGE=n" # index "PAGE=n" PAGE=n: Defines default page length. You can say "PAGE=0" to set continuous pages. (You have to have a page length specified if you're using the MULTICOLUMN option though.) Default value: PAGE=60. # index "Formatting commands" "PAGEEJECT" # index "PAGEEJECT" PAGEEJECT: Says that pages are to be terminated with the standard page eject sequence (the female symbol--decimal 12--followed by a carriage return and line feed) instead of padding the pages with blank lines. This is the default value and is the same thing as saying "PAGEEJECT=\012\013\010". See also: PAGEEJECT=string and PAGEFILL. # index "Formatting commands" "PAGEEJECT=string" # index "PAGEEJECT=string" PAGEEJECT=string: Says that pages are to be terminated with a user-defined character sequence instead of padding the pages with blank lines. The main reason for using this instead of just PAGEEJECT is if you want to remove the CR/LF that typically follows each page eject. Another reason is to use "PAGEEJECT=1\013\010" for files being generated for IBM mainframes that use carriage control characters. See also: PAGEEJECT and PAGEFILL. # index "Formatting commands" "PAGEFILL" # index "PAGEFILL" PAGEFILL: Says that pages are to be ended by padding them with blank lines up to the specified PAGE=n value. You are essentially using PAGEFILL if you specify a footer; pages have to be filled up with blank lines to read the footer line. See also: PAGEEJECT and PAGEEJECT=string. # index "Formatting commands" "PARAGRAPH" # index "PARAGRAPH" PARAGRAPH: Says that a new paragraph is about to begin. This is primarily used when you have something like bulleted text which might not be properly aligned. For example: # unit verbatim # align width 40 indent 5-2 * First bulleted item # paragraph * Second bulleted item. Note that this would have been considered to be part of the first paragraph since it started in column 1 and there was no blank line between them. # end # index "Formatting commands" "RIGHT" # index "RIGHT" RIGHT: Moves all text to be flush to the right margin. Doesn't adjust any spacing between words or anything. See also: ALIGN, CENTER, JUSTIFY, VERBATIM, and WRAP. See also WIDTH. # index "Formatting commands" "-RIGHT" # index "-RIGHT" -RIGHT: Same thing as VERBATIM. # index "Formatting commands" "RULE" # index "RULE string" RULE=string: Specifies that a string is to be repeated the width of the line. This is used to separate sections. The string can be a single character (like "RULE=-"), multiple characters (like "RULE="- ""), it can contain decimal and hexadecimal characters (like "RULE=\066\097\116"), it can be "RULE=NULL" (which typically results in a blank line), or just simply "RULE" (which is the same thing as "RULE=-"). Personally, if your printer supports IBM graphics characters, I find RULE=\196 to be the most pleasing of the rule lines. (See BRUCEHEX.DOC file.) # # index "Formatting commands" "SINGLE" # index "SINGLE" SINGLE: Single-spaces all text. This is the default spacing. See also: DOUBLE, SPACING=n, and TRIPLE. # index "Formatting commands" "SPACING=n" # index "SPACING=n" SPACING=n: Sets spacing between lines as "n" number of lines. See also: DOUBLE (which is SPACING=2), SINGLE (SPACING=1), and TRIPLE (SPACING=3). # index "END" "TITLE command" # index "Formatting commands" "TITLE" # index "TITLE" TITLE ... END: Defines a title to appear at the top of each page. Any number of lines can appear in the title. The title ends with a marker line that contains the "end" command; if no "end" command is provided, the program presumes there is one after the last line of your file. Spacing, indentation, width, and alignment cannot vary within the title; the last one assigned will win. See "control codes" discussion below for characters that can appear in the title. To eliminate the title, define a title without any lines in it. See also: FOOTER ... END, HEADER ... END and UNIT ... END. Example: # unit verbatim # title center width=80 This is my program! # end # end # indent 3 If you plan to change the title within the document, make sure you redefine it before the new page is generated. For example: # unit verbatim (text) # title center width=80 Index # end # # end If you define it after the page eject, the new title will not take effect until a subsequent page (if any) is generated. By the same token, make sure the title is defined in the document before any text is filled in if you want the title to appear on the very first page of the reformatted document. A very useful title is the following: # unit verbatim # title center width=80 ^O%12% ^B%3% Revised: ^A # end # end Consult the "control code" discussion afterward but this will fill in the output file's name (taking up 12 spaces so all of your titles look about the same), the page number (taking up 3 spaces for the page number), and the input file's date. # # indent 3-3 # index "Formatting commands" "-TITLE" # index "-TITLE" # index "TITLE" "Deactivating" -TITLE: Turns off the current title specification. See TITLE ... END. # index "Formatting commands" "TRIPLE" # index "TRIPLE" TRIPLE: Triple-spaces all text. See also: DOUBLE, SINGLE, and SPACING=n. # index "END" "UNIT command" # index "Formatting commands" "UNIT" # index "UNIT" UNIT ... END: Defines a unit of text with its own unique formatting. Units can have formatting which differs from the text around it and changing the formatting within the Unit will not affect the other text. Has same features that TITLE ... END has; see that discussion. # indent 3 A typical use for the UNIT command is in combination with VERBATIM. This is frequently used when you're aligning or justifying most of the text and then you have one section that isn't to be changed at all. # indent 3-3 # index "Formatting commands" "VERBATIM" # index "VERBATIM" VERBATIM: Specifies that the text which follows should not be aligned, justified, etc. See also: ALIGN, CENTER, JUSTIFY, RIGHT, and WRAP. See also WIDTH. # index "Formatting commands" "WIDTH=n" # index "WIDTH=n" WIDTH=n: Specifies the default line width. (Page lengths are controlled by the PAGE=command.) Default value: WIDTH=80. (Note that LENGTH=n is accepted as a synonym for WIDTH=n.) See also: ALIGN, CENTER, JUSTIFY, RIGHT, VERBATIM, and WRAP. # index "Formatting commands" "WRAP" # index "WRAP" # index "Streamed text" "WRAP command" WRAP: Specifies that long lines (longer than the specified line width) in the text which follows should be wrapped. Lines which are shorter than the specified line width are not affected at all. Primarily of use in files produced by a word-processor since they typically write the entire paragraph as a stream. Also useful for printing source code. See also: ALIGN, CENTER, JUSTIFY, RIGHT, and VERBATIM. See also WIDTH, WRAPBOL=string, and WRAPEOL=string. # index "Formatting commands" "-WRAP" # index "-WRAP" -WRAP: Same thing as VERBATIM. # # index "Formatting commands" "WRAPBOL" # index "WRAPBOL=string" WRAPBOL=string: Is used with the WRAP command to indicate that continued lines are to begin with the specific string. This is useful for source code listings. Initially defaults to WRAPBOL=NULL. An example of its use: # unit verbatim # length=50 # wrap # wrapbol=" > " # wrapeol=" <" IF Word2$ = "" THEN CALL WriteError("Missing required " + Item$ + " parameter", "", SourceText$) ELSEIF VAL(Word2$) < MinVal% OR VAL(Word2$) > MaxVal% THEN CALL WriteError("Invalid " + Item$ + " parameter", "", SourceText$) ELSE CkParmN% = VAL(Word2$) END IF # end will result in the following output: # unit verbatim IF Word2$ = "" THEN CALL WriteError("Missing required " + Item$ + < > " parameter", "", SourceText$) ELSEIF VAL(Word2$) < MinVal% OR VAL(Word2$) > < > MaxVal% THEN CALL WriteError("Invalid " + Item$ + " < > parameter", "", SourceText$) ELSE CkParmN% = VAL(Word2$) END IF # end # index "Formatting commands" "WRAPEOL" # index "WRAPEOL=string" WRAPEOL=string: Is used with the WRAP command to indicate that if the line can't fit on the current line, the end of the line is to be tagged with the specified string. This is useful for source code listings. Initially defaults to WRAPEOL=NULL. See the example under the WRAPBOL=string command. # # index "Database-related commands" # indent 0 # rule=- Database-related functions The PAGINATE command provides some features to allow you to use it to read in and print out ASCII-delimited and dBase files. For example: # from ascii "Apples",10,5 "Bananas",20,10 will come out as: Apples 10 5 Bananas 20 10 You can use this capability to embed tables within a report. You can also combine this with SORT=varspec, SELECT=varspec, and SUM=varspec specifications to have the report sorted on specified columns or to subset the columns that get printed out. There are some restrictions to all of this and these are described within each option as appropriate below. NOTE: In general, combining FROM ASCII or FROM DBF or several of the other data-base related functions with options like ALIGN and JUSTIFY will not work. The formatting options will, in general, be ignored. # index "Sorting" "Example" It's often the case that you will want to deal only with a single data set, and you'll have no need for actual text. For example, let's say that you really want something that will sort a file that contains a lot of data. No problem: PAGINATE infile outfile /-PAGE /SORT=1,10 # index "dBase files" "Example" Another example would be that you have something like a dBase file and you want to print it out. Again, no problem. Create a simple control file: # unit # verbatim # heading ^H # end # from dbf # include sample.dbf # end and then create your tables with: PAGINATE ctlfile outfile In general, keep in mind that sorting, totaling, and other special data base function requests should appear before the data are actually read in. This means #SORT or #SUM should appear before the #INCLUDE statement. # # index "Database-related commands" "Default values" Default initial values (database-related functions): BAD=ABORT -BREAK -DELETED DELIMS=",,, FROM FIXED GAP=2 INMISS=NULL INMISSC=NULL OUTMISS=NULL OUTMISSC=NULL SELECT=NULL SEPARATOR=" | " SORT=NULL SUM=NULL # indent 3-3 # index "ABORT parameter" "BAD=ABORT command" # index "Database-related commands" "BAD=ABORT" # index "BAD=ABORT" BAD=ABORT: Says that if the program runs into an invalid data value, it should abort processing entirely. # index "MISSING parameter" "BAD=MISSING command" # index "Database-related commands" "BAD=MISSING" # index "BAD=MISSING" BAD=MISSING: Says that if the program runs into an invalid data value, it should set the value of that variable as "missing" and continue processing. # index "SKIP parameter" "BAD=SKIP command" # index "Database-related commands" "BAD=SKIP" # index "BAD=SKIP" BAD=SKIP: Says that if the program runs into an invalid data value, it should skip the entire data record and continue processing with the next record. # index "Database-related commands" "BREAK" # index "BREAK" BREAK=varspec: BREAK provides a way of generating subtotals or subgroupings within a listing. Whenever the value of the variable specified changes, the program will generate either a blank line or a subtotal (if SUM=varspec has been specified). If subtotals are generated, at the end it will generate a grand total. # index "NULL parameter" "BREAK=NULL command" # index "Database-related commands" "BREAK NULL" # index "BREAK NULL" BREAK=NULL: Turns off all subtotalling. This is initially the default. # index "Database-related commands" "-BREAK" # index "-BREAK" -BREAK: Same as BREAK=NULL. # index "Database-related commands" "DELETED" # index "DELETED" DELETED: Says to process deleted records as well as non-deleted records from dBase files. # index "Database-related commands" "-DELETED" # index "-DELETED" -DELETED: Says to skip deleted records. # index "Database-related commands" "DELIMS" # index "DELIMS" # index "Hexadecimal codes" DELIMS=aroundstrings,aroundnums,betweenfields: Allows you to specify the delimiters (in sequence) around string fields, around numeric fields, and between fields. Defaults to: # unit verbatim DELIMS=",,, # end # indent 3 (Use quotes around character strings, nothing around numeric data, and the third comma indicates that there is a comma between fields.) The replacement string can include hexadecimal codes (in the &Hxx format) or decimal codes (in the \ddd format) if necessary so either of the following would put a tab between fields: # unit verbatim DELIMS=",,&H09 DELIMS=",,\009 # end See the BRUCEHEX.DOC file. # indent 3-3 # index "ASCII parameter" "FROM ASCII command" # index "Database-related commands" "FROM ASCII" # index "FROM ASCII" # index "ASCII-delimited files" # index "Files" "ASCII-delimited" FROM ASCII: Specifies that the next non-marker lines contain ASCII-delimited records. The ASCII-delimited records can be embedded within the report or stored as a separate file (brought in with an INCLUDE statement). See also: FROM DBF and FROM FIXED and most of the other commands in this section. See also: "Field-definition file" discussion. # INDEX "DBF parameter" "FROM DBF command" # index "Database-related commands" "FROM DBF" # index "FROM DBF" # index "dBase files" # index "Files" "dBase" FROM DBF: Specifies that the next INCLUDE statement is a dBase file. Unlike with FROM FIXED and FROM ASCII, the dBase file has to be external to the control cards. The output itself, however, will be included with the regular output file. See also: FROM ASCII and FROM FIXED and most of the other commands in this section. See also: "Field-definition file" discussion. # index "FIXED parameter" "FROM FIXED command" # index "Database-related commands" "FROM FIXED" # index "FROM FIXED" FROM FIXED: Specifies that the input file is a fixed-field file. Any document with regular text (for example, a letter to your best buddy) is considered fixed-field by the program; if you classify it as anything else, the program will try to parse it all. See also: FROM ASCII and FROM DBF. # index "Database-related commands" "-GAP" # index "-GAP" -GAP: Same as "GAP=0". # index "Database-related commands" "GAP=n" # index "GAP=n" GAP=n: Specifies the number of spaces to appear between columns when printing fielded data. If, for example, two columns of numbers are printed, the GAP parameter specifies that "n" number of spaces are to appear between these columns. You can specify "GAP=0" if you don't want any gap to be inserted. Defaults to GAP=2. # index "END" "HEADER command" # index "Database-related commands" "HEADER" # index "HEADER" # index "Column headers" HEADER ... END: Defines a set of column headers that should appear before the actual data. Typically, you can bring these in from the actual dBase file or else use whatever you've specified in the field-definition file by using the "^H" control code. Headers are affected by the MULTICOLUMN specification. Otherwise, they are treated pretty much like Titles and Footers. See the discussion of TITLE ... END. # index "Formatting commands" "-HEADER" # index "-HEADER" # index "HEADER" "Deactivating" -HEADER: Turns off the current header specification. See HEADER ... END. # index "filename parameter" "INCLUDE filename command" # index "Database-related commands" "INCLUDE filename" # index "INCLUDE filename" # index "Files" "Adding" INCLUDE filename: Adds text from another file in at this point. If the routine has been told that this is a FROM DBF or FROM ASCII file, it will process the file appropriately. The filename specification can include drive and path information if desired. # index "INDEX parameter" "INCLUDE INDEX command" # index "Database-related commands" "INCLUDE INDEX" # index "INCLUDE INDEX" INCLUDE INDEX: Creates an index listing at this point in the document. See also: INDEX. # index "filename parameter" "INDEF filename command" # index "Database-related commands" "INDEF filename" # index "INDEF filename" # index "Field-definition file" INDEF filename: Specifies that the file characteristics for the input file which follows are contained in a field-definition file specified as "filename". The filename spec can include drive and path information if desired. See the discussion of "Field-definition files" below. See also: INDEF NULL. # index "NULL parameter" "INDEF NULL command" # index "Database-related commands" "INDEF NULL" # index "INDEF NULL" INDEF NULL: Says there is no input file definition for what follows. Typically used to turn off the previously-specified input field-definition file. See also: INDEF filename. # index "Database-related commands" "-INDEF" # index "-INDEF" -INDEF: Same thing as INDEF NULL. # # index "DUMMY parameter" "INDEX command" # index "Database-related commands" "INDEX" # index "INDEX" # index "See Also references" INDEX "word" [ "word" ]... [DUMMY]: Saves an index record, with the specified text and the current page number, at this point. The index is then printed out when you add an INCLUDE INDEX option. The multiple word specifications allow you to specify up to 3 levels of indexing. For example, # unit verbatim # index "Computers" "Maintenance" # index "Computers" "Hardware" # eject # index "Computers" "Hardware" # index "Computers" "Software" # include index # end # indent 3 will generate output that looks in part like this: # unit verbatim Computers Hardware; 1, 2 Maintenance; 1 Software; 2 # end # index "MULTICOLUMN" "With INDEX" # index "INDEX" "With MULTICOLUMN" You can use MULTICOLUMN in combination with the INDEX command. Just make sure you specify the MULTICOLUMN before the INCLUDE INDEX statement as in: # unit verbatim # multicolumn 3 # include index # end # index "DUMMY index references" If DUMMY is specified, the page number is not displayed for this item. This is typically done when you want the index to provide a cross-reference but you don't really want any page numbers showing up. For example: # unit verbatim # index "Hardware" "(See Computers)" DUMMY # end My personal preference is to put all DUMMY index references near the start of your document so you can find them more easily. # indent 3-3 # index "Database-related commands" "INMISS=val" # index "INMISS=val" INMISS=val: Specifies for ASCII-delimited and dBase input files which numeric values are to be considered indicators for missing values. Missing values are not included in summations. Defaults to INMISS=NULL. See also: INMISSC=val, OUTMISS=val, and OUTMISSC=val. # index "Database-related commands" "INMISSC=val" # index "INMISSC=val" INMISSC=val: Specifies for ASCII-delimited and dBase input files which character values are to be considered indicators for missing values. Defaults to INMISSC=NULL. See also: INMISS=val, OUTMISS=val, and OUTMISSC=val. # index "END" "MULTICOLUMN command" # index "Database-related commands" "MULTICOLUMN" # index "MULTICOLUMN" # index "SEPARATOR" "With MULTICOLUMN" MULTICOLUMN=n ... END: Specifies that a given block is to be arranged in a multicolumn format. The number of columns is specified as "n"; "MULTICOLUMN=2" would set up a dual-column output. The SEPARATOR string appears between each of the columns. (MULTICOLUMN", by the way, can be abbreviated "MULTI" or "MULTICOL".) # indent 3 Make sure you put any CENTER or ALIGN or whatever statements after the MULTICOLUMN statement (VERBATIM will result in lines being truncated). Any width specification ("MULTICOLUMN=2 WIDTH=80") is used to determine the total line width, not the width of each column within the line. The width of each column is the total line width (typically 80) divided by the number of columns minus the width of the separator string. Otherwise, MULTICOLUMN has the same features that TITLE ... END has; see that discussion. (Remember, unless provided otherwise, the "END" command is presumed to be after the last line of your input file.) See also: SEPARATOR=string. Example: # unit verbatim # multicolumn 3 separator=" | " lines lots of lines still more # end # end # indent 3-3 # index "Database-related commands" "NULLS" # index "NULLS" NULLS: Says that the program will accept values that begin with a decimal zero as being a valid value. Defaults to NULLS. See also: -NULLS. # index "Database-related commands" "-NULLS" # index "-NULLS" -NULLS: Says that values which begin with a decimal zero should be treated as missing by the program. Defaults to NULLS. See also: NULLS. # index "filename parameter" "OUTDEF filename parameter" # index "Database-related commands" "OUTDEF filename" # index "OUTDEF filename" # index "Field-definition file" OUTDEF filename: Specifies the field-definition file to create. Typically, the only reason you'd ever use this command is if you want the program to create a field-definition file for a dBase input file. (See the discussion of "Field-definition file" later.) See also: OUTDEF NULL. # index "NULL parameter" "OUTDEF NULL command" # index "Database-related commands" "OUTDEF NULL" # index "OUTDEF NULL" OUTDEF NULL: Turns off the output field-definition file specification. See also: OUTDEF filename. # index "Database-related commands" "-OUTDEF" # index "-OUTDEF" -OUTDEF: Same as OUTDEF NULL. # index "Database-related commands" "OUTMISS=val" # index "OUTMISS=val" OUTMISS=val: Specifies what value will be substituted for missing numeric input values on output. Initially defaults to OUTMISS=NULL. See also: INMISS=val, INMISSC=val, and OUTMISSC=val. # index "Database-related commands" "OUTMISSC=val" # index "OUTMISSC=val" OUTMISSC=val: Specifies what value will be substituted for missing character input values on output. Initially defaults to OUTMISSC=NULL. See also: INMISS=val, INMISSC=val, and OUTMISS=val. # index "Database-related commands" "RESET=string" # index "RESET=string" RESET=string: Specifies a character string to stick at the end of the file, to reset the printer after the document is printed. A page eject character (or any other user-defined string in the case of PAGEEJECT=string) is typically added automatically if /EJECT is specified. The string can contain special characters by using a "\" followed by the three-digit ASCII code for the character. The typical use for this would be to issue a printer reinitialization string. On a Hewlett-Packard printer, this would probably be RESET=\027E. See also: SETUP=string. # index "Database-related commands" "SELECT=varspec" # index "SELECT=varspec" SELECT=varspec: Specifies which variables or columns should show up in the ultimate file. This allows you to take, for example, a text file and only print the middle 10 columns of it or else to take a dBase file and only print certain variables. See the discussion of "Varspecs" later. See also: SELECT=NULL. # index "NULL parameter" "SELECT=NULL command" # index "Database-related commands" "SELECT=NULL" # index "SELECT=NULL" SELECT=NULL: Specifies that all variables or columns should show up. This is initially the default. See also: SELECT=varspec. # index "Database-related commands" "-SELECT" # index "-SELECT" -SELECT: Same thing as SELECT=NULL. # index "Database-related commands" "SEPARATOR" # index "SEPARATOR" SEPARATOR=string: Specifies the string to appear between columns in a multicolumn output. The string can contain special characters by using a "\" followed by the three-digit ASCII code for the character. For example, to have a graphic vertical bar, use SEPARATOR=\032\179\032 or else enter it directly as SEPARATOR=" ³ ". Initially defaults to SEPARATOR=" | ". (In case that reflows when you reformat this documentation, that's quote, space, vertical bar, space, quote). See also: MULTICOLUMN=n. # index "Database-related commands" "SETUP=string" # index "SETUP=string" SETUP=string: Specifies the character string to strick at the beginning of the file, to initialize the printer before the document is printed. Typically, you might use an initialization string that sets the printer in compressed, landscape, or whatever mode. The string can contain special characters by using a "\" followed by the three-digit ASCII code for the character. On a Hewlett-Packard printer, this would typically be one of the following codes: # unit verbatim SETUP=\027E (portrait mode, 80 column) SETUP=\027E\027(s16.66H (portrait mode, 132 column) # end # indent 3 On an Epson MX dot-matrix printer, you would typically use these codes: # unit verbatim SETUP=\015 (portrait mode, 80 column) SETUP=\018 (portrait mode, 132 column) # end See also: RESET=string. # indent 3-3 # index "Database-related commands" "SORT=varspec" # index "SORT=varspec" SORT=varspec: Specifies that the lines which follow should be sorted according to a particular group of columns or variables. See the discussion of "Varspecs" later. Sorting is done based on a case-sensitive search ("Apple" and "Banana" will appear before "air"). Note that sorting works well for character strings but negative numbers can cause it all sorts of problems. The sort field specification is limited to 50 characters. Note that you cannot combine sorting specifications (for example, descending for some columns and ascending for others.) Initially defaults to SORT=NULL. See also: SORT=NULL. Basic sorting specifications available here (see each separately): # unit verbatim SORT --> case-sensitive, ascending sort SORTD --> case-sensitive, descending sort SORTI --> case-insensitive, ascending sort SORTDI --> case-insensitive, descending sort SORTID --> case-insensitive, descending sort # end # index "NULL parameter" "SORT=NULL command" # index "Database-related commands" "SORT=NULL" # index "SORT=NULL" SORT=NULL: Turns off any sorting specification. This statement is vital if you have any text appearing after a sorted section. Remember, you cannot have multiple sorting specifications going on so this is the same as all of the following: -SORT, -SORTI, -SORTD, -SORTID, -SORTDI, SORTI=NULL, SORTD=NULL, SORTDI=NULL, and SORTID=NULL. This statement is initially the default. # index "Database-related commands" "-SORT" # index "-SORT" -SORT: Same as SORT=NULL. # index "Database-related commands" "SORTD=varspec" # index "SORTD=varspec" SORTD=varspec: Similar to SORT=varspec but sorting is done in descending sequence. See SORT=varspec and SORT=NULL. # index "NULL parameter" "SORTD=NULL command" # index "Database-related commands" "SORTD=NULL" # index "SORTD=NULL" SORTD=NULL: Same as SORT=NULL. # index "Database-related commands" "-SORTD" # index "-SORTD" -SORTD: Same as SORT=NULL. # index "Database-related commands" "SORTDI=varspec" # index "SORTDI=varspec" SORTDI=varspec: Similar to SORT=varspec but sorting is done in descending sequence and sorting is case insensitive. Identical to SORTID=varspec. See SORT=varspec and SORT=NULL. # index "NULL parameter" "SORTDI=NULL command" # index "Database-related commands" "SORTDI=NULL" # index "SORTDI=NULL" SORTDI=NULL: Same as SORT=NULL. # index "Database-related commands" "-SORTDI" # index "-SORTDI" -SORTDI: Same as SORT=NULL. # index "Database-related commands" "SORTI=varspec" # index "SORTI=varspec" SORTI=varspec: Same as SORT=varspec except the sorting is done in a case-insensitive manner ("big" shows up between "Apple" and "Caramel"). See SORT=varspec and SORT=NULL. # index "NULL parameter" "SORTI=NULL command" # index "Database-related commands" "SORTI=NULL" # index "SORTI=NULL" SORTI=NULL: Same as SORT=NULL. # index "Database-related commands" "-SORTI" # index "-SORTI" -SORTI: Same as SORT=NULL. # index "Database-related commands" "SORTID=varspec" # index "SORTID=varspec" SORTID=varspec: Same as SORTDI=varspec. # index "NULL parameter" "SORTID=NULL command" # index "Database-related commands" "SORTID=NULL" # index "SORTID=NULL" SORTID=NULL: Same as SORT=NULL. # index "Database-related commands" "-SORTID" # index "-SORTID" -SORTID: Same as SORT=NULL. # index "Database-related commands" "SUM" # index "Adding Columns Of Numbers" "(See SUM)" DUMMY # index "SUM" SUM=varspec: Summarizes a group of numbers and presents the total after the items are displayed. Initially defaults to SUM=NULL. See also: SUM=NULL. # indent 3 An example of summing might be like the following: # unit verbatim # from fixed # sort=28-34 # sum=28-34,43-49,57-62,73-78 370 DISK STORAGE $75.14 $35.58 $23.28 $49.16 370 DISK STORAGE $12.80 $6.26 $6.24 $12.76 370 DISK STORAGE $0.00 $0.00 $0.00 $0.00 370 DISK STORAGE $0.00 $0.00 $11.38 $22.76 370 DISK STORAGE $61.56 $29.64 $11.40 $23.68 370 DISK STORAGE $0.00 $0.00 $0.00 $0.00 370 DISK STORAGE $0.72 $0.13 $0.13 $0.72 370 DISK STORAGE $1.99 $0.13 $1.64 $16.40 370 DISK STORAGE $0.00 $0.00 $0.00 $0.00 370 DISK STORAGE $0.27 $0.13 $0.13 $0.27 370 DISK STORAGE $0.00 $0.00 $0.00 $0.00 370 DISK STORAGE $195.48 $94.12 $39.28 $81.58 370 DISK STORAGE $0.00 $0.00 $0.00 $0.00 370 DISK STORAGE $130.01 $90.84 $24.99 $35.77 370 DISK STORAGE $8.10 $3.90 $2.62 $5.44 # -sum # end This will sort the 15 lines and summarize the four columns of numbers. # indent 3-3 # index "NULL parameter" "SUM=NULL command" # index "Database-related commands" "SUM=NULL" # index "SUM=NULL" SUM=NULL: Turns off summarization. # index "Database-related commands" "-SUM" # index "-SUM" -SUM: Same as SUM=NULL. # # indent 0 # index "Control codes" # index "Page numbers" # index "Date-stamps" # index "Time-stamps" # index "Column headers" # index "Titles" # index "^B" # index "^D" # index "^T" # index "^N" # index "^A" # index "^I" # index "^H" # index "^O" # index "%n%" Control codes: Within titles, headers, and footers, you can embed the following codes. These codes are case-sensitive; "^b^" will not translated as the current page number. These codes will be expanded on output: ^B current page number ^D pagination date (in mm/dd/yy or appropriate country format, or in whatever your DATE marker has set) ^T pagination time (in hh:mm format) ^N name of the input file (without drive or path information) ^A input file's creation date (in mm/dd/yy or appropriate country format, or in whatever your DATE marker has set) ^I input file's creation time (in hh:mm format) ^H column headers (when appropriate) ^O output file's name (without drive or path information) You can also immediately follow any of the control codes with a field width by including one or two digits within two percentage signs. For example, "^O%12%" will force the output file's name to be 12 characters in length. This is useful for making sure that the headers are all a uniform length, something which would otherwise be complicated because the length of the page number can vary. Without using the length codes, formatting commands like centering will be adjusted based on the replacement contents for these codes. A line containing a one-digit page number will be centered differently than the exact same line containing a three-digit page number. Example: # title center width 80 File ^N listing, page ^B # end or # title center width 80 ^O%12% ^B%3% Revised: ^A # end Date formats are based on your appropriate country date format although you can override this by using the DATE marker command. See the discussion on "date display" later for information on date formats. # # index "Varspecs" # index "Specifying columns" # index "Specifying variables" # index "Columns" "Specifying" Varspecs: Several of the commands (for example, SELECT and SORT) expect you to pass in a "varspec" parameter. Varspec's indicate which variables or columns to process. The format for the varspec is: n[-n] [ , n-[n] ]... where "n" is a single variable/column. "n-n" indicates you want a range of variables/columns. For FROM ASCII or FROM DBF, the "n" corresponds to a variable number. For FROM FIXED, the "n" corresponds to a physical one-byte column. For example: # from ascii # select 1,3 "Testing",2,4 "All",5,7 "This",1,6 says to display the 1st and 3rd variables and results in something like this: Testing 4 All 7 This 6 On the other hand, if you're processing fixed-fielded data, the varspec will select individual columns. So: # from fixed # select 1-10,15 1234567_10_2345678 Testing abcdefgh All abcdefgh This abcdefgh will come out like this: Testing e All e This e # # index "Field-definition file" # index "ASCII-delimited files" # index "dBase files" Field-definition file: For data files (ASCII-delimited, dBase, and fixed field input files), you can use PAGINATE.EXE to present a reasonably formatted listing of variables. Unless you are reading a dBase file, this program requires a field-definition file to figure out the characteristics for each field and also to set certain file characteristics. If you're processing an ASCII-delimited input file, the routine can try to create a field-definition file for you if desired. The definition file can be created with any text editor. The definition file consists of several records with the following fields separated by spaces. Except for the record type indicator (which must begin in column 1), all other fields can be placed in any columns: (1) record type (see below) (2) length of field on input (3) number of decimal places for numeric data (if you don't know, put a "?" here; for non-numeric data, a "0" is fine) on output (4) length of field on output Any characters after the field length are treated as comment fields. You would typically use this to enter the field name or column position or any other information of use to you. The data record types accepted by this routine are as follows: type C = character data (leading spaces are trimmed) V = verbatim character data (no leading spaces are trimmed) N = numeric L = logical (T or F) D = date (in yyyymmdd format) M = memo fields (only for dBase input files; ignored on output) The data fields should be in the order the fields are found in the source file. Note that for fixed field files, you have to account for every byte in the file. If you have something like this: 12345678_1_2345678_2_2345678_3 (column positions) APPLE X Y 12 BANANAS Even though you may think you only have five fields, the following .DEF file will NOT work: ; Bad .DEF file: Note does not account for blank spaces C 8 0 8 Fruit1 C 1 0 1 Class1 C 1 0 1 Class2 N 5 0 5 Value C 11 0 11 Fruit2 # You may want the Fruit1 field to be in columns 1 through 8 and Class1 to be in column 10 but the routine will not know to skip column 9 so it will start reading Class1 beginning in column 9, Class2 beginning in column 10, etc. To drop the blank positions, you have to add dummy fields on input and ask for them to be dropped on output: ; Good .DEF file: Spaces between fields are accounted for C 8 0 8 Fruit1 C 1 0 0 Filler C 1 0 1 Class1 C 1 0 0 Filler C 1 0 1 Class2 C 1 0 0 Filler N 5 0 5 Value C 1 0 0 Filler C 11 0 11 Fruit2 You can also use the input field length and output field lengths to either drop fields using other formats (by specifying a zero length for the output field length) or for creating fields on output (by specifying a zero length for the input field length). You can also use this to expand on contract a field. For example, if Fruit1 is 8 characters long but you only want it to occupy 4 characters on output (thus the field would be truncated), specify 8 for the input field length and 4 for the output field length. If the output field length is wider than the input field length, the data values will be shifted right or left depending on the data type. In general, numeric fields are shifted right (so extra spaces show up in front of the number) and all other field types (character, logical, or date) are shifted left. # # index "Parameters" "Specifying" # index "INI file" # index "SET PAGINATE environmental variable" # index "Marker commands" "From the command line" Specifying parameters: Parameters for this program can be set in the following ways. The last setting encountered always wins: - Read from an *.INI file (see BRUCEINI.DOC file), - Through the use of an environmental variable (SET PAGINATE=whatever), or - From the command line (see "Syntax" below) In most cases, the marker commands themselves can be passed in at the command line or through one of the other methods specified above. The only difference is that the marker commands then begin with "/" instead of (by default) "#". Some marker commands (like TITLE ... END) don't make sense in the command line. # index "Character-translation file" # index "/Linitfile parameter" # index "Graphics characters" "Removing" # index "Non-printable characters" "Removing" # index "Characters" "Removing" # index "(NONE) replacement" # index "/Iinitfile parameter" Character-translation file: PAGINATE will process a character-translation (lookup) table if one is found. This table can be in your standard *.INI file (for example, PAGINATE.INI) if desired or it can be a separate file specified using the /Linitfile parameter. This table allows you to replace all instances of one character in your input file with another when you write the file out. What would you use this for? Your document might contain characters like graphic characters. You might have problems if you wanted to e-mail this document to someone or print it on a printer than didn't recognize the characters. # For example, something like: # unit verbatim ΪΔΒΔΏ ΙΝΛΝ» ³ ³ ³ Ί Ί Ί ΓΔΕΔ΄ ΜΝΞΝΉ ³ ³ ³ Ί Ί Ί ΐΔΑΔΩ ΘΝΚΝΌ # end looks great on the screen but it might print out horribly. If you want, you can tell PAGINATE to do a one-for-one character replacement on any characters. This is done through the character-translation file. This file, which can be embedded in the standard PAGINATE.INI file, consists of a series of lines in the following format: inchar = outchar where "inchar" is the character to change from and "outchar" is what to change the character to. Both portions can consist of regular non-space ASCII text characters (like "A" or "z") as well as hexadecimal values (in the form &Hxx) or decimal values (in the form \nnn). (See the BRUCEHEX.DOC file.) To remove a character entirely, assign it the value of (NONE). You cannot use a space or equal sign in either "inchar" or "outchar"; use the hexadecimal or decimal representations instead. The table does not have to be in any specified order. Lines can end with "/*" followed by a comment if you want. Examples: \186 = | /* Ί becomes | \205 = - /* Ν becomes - \206 = + /* Ξ becomes + \027 = (NONE) /* Remove excape characters entirely Since lines beginning with "/" are treated as command-line defaults, you must use \047 or &H2F if you want to override the definition of "/". NOTE: If a character-translation file is specified, all instances of Alt-0 will be removed from the resulting file. (This is how the program handles replacements with (NONE)). Redefine \000 as \032 or something if you want to keep them. # index "Alt-255 key" "Removing" Note that Alt-255 is automatically translated to Alt-32 (regular space) even if character-translation table is used. Alt-255 is used internally by the program to handle things like bullets and such. It is also the recommended character to use to avoid certain combinations of words from wrapping. Blank lines or those beginning with the following are ignored as comments: ; (semi-colon) : (colon) ' (quote) # index "PAGNOASC.INI" The lookup tables can also be read from a different table specified by the /Linitfile parameter. Use the enclosed PAGNOASC.INI as your lookup file if you want to remove all non-standard characters from your file. Modify as necessary. # # Index "Date displays" # index "Date-stamps" "Formatting" Date displays: The characters that can be used in the output format include the following special characters (from the VB/DOS on-line help): # unit verbatim Symbol Description ΝΝΝΝΝΝ ΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝΝ d Display the day as a number without leading zeros (1-31) dd Display the day as a number with leading zeros (01-31) ddd Display the day as an abbreviation (Sun-Sat) dddd Display the day as a full name (Sunday-Saturday) ddddd Display a serial date number as a complete date (including day, month, and year) m Display the month as a number without leading zeros (1-12); if used immediately following h or hh, the minute rather than the month is displayed mm Display the month as a number with leading zeros (01-12); if used immediately following h or hh, the minute rather than the month is displayed mmm Display the month as an abbreviation (Jan-Dec) mmmm Display the month as a full name (January-December) yy Display the year as a two-digit number (00-99) yyyy Display the year as a four-digit number (1900-2040) # end You can embed other characters like punctuation in the format string as well. For example, if today is September 12, 1996, the following DATE=string specifications yield the following results: # unit verbatim DATE="mm/dd/yy" yields 09/12/96 DATE="mmm_dd,_yyyy" yields Sep 12, 1996 # end The program does not actually verify your DATE=string specification and you may get a run-time error if you specify it incorrectly. # # index "Examples" # index "Directories" "Multicolumn" # index "Formatting commands" "MARKER=c" "Example" # index "MARKER=c" "Example" Examples: This section adds some examples of how you can use PAGINATE. I'll add to it over time. Multicolumn Directories: You want to generate a multicolumn listing of directories which are sorted going down the page instead of across the page like "DIR /W" does. PAGINATE can handle this fairly easily. Create a control file called C:\DIRW.CTL with these statements (the SETUP and RESET statements work for Hewlett-Packard printers to put you into compressed mode): #WIDTH 132 #SETUP "\027E" #RESET "\027E\027(s16.66H" #MULTICOLUMN 7 #MARKER=* If you don't want it to be in a compressed mode, use the following control file: #WIDTH 80 #MULTICOLUMN 5 #MARKER=* (The #MARKER=* is in there because a number of shareware companies have gotten into using weird characters as the first letter of the file name to make sure the file sorts higher in an alphabetical list. Several programs may begin with a pound sign but none can begin with an asterisk.) Then create a batch file called DIRW.BAT: DIR /ON > TEMP.TXT PAGINATE TEMP.TXT TEMP.OUT /CC:\DIRW.CTL /OVERWRITE DEL TEMP.TXT This will route your directory to a disk file and rewrite it as TEMP.OUT in a multicolumn format with printer controls. # index "Windows" "Long-line files" # index "Lines" "Wrapping long ones" # index "Notepad" "Converting from" Those long-line things you get from writing out the file from Windows: You've done this. You ask for a text file. They've created it using the Windows notepad. You look at it and the lines scroll endlessly--one line per paragraph. How are you supposed to print that?! Simple. Let's say the file name is NOTEPAD.TXT. Just issue the following command: PAGINATE NOTEPAD.TXT /ALIGN /WIDTH=80 # # index "Syntax" Syntax: # unit verbatim PAGINATE [ filespec | (filelist) | @listfile ] [ outfile ] [ /Cctlfile ] [ /DEBUG ] [ /OVERWRITE | /APPEND | /-OVERWRITE | /OVERASK ] [ /marker command ]... [ /EXT=.xxx ] [ /P ] [ /BEEP ] [ /Linitfile ] [ /MONO ] [ /Iinitfile | /-I ] [ /-ENV ] [ /? ] [ /?&H ] # end where: # index "Filespec parameter" # index "Files" "Input" "filespec" tells the routine which file or files are to be processed. It can include path information if desired. It can also include standard DOS wildcards as long as an output file is not specified. The input files can contain INCLUDE statements to add in other files to process. If no input specification (filespec or @listfile) is provided, you'll be prompted for one. # index "(filelist) parameter" # index "Files" "Input" "(filelist)" allows you to specify multiple files to be processed from the command line. File names should be separated by spaces. They may include drive, path, and wildcard information. Remember that a command line in DOS cannot exceed 127 characters so you're limited as to how many different file specifications you can provide in this fashion. # index "@listfile parameter" # index "Files" "Input" "@listfile" allows you to have a variety of file specifications saved in a text file named "listfile". Each line in the file should consist of one file specification, each of which can include a path and wildcards if desired. Blank lines and lines beginning with semi-colons, colons, or quotes are ignored. If no input specification (filespec or @listfile) is provided, you'll be prompted for one. # index "Outfile parameter" "outfile" specifies the name of the output file that is to contain the resulting text. By default, the output file name will be the name of the input file with a .PAG extension. (The default .PAG extension can be overridden using the "/EXT=.xxx" parameter.) # index "Ctlfile parameter" # index "/Cctlfile parameter" "/Cctlfile" is basically the same thing as the infile but it typically contains only marker commands. For example, you might have a straight text file contained in "infile" and then use the "ctlfile" to say how that text file should be processed. # index "/DEBUG parameter" "/DEBUG" is used for debugging purposes. You might use it when you get an error message that doesn't clearly tell you where the error occurred. /DEBUG will show you the text as it's processed and let you see what's actually being processed and written. # index "/OVERWRITE parameter" "/OVERWRITE" says to overwrite the output file if it exists already. # index "/-OVERWRITE parameter" "/-OVERWRITE" says to abort if the output file exists already. # index "/APPEND parameter" "/APPEND" says to append (add) to the output file if it exists already. This option is only available if you're creating either a fixed-field or ASCII- delimited output file. # index "/OVERASK parameter" "/OVERASK" says to ask if the output file exists already. This is initially the default. # "/marker command" allows you to specify one or more marker commands. These are spelled out in this documentation. Note that not all marker commands can appear in the command line whereas all marker commands can instead be embedded in either the control file or the document itself. # index "/EXT=.xxx parameter" "/EXT=.xxx" allows you to specify a different default file extension for the output file. This parameter only matters if you do not explicitly specify an output file name. The default value is "/EXT=.PAG". # index "/PAUSE parameter" # index "/P parameter" "/P" (or "/PAUSE") waits for you to press ENTER if there is a compilation error and then returns you to DOS. This is useful if you're using PAGINATE to process a whole series of files. The default value is "/-P" ("/-PAUSE"). # index "/-PAUSE parameter" # index "/-P parameter" "/-P" (or "/-PAUSE") says to return to DOS without prompting you if there is a compilation error. This is initially the default. # index "/BEEP parameter" "/BEEP" says to sound a tone when the program is finished executing. The default value is "/-BEEP". # index "/-BEEP parameter" "/-BEEP" says to not sound a tone when the program finishes. This is initially the default. # index "/Linitfile parameter" "/Linitfile" says that the "Character-translation table" codes are found in a file other than from the default "/Iinitfile" file. This is primarily useful if you want to have a master *.INI file and a separate code lookup table. PAGNOASC.INI is provided as one sample character-translation table. It removes all graphics and other possibly non-printable characters from the output file. # index "/MONO parameter" # index "/-COLOR parameter" "/MONO" (or "/-COLOR") does not try to override screen colors. Initially defaults to "/COLOR". # index "/COLOR parameter" # index "/-MONO" parameter" "/COLOR" (or "/-MONO") allows screen colors to be overridden. This is initially the default. # index "/Iinitfile parameter" "/Iinitfile" says to read an initialization file with the file name "initfile". The file specification *must* contain a period. Initfiles are described in the BRUCEINI.DOC file. Initially defaults to "/IPAGINATE.INI". # index "/-I parameter" # index "/INULL parameter" "/-I" (or "/INULL") says to skip loading the initialization file. # index "/ENV parameter" "/ENV" says to look for %var% occurrences in the command line and try to resolve any apparent environmental variable references. See BRUCEINI.DOC for more information. This is initially the default. # index "/-ENV parameter" "/-ENV" says to skip resolving apparent %var% occurrences in the command line. Initially defaults to "/ENV". # index "/? parameter" "/?" or "/HELP" or "HELP" shows you the syntax for the command. # index "/?&H parameter" "/?&H" gives you a hexadecimal and decimal conversion table. # # index "Return codes" # index "ERRORLEVEL codes" Return codes: PAGINATE returns the following ERRORLEVEL codes: 0 = no problems 254 = errors encountered in processing input files 255 = syntax problems or /? requested # index "Guthrie, Bruce" # index "Wayne Software" # index "WayneSof@erols.com" # index "e-mail contact" # index "Author" Author: This program was written by Bruce Guthrie of Wayne Software. It is free for use and redistribution provided relevant documentation is kept with the program, no changes are made to the program or documentation, and it is not bundled with commercial programs or charged for separately. People who need to bundle it in for-sale packages must pay a $50 registration fee to "Wayne Software" at the following address. Additional information about this and other Wayne Software programs can be found in the file BRUCE.DOC which should be included in the original ZIP file. The recent change history for this and the other programs is provided in the HISTORY.ymm file which should be in the same ZIP file where "y" is replaced by the last digit of the year and "mm" is the two digit month of the release; HISTORY.611 came out in November 1996. This same naming convention is used in naming the ZIP file (PAGINymm.ZIP) that this program was included in. Comments and suggestions can also be sent to: Bruce Guthrie Wayne Software 113 Sheffield St. Silver Spring, MD 20910 e-mail: WayneSof@erols.com fax: (301) 588-8986 http://www.geocities.com/SiliconValley/Lakes/2414 Please provide an Internet e-mail address on all correspondence. # title center width=79 Index ^B%3% ^A # end # # multicolumn 2 # include index # end