Stars of Shareware: Programmierung

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

/ Stars of Shareware: Programmierung / SOURCE.mdf / programm / msdos / pascal / pxl214a / pxl.doc < prev next >

Wrap

Text File | 1992-07-16 | 63.5 KB | 1,687 lines

PXL Pascal Cross-Reference Lister Version 2.14 Programmer: R. N. Wisan, October, 1990 37 Clinton Street, Oneonta, NY, 13820 internet: wisanr@hartwick.edu Not Copyright: Enjoy. PXL 2.14 Contents Contents Contents 1 Introduction . . . . . . . . . . . . . . . . . 1 2 The Files . . . . . . . . . . . . . . . . . . . 2 3 Running PXL . . . . . . . . . . . . . . . . . . 3 3.1 The Interactive Mode . . . . . . . . . . . 3 3.2 The Command Line Mode . . . . . . . . . . 4 3.3 The Batch Mode . . . . . . . . . . . . . . 5 3.4 The Cross-Reference . . . . . . . . . . . 5 3.5 Include Files . . . . . . . . . . . . . . 6 3.6 Page Format . . . . . . . . . . . . . . . 6 3.6.1 Headers 6 3.6.2 Pagination 9 3.6.3 Tab Width 10 3.6.4 Style for Reserved Words 10 3.7 Redirecting PXL's Output . . . . . . . . 11 3.8 Stopping PXL . . . . . . . . . . . . . . 11 4 Adapting PXL . . . . . . . . . . . . . . . . 12 4.1 For Other Pascals . . . . . . . . . . . 12 4.2 For Other Printers . . . . . . . . . . . 13 4.3 PXLINST: Editing Print Control Symbols . 13 4.3.1 The Symbols You Need 13 4.3.2 Running PXLINST 15 4.3.3 Wide-Carriage Printers 16 4.4 Eliminating the Data Files . . . . . . . 16 4.5 Screen Colors . . . . . . . . . . . . . 17 Appendix A: Using PXL in a Network . . . . . . 18 Appendix B: History . . . . . . . . . . . . . . 19 Appendix C: About Updates . . . . . . . . . . . 25 -- i -- PXL 2.14 Introduction 1 Introduction 1 Introduction Once upon a time, Borland's Turbo Pascal came with an unad- vertised source lister called "TLIST." Unfortunately, it had bugs. This program was written to do some of the things TLIST was supposed to do and some things it didn't. Here are the main features: o It lists a file with headers: by default it puts file name with user's ID and creation date on page 1, file name and page numbers thereafter. Or, if you prefer, you can make your own header of up to five lines. o It will paginate automatically, but you can insert symbols in the file to control page breaks. o It handles lines of up to 255 characters. It normally uses two sizes of print, but they can be fonts of any size. o It offers options to - mark the reserved words by underlining them (or bold- facing or CAPITALIZING them or what you & your printer will). - number the lines and count begin-end pairs. - cross-reference the identifiers in the source file. - include in the listing (and cross-ref) files called with the {$I filename} directive. - redirect output to any device or file. - form-feed a blank page before listing. o It can be run from a batch file without stopping for interac- tion. Should anything go wrong, it sets ERRORLEVEL 1. o It will run on DOS 2.00 or later. If you leave the reserved words unmarked, of course, PXL will list any sort of plain ASCII file. -- 1 -- PXL 2.14 The Files 2 The Files 2 The Files PXL.DOC is the documentation you are now reading. PXL.EXE is the working compilation. You run it from DOS. PXL.WDS contains the list of reserved words PXL uses if you ask it to mark reserved words. This file must be in the default directory or somewhere on the DOS path when you run PXL.[1] PXL.PRN contains the printer control codes which PXL uses when it numbers the lines or marks the reserved words. As it comes, it contains the codes for an Epson FX-80, but it may be changed by means of PXLINST. It must be in the default di- rectory or somewhere on the DOS path when you run PXL.[1] PXLINST.EXE is an installation program to put the proper print control symbols in PXL.PRN. You don't need it to run PXL. It's only required if you have to adapt PXL for your printer. PXL.PAS, PXLINIT.PAS, PXLMENU.PAS and PXLLIST.PAS contain the source code for PXL.EXE. You might need it if you have to recompile to change colors or as in note [1]. PXLINST.PAS contains the source code for PXLINST.EXE. PXL.ID and PXL.HDR are not on your disk. You make them yourself. PXL.ID can hold a personal ID if you want one in your header: just type your name in the Turbo Pascal editor, and save it under "PXL.ID." When PXL finds such a file, it takes up to 24 characters from it for an ID. PXL.HDR can hold your own default header to replace PXL's standard one. See Section 3.6.1, "Headers," on page 6. ----------- 1. Strictly, PXL can be run without its .WDS and .PRN files. Without them it can still number the lines and break up long ones, but it can't mark reserved words or count begin-end pairs, and it can print only plain pica. If you ask for any- thing it can't do, it will stop and complain. __ But, there is a way of tinkering with the source code in PXL.PAS to get it to run properly without the external data files. See "Adapting PXL," esp. page 16, below. -- 2 -- PXL 2.14 Running PXL 3 Running PXL 3 Running PXL To run PXL, the two files, PXL.WDS and PXL.PRN must be on the default disk or somewhere on your DOS path. If you want an ID in the header, you must make a PXL.ID file and keep it on the path, too, and if you write your own default header do the same with PXL.HDR. There are two ways to run the program: 3.1 The Interactive Mode 3.1 The Interactive Mode You can simply enter PXL from the DOS prompt. It will ask what file you want to list. (It adds the extension .PAS unless you tell it otherwise.) It will search along the path, and, if it finds the file, it will ask you to confirm the file name. Then it offers some choices about how you want it printed. You can ask for up to five characters (upper and lower case both work): L L (Linenumber) makes it number the lines (and use elite type if your printer has it, to keep the lines from folding.) If you also call for [M]ark or [X]-Ref, it will keep count of begin- end pairs and print the number of open Begin (or Repeat or Case) statements at each line. M M (Mark) makes it underline the reserved words.[2] X X (X-Ref) makes it produce a cross-reference of the identifiers in your source code. F F (Form-Feed) makes it feed out a blank page before listing. To do this, however, the printer must form-feed on getting the FF (char 12) symbol. Unless it is told (in PXL.PRN) that the printer can do this, PXL will neither offer nor accept this option. P P (Plain) If you want none of these things, you can enter a nothing at all. Five blanks make it print plain (or, just hit <ENTER>). The menu says nothing about it, but a P has the same effect (and overrides most of the others). ----------- 2. Here and elsewhere, I speak of "underlining," but you can choose any other form of emphasis your printer can do. If you prefer or if your printer can't do anything else, you can mark by printing the reserved words in CAPITALS. -- 3 -- PXL 2.14 The Interactive Mode V V (Vanilla --plain text) This is for printing files that aren't program code at all. It differs from P(lain) in that it won't pay any attention to {$I instructions (see p. 6) or {. page formatting instructions (see p. 9) in the text. It prints what's there and nothing else. It paginates and breaks long lines, however, and you can give header and some format in- structions in PXL.HDR (see p. 6). 3.2 The Command Line Mode 3.2 The Command Line Mode Used interactively, PXL is gabby. It checks your choices, explains your errors, and lets you make corrections. This is helpful, maybe, but time-consuming. To short-cut, enter the in- formation at the DOS prompt. If you enter PXL filename PXL will accept the filename, check to see if it exists, and skip its opening inquiries. For better speed, enter PXL filename xxxx (where "xxxx" is any string of characters) it will pick the print style letters out of the string, show you what you've asked for and ask for confirmation. If you want a plain vanilla printout (no line numbers, key words unmarked), put a "P" in the string. Order doesn't matter, you can use upper or lower case, and addi- tional stray characters are ignored. Note: "P" will override anything else (except "X"). Thus, if you enter PXL XYZ whelp It will supply the suffix, ".PAS", notice the "p" and ignore the other letters. You'll get file XYZ.PAS, printed plain vanilla. PXL xyz.pas MeltWax would get you file XYZ.PAS, with the works: key words underlined (M), line numbers and begin-end counts (L), and a cross-ref (X). PXL XYZ.DOC L would print file XYZ.DOC with the lines numbered. When you enter the data at the command line this way, PXL will look for your file. If the file is found, you get one screen asking you to confirm the file name and the print mode choices. If you say, "Yes," it goes into its act. If you say, "No" (or if it can't find your file), it reverts to the inter- active mode, and you can correct your instructions. -- 4 -- PXL 2.14 The Command Line Mode However you start it going, PXL keeps you informed about what it's doing. (Sending lines to printer, Scanning without print- ing, Sending X-ref lines to printer, etc.) It gives you a run- ning line-count --to show that something's happening-- and at the end of an X-ref printout, you get some statistics about your file. 3.3 The Batch Mode 3.3 The Batch Mode If you want to run PXL from a batch file, put a line in your file just as you'd enter it in the Command Line Mode, but put the BAT letters, BAT (upper or lower case) in the instructions. In that case, PXL will not stop for interaction no matter what. If all is well, it will print out as instructed. If there is any hitch, file to print can't be found, .PRN or .WDS file not on the path, <Esc> or if somebody presses <Esc> during operation, it will set the ERRORLEVEL at 1. Your batch file can take account of that in deciding what to do next. Here's a sample, which will take the file name from the command line, execute PXL, printing the file with key words marked and lines numbered, and print "ALL WELL" if it's printed the whole file or "ENDED BADLY" if anything went wrong: echo off pxl %1 ml bat if errorlevel 1 goto Abort echo ALL WELL goto end :Abort echo ENDED BADLY :end 3.4 The Cross-Reference 3.4 The Cross-Reference The cross-reference cites all the identifiers in your program with the line numbers in which they occur. They are printed with the upper/lower case combination of their first occurrence. At the end of the identifier listing, you get a list of all the procedures and functions declared in the listing. Listing a Unit file, PXL will list the first occurrence in the implementa- tion of each procedure or function name (presumably it's the dec- laration). If you prefer to see the interface declaration, there's a brace-out section in PXLLIST.PAS, procedure Ins, along about line 850. -- 5 -- PXL 2.14 The Cross-Reference I should mention two limitations of the cross-reference: 1. As far as PXL can tell, an identifier is a given combina- tion of symbols. If you declare a variable like I: integer in several different procedures, they'll be lumped together in the X-ref listing. If you care about having an accurate list of the declared procedures, be careful not to use a procedure name as a local variable earlier in the program. 2. Standard Pascal allows only numbers to be used as labels. Turbo Pascal allows any legal identifier (which must start with a letter) as well. PXL ignores numbers, so it can't pick up labels like 99. If you want your labels listed, start them with a letter. 3.5 Include Files 3.5 Include Files Files called with the Include directive {$I filename}, will be included in the listing and cross-reference, provided: 1. PXL can find it. If the filename specifies a path, say {$I B:PXL2.INC}, it will look for the file first in the place specified and then search along the path. Whether it finds the file or not, it will print a message on the screen and in the printout showing what's happened. 2. The {$I filename} directive begins in the first column of the code (if the directive starts anywhere else, PXL will simply ignore it). This give you two ways to control inclusion of files in your listing. Note: As it does with the main file, PXL will add the suffix "PAS" to the name of include files if none is given. To in- struct it otherwise, put a period at the end of the filename. 3.6 Page Format 3.6 Page Format Unless otherwise instructed, PXL will make a one-line header of its own devising and paginate automatically every 62 lines (including the header). But, you can instruct it otherwise. -- 6 -- PXL 2.14 Headers 3.6.1 Headers 3.6.1 Headers The standard default header occupies one line. On the left it puts the file name and the user's ID (if it can find a PXL.ID file). On the right of page 1 it puts the file date; subsequent pages get the page number instead. If you prefer a different default header, you can write your own. Keep it in a file called PXL.HDR anywhere on the path, and PXL will use it for its default header.[3] Whichever default header you use, you can further alter the header by putting in- structions in your text. Here are the rules for header instruc- tions, whether in the text or in PXL.HDR: A PXL header can have up to five lines.[4] You can change it at any point in the file. Each header line has three segments which must be separately specified. Each segment specifier has five parts: 1. { (opening brace) 2. One of the following symbols: .HnL = left side of Header line #n .HnC = center of Header line #n .HnR = right side of Header line #n .HnN = no Header line number #n .HN = no header at all .HA = Alternate left & right header segments on odd/even pages (for 2-sided print) .HTnn = expand tabs to nn characters .HPLnn = page length: print nn lines per page. "n" of course, stands for a numeral. The other symbols must be upper case exactly as shown. Those last two aren't really about the header at all, but they can be placed in PXL.HDR. See under "Pagination" p. 9, and "Tab Width" p.10. 3. a space. (That's ONE space. Spaces after the first become part of the text of the header segment.) ----------- 3. There's a heavily commented header file on the disk, under the name XXL.HDR. To see what it does, change its name to PXL.HDR and run PXL. 4. This limit is controlled by constant MaxHeader, at the top of PXLLIST.PAS. -- 7 -- PXL 2.14 Headers 4. the text of the header segment. Within the text, you can use the following symbols: .Fn = file name .Fd = file date (style: July 4, 1776) .Ft = file time (style: 2:25 pm) .Pd = present (or printout) date (style: 7/4/76) .Pt = present (or printout) time (style: 14:25) .Id = user ID (from PXL.ID) # = page number (no period) These symbols are case-sensitive. They must be upper/lower case exactly as shown. 5. } (closing brace) Some remarks: o Header instructions can appear anywhere in a line, but each one must begin and end on the same line. o To empty a segment (that's previously been filled), put the closing brace right after the symbol and space: {.H2R} means empty right segment for 2nd header line. In general, to emp- ty header lines: ___ {.HN} empties all the header lines (i.e., no header). {.H2N} empties the second (#2) header line. {.H2L} empties left segment of the second header line. o PXL normally puts one blank line above and one blank line below the header. To force extra blanks lines below the header, make a blank (not empty) header segment. {.H5L } would do it --note the extra spaces between L and }. The first space is eaten, the others become the left segment of header line 5. o Normally, header instructions take effect on the next page after the instructions. To specify the opening header, you ___ have to put all the instructions for it at the top of your file. You can use several consecutive lines to do it, but there must be no blank lines between or before them. At the top of the file, you could (almost) specify the standard default header thus: {.H1L File: .Fn [.Id]} {.H1R .Ft, .Fd} Then, there or anywhere in the first page's worth of text: {.H1R Page #} ___ o Note: in PXL 1.41, specifying any header segments at all anywhere in the text canceled the default header. This has -- 8 -- PXL 2.14 Headers been changed. Beginning with PXL 1.42, new header specs change only the segments specified. Thus: - To cancel the default header for a particular file, you must use {.HN}. Put that in the first line of the file to head off the default before it gets onto the page. - Unlike header specs in the text, a PXL.HDR file complete- ly replaces the standard default header. If you don't want a default header at all --not ever, create a PXL.HDR file that contains no header instructions. A zero-byte file will do. So long as that's on the path, PXL will make no headers on its own. You can still insert header specs in the body of your file. o You can differentiate between headers for the first page and for subsequent pages. Within PXL.HDR (and at the top of the text), the first specification for a given segment defines what's to go on the first page. A subsequent spec for that segment will be used for other pages. Thereafter, specifica- tions simply supersede each other. o {.HA} will make PXL reverse the left and right header seg- ments on even-numbered pages for printing on both sides of the page. Notice that you can't turn it off. You can leave it off, but once on, it's on for the rest of the file. o If you need several default headers for different sorts of file, you could manage it by controlling the DOS PATH. 3.6.2 Pagination 3.6.2 Pagination To control page breaks, put the following symbols in the file: {.PA} {.PA} produces an absolute page advance. The line on which the symbol appears will be the first line of the new page. {.CPnn} {.CPnn} (where nn is a number) makes a conditional page break. If there isn't room for nn lines, it will start a new page at that point. Look at the PXL source code. It's peppered with these to keep the procedures whole. Caution: This command specifies physical lines on the page. If you write lines long enough to fold, PXL will not make allowance for it and may run out of space on the page and split your block across the page break. If you write such lines, be sure to allow for it in specifying the nn. {.HPLnn} (where nn is a number) specifies the number of lines PXL is to print on the page (including the header). The default -- 9 -- PXL 2.14 Pagination is 62 lines on a 66 line page. This command will override the standard 4-line bottom margin.[5] Here, too, a caution: This specifies the number of lines to print, not the size of the paper. Make sure you don't over- run the paper by putting too large a number in HPL. Specify actual paper size (in lines) in "Page Control", using PXLINST (see p. 14). Of course, if the printer can page correctly with FF, you don't need to specify how many lines it fits on the paper so long as it's more than you tell PXL to put. Even though it's not a header specification, an HPL instruc- tion can be placed in PXL.HDR. 3.6.3 Tab Width 3.6.3 Tab Width The tab key on earlier Turbo Pascal editors worked by insert- ing spaces in your text. Beginning with 4.00, however, Turbo Pascal allows you to insert tab characters directly in your text, and expands them in the display. By default, PXL will expand the tab characters in printout to columns 8 characters wide. You can adjust tab width with header tab symbol: {.HTnn}. {.HT3}, for example, sets the tab width to 3. You can, of course, put the tab symbol in PXL.HDR. I suggest it probably ought to go in the text. You'll want the printer to use the same tab width you used when editing. 3.6.4 Style for Reserved Words 3.6.4 Style for Reserved Words As it comes, PXL is set to underline TP's key (reserved) words when you ask to [M]ark them. It inserts printer control symbols at the beginning and end of key words. (What's a key word is determined by the list in PXL.WDS.) It comes set to use the Epson instructions for "start underline" and "stop under- line." If your printer needs something different or if you pre- fer some other style for key word marking (like boldface), you can make the changes with PXLINST. If your printer can't start and stop underlining that way, give PXL nothing at all for "start underline" and "stop under- line." Then, it will do its underlining by sending a bare car- riage return (without line feed) and overprinting the line with appropriately placed underscores. ----------- 5. The default is controlled by variable BottomMargin, set in procedure SetUp in PXL.PAS -- 10 -- PXL 2.14 Style for Reserved Words If your printer can't do a bare carriage return without add- ing a linefeed, or if you prefer to mark key words by having the key words printed in CAPITALS, there's a constant you can change in PXL.PAS procedure SetUp that will make it so. There's more about how to customize PXL in Sections 4.3, p. 13 and 4.4, p. 16 . 3.7 Redirecting PXL's Output 3.7 Redirecting PXL's Output Just below the file name, PXL's screen shows where its output will be sent. Normally, it goes to the default printer, PRN, but you may want it sent to some other device or to a file. Some- where in the command line put the name of that file or device with double quotes around it: PXL MYFILE LMX "C:\PAS\MYFILE.LST" would list MYFILE.PAS with line numbers, marking the key words, making a cross-ref, and sending the output to C:\PAS\MYFILE.LST instead of to the printer. Notice that you cannot do this from ____ inside PXL. It can only be done on the command line. If you _______ prefer, you can change the default output device. Just change the assignment to constant OutputDevice in procedure SetUp in PXL.PAS. Writing to a file is quicker and doesn't produce piles of printout. That's convenient when you use PXL's BEGIN-END count to debug "; expected" at the "end." (The BEGIN-END count should ______ _____ always go to 0 at the end of each procedure, and it should never go negative except at the end of a Unit which has a terminal "end." without a "begin".) 3.8 Stopping PXL 3.8 Stopping PXL You can stop PXL at any point by pressing the <Esc> key. You may have to wait while it finishes the line it's working on and folds up the files, but don't panic. It will stop. -- 11 -- PXL 2.14 Adapting PXL 4 Adapting PXL 4 Adapting PXL As it comes, PXL is designed to print source files from Turbo Pascal 4 or 5 on an Epson FX-80 from an IBM PC. When asked to mark reserved words, it sends the Epson printer control strings to start and stop underlining. If that's what you want to do, you can use PXL.EXE as it is. If you prefer to mark reserved words by printing them in CAP- ITALS, constant MarkWCaps in procedure SetUp in PXL.PAS controls it. In addition, PXL can be adapted: o For other printers, or to mark key words in some other way, you can change the print control symbols in PXL.PRN. See the instructions for other printers. o Other Pascals (including earlier versions of Turbo Pascal can also be accommodated by changing the reserved word list in PXL.WDS (see below). 4.1 For Other Pascals 4.1 For Other Pascals The only Pascal I'm familiar with is Borland's Turbo Pascal. If your source code is in plain ASCII text files, the main diffi- culty about other Pascals ought to be the list of reserved words. (PXL would print the file, but it would mark only words reserved in Turbo Pascal 4). Used normally, with its data files, PXL will adjust semi- automatically to Turbo Pascal 3. It takes its clue from the number of reserved words in PXL.WDS. When you call for the M or X options, PXL reads in PXL.WDS, and if it finds a PXL.WDS on the path that fits TP3, it will adjust. (Apart from the difference in reserved words lists, TP3 and TP4+ need somewhat different handling of the {$I } directives.) Run without an M or X option, of course, PXL never reads in PXL.WDS, and so doesn't get the word. In procedure SetUp (in PXL.PAS), there's a constant, Turbo3, normally set to FALSE. To make PXL default to TP3 when printing plain, set Turbo3 to TRUE. You can control which file PXL finds by adjusting the PATH. I keep both TP3 and TP5 on my disk. They're in different direc- tories, and I set the PATH to exclude the one I'm not using. Each TP directory has a PXL.WDS that fits its version of TP. PXL lives in a utilities directory that's always on the path. Thus, -- 12 -- PXL 2.14 For Other Pascals PXL always finds the right PXL.WDS. More about this in section 4.4 on p. 16. The list of reserved words is in the file PXL.WDS, so all you need to do is rewrite the PXL.WDS file to contain your Pascal's reserved words. Any text editor (like the Turbo Pascal editor) which makes plain ASCII files will do. Put one word on each line (without any extra blanks). Order doesn't matter. Upper/lower case doesn't matter. PXL can handle up to 100 reserved words (there are 43 in Turbo Pascal 1.00, 44 in 2.00 and 3.00 and 48 in 4.00 and 5.00) and the words may be up to 15 characters long. If you need more than that, you'll have to rewrite the source code. The only things you'd have to change are in procedure SetUp at the beginning of the implementation of PXL.PAS. They are identi- fied with comments. 4.2 For Other Printers 4.2 For Other Printers The Epson MX and early IBM printers, resemble the FX-80, but with the standard PXL.PRN data, the line numbering mode may come out odd because it expects an elite font, which these printers lack. If you write lines long enough to fold, you should use PXLINST to change the print control symbols in PXL.PRN. For other printers, consult your printer manual to see what you need. Again, use PXLINST to install the proper data. 4.3 PXLINST: Editing Print Control Symbols 4.3 PXLINST: Editing Print Control Symbols To change the print control symbols, you must first work out what symbols you'll need. Then, with PXL.PRN on the default drive, run PXLINST. 4.3.1 The Symbols You Need 4.3.1 The Symbols You Need PXL assumes that your printer can be made to underline and to adjust its type to two different widths by sending it control codes of 1 to 7 characters. These characters must be in PXL.PRN, on the default drive when you run PXL. Up to six print control strings are required, start and stop for two type styles, a pre- printout printer initialization string, and a post-printout printer reset string. It can be told to feed out pages by send- ing a form-feed (character #12) or by feeding out blank lines to a specified number. -- 13 -- PXL 2.14 The Symbols You Need ___________ Underlining. If you prefer to mark your reserved words in some other way (boldface? italics?), put here whatever your print- er needs for it. Some printers have no underline or other suitable instruction, but they can back up and overprint a line when sent a bare CR (ASCII #13). In that case, put no- thing at all for Start Underline and Stop Underline, and PXL will overprint reserved words with underscores. If you want to mark reserved words by putting them in CAPITALS, find the constant, MarkWCaps, in procedure SetUp (in PXL.PAS), change it to True, and that's what PXL will do no matter what's in PXL.PRN. ________________ Start using Pica: this should turn off the other type style (called "elite" here) and turn on whatever you want for the headers and for the main body of text when not numbering lines. It doesn't have to be pica (10 characters per inch), so long as you give the right number of "Cols/Ln in Pica" below. _________________ Start using Elite: should turn off the "pica" font and turn on a narrower one. It doesn't have to be true elite (12 charac- ters per inch), so long as you give the right number of "Cols/Ln in Elite" below. Normally, PXL uses this font when numbering the lines. You don't have to use two type sizes. If you prefer, you can put the same instruction for both of these sizes or use dif- ferent type faces of the same size, or what you will. If you give nothing at all for "Start using Elite," PXL will manage without it. _______________ Before Printing. If you need to send some symbols to initialize the printer (to set it in draft mode, for example), put the ASCII code for those character here. PXL will send them to the printer before it sends anything else. This instruction is entirely optional. You needn't put anything here. ______________ After Printing. Conversely, you may need to send some symbols to reset the printer when you're through (to return the printer to letter quality, for example). Specify those characters here, and PXL will send them after it's sent everything else. You might keep in mind that if PXL has used "elite" in its print run, it will turn it off immediately before sending any "After Printing" sequence you specify. ____________ Page Control. Here, it needs to be told whether your printer will feed out a new page when sent a Char #12 ("FF") and, if not, how many lines it puts on a page. If you give it a 12 for "Page control," it will use Char #12 to form-feed. If you give it any other number, it will take that for the num- ber of lines the printer gets to a page. -- 14 -- PXL 2.14 The Symbols You Need _______________ Cols/Ln in Pica: a single number representing the number of ____ columns per line the printer gets in the "pica" font you specified above. This method of specifying columns per line allows you to adjust for type style and carriage width. Nor- mal pica gets 80 columns per line on a narrow printer like the Epson FX-80 and 133 columns per line on a wide carriage printer like the Epson FX-100. ________________ Cols/Ln in Elite: the number of columns per line in the font you specified for "elite." Look up the print control symbols in your printer manual. Work out the ASCII numbers for them. PXLINST requires the num- bers; it can't accept characters. Thus, to enter "Escape G", you would use the numbers, 27, 71. 27 is the ASCII number for "Es- cape", and 71 is the number for "G". When you know what numbers you're going to need, put PXL.PRN on the default drive, and run PXLINST. 4.3.2 Running PXLINST 4.3.2 Running PXLINST Since it's an .EXE file, PXLINST, like PXL runs straight from DOS. When you run it, PXLINST gives you a screen showing the nine different instructions. If it finds PXL.PRN somewhere on your DOS path, it will show you what is currently in the file for each instruction and the "Present Data" you (or the file) have set for them. It gives pretty good operating instructions. o With the up and down arrows, move the cursor bar to the line you want to change. o You can edit whatever happens to be on the line. When you've NUMBERS got the proper sequence of numbers (NUMBERS, not characters), press <Enter>, and it will move on to the next instructions. You can use up to seven ASCII numbers per instruction. ___ To abandon what you've done on a line, do not press <Enter>, Just move off the line with the up or down arrows. o If you want nothing for a given instruction, delete every- thing on the line and press <Enter>.[6] ----------- 6. If you don't want any of these print options (or your printer doesn't have them), put nothing for every instruction but "Page Control," "Cols/Ln in Pica" and "Cols/Ln in Elite." PXL will then print plain vanilla, but it'll break the lines ap- propriately, number them, give you begin-end counts, mark the reserved words by overprinting them with underscores, and make cross-references. -- 15 -- PXL 2.14 Running PXLINST o Make sure the "Present Data" display indicates what you wanted. o When the "Present Data" is what you want, press <Esc> to end the program. It will then ask whether you want the file re- written with your new data. Up to this point, PXLINST hasn't actually changed the file. If you've made a mess, you can say "No." If you happen to run PXLINST without PXL.PRN somewhere on the path, no matter. It won't have any file data to show you, and it will start you out with "Present Data" of "[nothing]," but you can enter the numbers you want, and PXLINST will create a new PXL.PRN file on the default disk. Earlier versions of PXL (before version 2.00) used a differ- ent PXL.PRN file. If PXLINST finds such a PXL.PRN on your path, it will read the data from it correctly. In such a case, you'll get a warning. If you proceed with PXLINST and finally update the file, it will be converted to the new format. To preserve the old file as is, exit without saving. (But then, why were you running PXLINST at all?) PXL 2.00, by the way, can read the old style files perfectly well. If your old printer instructions were all you want, you don't need to manufacture a new PXL.PRN. 4.3.3 Wide-Carriage Printers 4.3.3 Wide-Carriage Printers Earlier versions of PXL needed to be carefully cozened to make them run properly on a wide-carriage printer. Beginning with version 2.11, all that's gone. If you tell PXL (through PXLINST) that your "Pica" font puts 133 characters per line, it will believe you. 4.4 Eliminating the Data Files 4.4 Eliminating the Data Files PXL can be made to run without the .PRN and .WDS data files by a simple alteration in PXL.PAS. The program already contains the necessary code for loading the print instructions and re- served word list internally. All you have to do is set the value of DataFiles to False instead of True. (You do this in procedure SetUp in PXL.PAS. The comments there will show you what's what.) That will get you the TP4+/Epson data that's in the code. If you want to change ____ that, you must go deeper: o Procedure LoadReserv in PXLMENU.PAS contains the lists of key words for Turbo Pascal 3 and for Turbo Pascal 4+ (presently, -- 16 -- PXL 2.14 Eliminating the Data Files it has TP5.5's list). Which list is used depends on the set- ting of constant Turbo3 in procedure SetUp in PXL.PAS. If that's what you want, you can set the constant whichever way you want. Any other list you must make yourself. If you set DataFiles to False, you commit PXL to whatever Turbo3 is set for. When PXL is run normally, with Data- Files=True, Turbo3 controls the default, and PXL will switch semi-automatically between TP3 and TP4+. Printing plain, it can't do it, but the M and X options require the word list and so force PXL.WDS to be read, and the number of words fount triggers the TP3/TP4+ setting. (Apart from the actual reserved words, it matters for a few oddities like the hand- ling of {$I compiler directives.) o Procedure GetPrinterData in PXLINIT.PAS has the print control symbols. Be careful to preserve the data form. (Essential- ly, it's just like a Turbo Pascal string[7].) Each of the first 6 instruction takes eight bytes. The first (subscript 0) contains the number of following bytes which are signif- icant in the instruction. Set unused bytes to $FF. The last 3 instructions take a single byte each. This is exactly how the data would come in from PXL.PRN. I suggest you begin by using PXL with the external files, be- cause it's easier to experiment on printer data with PXLINST than by changing and re-compiling PXL. When you know what numbers you need, you can make the necessary changes to Get- PrinterData in PXLINIT.PAS, set DataFiles in PXL.PAS false, and recompile. If you set out to make this (or any other) adaptation, it would be wise to make a copy of PXL first and experiment on the copy. 4.5 Screen Colors 4.5 Screen Colors On a monochrome text monitor, PXL always runs in black and white. On other monitors it normally uses color, and three vari- ables: NormalColor, FrameColor, and Background control the colors. FrameColor is used only for the ornamental rectangle. Everything else is in NormalColor. To set the colors to your liking, change the values in procedure SetUp in PXL.PAS. Programmer: R. N. Wisan, October, 1990 37 Clinton Street, Oneonta, NY, 13820 internet: wisanr@hartwick.edu -- 17 -- PXL 2.14 Using PXL in a Network Appendix A: Using PXL in a Network Appendix A: Using PXL in a Network The batch mode (BAT) and form-feed (F) options were added in order to make PXL usable conveniently on a printer-sharing net- work. To illustrate this use of PXL, this appendix describes the use made of it with elementary classes in the PC Lab at Hartwick College in Oneonta, NY. The network was the University of Waterloo's JANET. In this system, all utilities were kept on a virtual disk in "Drive A." Students kept their own programs on a real disk drive labelled D: by the network, and they kept a PXL.ID user ID file on their disks. They were taught to send printer output from their programs to a file, D:OUT.PUT. To allow these beginning students to get their printouts with a minimum of confusion and a minimum of instruction, PXL was run from a batch file. To get printouts, they merely entered: A:NEWPRINT programfilename Here is an annotated copy of NEWPRINT.BAT: ECHO OFF A:PXL D:%1 MLXF BAT REM List program marked, numbered, xref, & FF REM (to avoid the network's printout header) IF ERRORLEVEL 1 GOTO ABORT REM If program listing went well A:PXL D:OUT.PUT BAT REM List output file plain w/o FF IF ERRORLEVEL 1 GOTO ABORT REM If this, too, went well, A:PRINTIT REM send to printer REM and report success:- ECHO D:%1 and OUT.PUT sent to printer GOTO END :ABORT REM If all did not go well, A:PURGE * REM Abort printing, & report failure: ECHO Error in listing. Printout has been aborted. :END Note: PRINTIT is the network's print command. PURGE * cancels everything sent to the print spool from this work station. -- 18 -- PXL 2.14 History Appendix B: History Appendix B: History In olden times, Turbo Pascal version 1.0 came with a source lister called TLIST. Unfortunately, it was buggy. Borland ex- plained that TLIST was an unadvertised freebie and wouldn't work on all printers.[7] Mainly as an exercise, I wrote ELIST to do on my Epson (FX-80) some of the things TLIST was supposed to do. Some versions of it were circulated in July, 1984. In August of 1984, ELIST was revised to allow use of other printers and other Pascals by putting printer control symbols and reserved words in separate data files. An awkward installation program was supplied to edit the printer data. In honor of that, I renamed it "NELIST" (pronounce "N" and "E" separately). Early versions worked only in the interactive mode. Later versions added a command line mode to skip (most of) the interactive gab. NELIST Version 2.0, April, 1985, was improved: 1. Handles wide files (up to 255 characters): o Breaks long lines neatly to prevent folding. o Condensed print ("W") option added for wide files. 2. File header contains file's creation date instead of print- out date. 3. Include files {$I filename} incorporated in the listing. 4. Interactive messages streamlined a little, especially for the command line mode. PXL Version 1.00, June, 1985: In the spring of 1985, when our Computer Science program (at Hartwick College) was overhauled, Turbo Pascal 3 was adopted as the beginning language, to be run on an IBM PC equipped network. For that installation, NELIST 2 seemed a useful accessory, but a ----------- _________ 7. According to TUG Lines Vol. I, No. 3, p. 1, Borland will prob- ably never fix the bugs in TLIST. Apparently, it was written as an in-house utility, and providing it to the customers "was entirely an afterthought. One day the source code for TLIST was accidentally deleted..." -- 19 -- PXL 2.14 History cross-reference function was desired. PXL is the result. It is built on the old NELIST foundation, with the following changes: 1. The cross-reference (X) feature is, of course, the most important addition. 2. The options have been simplified. The user now gets no choice about the manner of marking reserved words. If you want to boldface instead of underlining them, you must change PXL.PRN. 3. Changing PXL.PRN is now much easier. Installation program (now called PXLINST) rebuilt with full-screen data entry. 4. The ability to run without external .PRN and .WDS files has been built into the program. If constant DataFiles is set to False, PXL will use built-in data. 5. While the program is running, a line count is displayed. The point of this is to assure user that the computer has not died. At the end of an X-ref listing, various statis- tics about the program are given. PXL Version 1.10, July, 1985: Better documentation in PXL2.INC, smoother interactive mode, and: 1. PXL now understands hex numbers. 2. Programs containing exactly one procedure or function will now cross-ref properly. 3. For the sake of consistency, the former PXLID.DAT (the per- sonal ID file) has been renamed, PXL.ID. 4. You can now STOP the program at any point by pressing the <Esc> key. (Control-Break doesn't work.) 5. PXL will now handle file names which have no extension. PXL Version 1.11, October, 1985 1. The main addition is the ability to run from batch files. In the batch mode it avoids interactive pauses and sets ERRORLEVEL 1 if anything goes wrong. 2. File name entered without a drive letter will be shown with the default drive letter. -- 20 -- PXL 2.14 History 3. Better control over include files. Like TLIST, PXL will incorporate include files only if the {$I filename} command begins in the first column. 4. Manual includes better treatment of the problems of adap- ting PXL to other machines and operating systems. PXL Version 1.12, February, 1986 1. F (Form-Feed) option added to allow operation under a network which puts its own header on printouts. The F option clears the network's header off the page. 2. PXL 1.11 could not safely be used in the batch mode under DOS 1.10 because any hitch would hang the machine. Proce- dure SetErrorLevel now checks for DOS version, so batch mode is now safe under any DOS version. PXL Version 1.20, June, 1986 PXL now searches along the whole DOS path both for the file it's to process and for its own auxiliary files. This requires the newer DOS 2 file handling procedures, and the problem of DOS compatibility is evaded by abandoning DOS 1.10 entirely. PXL Version 1.21, September, 1986 PXL is now savvy about screen colors. Constants added to set colors to taste. Further, PXL is polite: on exit, it returns the screen to the color it found there. PXL Version 1.22, November 15, 1986 Small bug about Xref printout corrected. Background added to screen color constants. PXL Version 1.23, November 22, 1986 Bug corrected: PXL no longer hangs the machine on (a) no path, (b) a path which contains no semi-colon, or (c) a blank command-line entry. PXL Version 1.4X January, 1988 The X means "experimental." Rewritten in and for Turbo Pascal 4.00. Provision made for Turbo 4's 8 layers of include files. Asterisks at right of page indicate depth of inclusion. -- 21 -- PXL 2.14 History Instead of constants to switch colors & such, you must jigger procedure SetUp in PXL.PAS. PXL Version 1.41 February, 1988 Some cleansy-upsy in source code. The menu is still a hor- rible hack, but less horrible. Generally, a less hasty response to TP4 than 1.4X was. New feature: User can override the default header and specify a header of up to five lines. PXL Version 1.42 April, 1988 Improvement in header specification. Version 1.41's in-text specification methods are still available, but now you can write _______ you own default header to replace PXL's by keeping what you want in PXL.HDR, anywhere on the path. One difference: in 1.41, any header specification in the text would cancel the entire default header. Now, header instructions in the text replace only the segments specified. To wipe out the default header, you must do so explicitly. PXL Version 1.43 June, 1988 New function is output redirection. First thing in quite a _ while added because I wanted it. You can still set the default output place (PRN, LPT1, Filename, etc.) in PXL.PAS (procedure SetUp), but you can override it at run-time from the command line. Note: some people who had 1.43 were sent a bug-fix patch: begin-end count on Unit source would hang if the initialization section at the end had no "begin". PXL Version 2.00 August, 1988 Should have used "2.00" earlier, maybe as early as 1.4x. Apart from a small bug-fix (it wouldn't mark the reserved word, "implementation"), this version has two changes: 1. The more important change is an extension of printer codes: o Each print instruction may now have up to 7 characters (instead of 3). The purpose of this is to accommodate printers requiring more than 3 characters. In conse- quence, an Epson owner could now mark reserved words in underlined, boldfaced italics. -- 22 -- PXL 2.14 History o Two new print instructions added: PreP sent to initialize printer before printing the file, and PostP sent after printout to put the printer back to bed. To accommodate this, PXLINIT had to be heavily revised, also. The new PXLINST will convert old style PXL.PRN files to new, and the new PXL will still accept an old style PXL.PRN. 2. Since the TP editor allows tab characters to be embedded in the file, PXL 2 offers an option to set the tab width. The default is left at 8. I don't think I ever documented the fact that PXL would expand tabs at all. PXL Version 2.01 September, 1988 Some smoothing of the .HN header instruction. Also, fixed a small bug: printing plain, junk sometimes appeared above the header. PXL Version 2.02 November, 1988 Added {.HA} header instruction. For printing on both sides of the page, it reverses left and right header segments on alter- nate pages. PXL Version 2.03 November, 1988 Small bug corrected: TP4's {$IFDEF etc. were treated as in- cludes. PXL Version 2.04 December, 1988 New option: V(anilla) or T(ext) for printing ordinary text files. This differs from P(lain) in that instructions in the text (for headers, file inclusion or page control) are ignored. PXL.HDR, however, still works. PXL Version 2.10 April, 1989 Corrected bugs about long printer instructions, hash proce- dure (in X-ref) and one-line RECORD .. END declarations. Fixing the latter required processing reserved words from left to right in the line. As a side effect, the new method gives about a 40% increase in speed. -- 23 -- PXL 2.14 History PXL Version 2.11 May, 1989 o Bad bug in 2.10's new processing procedure caught and fixed. o A bug introduced by v. 2.04's Vanilla or Text option was preventing the batch mode from using fancy formatting. The fix is leaving V(anilla) but removing the T(ext) instruction. (It was the "T" in "BAT".) o New PXL.PRN format allows fewer fonts (only "pica" and _______ "elite") but user can specify width of page in columns for each, so any odd character widths are now usable, narrow paper or wide. "Wide" option dropped as no longer needed. o Change in cross-ref list of procedures & functions; listing a unit file, it now shows declaration in implementation instead of in interface. PXL Version 2.12 (July 1989) is the same as 2.11 but accomodates TP 5.5's four new reserved words. PXL Version 2.13 (June 1990) Fixed a hanging bug in PXLLIST's alphabetizing of the list of procedures and functions. Probably introduced in ver. 2.10 PXL Version 2.14 (October 1990) Woeful deficiencies of the local computer lab's main printer require additional methods of marking reserved words: o If given no printer instruction strings for start and stop underlining, PXL will now use bare CR's to mark reserved words by overprinting them with underscores. o New constant in procedure SetUp (in PXL.PAS) can force PXL to mark reserved words by printing them in CAPITALS instead of trying to underline them. -- 24 -- PXL 2.14 About Updates Appendix C: About Updates Appendix C: About Updates Updates to my programs appear irregularly and sometimes fre- quently, as bugs and suggestions are brought to my attention. Since I make no charge for these things, I can't afford to send updates to every software library and BBS which may be carrying the programs. As of this writing, one place I do make an effort to keep up to date is Nelson Ford's "Public (software) Library." The address is: The Public (software) Library P.O. Box 35705 Houston, TX 77235-5705 Since the PsL is prompt both in updating their material and in filling their orders, they're one place where you can be sure of getting my latest efforts. It is not unethical to take my pro- __ grams off a PsL disk and package them yourself. (It is unethical and probably illegal to copy the whole PsL disk including other programs and the PsL's own explanatory files and programs.) Of course, people who send me useful suggestions and bug reports are liable to be sent a copy of the fix (if I can make one). They're also liable to be drafted into my Beta Testing Division. -- 25 --