PROGRAMMER'S PROGRAMMER'S PROGRAMMER'S FILE FILE FILE PRINTER PRINTER PRINTER Version 2.01 Version 2.01 Version 2.01 Programmer's File Printer Programmer's File Printer Programmer's File Printer I I INTRODUCTION NTRODUCTION NTRODUCTION Thank you for using Programmer's File Printer. The author hopes that you'll find it a useful addition to your Windows 3 applications and that it will make work on Windows even easier. This manual covers all the aspects of Programmer's File Printer in detail, and you can use it to as a reference. You'll find, though, that the program is quite intuitive to use, as it follows the standard Windows methods of doing things, so you shouldn't need to read much below in order to use it. The author is interested to hear any reports about how you find the program. Your comments and suggestions for further development are welcome, as are reports of any problems. You'll find details of the author's electronic mail address below. Abstract Abstract Abstract Programmer's File Printer is a Windows 3 application that lets you print text files such as program listings, and produce hexadecimal dumps of binary files. You have full control over the format of a text file listing: you can specify - Whether lines are numbered - Whether pages have headers - Whether long lines are wrapped or truncated - How wide a tab stop is as well as selecting the type face and type size. For both text listings and hex dumps, you can choose to print either the whole file, or only a part. You can, if you wish, specify a set of listing attributes to be used for all files of specific types, so that, for instance, you could list all .c .c .c files in one way, and .dat .dat .dat files in another. You can also over-ride the details on an individual file basis for exact control. For single-sheet printers that stack pages the "wrong" way, you can specify that files are to be printed in reverse page order. Distribution and Use Distribution and Use Distribution and Use Programmer's File Printer is Copyright (c) 1991 Alan Phillips. It may be freely used by individuals, educational institutions and charities; however use by commercial organisations is not permitted except with the prior written agreement of the author. The program may be stored in software archives or posted to Bulletin Board systems. Apart from reasonable media and handling costs, no charge may be levied for its distribution. The program should be stored with all the files that accompany its release Page Page Page 1 1 1 Programmer's File Printer Programmer's File Printer Programmer's File Printer by the author; however archive systems may repackage the files to suit their own storage conventions. Disclaimer Disclaimer Disclaimer Programmer's File Printer is offered on an as is basis. No guarantee of any sort is made or should be inferred as to its functioning, or to its suitability for any purpose. The author accepts no liability for any loss or damage whatsoever occasioned in connection with its use. This program is produced as a private activity by the author, unconnected with his employment by the University of Lancaster. The author welcomes comments and bug reports; but there is no commitment to add any new features, nor to address any problems that may be reported. Contacting the Author Contacting the Author Contacting the Author Comments and suggestions on Programmer's File Printer are welcomed. The author can be contacted by electronic mail; addresses are alan@uk.ac.lancaster alan@uk.ac.lancaster alan@uk.ac.lancaster JANET JANET JANET alan@lancaster.ac.uk alan@lancaster.ac.uk alan@lancaster.ac.uk Internet and BITNET Internet and BITNET Internet and BITNET alan%uk.ac.lancaster@ukc alan%uk.ac.lancaster@ukc alan%uk.ac.lancaster@ukc UUCP UUCP UUCP Page Page Page 2 2 2 Programmer's File Printer Programmer's File Printer Programmer's File Printer G G GETTING ETTING ETTING S S STARTED TARTED TARTED You can start to use Programmer's File Printer at once, since it has been set up to be useful even without configuration. Installing the program Installing the program Installing the program To install Programmer's File Printer, simply copy the pfp.exe pfp.exe pfp.exe, pfp.ini pfp.ini pfp.ini and pfp.hlp pfp.hlp pfp.hlp files into a directory on your path. You can then start it from Program Manager or from File Manager as any other application. Simple Use Simple Use Simple Use Programmer's File Printer can be used very simply, without the need for configuration. When you start it, you'll see the main window appear: this contains two list boxes on the left, one on the right, and a group of check boxes that are initially inactive. On the far left you'll see the Directories list. This shows you the names of sub-directories and drives, and you move around your disk by double-clicking entries here. The program will always select the directory that you were working in the last time you used it, provided that it still exists and is on a hard disk or a network. To the right of this is the Files list. Until you configure the program, you'll see the names of every file in the current directory in this list. If there are more files than can be shown you'll see a scroll bar on the right of the list that will let you move up and down. You select the files you want to print from this list. You can click on an entry to highlight it; you can add files to those highlighted by holding down CONTROL CONTROL CONTROL and clicking, or select a range by holding SHIFT SHIFT SHIFT and clicking. Once you have one or more files highlighted, you'll see the Select Select Select button become active. Clicking this will copy the names of the selected file into the list on the far right, the Files Selected To Print list. You can move around your disk and add files to the list on the right as you please. Then, when you've selected all the files you want to print, simply press the Print Print Print button to start printing. The first time you do this, Programmer's File Printer will show you a dialog box letting you select the type face and type size to use; the program remembers what you select, and so you won't need this dialog again unless you choose to use a different type face or size. Finally, when printing is complete, the Files Selected To Print list will be emptied. If you decide that you don't want to print some of the files you've selected, simply highlight them by clicking them (here Page Page Page 3 3 3 Programmer's File Printer Programmer's File Printer Programmer's File Printer again you can use the CONTROL CONTROL CONTROL and SHIFT SHIFT SHIFT keys to select more than one file) and press the Unselect Unselect Unselect button. Other Possibilities Other Possibilities Other Possibilities The section above showed you the simplest way to use Programmer's File Printer, using only the default settings. However, the program can be tuned to do exactly what you need in several ways. The files shown in the list The files shown in the list The files shown in the list One thing you might want to do is to restrict the file names shown the in the Files list to those with specific file types. At the bottom left of the main window you'll see the File Types Shown In List area, containing 8 check boxes. Initially the boxes have no text beside them, and the whole area is grayed and inactive. If you want, you can associate up to eight file types - such as .c .c .c, .h .h .h and .asm .asm .asm - with the boxes; then, with the area active, Programmer's File Printer will show only those files whose types are given beside boxes that you check. How listings are formatted How listings are formatted How listings are formatted As installed, Programmer's File Printer will list all files with line numbering and page headers, using a tab size of 8. Most files will be printed as text listings, but some, such as .exe .exe .exe, .obj .obj .obj and .lib .lib .lib files, will be dumped in hexadecimal and ASCII. You can specify your own formats for listing through an easy- to-use dialog. For example, you can select .c .c .c files to be printed with a tab size of 4 and line numbering; and .asm .asm .asm files with a tab size of 8. Page printing order Page printing order Page printing order If you are using a single sheet printer such as an HP Deskjet, the output pages will be stacked in the wrong order, so you need to manually shuffle them when printing is complete. You can configure Programmer's File Printer to print files in reverse page order, so that the output stack is the correct way up. Page Page Page 4 4 4 Programmer's File Printer Programmer's File Printer Programmer's File Printer T T THE HE HE M M MAIN AIN AIN M M MENU ENU ENU Many of Programmer's File Printer's actions are controlled by the main menu, which you will see at the top of the main window. In this section we look at the various options available and describe how you use them. The Files Menu The Files Menu The Files Menu This menu controls things related to your files. It lets you specify what file types are shown in the File Types Shown In List area, set up how you want each type to be printed, and also to set up specific listing requirements for individual files. The menu also contains a number of miscellaneous items. Set attributes for file types Set attributes for file types Set attributes for file types This menu options starts a dialog that lets you specify how files of particular types are to be listed. You can choose between text lists and hex dumps, and specify whether you want the lines to be numbered and the pages to have titles. To specify the settings you want to apply to a given file type, either select the type from the list box or type it in to the edit control. Be careful when you type that you include a leading dot character. You can then check the options that you require for the file type and give the tab size; then, to make Programmer's File Printer apply the values click the Use Use Use button. If you want to record the options you've set permanently, click the Save Save Save button. Note that if you select the option to dump files with a given type in hexadecimal rather than listing them as text, Programmer's File Printer will dump the whole of the file. If you want to dump only part of the file, use the Set Attributes For Selected Files option described below. Set attributes for selected file Set attributes for selected file Set attributes for selected file This menu option starts a dialog that lets you specify listing attributes for the specific files that are highlighted in the Files Selected For Printing list. With it you can over-ride the default listing attributes that Programmer's File Printer determines from the file type, and also select more complex options like a range of lines to be listed. You can only use this option if you've selected one or more files in the Files Selected For Printing list. Page Page Page 5 5 5 Programmer's File Printer Programmer's File Printer Programmer's File Printer The dialog allows you to switch the way the file is listed between text printing and dumping in hexadecimal as you wish, and to specify such things as the tab size and whether you want line numbering. By default, the Whole File box is checked, indicating that Programmer's File Printer will print or dump the whole file. If you want select a range, click the box to uncheck it and fill in the start and finish values you require. When giving range values, you're specifying file addresses or offsets for a hex dump, and can give them either in decimal, or as hex numbers preceded by x x x or 0x 0x 0x. For a text listing you're giving line numbers (the first line in the file is numbered 1). In either case you can use the words start start start and end end end for the start and end of the file if you wish. If you had more than one file name highlighted in the Files Selected For Printing list when you selected this menu option, the dialog box will appear for each one in turn. An alternative way of starting the dialog to set the details is to double click on the file concerned in the Files Selected For Printing list. Edit displayed types list Edit displayed types list Edit displayed types list Clicking this option starts a dialog which lets you choose what file types you want associated with the eight check boxes in the File Types Shown In List area. The dialog box contains eight edit controls, each with a check box beside it. To associate a file type with a check box in the File Types Shown In List area, simply type it into the corresponding edit control (remembering that you must always give a leading dot). If you want the file type to be shown in the list of files, check the box beside the file type. Once you leave the dialog, the boxes in the File Types Shown In List will be updated. You can also use this dialog to set whether Programmer's File Printer uses the file types selected or shows all the files in the directory; this is equivalent to using the Show All Show All Show All File Types File Types File Types menu option. If you want to make the selection of file types permanent, click the Save Save Save button in the dialog box. Show all files in directory Show all files in directory Show all files in directory Clicking this menu option switches tells Programmer's File Printer to switch between showing you all the files in the current directory, and showing only those whose file types are checked in the Files Types Shown In List area. Page Page Page 6 6 6 Programmer's File Printer Programmer's File Printer Programmer's File Printer If a check mark is shown next to the item Programmer's File Printer will display the names of all the files in the current directory, regardless of their type. Also, the check boxes in the File Types Shown In List area will be inactive. Rescan current directory Rescan current directory Rescan current directory Clicking this menu option forces Programmer's File Printer to re-read the current directory and rebuild the list of files shown. You will eed to use this option to re-scan the directory if you've disabled automatic rescanning and you've clicked some of the file type boxes in the File Types Shown In List area. Control Panel Control Panel Control Panel This menu option runs the Windows Control Panel, and lets you configure aspects of your Windows system. The Printer Menu The Printer Menu The Printer Menu This menu allows you to set things that affect your printer and the page layout. You can select which printer you wish to use, specify the type face and type size, and specify what margins should be applied. Select font to use Select font to use Select font to use This option starts a dialog that lets you choose what typeface Programmer's File Printer is to use to print. Since Programmer's File Printer is designed to list files such as program source, it contains no word processing features, and only fixed pitch fonts, in which every character occupies the same width, will be shown in the list. After selecting the type face you want, you can also select the type size. Programmer's File Printer records the details of the type face you select, and will automatically select it when you use the same printer. Set page margins Set page margins Set page margins Clicking this menu option lets you tell Programmer's File Printer what margins it should leave on each page. You can select margins at the top, bottom, left and right independently. Page Page Page 7 7 7 Programmer's File Printer Programmer's File Printer Programmer's File Printer The settings you give take effect immediately. If you want them to become the default the next time you use Programmer's File Printer, use the Save Save Save button to store them. All the margins are half an inch in size. Printer setup Printer setup Printer setup This menu option runs a dialog that lets you choose the printer to use, and to run the print driver's particular set- up program. It also lets you specify whether output to a particular device is to be done in reverse page order. Programmer's File Printer will select the printer you used the last time you ran the program when it starts (when you use it for the first time, it will use the system's default printer). This dialog allows you to choose any other printer that is available in your system configuration. The Setup Setup Setup button runs the specified printer's set-up program, and lets you, for example, set the paper size or change between landscape and portrait modes (if you printer supports this, of course). Checking the Reverse page order Reverse page order Reverse page order button causes output to the selected device to be sent in reverse order. The setting is stored in the initialisation file, so you need to set this up only once for each printer. The Options Menu The Options Menu The Options Menu This menu item controls various miscellaneous options that you may find useful. Set options Set options Set options This option runs a dialog that lets you set various miscellaneous options. You can make the settings permanent by clicking the Save Save Save button. The options currently selectable are: Clear selection after printing Clear selection after printing Clear selection after printing If you select this option, Programmer's File Printer will empty the Files Selected For Printing list when printing completes. Otherwise it leaves the files showing and you can, if you wish, print them again. Don't action form feed Don't action form feed Don't action form feed If this option is selected, Programmer's File Printer will not start a new page when it encounters a Form Feed character (ASCII 12) in the files it prints, but instead will print them as ^L ^L ^L. Page Page Page 8 8 8 Programmer's File Printer Programmer's File Printer Programmer's File Printer Restart in same directory Restart in same directory Restart in same directory If this option is selected Programmer's File Printer will start each session in the last directory on a hard disk or network drive selected in the previous session. Otherwise, it starts in whatever the current working directory happens to be. The Help Menu The Help Menu The Help Menu This menu runs the Windows help system to provide you with assistance using Programmer's File Printer. Index Index Index This option takes you to the main index of the help information. Using PFP Using PFP Using PFP This option takes you to the tutorial section of the help file. Here you'll find guidance on what the program can do, and how you can control it. Command reference Command reference Command reference This option takes you the reference section of the help file that covers all the menu options. Dialog reference Dialog reference Dialog reference This option takes you to the reference section of the help file that covers use of the various dialog boxes you use to configure Programmer's File Printer. Using help Using help Using help This option takes you into a tutorial section that explains how to use the help system. About About About This shows you information about the current version of Programmer's File Printer. If you want to pass any comments or bug reports to the author, please determine the number of the version you're using with this menu option. Page Page Page 9 9 9 Programmer's File Printer Programmer's File Printer Programmer's File Printer A A APPENDIX PPENDIX PPENDIX 1: THE INITIALISATION FILE 1: THE INITIALISATION FILE 1: THE INITIALISATION FILE Programmer's File Printer reads initialisation information from the file pfp.ini pfp.ini pfp.ini when it starts, and at certain times while it's running. This file is held in the same directory that you keep the executable program file in. Some of the information is placed in pfp.ini pfp.ini pfp.ini by Programmer's File Printer itself, and some of it can be put there by you, using an editor such as the Notepad Editor supplied with Windows. The format of the file is the same as for the standard Windows initialisation files such as win.ini win.ini win.ini. It's divided into a number of sections, each preceded by the section name in brackets: for example [fonts] [fonts] [fonts] introduces the section concerned with fonts. Within each section are one or more lines, which have the general form key_string=arguments_list key_string=arguments_list key_string=arguments_list The key_string part is a string of characters, possibly including spaces, which Programmer's File Printer uses to locate the line. The arguments_list part is a number of strings, separated by commas, which provide whatever information is appropriate. For example, a line might look like this: margins=y,n,n,n margins=y,n,n,n margins=y,n,n,n where the key_string is "margins" and there are four arguments, "y", "n","n" and "n". The [fonts] section The [fonts] section The [fonts] section This section records the font that you have selected for the current default printer. Programmer's File Printer updates this section whenever you click the OK button to end the font selection dialog. Every record in this section has the general form: printer name=font name,size printer name=font name,size printer name=font name,size Printer name is the name of the printer you are using; font name is the default font to be used with that printer; and size is the size in points to use with that font. For example, a record Epson 24 pin=Roman 15cpi,10 Epson 24 pin=Roman 15cpi,10 Epson 24 pin=Roman 15cpi,10 tells Programmer's File Printer to select the "Roman 15cpi" font, 10 points high, whenever the default printer is "Epson 24 pin". Page Page Page 10 10 10 Programmer's File Printer Programmer's File Printer Programmer's File Printer The [general] section The [general] section The [general] section This section contains general settings used by Programmer's File Printer. Clearing selected files list Clearing selected files list Clearing selected files list The clear_after record specifies whether Programmer's File Printer will empty the Files Selected For Printing List after printing them. The format of this record is: clear_after=state clear_after=state clear_after=state where state is either y or n. If this record is absent, Programmer's File Printer will clear the list of files after they are printed. Setting margins Setting margins Setting margins The margins record sets the default selection of page margins. The format of this record is: margins=left,right,top,bottom margins=left,right,top,bottom margins=left,right,top,bottom where left, right, top and bottom should be either y or n. If this record is absent, Programmer's File Printer will not use any margins. For example, the record margins=y,n,n,n margins=y,n,n,n margins=y,n,n,n selects a left margin, but no others. All margins are half-an-inch wide. Updating the files list Updating the files list Updating the files list The auto_refresh record tells Programmer's File Printer whether the list of files in the current directory should be updated automatically whenever you click one of the file type selection check boxes. If the current disk is a floppy, you may find it more convenient to turn automatic updating off. The format of this record is auto_refresh=state auto_refresh=state auto_refresh=state where state must be y or n. Page Page Page 11 11 11 Programmer's File Printer Programmer's File Printer Programmer's File Printer The default printer The default printer The default printer The printer record tells Programmer's File Printer what device to use for output. The format of the record is: printer=name,driver,port,reverse_order printer=name,driver,port,reverse_order printer=name,driver,port,reverse_order where name is the device name as it appears in the win.ini win.ini win.ini file; driver is the name of the printer's driver module; port is the name of the output port to which the device is attached; and reverse_order is "y" for reverse order printing and n" for forward printing. For example, a record printer=HP Deskjet Family,DESKJET,LPT1:,y printer=HP Deskjet Family,DESKJET,LPT1:,y printer=HP Deskjet Family,DESKJET,LPT1:,y specifies the default printer to be an HP Deskjet on LPT1, and selects reverse page order printing. The initial directory The initial directory The initial directory Programmer's File Printer can be configured so that it changes the working directory to the directory that was current the last time it was used. This facility is controlled by two initialisation file records, as follows: The reset_dir record enables or disables the facility; the format is reset_dir=state reset_dir=state reset_dir=state where state must be y or n. The directory record specifies the target directory. The format is: directory=pathname directory=pathname directory=pathname For example: directory=c:\software\newapp\src directory=c:\software\newapp\src directory=c:\software\newapp\src The [select] section The [select] section The [select] section This section controls what file types appear associated with the eight selection check boxes in the File Types Shown In List area. In order to select a file type, such as .c .c .c explicitly, it must have an entry in this section. Each record in this section has the form .filetype=letter .filetype=letter .filetype=letter where letter must be either y or n. Filetype is the file type concerned, and must be preceded by a dot. Page Page Page 12 12 12 Programmer's File Printer Programmer's File Printer Programmer's File Printer Programmer's File Printer will read up to eight lines from this section, and will associate the types they define with the check boxes in the selection area, in the order that they appear. If letter is y, the box will automatically be checked, and files with this type will appear in the Files list. If letter is n, the box will not be checked, and files with this type will not appear in the Files list until you subsequently click the box. One special record in this section controls whether you want to see all file types in the file list. If the section contains a record *=y *=y *=y all files in the current directory will be shown in the file list, regardless of their type. For example, the record .asm=y .asm=y .asm=y will label one of the check boxes with .asm .asm .asm, and the box will be checked by default. The [formatting] section The [formatting] section The [formatting] section This section defines how you want to format listings for specific file types. It contains a number of records, all with the general form .filetype=number,header,wrap,tabsize,hexdump .filetype=number,header,wrap,tabsize,hexdump .filetype=number,header,wrap,tabsize,hexdump Here .filetype is the file type, preceded by a dot. Number, title and wrap must all be either y or n, and control whether lines are numbered, whether pages have headers, and whether long lines are wrapped respectively. Tabsize sets the width of a tab stop, and must be a number between 4 and 16. Hexdump, which must be y or n, specifies whether the file is to printed as text or dumped in hexadecimal and ASCII. For example, the line .c=y,y,n,4,n .c=y,y,n,4,n .c=y,y,n,4,n sets the formatting for files with type " .c .c .c". The file will be printed as text; lines will be numbered; pages will have headers; long lines will be truncated; and tabs are expanded to every 4 characters. Note that when a hexadecimal dump is specified for a file in this way, Programmer's File Printer will dump the entire file. Page Page Page 13 13 13 Programmer's File Printer Programmer's File Printer Programmer's File Printer The [printers] section The [printers] section The [printers] section This section records details relevant to the various printers configured on your system. It contains records of the general form: printer name=reverse_order printer name=reverse_order printer name=reverse_order Printer name is the device name as it appears in your win.ini win.ini win.ini file, and reverse_order is either " y" to select reverse page order printing or "n" to select normal order. Page Page Page 14 14 14 Programmer's File Printer Programmer's File Printer Programmer's File Printer APPENDIX 2: D APPENDIX 2: D APPENDIX 2: DEVICE EVICE EVICE F F FONTS AND ONTS AND ONTS AND GDI F GDI F GDI FONTS ONTS ONTS Windows 3 produces text output on printers using one of two mechanisms. The most common method is to use GDI fonts, in which it sends the text to the printer as a graphics dump. The other method involves the use of device fonts - here Windows sends the text as a stream of characters, and the printer uses the fonts built in to it. For an application such as Programmer's File Printer, designed to list text files, there are great advantages to using device fonts rather than GDI fonts. There is no need for Windows to construct a (very large) graphics dump file to send to the printer, and so both the listing operation and the printing operation are very much quicker, and very much less disk space is needed by Print Manager for the spool file. Programmer's File Printer attempts to show you only device fonts in the list given in the Fonts dialog. However, applications such as Adobe Type Manager and sophisticated print drivers such as that for the Hewlett Packard Deskjet 500 printer can prevent it from determining which fonts are GDI fonts and which are device fonts, so that the list you are shown may contain both. For both Adobe Type Manager and the HP Deskjet 500 driver, for example, the font Courier will appear in the list, even though it is a GDI font and not a device font. Programmer's File Printer will work satisfactorily whatever type of font you choose. However, if you select a GDI font the program will be significantly slower, and you will need a very large amount of disk spool space to accommodate the graphics dump. Printing will also be significantly slower. The HP Deskjet 500 printer The HP Deskjet 500 printer The HP Deskjet 500 printer The HP Deskjet 500 driver supports only GDI fonts. The only font name you will see in the font selection dialog list is Courier, and output with this font will be sent to the printer as a graphics dump. Each listing will need typically twenty to thirty times the size of the input file for spool space. You can substantially improve matters by using the HP Deskjet Family print driver, supplied on your Windows 3 release disks. This operates perfectly satisfactorily with the Deskjet 500 for text output (and for most graphics output). This driver supports the fonts built in to the printer, and also any font cartridges you may have containing fixed-pitch fonts; using this driver lets you send listings as text, with a marked speed improvement and very great reduction in spool space requirements. You can select the HP Deskjet Family driver using the Control Panel, which you can conveniently start from Programmer's File Printer's system menu. One physical difference between the Deskjet 500 and other Deskjet families needs to be compensated for in order for printing to work correctly. The printable area of a page is Page Page Page 15 15 15 Programmer's File Printer Programmer's File Printer Programmer's File Printer slightly different between printer models, and the HP Deskjet Family driver believes the printable area to be larger than it actually is. To correct this, include the following lines in your pfp.ini pfp.ini pfp.ini file: [printable_area] [printable_area] [printable_area] HP Deskjet Family=11300,15360 HP Deskjet Family=11300,15360 HP Deskjet Family=11300,15360 This sets the correct printable area size for A4 (210mm x 297mm) paper. However, since the built-in fonts in the Deskjet 500 are slightly wider than in the Deskjet Plus, you will find that you need to reduce the width value if you use very small fonts such as Letter Gothic 33 pitch. Page Page Page 16 16 16