home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Monster Media 1994 #1
/
monster.zip
/
monster
/
PRINT
/
PRNF245.ZIP
/
PAGIN321.EXE
/
PAGINA.DOC
< prev
next >
Wrap
Text File
|
1993-07-26
|
27KB
|
537 lines
______PAGINA Ver. 3.21
Purpose: A simple file paginator. Breaks a continuous ASCII text file into
page-sized units, using form-feeds (ASCII #12). Adds headers and
footers if desired.
Format: PAGINA [[$]filespec [outfilespec [headerfilespec|NONE]
[BATCHMODE]]]
If any parameter strings are given, Pagina takes the first one for
the name of the file to be paginated. If there are two, the sec-
ond becomes the name of the output file, and if there's a third,
it will be the name of the header file to be used. What you don't
specify on the command line, Pagina will ask for interactively.
NUL or NONE gets you pagination without any header at all.
$ before the first filespec tells Pagina to use the file named as
a list of files. It will paginate the files named therein, all
output going to a single file with continuous page numbers.
BATCHMODE runs Pagina without stopping for keyboard inputs, as it
must if you run it from a batch file. It makes a fair guess at
parameters you haven't mentioned, but it's better to specify and
be sure.
For a quick-&-dirty job, outfilespec can be PRN.
Remarks: The point of Pagina is to paginate the kind of ASCII files usually
used for program documentation and the like. Most of these files
contain nothing that isn't printable by a very plain printer, and
many programs will break them into pages. Occasionally, however,
a DOC file will make minimal efforts to provide special effects
___________ boldface like underlining or boldface by using a bare carriage return
(ASCII #13) without the usual line feed (ASCII #10). This allows
overprinting the line with underscores and such to get the special
effects. Oddly, most simple paginator programs and many simple
text editors collapse on such files. The usual way of reading
text files treats the CR as the end-of-line marker. Turbo Pascal
(readln) and BASIC (LINE INPUT) do this, and they'll divide a
special effects line into two lines, at least one of which will be
very odd. The trick is to read lines up to the LF (line feed),
treating CR's like any other character, & that's what Pagina does.
The Main complexity in Pagina is the provision for headers and
footers. By default, Pagina's header is merely two blank lines,
and its footer is simply the page number flanked by hyphens in the
center of line 64, under at least three blank lines. To specify
any other header, you must make a header file. Unless you specify
a header file in the command line, Pagina will look all over the
DOS path for a file with the name PAGINA.HDR. If it can't find
that, it looks for PXL.HDR.[1] Even if it finds one of these,
-----------
1. Pagina's header scheme was lifted originally from PXL, a Turbo Pascal
cross-reference and lister I wrote and have been maintaining for some
years. If you use PXL and like your PXL.HDR file, just keep its direc-
tory on the path, and Pagina will use it, too.
______PAGINA Page 2
however, it stops to show you what it's found, and you get a
chance to give it something else. On the disk with Pagina, you
should find two header files. PAGINA.HDR is a simple alternative
to the default: it gives no footer at all and simple one-line
header. The name of the file appears at the left and on the right
is the file's date on page one and the page number on subsequent
pages. Also you should find XXX.HDR. It's a heavily commented
demonstration of some of the header and footer features. It'll
work, but you really wouldn't want to use it.
If you want to paginate a set of text files with one continuous
set of page numbers, make a list of them in a file, one filename
per line, in the order you want them placed. Put a $ in front of
the file spec, and give it to Pagina instead of the name of the
file to paginate. Thus:
PAGINA B:STORY.TXT C:STORY.PRN ALT
tells Pagina to paginate B:STORY.TXT, put the paged output in
B:STORY.PRN, using the header in ALT.HDR.
PAGINA $B:STORY.LST C:STORY.PRN ALT.HDR
says to paginate all the files named in B:STORY.LST, put the
output in C:STORY.PRN, etc.
In a file list, you can put a title for each file on the same line
with it, separated from the file name by at least one space. This
has two effects:
1. Wherever you've put .Fn in your headers and footers, the title
will be used instead of the file name.
2. At the end of the output files, Pagina will put a table of
contents, listing the titles and page numbers. The first file
will always be listed as starting at page 1. Pagina assumes
that if you've called for unnumbered pages, the real beginning
of the text comes on whatever you're calling page 1.
In TITLES.HDR, I've put a sample header which shows a way to make
a set of files print out as chapters.
If you give one file a title, you must give them all titles. If
one but not all of the files have titles, Pagina will stop and
complain. If one or more of the files in the list can't be found,
Pagina will inform you and ask whether to continue. If you say
yes, it will process what it can find.
If you give it a bare file name, Pagina will hunt all over the DOS
path. Given a complete file spec (with drive & directory) and for
file specs in a $FILELIST, Pagina will search only where directed.
Pagina is meant to neaten up unpaginated files you found on some-
body else's disk. It's formatting capabilities are less sophis-
ticated than a real word-processor's, and it should be used with
caution if at all on a file that's already paginated. CountPgs
______PAGINA Page 3
will tell you if the file already has any FF's. If Pagina finds
any in the file it will respect them and start a new page at that
point. In the normal case there's a certain amount of text be-
tween FF's (whether Pagina's or already in the text), and Pagina
will add its headers and footers. If there's no text between FF's
(blanks, tabs, CR's and LF's don't count), Pagina will preserve
the FF's and include them in the page count, but it won't make
headers. The theory is that FF's back to back call for completely
blank pages like the ones Pagina makes on the .HBPA instruction.
to even up index, title page &c. (See page 6, below about .BPA
instructions.)
Frankly, the presence of FF's usually means either that the file
is already Paginated (so skip Pagina altogether) or it's been
bungled, and you'd better look at it and do some editing. Con-
ceivably, you might get away with just stripping the FF's out with
Mangler. In a really drastic case, you can get Mangler to remove
____ the headers and footers altogether and then strip the FF's.
______PAGINA Page 4
_________________________ How to Write Header Files
If you wish to write your own header files, here are the rules: A header
(or footer --I'll just say "header" when I mean both) can have up to five
lines. Each header line has three segments which must be separately spec-
ified. Each segment specifier has five parts:
1. { (opening brace)
2. One of the following symbols:
_ .HnL = Left side of Header line #n
_ .HnC = Center of Header line #n
_ .HnR = Right side of Header line #n
_ .HnN = No header line number #n
_ .HN = No header at all
.H@filespec = The entire contents of the file named will be printed
at the bottom of the header specified before this line.
.H@@filespec = Same as .H@filespec but takes effect starting on
page 2. (No, .H@@@ doesn't postpone it to p. 3.)
_ _ .HW = Header Width in characters; should match widest line in
the text. Default is 79.
_ .HMnn/nn/nn = set Margins: left margin/header width/paper width
_ .HA = Alternate left & right header segments on odd/even
pages for 2-sided print.
_ _ .HPLnn = Page Length: print nn lines per page (including headers
& footers). Default is 63.[2]
_ _ _ .HBPAn1,n2,n3... = insert a Blank Page After pages
n1, n2, n3...
_ _ .HPgn = start Page numbering with n
_ _ .HUPn = leave n Unnumbered Pages at the beginning.
_ .HTnn = expand Tabs to nn characters. Default is 8.
_ .U "xxx"[yyy] = (for "User's Line") Offer the user a chance to
insert a HDR file line at run time. (Text in "double
quotes" following it comes up as default text for the
entry. Text in [square brackets] becomes an explana-
tory prompt line. )
"n" of course, stands for a numeral xxx & yyy stand for text. All the
other symbols must be upper/lower case exactly as shown. Wherever .H
appears, you can put .F to mean "footer" instead of "header". A, W, M,
Pnn Pg, PBA, Tnn, UP will have the same effect whether written with .H
or .F. @filespec is the exception. It can be used only in a header
and only with .H. .U is the only instruction that doesn't start with
.H or .F.
.HM will override .HW (retained for compatibility with PXL and earlier
Paginas). As a rule, the 2nd parameter, "header width" should match
the widest normal line in the text, though you may want to allow a
slight overhang here and there. The 3rd parameter is optional; it's
-----------
2. Because of a bug in some versions, this version will recognize both
.HPnn and .HPLnn as page length specs.
______PAGINA Page 5
used only to calculate even-page margins when you're using .HA to al-
ternate left and right headers for printing on both sides of the paper.
.HT sets tab expansion for tabs found in the text. Tabs in the header
text are not expanded. (Why are you putting tabs in your header?)
.H@filespec is meant for the case of a very large and complex header
block.[3] The text in the specified file will be printed flushleft
against the margin, and no space will be added between it and the text.
If you want any blank lines there, or any extra left margin, you must
put them into the header block file yourself.
.H@filepec must be the last item in the .HDR file. Pagina will ignore
anything after it. You can specify other things, even other header
______ lines, footer lines, margins, etc., so long as you put them before the
.H@filespec instruction.
An extra @ sign in the instruction: .H@@ postpones the use of the block
header until page 2. (You can't stretch it further though; .H@@@ won't
postpone to page 3.)
3. a space. (That's ONE space. Spaces after the first become part of the
text of the header segment.)
4. the text of the header segment. Within the text, you can use the fol-
lowing symbols:
.Fn = file name
.Fd = file date (style: July 4, 1776)
.Ft = file time (style: 2:25 pm)
.Pd = present (or printout) date (style: 7/4/76)
.Pt = present (or printout) time (style: 14:25)
.Us = "User's string" (from the keyboard at run time)
.Id = user's ID if found in PXL.ID on the DOS path. (Provided
here for compatibility with PXL header files.)
# = page number (no period)
These symbols are case-sensitive. They must be upper/lower case exact-
ly as shown. Note that if you include a .U line or .Us in a header
string, Pagina will ask you for a string to put in its place.
5. } (closing brace)
You can differentiate between headers for the first page and for subsequent
pages. The first specification for a given segment defines what's to go on
the first page. A subsequent spec for that segment will be used for other
pages. Thereafter, specifications simply supersede each other.
-----------
3. The .H@ option was inspired by VIRLIST.TXT, a file which comes with the
McAfee virus protection programs. If you've seen it, you understand why
we need this.
______PAGINA Page 6
To empty a segment (that's previously been filled), put the closing brace
right after the symbol and space: {.H2R} means empty right segment for 2nd
header line. In general, to empty header lines:
___ {.HN} empties all the header lines (i.e., no header).
{.H2N} empties the second (#2) header line.
{.H2L} empties left segment of the second header line.
Pagina normally puts one blank line above and one blank line below the
header. To force extra blanks lines below the header, make a blank (not
empty) header segment. {.H5L } would do it --note the extra spaces be-
tween L and }. The first space is eaten, the others become the left seg-
ment of header line 5. Blank lines above the footer are easier: if the
only instruction for the footer is, say {.F3C - # -} you get a footer with
the page number in the middle of its third line and, perforce, an empty
first and second line above it. (This, by the way, is the default header.)
If you want a literal # (not the page number) in your header, put a back-
slash in front of it: \#. To put a literal backslash, put two of them: \\.
(This backslash isn't a true literal escape character. It works only on
itself and #.)
To leave some unnumbered pages (for cover page, introduction &c.) before
page 1, {.HUPn} (where n is the number of pages to skip) will do it. On
the first n pages, any header segment will that contains the # (page num-
ber) symbol will be omitted. If you're using the $ file list option, un-
numbered pages will be skipped only in the first file listed.
Note that this will not affect which pages are reversed by the {.HA} op-
tion. If the file has a title page and two pages of introduction you don't
want to number, put {.HUP3} into the HDR file. That will cause the first
three pages (title and two introduction pages) to carry no page numbers.
Numbering begins with the next page, which will carry "Page 1" in the right
header segment.
If this file has the {.HA} instruction to reverse alternate pages for
printing on both sides of the paper, that "Page 1" segment will appear on
the left side, because Pagina knows that the second page is an even one,
regardless what number you're printing on it.
{.HBPA} ("Blank pages after) allows you to order blank pages inserted after
specified pages. If you want the title page to have a blank back and the
page marked 1 to be a recto (that is, to appear on the right side of the
book), you need an extra FF at the end of the title page, and .HBPA1 would
do that. Say the file has a title page followed immediately by a one page
table of contents, followed by page 1 of the text. You need an extra FF
after the title page, of course, but that will put page 1 to the back of
the table of contents. To make the contents and page 1 both appear as
normal recto (right-hand side) pages, you need an extra FF after the title
page and another after the contents. .HBPA1,3 will do that for you. (Note
that the inserted blanks are counted as pages.)
.HBPA and .HUP are cumbersome ways of doing things more easily done with a
text editor. They're included in Pagina in case the file you want to pag-
inate contains bare CR's your text editor can't handle.
______PAGINA Page 7
Adding Header Strings at Run-time
If you want to make a single standard .HDR file to do for most of your pa-
ginations, there are a few things like margins and header width you might
want to change to fit the particular file you're printing. Pagina has two
ways to make a file do that: you can insert .U (U for "user") lines in the
HDR file, and you can put a .Us symbol in any header segment string. If
you put one of these in your HDR file, Pagina will ask you at run time for
a string to put in its place. If you're combining several files into one
with the $ option, you'll be asked only once; if you put .Us in several
segments, you get the same string in all of them. You can put other text
and symbols (.Fn, .Pd, Pgn &c.) in the string. (If you try to put .Us in
the string, an error condition occurs, and the whole string is canceled.)
The full syntax for these goes like this:
{.U "xxx"[yyy]}
.Us "xxx"[yyy]
where xxx in "double quotes" is a default string; it will pop up, and you
can accept it with one <Enter> or overwrite it. yyy in [square brackets]
will be displayed as an explanatory prompt. If there's no "xxx" string
there's no default. If there's no [yyy] string, you'll get a default
prompt.
The two forms of user string are slightly different:
.U accepts a line like any other line in the HDR file. Anything you can
put on a line in the HDR file, you can enter for a .U line. If you
wish, you can put several complete segment specs -- complete with
{curly brackets} -- when the .U line comes up at run time.
You can put as many .U lines in a HDR file as you like.
.Us is intended for strings that will become part of an already specified
___ header segment. Well, you can put a complete segment spec into such a
string, but you can put only one, and it will wipe out anything else
specified for the segment.[4]
You can put .Us as many times as you like, you can even have several in
one header segment, but you'll be asked to enter text for it only once,
and that text will replace .Us wherever it occurs in the headers and
footers.
If you run Pagina with the BATCHMODE switch in, it doesn't stop for input
from the keyboard. If the header contains {.U or .Us strings, they'll get
their default ("xxx") values.
-----------
4. That's a bug, but I'm trying to make it sound like a feature.
______PAGINA Page 8
Headers for Consecutive Pagination:
The idea of the $ option to paginate a list of files is that the successive
files are something like chapters in a book. If you use this option, you
have to use the same header for the whole run, but each time a file comes
up, Pagina will
1. Rebuild the header to make the file name, file date, &c match the cur-
rent file. You won't be asked for a new .Us user string.
2. Begin with the first page header again, and start the new file on a
fresh page. Even if your header contains .HUPn or .HBPA, it will leave
unnumbered pages and insert blank pages only in the first file (unless
you've called for .HBPA with page numbers that turn up in the
subsequent files).
If you prefer to paginate the files separately, you can use the .HPgn in-
struction to start page numbering at any number you like. If you like,
this instruction can be put in a user's string with the .Us symbol. You
can put other things in, too:
{.HPg5Woldery Wine}
in a user's string (or a normal header segment), will get you "Woldery
Wine"; the ".HPg5" will be obeyed, but not printed. You can tell what you
need from the "Pages" display on Pagina's billboard; it shows the numbers
actually put on the pages, not the true number of pages.
If You Don't Want Headers:
You can kill the header by entering NONE or a couple of blanks when asked
for a header file name, or you can specify NONE on the command line. In
addition, a header file completely replaces the standard default header.
If you don't want a default header at all -- not ever -- make a PAGINA.HDR
file that contains no header instructions. A zero-byte file will do. So
long as that's on the path, Pagina will make no headers on its own.
If You Also Use PXL:
As mentioned above, Pagina can read and obey any header instruction found
in a PXL header file. PXL will also read and obey header and Pagination
instructions in the body of the file being Paginated. Pagina will not.
A Note About Colors:
PrnSet (2.80 and later) has an option to customize its colors. (From Prn-
Set's main menu, press F3.) If PAGINA.EXE is on the default drive\direc-
tory when you run PrnSet's color changer, it will change Pagina's colors,
too.
Lacking a copy of PrnSet, if you know how to use DEBUG or a disk editor
(like Peter Norton's NU), you can change the bytes in the file directly.
___________Search for the flag, "COLORS:". Immediately after the colon are 4 bytes
______PAGINA Page 9
specifying colors, in this order: Normal, Emphasized, Frame, and Reversed.
I often set them up thus: (in hex numbers): 02 0E 60 70 for green-on-black,
yellow-on-black, black-on-brown, black-on-white.
_______________Version History
2.00 (5/89) adds two ways to handle multiple files:
$FILELIST option to combine several text files into one, con-
secutively numbered file.
.HPgn option to allow page numbering to start with any (posit-
ive) number you please.
Interactive file requests allow confirmation of requests.
2.01 (6/89) adds the NONE option to call for no header.
2.02 (6/89) minor aesthetic improvements.
2.10 (6/89) accepts wildcards in the filespec.
2.11, (7/89) adds margin setting (.HMnn/nn/nn) and the backslash
literal for putting # in a header.
2.12, (9/89) repairs bug with header file when working from a
$FILE.LST
2.13, (12/89) expands tabs in the text to width set by .HTnn (the
default is 8). Incredibly, it appears I've had that .HT tab width
command in place for many versions, but never implemented the ac-
tual expansion. 2.13d corrects a bug in the path-searching routine.
2.20 (1/90) Adds two instructions:
.UPn to leave n pages unnumbered at start of file.
.BPAn1,n2... to insert a Blank Page After pages n1, n2 &c.
Bug fixes: Pagina was refusing to accept output file name interact-
ively. 2.20a fixes another: should now leave the cursor alone on a
VGA. 2.20b stops on <Esc>, Ctrl-Break, or Ctrl-C more reliable.
2.21 (4/90) Two refinements: takes better control of FF's found
in the text, and no longer manufactures an extra page out of
stray CR's, blanks, or other white space after the final FF.
2.21a fixes a bug in .HPgnn when working from a $file list.
2.21b allows longer header lines --up to 255 columns. 2.21c
fixes the fix in 2.21. 2.21d counts blank lines properly.
2.22 A slight refinement: working interactively, Pagina will
manufacture and suggest a name for the output file, the same
file name with extension ".001" or, if the input file exten-
sion has a numer- ical value, you get the next higher number,
".002", ".003", etc.
______PAGINA Page 10
2.30 (3/91) improves the user string option in .HDR files. .U is a new
option to add a line at run time to the instructions (instead of
merely some extra text into a header section as .Us does). Both
.U and the old .Us option can have explanatory prompts and default
strings. This should help in making one basic PAGINA.HDR do for
many different files.
2.40 (10/91) adds BATCHMODE to permit non-interactive operation. Someone
sent me a review which said that these programs can be run from a
batch file, so I thought I'd better make it true.
2.41 Makes use of a new line-reading function. If all's well,
you'll never notice, but changing the version number makes
it easier to keep track of bugs.
3.00 (8/92) Makes use of that line-reading function properly. Instead of
255-character lines, it can now handle lines of up to about 30,000
characters (including underlining &c added after bare CR's.)
3.01 (10/92) works around Turbo Pascal 6 bug: reset balks at read-only
non-text files. Now uses text files where possible and changes
attribute temporarily where file must be opened as non-text.
3.01a (12/92) does it better. No need to fiddle the attributes.
3.10 (2/93) New function: .H@filespec puts the entire text of the speci-
fied file into the header. Suggested by Lewis Paper for dealing with
McAfee's VIRLIST.TXT. 3.10a allows .H@@filespec to postpone use of
this header until 2nd page.
3.20 (6/93) Titles may now be given to files in a $FILELIST. The titles
will substitute for the file name in .Fn header lines. If titles are
given, a table of contents will be generated, treating the separate
files as chapters.
3.21 (7/93) parameter /? gets a syntax help screen.
R. N. Wisan, July 1993
37 Clinton St., Oneonta, NY 13820
internet: wisanr@hartwick.edu