CD Actual 14

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

/ CD Actual 14 / CDACTUAL.iso / cdactual / demobin / share / program / Basic / SOURCE13.ZIP / SOURCE.DOC < prev next >

Wrap

Text File | 1992-11-07 | 101.8 KB | 2,276 lines

SOURCE Version 1.3 November 7, 1992 Written by Rick Maddy SOURCE Table of Contents 1 Distribution . . . . . . . . . . . . . . . . . . . . Page 1 2 What is SOURCE? . . . . . . . . . . . . . . . . . . Page 1 3 Quick Start . . . . . . . . . . . . . . . . . . . . Page 2 4 The SOURCE Command Line . . . . . . . . . . . . . . Page 3 4.1 Global Options . . . . . . . . . . . . . . . . Page 3 4.2 Filenames . . . . . . . . . . . . . . . . . . . Page 4 4.3 Local Options . . . . . . . . . . . . . . . . . Page 5 4.4 Full Command Line . . . . . . . . . . . . . . . Page 5 5 SOURCE Options . . . . . . . . . . . . . . . . . . . Page 5 6 SOURCE.CFG . . . . . . . . . . . . . . . . . . . . . Page 17 6.1 SOURCE.CFG Location . . . . . . . . . . . . . . Page 17 6.2 Named Configuration Options . . . . . . . . . . Page 17 6.3 SOURCE.CFG Format . . . . . . . . . . . . . . . Page 18 6.4 Commenting SOURCE.CFG . . . . . . . . . . . . . Page 19 6.5 Modifying SOURCE.CFG . . . . . . . . . . . . . Page 19 7 SOURCE.PRT . . . . . . . . . . . . . . . . . . . . . Page 19 7.1 Default Printer . . . . . . . . . . . . . . . . Page 20 7.2 SOURCE.PRT Format . . . . . . . . . . . . . . . Page 20 7.3 Modifying Your Printer . . . . . . . . . . . . Page 24 8 SOURCE.LNG . . . . . . . . . . . . . . . . . . . . . Page 24 8.1 SOURCE.LNG Location . . . . . . . . . . . . . . Page 24 8.2 SOURCE.LNG Format . . . . . . . . . . . . . . . Page 25 8.3 Commenting SOURCE.LNG . . . . . . . . . . . . . Page 26 8.4 Defining Language Specific Features . . . . . . Page 26 8.4.1 Comments . . . . . . . . . . . . . . Page 26 8.4.2 String and Character Literals . . . . Page 27 8.4.3 Blocks . . . . . . . . . . . . . . . Page 28 8.4.4 Keywords . . . . . . . . . . . . . . Page 29 8.4.5 Complete Definition . . . . . . . . . Page 30 8.5 General Points . . . . . . . . . . . . . . . . Page 31 9 Network Support . . . . . . . . . . . . . . . . . . Page 31 10 Definition of Shareware . . . . . . . . . . . . . . Page 32 11 Disclaimer - Agreement For Trying SOURCE . . . . . . Page 33 12 Registering . . . . . . . . . . . . . . . . . . . . Page 33 13 Future Enhancements . . . . . . . . . . . . . . . . Page 34 14 Acknowledgements . . . . . . . . . . . . . . . . . . Page 34 15 Release History . . . . . . . . . . . . . . . . . . Page 34 SOURCE REGISTRATION . . . . . . . . . . . . . . . . . . . Page 37 Page i SOURCE SOURCE Version 1.3 - Source code file printing utility Copyright 1992 Rick Maddy 1 Distribution The SOURCE program is made up of these files: SOURCE.EXE The SOURCE program file. SOURCE.DOC This documentation file. SOURCE.PRT The default printer definition file. SOURCE.CFG The default configuration option file. SOURCE.LNG The default language definition file. README.1ST Quick summary and last minute notes. REGISTER.TXT Order form to register SOURCE. This unregistered shareware program is distributed in the PKZIP format. SOURCE.ZIP may be passed onto as many people as you like, provided it remains intact, ALL files are kept together, and only the original files are distributed. DO NOT zip up and pass on your modified files. See section 10 below for further information on shareware. 2 What is SOURCE? SOURCE, in its most basic form, is a program for printing source code and text files. However, using SOURCE to its fullest potential gives you an extremely powerful and flexible program for printing source code and allows for numerous options for formatting the output: - Custom page sizing - Adjustable margins - Page orientation (portrait or landscape) - Character pitch (pica, elite, or compressed) - Number of columns per page - User definable page header/footers - Optional banner page before/after files - Output may be redirected to any device or file - Printing ranges may be specified, including starting and/or ending line or page numbers - Multiple files can be queued for printing In addition to these basic printing options, SOURCE contains many options specifically geared toward formatting source code (such as C, Pascal, Fortran, dBase, or whatever you code in). These include: - User definable line and page numbering - Comments in the source code may be printed as bold, italic, or underlined - Keywords may be highlighted - Code blocks grouped graphically - Adjustable tab sizes for printing - Configurable language support Page 1 SOURCE These are just some of the powerful options available to you. Yet, SOURCE is very easy to use. SOURCE only needs to know the name of the file(s) you wish to print and it does the rest. You can use SOURCE right out of the box (so to speak). For example: C:\> SOURCE kludge.c This would print your file to the default printer using the built in defaults. You may configure each option to suit your needs. See section 5 for a complete list of all the options. Besides the printing options, SOURCE is extremely flexible in its ability to work with almost any printer and most programming languages. To facilitate this dynamic environment, SOURCE consists of an executable (SOURCE.EXE) and three support files: SOURCE.PRT: Contains all the printer definitions. SOURCE.CFG: Contains all the default options used by SOURCE to print your files. SOURCE.LNG: Contains all the language and filename extension specifications needed for comment and keyword highlighting and block grouping. By default, all four files that make up SOURCE are named "SOURCE.???" where '???' is "EXE", "PRT", "CFG", and "LNG". If you prefer to use a different name, such as "SRC", instead of "SOURCE", simply rename all four files to the same prefix. Example: C:\>ren source.* src.* This will result in all four files having the "SRC.???" name instead of "SOURCE.???". Anywhere in this documentation you are to execute "SOURCE", enter "SRC" instead. The only advantage to this is to save on typing "SOURCE" all the time, now you enter "SRC". You could even change all the names to "S" if you really like terse, UNIX-like command names. 3 Quick Start Before running SOURCE for the first time (as if you have read this far without having already done so), make sure you have placed SOURCE.EXE, SOURCE.PRT, SOURCE.LNG, and SOURCE.CFG all within the same directory. You may also wish to include this directory in your path so that you can run SOURCE from anywhere on your system. If you need more information on PATHs, see your DOS manual. The simplest way of running SOURCE is to type: SOURCE filename.ext Page 2 SOURCE "SOURCE" is the program SOURCE and "filename.ext" is the name of the file you are going to print. You may press the [Esc] key anytime while a file is printing to abort SOURCE and stop the current file from printing. Remember, most printers have buffers and the printing will probably not stop immediately. The first time you run SOURCE you will be asked to select your default printer. This printer should be the one connected to printer port one, "LPT1:". If you are using a different port, see section 6.5 for information on changing the printer port used by SOURCE. The list of printers initially supported by SOURCE contains printers which should cover most of the printers in use. Pick the printer that closest matches the one you have. Note: If none of the printers are like yours, select the "Generic" printer for now. You will still be able to print files, you just won't be able to take full advantage of SOURCE's strengths. Later on you'll see how to modify SOURCE.PRT to take full advantage of your printer. See section 7 for more information on printer definitions. Typing "SOURCE" at the prompt with no options will give you a few lines about the general command line syntax. You may type "SOURCE -?" to see a few screens showing the command line syntax, what each option is, and the options' current defaults. After the options, you will be shown what printers, languages, and named configuration options are defined in the SOURCE.PRT, SOURCE.LNG, and SOURCE.CFG files. 4 The SOURCE Command Line SOURCE is a command line utility. To run SOURCE, type the name of this program, SOURCE, followed by any options you wish to use along with the filename(s) of the file(s) you wish to print. The command line syntax is as follows: SOURCE [-global options] filename.ext [-local options] . . . Objects in square brackets are optional and the ". . ." means you may repeat as many filenames as you wish to have printed. The command line has two levels of options, global and local. Global options are configuration options that apply to all files on the command line. Local options only apply to the files that immediately precede them. 4.1 Global Options Global options appear after the program name and before the first filename. These options apply to all the files specified on the command line. Global parameters are optional. The syntax of global options is a hyphen ( - ) followed by a one letter option followed by any required parameters. Options that take parameters require that there be no space between the option and Page 3 SOURCE the parameter. String parameters are slightly different. A space before the parameter is allowed. String parameters may also be enclosed in double quotes. The quotes are required only if the string contains spaces. An example is: SOURCE -n -N4 -r com1 The above example only contains global options (in this case, four digit line numbers with output redirected to comm port one). This example will not actually produce any output because no files are specified yet. Options that you use frequently can be permanently preset within the SOURCE.CFG file. This way, you do not have to specify them each time you use SOURCE. See section 6 for a discussion on setting global options as defaults. 4.2 Filenames After the global parameters, if any, you may specify the files you wish to print. In the simplest form, this would be a single filename and its extension. SOURCE foobar.c Running this would cause SOURCE to print the file "foobar.c" from the current directory. To specify a file in another directory or on another disk drive, use the full path name, as in the example below: SOURCE c:\src\code.pas This would print the file "code.pas" found in the "c:\src" directory despite your current working directory. There are three methods for printing multiple files. The most tiresome is to run SOURCE once for each file you need to print. The second option is to use wildcards when specifying the filename. The wildcards allowed are '*' and '?'. These behave exactly like the wildcards used by DOS commands (such as copy and delete). If you do not understand how wildcards work, please refer to your DOS manual for more information. An example of wildcard use is: SOURCE *.c This would cause SOURCE to print all files in the current directory that had the extension ".c". Each file will be printed separately, starting on page one, line one. The third method for printing multiple files is to enter more than one name on the command line: SOURCE program.c data.txt Page 4 SOURCE This would cause SOURCE to print the two files, "program.c" and "data.txt", from the current directory. You may specify as many files as the command line has room for. Any combination of these methods may be used, for example: SOURCE *.c b:*.txt c:\proj\*.* This command line would print all 'C' files in the current directory, all files with the extension ".txt" from the disk in the B drive, and all files from the "proj" directory of the C drive. 4.3 Local Options In addition to the global options, you may specify "local" options after each filename. These local options override the global options and only apply to the file they immediately follow on the command line. Local options are optional. The syntax for local options is identical to that of global options (see section 4.1). Example: SOURCE -n hello.c goodbye.c -n- This command will cause SOURCE to print the file "hello.c" from the current directory with line numbers and "goodbye.c" without line numbers. The global option "-n" causes line numbering to be turned on for all files. Specifying "-n-" after "goodbye.c" tells SOURCE to turn line numbering off only for "goodbye.c" and does not affect "hello.c". Local options used after filenames with wildcards will apply to all the files matched by the wildcards: SOURCE *.c -b -c will print all 'C' files with block tracing and highlighted comments turned on for each file. This also shows that you may specify more than one local option per file. Of course, you do not have to specify any local options if they are not needed. 4.4 Full Command Line The command line for SOURCE is very flexible. This flexibility can also lead to some pretty long and complicated command lines. There are many ways to remedy this. See section 6 for ways to minimize the command line options. The most complex command line would be as follows: SOURCE -n -N4 file.pas -c -b *.c -h2 *.dat -n- This line contains global options and three file specifications each giving their own local options. You will not normally have such lines, but the power is there to use. 5 SOURCE Options Page 5 SOURCE What follows is an alphabetized list of all the command line options that SOURCE recognizes. These options may be specified as global or local options on the command line (unless indicated otherwise). They may also appear in the SOURCE.CFG file to define default options for those options you wish to have in effect each time you run SOURCE. See section 6 for more on the SOURCE.CFG file. All options are case sensitive so do not run SOURCE with your caps lock on. Conventions used below: [x] Square brackets indicate optional items. There may not be a space between the option and the parameter if specified. Example: n[-] may entered as n or n-. {x|y} Curly braces containing a list of choices separated with a vertical bar indicate that you must select one of the options available for that item. There may not be a space between the option and the chosen parameter. Example: a{a|o|r} allows aa, ao, or ar. "text" Quotes indicate that you must enter a text string. You do not have to type the double quotes unless the string contains spaces. There may be a space between the option and the string. Example: z "list" allows: z.exe.obj <== No spaces z".exe.obj" <== Quotes optional, no spaces z".exe .obj" <== Quotes required, spaces z .exe.obj z ".exe.obj" z ".exe .obj" Not allowed would be: z .exe .obj because the parameter contains a space and must be enclosed in quotes. # A pound symbol indicates that you must enter a number after the option. Numbers may be made up of the 10 numeric digits and minus for negative numbers. There may not be a space between the option and the number. Example: w# allows w1, w2, w3, etc. h# allows h-1, h2, h0, etc. Page 6 SOURCE Option Description -? Help. The '?' option displays a quick command summary showing all the available options and their current defaults. Running SOURCE with no options simply shows the command line syntax and the '-?' option. -a{a|o|r} Append/Overwrite. The 'a' option describes the action SOURCE will take when redirecting the output to a file and the file already exists. See the 'r' option for more on redirecting the output. When the 'a' option is followed by an 'a', SOURCE will automatically append the new output to the previous contents of the file. When followed by an 'o', SOURCE will automatically overwrite the old contents of the file and leave only the new output. When followed by an 'r', SOURCE will interactively prompt you for the action to take. You may specify 'append', 'overwrite', enter a different file, or quit SOURCE. Default is 'ar', request. -b[-] Block Grouping. The 'b' option sets whether block grouping is turned on or not. The 'b' may be followed by '-'. The 'b' option alone turns on block grouping, the minus turns it off. For this option to work, SOURCE must know what language the file is written in. This is done by using the filename extension as defined in the SOURCE.LNG file or the 'x' option may be used to force a specific language. The lines used for block grouping may be drawn using either standard ASCII characters or the IBM line drawing characters. See the 'g' option to set how the lines are drawn. Default is 'b', block grouping on. Below is some sample C code with block grouping turned on: while (x < 10) ┌{ │if (a < b) │ ┌{ │ │puts("Hello"); │ └} │else │ ┌{ │ │puts("Goodbye"); │ └} │x++; └} Page 7 SOURCE The above also assumes the 'g' option is on. With the 'g' option off, the same code looks as follows: while (x < 10) +{ |if (a < b) | +{ | |puts("Hello"); | +} |else | +{ | |puts("Goodbye"); | +} |x++; +} -B[*]# Banner. The 'B' option allows you to print a banner before and/or after each file. The banner contains the filename and extension in BIG letters. The 'B' must be followed by a number from 0 to 3. 0 means no banner at all. 1 means a banner only before the file. 2 means a banner only after the file. 3 means a banner before and after the file. You may also specify an optional asterisk ('*') before the number. This will cause the letters of the banner to be made up of asterisks instead of the default individual letter. Default is 'B3', print banner before and after using letters. -c[-] Comment Highlighting. The 'c' option sets whether comments within your programming code are highlighted or not. The 'c' may be followed by '-'. The 'c' option alone turns on highlighting, the minus turns it off. For this option to work, SOURCE must know what language the file is written in. This is done by using the filename extension as defined in the SOURCE.LNG file or the 'x' option may be used to force a specific language. The highlighting method used is as defined in the SOURCE.PRT file for the selected pitch. Default is 'c', highlighted comments on. -d "printer" Select Printer. The 'd' option specifies which printer definition in the SOURCE.PRT file SOURCE should use when printing out files. The 'd' must be followed by the printer name. The name specified is not case sensitive. If you only have one printer connected to your computer you will not need to use this option. If you have multiple printers connected to different ports, you can specify this option at the command line when you are using a printer Page 8 SOURCE other than the default. If this is the case, you will also need to use the 'r' option to specify the port the printer is connected to. If you use different printers often, you may wish to define a named configuration in the SOURCE.CFG file for each printer. Then all you need to specify on the command line is the 'u' option. See the 'u' option for more details on using named configurations. The default printer is selected by the user the first time SOURCE is run or by modifying the SOURCE.PRT file. See section 7 for more on SOURCE.PRT. -e[-] Escape Codes. The 'e' option sets whether printer escape codes are output along with your text or not. Normally you would want this left on so your printer will print the file properly. Turning this option off would typically be used when redirecting output to a file when you would not want the escape codes embedded in the target file. The 'e' may be followed by '-'. The 'e' option alone causes the codes to be printed, the minus prevents the codes. Default is 'e', codes printed. -f# Final Line. The 'f' option allows you to specify the final line number of the file to print out. This would be used to print only a desired block of code instead of having to print the entire file. The 'f' must be followed by a positive number. Specifying zero means the last physical line. This option may not be used with the 'F' or 'I' options unless set to zero. Default is 'f0', print through last line. -F# Final Page. The 'F' option allows you to specify the number of the final page of the file to print out. This would be used to print only a block of code, or part of a page range, instead of printing out the entire file. The 'F' must be followed by a positive number. Specifying zero means the last physical page. This option may not be used with the 'f' or 'i' options unless set to zero. Default is 'F0', print through last page. -g[-] Graphics. The 'g' option determines how the block group lines are printed (see option 'b' for more on block grouping). When the option is on, the lines will be printed using the IBM line drawing characters. With the option off, simple ASCII characters will be used. If your printer cannot print the extended IBM character set then turn this off. If your printer can print the lines then set this to on. You may need to send a special code to your printer to select the IBM Page 9 SOURCE extended character set. To do so, place the proper printer codes in the 'Init' record in the SOURCE.PRT file for your printer. Default is 'g-', print using standard ASCII. -h# Header Page. The 'h' option is used to specify when to print the page header or footer. The 'h' must be followed by a number. Zero means no header or footer will be printed. A one means to print the header only on the first page. Any value of two or more will result in the header being printed on all pages. To cause the header to be printed at the bottom of the page (now a footer), specify a negative number. Negative one means to print a footer only on the first page. Any number of -2 or less (-100 etc.) will cause the footer to be placed on all pages. Page headers and footers are underlined and printed in 10 pitch regardless of the pitch selected for the rest of the file. The contents of the header are user definable by using the 'H' option. Default is 'h2', header on all pages. -H "header" Header Definition. The 'H' option is used to define the contents of the header or footer. The definition consists of literal text and escape codes. Since the definition will likely contain literal spaces, remember to enclose the definition within double quotes. The escape commands are case sensitive and literal text will be shown as entered. The escape sequences are described here: &fn Current filename and extension. The filename is shown in uppercase. No path is displayed. &fd#c File creation date in specified format where # is 1 to 5 and c is the delimiter character ('/', ',', or '.'). &ft#c File creation time in specified format where # is 1 to 4 and c is the delimiter character (':', ',', or '.'). &cd#c Current date in specified format where # is 1 to 5 and c is the delimiter character ('/', ',', or '.'). &ct#c Current time in specified format where # is 1 to 4 and c is the delimiter character (':', ',', or '.'). &pn# Current page number in specified format where # is the number of digits the page number will take up. The value must be in the range 1 to 9. The page number will be left padded with spaces. If you prefer zeros instead, precede the number with a zero. Example: &pn03. &li Initial line number on page. Page 10 SOURCE &lf Final line number on page. &h+ Turn on highlighting (using 10 high). &h- Turn off highlighting (using 10 high). &jl Left justify text. &jc Center justify text. &jr Right justify text. && Prints a literal ampersand character. Date formats: 1) mm dd yy ex. &fd1/ 07/31/92 2) dd mm yy ex. &cd2. 31.07.92 3) yy mm dd ex. &cd3, 92,07,31 4) dd Mmm yy ex. &fd4- 31-Jul-92 5) Month dd yyyy ex. &cd5, July 31, 1992 Time formats: 1) hh mm ss ex. &ct1: 15:45:21 2) hh mm ex. &ft2. 15.45 3) hh mm ss am ex. &ft3, 03,45,21 pm 4) hh mm am ex. &cd4: 03:45 pm Example header definition: '&h+File:&h- &fn&jr&h+Page:&h- &pn03' This definition results in the following text: File: filename.ext Page: 001 where the text 'File:' and 'Page:' are highlighted, 'filename.ext' is the actual filename of the file, and the page number is right justified on the page. Default is "File: ", filename, file date, file time, "Printed: ", date, time, "Page: ", page number. -i# Initial Line. The 'i' option allows you to specify the initial line number of the file to output. This would be used to print only a block of code instead of the whole file. The 'i' must be followed by a positive number. Specifying zero means the first physical line. It is likely that 'i' would be used in conjunction with the 'f' option to print a specific range of text starting and finishing at the line numbers chosen. This option may not be used with the 'F' or 'I' options unless set to zero. Default is 'i0', the first line. -I# Initial Page. The 'I' option allows you to specify the final page number of the file to output. This would be used to print only a block of code instead of the whole file. The 'I' must be followed by a positive number. Specifying zero means the first physical page. It is likely that Page 11 SOURCE 'I' would be used in conjunction with the 'F' option to print a specific range of text starting and finishing at the page numbers chosen. This option may not be used with the 'f' or 'i' options unless set to zero. Default is 'I0', the first page. -k[-] Highlighted Keywords. The 'k' option sets whether keywords within your programming code are highlighted or not. The 'k' may be followed by '-'. The 'k' option alone turns on highlighting, the minus turns it off. Only those words listed in the "keyword" section of a language definition are highlighted. For this option to work, SOURCE must know what language the file is written in. This is done by using the filename extension as defined in the SOURCE.LNG file or the 'x' option may be used to force a specific language. The highlighting method used is as defined in the SOURCE.PRT file for the selected pitch. Default is 'k', highlighted keywords on. -l{6|8} Line Spacing. The 'l' option specifies the number of lines per inch to print. The 'l' must be followed by a 6 or an 8. Ensure that the proper printer codes have been defined in the SOURCE.PRT file for the eight lines per inch option to work. Default is 'l6', six lines per inch. m Shareware Message. The 'm' option causes a full screen message to display about registering SOURCE. This command is only recognized if in SOURCE.CFG or as a global command line option. -n[-] Line Numbering. The 'n' option is used to specify whether line numbers will be shown or not. Line numbers are shown in the format specified in the 'N' option. The 'n' may be followed by '-'. The 'n' option alone turns on line numbering, the minus turns it off. Default is 'n', line numbering on. -N "beg#end" Line Number Format. The 'N' option specifies the size and format of line numbers. The value of # must be a number between 1 and 9. The terms "beg" and "end" represent literal text that may be shown before and after the line numbers. For example, if you want four digit line numbers within square brackets, you would specify the option as 'N[4]'. This would result in [ 1], [ 2], etc., being printed. Another example would be if you wanted to specify 'N04:', which is the default, and this would result in the line numbers being printed as 0001:, 0002:, and so on. Page 12 SOURCE The line numbers are left padded with spaces. If you prefer the number to be left padded with zeros, precede the number with a zero. For example: 'N4' will cause 1, 2, entering 'N04' will cause 0001, 0002, etc. Both the 'begin' and 'end' text are optional. If there is no 'end' text, the source code will be adjacent to the line number. To avoid this, you may wish to specify 'N"4 "'. The space inside the double quotes will print after each line number. Specifying a value for the number of digits that is too small for the number of lines in the file to be printed will result in the line numbers wrapping around. For example, if you specify N01 and have 19 lines, line 10 would show up as 0, and line 11 would become 1. This wrapping holds true for any size specified. If your code typically has less than 1000 lines, specify 3 for the value of #, less than 10,000 lines, specify 4. The default is 'N04:' which will produce 0001:, 0002:, etc. -o{l|p} Page Orientation. The 'o' option specifies the page orientation. This will probably only work on laser printers since most dot matrix printers cannot print in landscape. The 'o' must be followed by 'l' or 'p'. The 'l' indicates landscape (sideways) printing and the 'p' is portrait (normal). The landscape option requires that the 'landscape' field be filled in in the SOURCE.PRT file. Default is 'op', portrait. -p{p|e|c} Pitch. The 'p' option indicates the character pitch to print the files in. The 'p' must be followed by 'p' (pica or 10 cpi), 'e' (elite or 12 cpi), or 'c' (compressed using your printers compressed value, usually 15, 16.666, or 17). If your printer allows large pitch sizes such as 5 cpi, you could also use the compressed setting for this. See section 7 for more on setting the compressed pitch value. Default is 'pp', pica. -q[-] Page Count Query. The 'q' option causes SOURCE to pre-scan each file and return the number of lines in the file and how many pages (excluding any banner pages) are required to print it based on all other print options. You are then asked to confirm whether to print the file or not. Pressing 'Y' or 'y' will cause the file to be printed. Any other keystroke will prevent the file from being printed. Pressing the [Esc] key will cause SOURCE to terminate. The 'q' may be followed by '-'. The 'q' option alone turns on the print statistics, the minus turns it off. Page 13 SOURCE Turning on the 'q' option automatically turns on the 'v' (print verification) option. Default is 'q', show page count. -r "output" Redirect. The 'r' option allows you to redirect the output to a file or other device such as the screen or another printer port. The 'r' must be followed by a filename or device name. The file or device name is not case sensitive. Example devices would be "LPT1", "PRN", or "COM2". You may even specify "CON" to send the output to the screen. When specifying a file, enter as much of the full path name as is needed. You may specify another drive or directory. You may specify wildcards in the filename. This allows you to do things like: SOURCE *.c -r*.prn This will result in each 'C' file being output to its own '.prn' file. The wildcards act just like they would in a DOS COPY command. If the specified file already exists, SOURCE will act as specified by the 'a' option. If more than one file being printed is to be redirected to the same output file, the latter ones will be appended to the first. Default is 'r lpt1', output to printer port one. -s{1|2} Column Count. The 's' option specifies the number of columns to print per page. The 's' must be followed by a 1 or a 2. It is recommended that compressed landscape printing be used with two columns. Using two columns in 10 pitch, portrait print, leads to some difficult to read output. Default is 's1', one column per page. -S[-] Show Column Separator. The 'S' option is used in conjunction with the 's' option. When you specify more than one column, the columns are separated by a vertical line. The 'S' option allows you to tell SOURCE whether to display this vertical line or not. The 'S' may be followed by '-'. The 'S' alone turns the line on, the minus turns it off. Default is 'S', line on. -t# Tab Stop Size. The 't' option allows you to specify how many spaces a tab character should be printed as. The 't' must be followed by a number from 0 to 8. Specifying zero is equivalent to having all tabs removed from the file. Default is 't8', eight spaces per tab stop. -u "name" Use Named Configuration. The 'u' option is used to specify a named configuration from within the Page 14 SOURCE SOURCE.CFG file. See section 6.2 for more on named configurations. The 'u' must be followed by a configuration name that has been defined in SOURCE.CFG. The name is not case sensitive. No default. -v[-] Print Verification. The 'v' option is used to ask the user to confirm the printing of each file. This would most likely be used in conjunction with wildcards in the filename. For example, you want to print all but one or two files in a directory. Specify "*.*/v" on the command line to select all the files. SOURCE will then ask you to confirm the printing of each file. Just press 'Y' or 'y' for the ones you want to print. Any other key stroke other than 'Y' or 'y' will be the same as no. Pressing the [Esc] key will cause SOURCE to terminate. The 'v' option is automatically turned on when the 'q' option is turned on. The 'v' option may be followed by '-'. The 'v' option alone turns on the print verify, the minus turns it off. Default is 'v-', do not ask about each file. -w# Whitespace. The 'w' option is used to specify the number of blank lines printed between the header/footer and the first/last line of text of the file on the page. The 'w' must be followed by a value between 0 and 9. Specifying zero will result in no blank space. See the 'h' and 'H' options for more on user definable headers and footers. Default is 'w1', one line. -x "language" Force Language. The 'x' option allows you to tell SOURCE the language of a file regardless of its extension. This option is useful only when using the 'b', 'c', or 'k' options (block grouping and comment or keyword highlighting). The 'x' must be followed by a language name defined in SOURCE.LNG. The name is not case sensitive. For example, if you have a file with a 'bak' extension that really is a Pascal program, by following the file with the '-xPascal' option, SOURCE will treat the file as Pascal code so comments and blocks print correctly. This assumes that there is a definition for 'Pascal' in the SOURCE.LNG file. Default is none (use extension). -y[-] Sound. The 'y' option determines whether the speaker will emit a bell or buzz sound when prompts or errors occur. This option is not recognized as a local option. The 'y' may be followed by '-'. The 'y' option alone turns on sound, the minus turns them off. Default is 'y-', sound off. Page 15 SOURCE -z "list" Ignore These Extensions. The 'z' option is used to tell SOURCE what files to ignore during wildcard expansion. For example, if you run SOURCE with "*.*", you will have a mess at your printer when it tries to print executables and object code! You could specify the 'v' option each time and say no to files with ".exe" or ".obj" extensions, or you could use the 'z' option to tell SOURCE to automatically ignore the ".exe" and ".obj" extensions every time. The syntax for the 'z' option is the list of extensions (including the period) between a pair of double quotes (if you place a space between each). The list is not case sensitive. To continue the example, specify the 'z' option as 'z ".exe .obj"'. You may specify as many extensions as you like as long as all are specified with one 'z' option. Using two 'z' options will cause the first one to be ignored. Default is 'z ".exe .com .sys .obj"'. Below is a list of the command line options broken out by category. Page Format: -p Pitch. -o Page Orientation. -s Column Count. -S Show Column Separator. -l Line Spacing. -g Graphics. -e Escape Codes. Page Layout: -t Tab Stop Size. -n Line Numbering. -N Line Number Format. -h Header Page. -H Header Definition. -w Whitespace. -B Banner. Language Features: -b Block Grouping. -c Comment Highlighting. -k Keyword Highlighting. -x Force Language. File Selection: -i Initial Line. -f Final Line. -I Initial Page. -F Final Page. -q Page Count Query. -v Print Verification. Page 16 SOURCE -z Ignore These Extensions. Output: -r Redirect. -a Append/Overwrite. -d Select Printer. Miscellaneous: -? Help. -y Sound. -u Use Named Configuration. 6 SOURCE.CFG The SOURCE.CFG file is used to store groups of configuration options that may be used by SOURCE. Among these groups are a set of default options. These default options are seen by running SOURCE with the '-?' global option. These default options, as initially defined, are actually the same defaults hard coded within SOURCE itself. 6.1 SOURCE.CFG Location SOURCE.CFG is actually not needed. If SOURCE can not find SOURCE.CFG, it will fall back on the built in defaults and continue to work fine. SOURCE.CFG can be located in many different places. By default, you should place a copy in the same directory as SOURCE.EXE (from now on referred to as the SOURCE directory). With this setup, running SOURCE from any directory will cause SOURCE to use the defaults defined in SOURCE.CFG in the SOURCE directory. In addition to placing SOURCE.CFG in the SOURCE directory, you may also place other copies in any other directory you wish. For example, you have a 'prog' directory on your hard disk. If you place another copy of SOURCE.CFG in 'prog' and run SOURCE while your default directory is 'prog', SOURCE will use the SOURCE.CFG file in the 'prog' directory instead of the SOURCE directory. By tailoring the SOURCE.CFG file to the files in 'prog', you can minimize the amount of command line options you need to specify. The whole point to allowing this kind of flexibility is that you might be working on different projects that require different printing styles. By placing tailored SOURCE.CFG files in the different directories, you can easily accomplish the diverse printing needs. 6.2 Named Configuration Options If you have looked at the contents of SOURCE.CFG, you will notice that there seems to be more than just defaults defined in there. SOURCE.CFG can actually store up to fifty sets of configuration options. The first of which (as supplied) is the default options. These different sets of options are referred to as named configuration options. The supplied defaults are actually a named configuration option titled 'Default'. SOURCE Page 17 SOURCE automatically looks for 'Default' and loads the options in if found. In addition to the 'Default' setup, you may define 49 more of your own design. If for some reason you do not want the defaults loaded, rename 'Default' to something else. You may then refer to the defaults explicitly by using the 'u' option on the command line. See section 5 for more information on selecting named configurations from the command line using the 'u' option. The idea behind named configurations allows you to define a commonly used, but cumbersome, set of configuration options into a simple, single command line option. A common use for them might be on a LAN where each user has their own favorite set of defaults. The SOURCE.CFG file could contain one set for each user using their name or initials to name the options. On the command line, simply specify "-u name" and all the options defined as "name" in SOURCE.CFG will be used. Another circumstance could be to use named options when you are using SOURCE with multiple printers. If you have "printer1" on "lpt1" and "printer2" on "com3", you could add two named configurations, "p1" and "p2". "p1" would have '-d printer1 -r lpt1' and "p2" would have '-d printer2 -r com3'. You could also add the 'g' option if one printer could print the IBM line drawing characters and one could not. Typing 'source -u p1' at the command line is easier than 'source -d printer1 -r lpt1 -g'. One other possibility would be if you wished to print source code in different languages in different formats. The named set of options may also contain a 'u' option. This allows for nested definitions. As an example, let's say you have two named configurations, "name1" and "name2". If "name1" contains '-u name2', "name1" will pull in the options defined in "name2". The result of using "name1" will be all the options in "name1" and all the options in "name2" being used. 6.3 SOURCE.CFG Format The format of the SOURCE.CFG file is simple. A named configuration begins with the key word "begin" followed by a name. This name can contain any characters you can type at the DOS prompt. I recommend descriptive names that indicate what the options represent. Spaces are not allowed in the name. The only limit is the full name must be 20 characters or less. After the "begin" line, enter any set of options you like. There are two ways of entering the options. The easiest to read is to place one command per line. Each command must be preceded by a hyphen. Example: -t3 -pp The second method allows more than one command per line. This is identical to global options on the command line. Simply separate the commands by at least one space. Again, each command must be preceded by a hyphen. Example: Page 18 SOURCE -l8 -s2 You may also enter the commands using any combination of the two methods. Example: -q -i5 -f100 -z ".exe .obj .sys" After all options have been specified, enter the key word "end" on a line by itself to signal the end of the named definition. You may define up to 20 named configurations. A full definition would look as follows: begin Test -q -F2 end 6.4 Commenting SOURCE.CFG You may place comments in the SOURCE.CFG file by beginning a line with a semicolon ( ; ). All text on that line will be ignored by SOURCE. Do not place comments on lines with options. The comment must go on a line by itself. Example: ; This is a valid comment -b -c ; This is not a valid comment - must be on own line 6.5 Modifying SOURCE.CFG I recommend you modify the 'Default' named option in SOURCE.CFG to suit your most common needs. This will result in having to specify little on the command line other than the filenames to print. If you need to print a file slightly different one time, specify only the options required for the difference. Add other named options for other commonly used configurations like those mentioned above. This allows you to use very different print formats with minimal command line typing. One common change to the defaults would be to specify a different printer port. Initially, SOURCE assumes printer port one, LPT1:. If you are using a serial printer on a COM port or another printer port, change the default setting for the 'r' option. Replace the word 'lpt1' with 'com1' or 'lpt2' or whatever is appropriate for you. 7 SOURCE.PRT This file allows you to define any printer configuration you may have. Only one copy of SOURCE.PRT is used and this must reside in the same directory as SOURCE.EXE. This file is required and SOURCE will not run if not found. SOURCE.PRT can contain printer definitions for up to 20 different printers, though I doubt you will ever need that many. Once you define your printer, you can delete all other definitions if you like. However, if you have more than one printer, leave all the necessary definitions. Page 19 SOURCE 7.1 Default Printer If you have more than one printer defined, you must make one the default. This can be done automatically the first time you run SOURCE. If you would like to change that default at a later time, you must manually edit the SOURCE.PRT file. To make a printer the default, place the keyword "default" after the printer name. Example: 'begin HPLJII+ default'. If you specify more than one default, the fist one will be chosen. Remember you can use the 'd' option to select a printer other than the default if needed. If you only have one printer defined in SOURCE.PRT you do not need to specify the keyword "default". 7.2 SOURCE.PRT Format Similar to SOURCE.CFG, each definition in SOURCE.PRT begins with the keyword 'begin' followed by a name. The name may be made up of any characters you can type at the DOS prompt up to 20 characters. The name may not contain spaces. The printer definition ends with the keyword 'end' on a line by itself. In between are the lines specifying your printer setup. The syntax of each line is a field name, a colon, and the value you enter for that field. Each line can contain only one field. For those fields that require a printer escape sequence, you can enter the codes as literal characters or by entering the decimal value in square brackets. You may also enter the code as a combination of both. For example, the reset code on a Hewlett Packard Laser Jet is [Esc]E. You might not be able to enter a literal escape character in your editor. The solution is to use the decimal value in square brackets. [Esc] is ASCII value 27. The 'E' can be entered literally. The two codes together would be entered into the reset field as: [27]E. Since the square brackets are being used as special characters by SOURCE, you may not enter them as literal characters in the printer code. If your code needs the characters '[' or ']', enter the decimal value in square brackets. The left bracket '[' becomes [91] and the right bracket ']' becomes [93]. The value inside the bracket must be a decimal number from 1 to 255. If an ASCII character of 32 (space) is required, you may enter a literal space or [32]. A list of the fields and a description of each is as follows: page width: This field is the physical page width in inches. This will typically be 8.5 for standard letter sized paper. If you are using wide computer paper, this could be 14. This field is required. page length: This field is the physical page length in inches. Normal letter size paper would be 11. Legal size paper would be 14. This field is required. top margin: Indicates the top margin in inches. The first printed line will be placed this far from the top of the page. A standard half inch margin would be Page 20 SOURCE .5. This value must be greater than or equal to the top edge. This field is required. bottom margin: Indicates the bottom margin in inches. The last line printed will be this far from the bottom of the page. This value must be greater than or equal to the bottom edge. This field is required. left margin: This is the left margin in inches. The left most characters will be this far from the left edge of the paper. This value must be greater than or equal to the left edge. This field is required. right margin: This is the right margin in inches. The right most characters will be this far from the right edge of the paper. This value must be greater than or equal to the right edge. This field is required. top edge: The top edge is used to define the physical limitation of the printer to print at the top of the page. Laser printers typically are set with a half inch limit at the top. By entering .5 here, the margin specified in 'top margin' will come out correctly. This field is required. bottom edge: The bottom edge is used to define the physical limitation of the printer to print at the bottom of the page. Laser printers typically are set with a half inch limit at the bottom. By entering .5 here, the margin specified in 'bottom margin' will come out correctly. This field is required. left edge: The left edge is used to define the physical limitation of the printer to print at the left edge of the page. Laser printers typically cannot print on the first quarter inch of the left edge. By entering .25 here, the margin specified in 'left margin' will come out correctly. The exact value entered may be slightly different. Try .2 or .3. Experiment with the proper value to set your printer up correctly. This field is required. right edge: The right edge is used to define the physical limitation of the printer to print at the right edge of the page. Laser printers typically cannot print on the last quarter inch of the right edge. By entering .25 here, the margin specified in 'right margin' will come out correctly. The exact value entered may be slightly different. Try .2 or .3. Experiment with the proper value to set your printer up correctly. This field is required. Page 21 SOURCE 10 pitch: This field is used to enter the escape sequence used by your printer to print text at ten characters per inch. Enter the sequence exactly as shown in your printer manual including case. 12 pitch: This field is used to enter the escape sequence used by your printer to print text at 12 characters per inch. Enter the sequence exactly as shown in your printer manual including case. This field is required to use this feature. compressed: This field is used to enter the escape sequence used by your printer to print text in compressed mode. This is usually 15, 16.66, or 17. You may even enter the code for enlarged print such as 5 cpi. Enter the sequence exactly as shown in your printer manual including case. This field is required to use this feature. comp size: This field is used to specify the characters per inch your printer will print while in compressed mode. Typically this value will be 15, 16.666, or 17 (or even 5 for enlarged print). This field is required to print in compressed mode. underline on: This is the printer escape sequence for turning underlining on. This is used only by the page header/footer. This field is required to use this feature. If you do not want the header underlined, leave this field blank. underline off: This is the printer escape sequence for turning underlining off. This is used only by the page header/footer. This field is required to use this feature. If you do not want the header underlined, leave this field blank. 10 high on: This is the printer escape sequence used to print comments when the 'c' option is used and the 'p' option was set to 10. This code could be almost anything your printer can do. Examples are bold, underline, and italic. DO NOT use a code that prints in a different size font like expanded or double height. This will cause the file to print incorrectly. Whatever code is used must not change the current print size. This field is required to use this feature. 10 high off: This is the printer escape sequence used to turn off the code used by '10 high on'. This field is required to use this feature. 12 high on: This is the printer escape sequence used to print comments when the 'c' option is used and the 'p' option was set to 12. This code could be almost Page 22 SOURCE anything your printer can do. Examples are bold, underline, and italic. DO NOT use a code that prints in a different size font like expanded or double height. This will cause the file to print incorrectly. What ever code is used must not change the current print size. This field is required to use this feature. 12 high off: This is the printer escape sequence used to turn off the code used by '12 high on'. This field is required to use this feature. comp high on: This is the printer escape sequence used to print comments when the 'c' option is used and the 'p' option was set to your compressed value. This code could be almost anything your printer can do. Examples are bold, underline, and italic. DO NOT use a code that prints in a different size font like expanded or double height. This will cause the file to print incorrectly. What ever code is used must not change the current print size. This field is required to use this feature. comp high off: This is the printer escape sequence used to turn off the code used by 'comp high on'. This field is required to use this feature. init: This code is sent to the printer before the first file is printed. This should contain all required printer initialization codes to setup your printer. Examples would be the initialize printer code, character set selection (not pitch size), and print quality (draft, NLQ, etc.). There should be nothing in here for selecting pitch or page orientation since this will be done using the other codes specific to those settings. This is not required. reset: This code is sent to the printer after the last file is sent. This can be blank. This may be used to place the printer back into the mode it was prior to the "Init" code being sent. This is not required. portrait: This is the code sent to the printer to set the paper orientation to portrait - the usual way the page is set. This only applies to laser printers since dot matrix printers cannot print any other way using straight text printing (as opposed to graphics). This must be filled in if your printer supports portrait and landscape printing. landscape: This is the code sent to the printer to set the paper orientation to landscape - sideways printing. This only applies to laser printers Page 23 SOURCE since dot matrix printers cannot print landscape without using graphics. This must be filled in to make use of the landscape printing feature. 6 lpi: This code is used to print the file at six lines per inch. This is the usual default for all printers. If your printer does not support eight lines per inch than you may leave this blank, otherwise this is required. 8 lpi: This code is used to print the file at eight lines per inch. If your printer does not support eight lines per inch than you may leave this blank, otherwise this is required to use the feature. There are many relationships between the values placed in the above fields. The sum of the top and bottom margins must be less than the page length. The sum of the left and right margins must be less than the page width. All margins must be greater than or equal to their corresponding edge. If you only have 10 pitch printing, you may leave all three pitch codes blank. If you can only print at six lines per inch, you may leave both the six and eight lines per inch codes blank. Certain combinations of print options do not work together on some printers. For example, Hewlett Packard laser jet printers will not print bold or italic while in compressed print. This is why there are separate highlight codes for the different pitch sizes. This allows you to specify bold or italic for 10 and 12 pitch and underlining for compressed printing. 7.3 Modifying Your Printer As delivered, the SOURCE.PRT file has only a few basic printers within it. These may not fit your printer completely if at all. To take full advantage of your printer's abilities, you can edit SOURCE.PRT by placing an entry for your printer within it. To do so, either reuse an existing entry that is similar to your printer or copy the 'Generic' definition and rename the copy to match your printer name. Once you have this done, open up your printer's reference manual to the section that describes all the features and their associated escape sequences. Enter the codes you need into the proper fields and you will be ready to go. It may take some trial and error to get everything perfect, but it can be done. 8 SOURCE.LNG SOURCE.LNG contains the definitions for the language support features of SOURCE. The two options are comment highlighting and code block grouping or tracing. The SOURCE.LNG file details what makes a comment, a literal string and character, and what represents a code block. 8.1 SOURCE.LNG Location Page 24 SOURCE SOURCE.LNG is not a required file. If SOURCE can not find SOURCE.LNG, it will ignore the use of the b and c options and continue to work fine. SOURCE.LNG can actually be located in many different places. By default, you should place a copy in the same directory as SOURCE.EXE (from now on referred to as the SOURCE directory). With this setup, running SOURCE from any directory will cause SOURCE to use the definitions in the SOURCE.LNG in the SOURCE directory. In addition to placing SOURCE.LNG in the SOURCE directory, you may also place other copies in any other directory you wish. For example, you have a 'prog' directory on your hard disk. If you place another copy of SOURCE.LNG in 'prog' and run SOURCE while your default directory is 'prog', SOURCE will use the SOURCE.LNG file in the 'prog' directory instead of the SOURCE directory. By tailoring the SOURCE.LNG file to the files in 'prog', you can work with different dialects of the same language. The whole point to allowing this kind of flexibility is that you might be working on different projects that require different language definitions. By placing tailored SOURCE.LNG files in the different directories, you can easily accomplish the diverse needs. 8.2 SOURCE.LNG Format The format of SOURCE.LNG is similar to the other support files. You begin a language definition with the keyword 'beginlang' followed first by the name of the language and then a list of filename extensions associated with the language. The language name can be any characters you can type at the DOS prompt. The name cannot contain spaces and may be up to 20 characters long. The list of extensions are used to tell SOURCE to treat any file with the given extension as a file of that language. An example would be: 'beginlang C .c .h'. This defines a language called "C". Any file with the extension ".c" or ".h" would be treated as a "C" file. You may specify up to 10 extensions per language. The second line of the definition is a list of legal characters that may be found in identifiers and keywords. Identifiers include variables and labels within a program. These characters are used to tell SOURCE how to discern between to words in a program. Most languages allow letter and numbers. Some also allow some puncuation like underscores. See your language reference. It should detail the allowable characters. The list of characters must be contiguous and on one line with no spaces. You only need to specify either lower or upper case letters, not both. The language definition is completed with the keyword 'endlang' on a line by itself. This may be followed by the keyword 'case' to indicate that the language is case sensitive and/or 'part' to indicate that keywords only need to match partially. This is explained in detail below. Any other keywords, or none at all, indicate that the language is case independent and keywords Page 25 SOURCE require a full match. Example: 'endlang case' terminates the language definition and specifies case dependency. 'endlang' or 'endlang nocase' indicate the end of a case independent language. The SOURCE.LNG file may contain up to twenty language definitions. You only need those for which you have use, so feel free to delete unneeded languages from the supplied SOURCE.LNG file. 8.3 Commenting SOURCE.LNG You may place comments in the SOURCE.LNG file by beginning a line with a semicolon (;). All text on that line will be ignored by SOURCE. Do not place comments within a language definition, only before the 'beginlang' line or after the 'endlang' line. 8.4 Defining Language Specific Features 8.4.1 Comments After the 'beginlang' line, you specify how comments are defined. This begins with the line ':comment:'. After the ':comment:' line, you specify three lines. The first line is the begin comment command, the second is the end comment command. The third line contains a number from zero to 80 or the letter 'B'. If a number is specified, it indicates the column that the begin comment command must begin in. A zero indicates that the comment may begin in any column. If the letter 'B' is specified, it means that the begin comment marker may begin in any column but mst be the first non-whitespace character on the line. An example for the 'C' language would be: :comment: /* <== Begin comment */ <== End comment 0 <== Comment may be in any column You may specify more than one comment. For example, Turbo Pascal allows the following: :comment: { } 0 (* *) 0 For languages such as BASIC where comments are terminated by the end of line, specify the begin command on the first line and leave the second line blank. Example: :comment: REM <== This is a blank line Page 26 SOURCE 0 One of the few examples of specifying a non-zero column number would be for FORTRAN. Comments in FORTRAN are specified by placing a 'C' in column one. The definition for this would be: :comment: C <== Comments begin with a C <== Terminated by end-of-line 1 <== 'C' must be in column one An example of using the 'B' column position is dBASE. The 'note' and '*' comment markers used for comments must be the first characters on the line (not necessarily column one). The definition would be: :comment: * <== Comment begins with '*' <== Terminated by end-of-line B <== * must be first character note <== Comment begins with 'note' <== Terminated by end-of-line B <== 'n' must be first character Since blank lines are interpreted as part of the syntax, you may not leave blank lines within a language definition in the SOURCE.LNG file unless it is required as above. You may define up to 7 comment marker pairs per language. 8.4.2 String and Character Literals After defining the comments, you define what makes up literal strings and characters. This is done just like comments. You begin with the line ':string:'. After this line, you enter two lines per string or character. The first line contains the delimiter used to begin and end a literal string or character (typically a single or double quote). The second line specifies an escape sequence. This is the sequence (usually one character) used to allow the delimiter character to be used literally within a string or as a character. 'C' is a good example of this. Strings are set in double quotes. To place a double quote within a string, you must precede the double quote with a backslash ("He said \"Hello\""). The definition would be as follows: :string: " <== String Delimiter \ <== Escape Sequence Characters in 'C' are similar. Literal characters are defined by single quotes. To assign a literal single quote in 'C', you precede the literal quote with a backslash ('\''). The definition would be: :string: ' <== Character Delimiter Page 27 SOURCE \ <== Escape Sequence For languages such as Pascal where strings are defined by single quotes and a literal single quote is specified by two single quotes ('It''s mine'), simply place the following definition: :string: ' <== String & Character Delimiter ' <== Escape Sequence For languages such as BASIC which do not allow you to place the string delimiter within the string, you would leave the second line blank. You may declare up to five pairs of delimiters per language. The full string definition for 'C' would be: :string: " \ ' \ 8.4.3 Blocks After specifying the string definition, you must define what commands make up blocks. The keywords defined here are used with the 'b' option to allow block grouping to work. The definition begins with the keyword ':block:'. Following are two lines per block. The first line is the begin block command and the second line is the end block command. For 'C', this is easy because all blocks are marked the same. Blocks begin with a left curly brace and end with a right curly brace. The definition would be: :block: { } For languages like Pascal, you may have numerous block pairs. Example: :block: begin end record end case end repeat until For most languages, the keyword used to define a block must be entered in its entirety. You can't specify beg Page 28 SOURCE ... end in Pascal for example. You must enter the whole keyword. A counter example to this is the dBase programming language. dBase allows you to enter only the first four letters of each keyword. A 'while' loop could be entered as: do while do whil ... or ... enddo endd For SOURCE to work with a language such as this, you must specify the "part" or "partial" keyword after the "endlang" keyword at the end of the language definition followed by the number of characters needed. SOURCE will use this number when comparing the block specified in SOURCE.LNG with words found in the source file. If the number of characters required is 4, and the keyword is 'endif', SOURCE will recognize 'endi' and 'endif', but not 'end', 'endis' or 'endif1'. If the 'part' keyword is not specified, SOURCE will treat the comment and block keywords in SOURCE.LNG as the full keyword that must be found in the file being printed. 8.4.4 Keywords After specifying the block definition, you must define those keywords that you would like highlighted when the 'k' option is active. The definition begins with the keyword ':keyword:' and is followed by one keyword per line. The keywords may have spaces in them. The words may be entered in any order. You may enter any words you like. The idea is to highlight reserved words so you can pick out variables and function names easier. If you have certain functions or other words you would like highlighted, simply add them to the list. A partial list for 'C' would be: :keyword: auto break case char const continue . . . If the language is case dependant, ensure the keywords are entered in the proper case. If case independant, the entered case is irrelevant. If the language supports partial keyword matching (like dBASE), you must still enter the entire keyword. SOURCE will highlight the entire keyword found in the program. For example, if you have the keyword 'endtext' in the language definition, SOURCE will highlight 'endt', 'endte', 'endtex', or 'endtext' in the program if the 'part 4' definition was placed at the end of language definition. Page 29 SOURCE It is important that the keywords entered into the definition only contain those characters entered on the second line of language definition. If other characters are used, the keyword may not be highlighted properly. You may define up to 400 keywords per language. 8.4.5 Complete Definition Now that you have seen each part of the definition, here is a full definition as it would appear in SOURCE.LNG for 'C'. beginlang C .c .h abcdefghijklmnopqrstuvwxyz0123456789_ <== Valid characters :comment: /* */ 0 <== Any column :string: " \ ' \ :block: { } :keyword: auto break case char const continue . . . <== There are more, but you get the point endlang case For dBase, the full definition would be: beginlang dbase .prg :comment: * <== Comments end with end-of-line B <== Any column, but first character && <== Comments end with end-of-line 0 <== Comment begins in any column note <== Comments end with end-of-line B :string: " <== No double quotes in strings :block: do case endcase do while Page 30 SOURCE enddo if endif text endtext :keyword: accept additive alias all all like append append from . . . <== There are more, but you get the point endlang part 4 8.5 General Points Some points to keep in mind when defining a language. If you have more than one language with the same extension, SOURCE will choose the last. To override this, you can use the 'x' option on the command line to explicitly choose the language you really need. While defining a comment or a block, you may not define two or more pairs that begin with the same keyword, regardless of the ending keyword. However, you may define any number of pairs that have the same ending keyword as long as the beginning keywords are unique. This should never be a problem because two blocks with the same beginning keyword would lead to a rather ambiguous syntax. When defining blocks for the language, be careful with statements using variable syntax. A good example is the 'IF' statement in some BASICs. The syntax can be: 1) IF condition THEN statement [ELSE statement] or 2) IF condition THEN statements [ELSE statements] ENDIF DO NOT specify in your block definitions 'IF' - 'ENDIF' because if SOURCE encounters the first syntax, the line will never terminate because it will not find the 'ENDIF'. Unfortunately, there is no solution to this. The only downside is that you will not get trace lines for your IF statements. If you know for a fact that you did not use the first syntax, then go ahead and specify the 'IF' - 'ENDIF' block. 9 Network Support Page 31 SOURCE SOURCE currently has limited network support. The support offered at this time allows you to define an environment variable called "USER". SOURCE will determine the value of "USER" and load the named configuration, from SOURCE.CFG, of the same name. This configuration option will be used as the default set of options instead of "Default". This setup allows SOURCE to be installed on a network server. Each user would add a line like: set USER=<name> to their "autoexec.bat" file. The <name> would be a unique identifier for that person. This could be a last name or initials. The SOURCE.CFG file in the SOURCE directory would contain a named configuration for each user on the network. Care must be taken to limit write access to the common SOURCE.CFG file. You may wish to allow only the network supervisor to update this file to prevent problems with each user adding their options. Data will get lost if two people try editing at the same time. If SOURCE cannot find a named configuration with the same name as the value of "USER", SOURCE will fall back on the "Default" named configuration. Having the environment variable defined is slightly different from using the '-u <name>' command line option. When using the environment variable, the matching named configuration is used in place of the default named configuration. When using the 'u' option, the matching named configuration is loaded in addition to the default named configuration. 10 Definition of Shareware Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and continue using it, you are expected to register. Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights, with a few specific exceptions as stated below. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribution. The author specifically grants the right to copy and distribute the software, either to all and sundry or to a specific group. For example, some authors require written permission before a commercial disk vendor may copy their Shareware. Shareware is a distribution method, not a type of software. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware. The Shareware system makes Page 32 SOURCE fitting your needs easier, because you can try before you buy. And because the overhead is low, prices are low also. Shareware has the ultimate money-back guarantee -- if you don't use the product, you don't pay for it. 11 Disclaimer - Agreement For Trying SOURCE Users of SOURCE must accept this disclaimer of warranty: "SOURCE is supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author assumes no liability for damages, direct or consequential, which may result from the use of SOURCE." SOURCE is a "shareware program" and is provided at no charge to the user for evaluation. Feel free to share it with your friends, but please do not give it away altered or as part of another system. The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products. If you find this program useful and find that you are using SOURCE and continue to use SOURCE after a reasonable trial period, you must make a registration payment to Rick Maddy. The registration fee will license one copy for use on any one computer at any one time. You must treat this software just like a book. An example is that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Just as a book cannot be read by two different persons at the same time. Site-License arrangements may be made by contacting Rick Maddy. You are encouraged to pass a copy of SOURCE along to your friends for evaluation. Please encourage them to register their copy if they find that they can use it. All registered users will receive a copy of the latest version of SOURCE in your name, printed documentation, a quick reference card, upgrade notices and discounts, and customer support. 12 Registering You may use SOURCE for a free 30 day trial period. If you continue to use SOURCE after the 30 day trial period, you are required to register your copy of SOURCE. When you register SOURCE you will be sent a disk with the latest version of SOURCE in your name, printed documentation, a quick reference card, upgrade notices and discounts, and customer support. The cost of registration is $20.00. Page 33 SOURCE You can order directly from Rick Maddy by completing the registration form and mailing it and a check to: Rick Maddy 7111 Kurth Lane Seabrook, MD 20706 The registration form is at the end of this document and in a separate file called register.txt. If you have any questions or comments, feel free to call Rick Maddy at (301) 794-8466 or leave a mail message on Compuserve at 76460,1601. 13 Future Enhancements I have a few ideas for making SOURCE an even better utility. Here is a brief list: - Full screen interface to replace command line. - Full screen programs for editing printer, language, and configuration files. - Windows 3.1 version. - Optional log file of all printed files. - Expanded file selection (i.e. date range). - Print files in sorted order by name, size, date, etc. - Expanded network/multi-user support. I am open to any comments or suggestions for improvements or additions to SOURCE. Please drop me a line. 14 Acknowledgements I would like to thank the following people for all there help in finishing this program: - Scott Sidel for his help with making this program easier to use and writing this documentation. - Robert Harvey and William Moussiaux for beta testing SOURCE. - All the kind people who answered my questions about OS/2 on Compuserve. 15 Release History 10/14/92 Version 1.01 - Original public release. 10/21/92 Version 1.1 - Fixed comment highlighting bug. If two comment markers were found one character apart, SOURCE picked the one defined first in SOURCE.LNG instead of the first on the line. Example in C: Page 34 SOURCE //*** Comment *** SOURCE found the /* marker and then the // marker. Since the starting position was only one character apart, SOURCE chose the /* marker since it was defined first. - Added additional comment support by adding the 'B' position specifier. This allows you to define a comment to be anywhere on the line as long as it is the first non- whitespace character found. Example in dBASE: * This is a comment A = B * C The '*' is a comment marker. The entire first line is a comment. The second line does not contain a comment since the '*' is not the first character. Version 1.01 would have highlighted the '*' and the 'C' on the second line since the comment position was specified to be 0, any position. - Fixed Append/Overwrite mode with numerous files. When specifying overwrite mode with a list of files, the output of each file overwrote the output of the previous file. Now, each subsequent file's output is appended to the first file's output. - Fixed a bug that caused comment highlighting to always be on if keyword highlighting was on. - Fixed a bug that caused keyword highlighting to work incorrectly if comment highlighting and block tracing were turned off. - Added a print statement explaining which language SOURCE will default to for an extension defined in more than one language. 10/30/92 Version 1.2 - Changed 'B' option to allow user to specify whether the letters of the banner are made up of the specific letter or asterisks. - Changed how SOURCE performs query or verify so all files are checked before any printing is done. - Enhanced a few error messages so they are more clear. - Enhanced the 'r' option to allow wildcards when redirecting to a file. The functionality is now equivalent to the DOS COPY command. 11/07/92 Version 1.3 - Changed how partial keyword matching is implemented. This change now requires that the full keywords be listed in Page 35 the SOURCE.LNG file for languages like dBASE and Clipper. This makes their definition like all other languages except for the 'part #' after the 'endlang' line in the definition. This change will lower the number of extraneous keyword highlighting occurrences. - Fixed a small bug that only occured if you had a [91] or [95] in the 8 lpi line of a printer definition. - Fixed a small bug that prevented SOURCE from reporting an error if the printer code was too long for a given attribute. SOURCE REGISTRATION Remit to: From: Rick Maddy Name:__________________________________ 7111 Kurth Lane Company:_______________________________ Seabrook, Md 20706 Street:________________________________ (301) 794-8466 City:__________________________________ State/Zip:_____________________________ Compuserve Id: Phone:_________________________________ 76460, 1601 Name to register in: (Up to 40 characters) _______________________________________ Qty: Unit Price Total: ____ SOURCE Software $20.00 ________ Specify Disk Size: _____ 5 1/4" _____ 3 1/2" Current Version of Source:______________________________________