@MAIN HEAD = VP FILE GROOMER

@CREDITS = Copyright <189>1990

@CREDITS = by Peter Donnelly

@CREDITS = 1301 Ryan Street

@CREDITS = Victoria BC Canada V8T 4Y8

@SECTION HEAD = Introduction

In theory it is possible to produce text in any standard word processor 
and lay it out in Xerox Ventura Publisher without further editing. 
However, in practice a great deal of tinkering usually has to be done 
in order to produce a document of truly typographical quality. This 
is especially true when the Ventura Publisher operator has little 
or no control over the preparation of the text before it is presented 
for typesetting.

VP F<MS>ILE<D> G<MS>ROOMER<D> takes much of the work out of fine-tuning 
documents for publication. In a single pass it can make many changes 
that otherwise would have to be done with tedious search-and-replace 
operations in a word processor, or by editing and paragraph-tagging 
within Ventura itself. Among the tasks it can perform are:

@BULLET = Strip redundant spaces and tabs.

@BULLET = Change text attributes, e.g. from underlining to italics.

@BULLET = Set typographical fractions.

@BULLET = Set single and double quotation marks, and bring periods 
and commas inside quotations.

@BULLET = Convert hyphens to em and en dashes, with or without surrounding 
space.

@BULLET = Improve the appearance of ellipses.

@BULLET = Replace dot leaders with tabs.

@BULLET = Assign style tags to paragraphs based on their format in 
the original document.

@SECTION HEAD = To prepare a document

VP F<MS>ILE <D>G<MS>ROOMER<D> works with files in Ventura's <169>generated<170> 
format. These are essentially ASCII files with attributes, etc., encoded 
in angle brackets. Any text file that can be loaded into Ventura Publisher 
can easily be converted into this format.

First import the text file into any Ventura chapter using the appropriate 
<169>Text Format<170> choice under <169>File: Load Text/Picture.<170> 
(References to Ventura Publisher are to the GEM edition. The menu 
structure may vary in the Windows version.) If you intend to use VP 
F<MS>ILE<D> G<MS>ROOMER<D> to create typographical quotation marks 
or dashes, be sure to set <169>Auto-Adjustments<170> (under <169>Options: 
Set Preferences<170>) to <169>None.<170>

Now, in frame mode, put the text in a frame and choose <169>Edit: 
File Type/Rename<170>. Save the file in <169>Generated<170> text format, 
preferably with the extension <169>.GEN<170>. The file will retain 
the same name after processing in VP F<MS>ILE<D> G<MS>ROOMER<D> and 
will remain attached to the chapter.

VP F<MS>ILE<D> G<MS>ROOMER<D> will not interfere with any paragraph 
tags or other special codes already inserted in the document, except 
to change attributes as specified by the user.

The program will always strip spaces that occur immediately in front 
of a carriage return, in order to eliminate quasi-blank paragraphs 
that would not otherwise be caught by PARAFILTR<N>ON. This means that 
you cannot override the PARAFILTR<N>ON tag by creating a dummy paragraph 
with just a space in it.

@SECTION HEAD = To start the program

You may enter the path name of a text file on the command line, and 
the file will be loaded immediately. The extension <169>.GEN<170> 
is assumed if the file name does not contain a period. If the path 
name contains wildcards (? or *), the program will start up in a dialog 
box with a list of matching files.

@SECTION HEAD = Menus and dialog boxes

The Borland Turbo Vision interface used in VP F<MS>ILE <D>G<MS>ROOMER<D> 
is very similar to GEM and Microsoft Windows, so we can safely skip 
the basics of how to use menus, dialog boxes and scroll bars. 

Here are a few tips about Turbo Vision features that may be new to 
you. (We will assume you use a mouse, but the program is fully operable 
with the keyboard alone. Additional keyboard commands are given in 
a separate section.)

@BULLET = Dialog boxes can be closed in several ways. You may discard 
all changes by hitting <F2B>Esc<F255D>, or by clicking on the little square 
in the upper left corner, or by clicking on <B>[Cancel]<D>. To save 
changes, click on <B>[OK]<D>. Striking the <F2B>Enter<F255D> key has the 
same effect as clicking on an illuminated button (usually <B>[OK]<D>).

@BULLET = There are two types of option switches in the dialog boxes. 
Parentheses enclose <169>radio buttons,<170> which are like the frequency-selection 
buttons on a receiver<197>one and only one is always active. Square 
brackets are check boxes; you can check all, or none.

@BULLET = When you tab to an input field, or click on the field label, 
any text in the field is highlighted. You can also highlight text 
by dragging the cursor over it, or by double-clicking anywhere on 
the line. If the cursor is in insert mode (it appears as an underline), 
highlighted text will be deleted when you start typing, or if you 
strike <F2B>Del<F255D>. To un-highlight text, strike a control key such 
as an arrow, or click once where you want to begin editing.

@BULLET = When the cursor is blinking in a long list of tags or files, 
you can move quickly to a name by typing the first few letters.

@BULLET = When editing a text field, you can use the arrow keys as 
well as <F2B>Home<F255D>, <F2B>End<F255D>, <F2B>Back<N>Space<F255D>, and <F2B>Del<F255D>. 
You can also toggle between insert and overstrike modes with <F2B>Ins<F255D>.

@BULLET = File pathnames can be longer than the visible field. Just 
keep typing and the text will scroll. To scroll existing text, click 
on the arrows that appear when the text is longer than the window, 
or use <F2B>Home<F255D> and <F2B>End<F255D>.

@BULLET = You can exit to DOS through the <B>Program<D> menu, or by 
striking <F2B>Alt-X<F255D>.

@SECTION HEAD = To process a file

There are two steps to processing a file. First you must load it, 
either on the command line, or through the menu, or by pressing <F2B>F3<F255D>. 
The file will appear on the screen when it has been loaded. Then, 
to begin the actual processing, select <B>Process<D> from the <B>File<D> 
menu, or strike <F2B>F4<F255D>.

Options for processing can be set before or after the file is loaded 
into the viewer.

The processed file retains the name of the original file, and the 
original file is saved with the extension <169>.BAK<170>. Any previous 
<169>.BAK<170> file with the same name is deleted. If you process 
a <169>.BAK<170> file, it will be overwritten by the new file.

@SECTION HEAD = The file viewer

The file is loaded into a viewer before and after processing, so that 
you can look through it and determine what sorts of changes need to 
be made and whether the results are satisfactory. Very large files 
may not be loaded in their entirety, but the entire file is processed 
just the same.

Tabs appear in the viewer as a hollow bullet. Paragraphs have a blank 
line between them, inserted by Ventura as a marker; these single blank 
lines will not appear as blank lines in the typeset document and do 
not have to be filtered out. Some text lines may be wider than the 
view window; this doesn't make any difference to Ventura.

@SECTION HEAD = When there is no mouse

Open a menu by pressing <F2B>Alt<F255D> plus the highlighted letter. Move 
to different menus with the left and right arrows. Close the menu 
with <F2B>Esc<F255D>. Select an item from a menu by moving the highlight 
bar with the up and down arrows, then striking <F2B>Enter<F255D>, or by 
pressing the key corresponding to the highlighted letter in the desired 
item.

In dialog boxes, move the highlight from area to area and from button 
to button with the <F2B>Tab<F255D> key, or backwards with <F2B>Shift-Tab<F255D>. 
If there is a highlighted letter in the label for the area, you can 
move directly there by pressing the letter, alone or with <F2B>Alt<F255D>. 
Within an area, move from field to field with the arrows. Moving the 
highlight within a radio-button area also moves the active button. 
The space bar marks and unmarks check boxes.

Striking <F2B>Enter<F255D> is always equivalent to clicking on <B>[OK]<D>, 
except when you have tabbed the highlight to <B>[Cancel]<D>. You can 
always cancel out of a dialog box with <F2B>Esc<F255D>.

There are three shortcuts to bypass the menus: <F2B>F3<F255D> to load a 
text file, <F2B>F4<F255D> to process it, and <F2B>Alt-X<F255D> to quit the program.

The text file may be scrolled with the arrows and with <F2B>PgUp<F255D> 
and <F2B>PgDn<F255D>. If there are any long lines, strike <F2B>End<F255D> and 
<F2B>Home<F255D> to jump to the end and beginning of the line. <F2B>Ctrl-PgUp<F255D> 
and <F2B>Ctrl-PgDn<F255D> go to the beginning and end of the displayed portion 
of the file.

@SECTION HEAD = Technical support

The author is pleased to respond to any questions, bug reports, or 
requests for new features when these come from registered owners of 
the program. If you have not already registered, please enclose a 
check or money order for $50 with your letter. 

@SECTION HEAD = Acknowledgments

The program was written with Turbo Pascal and Turbo Vision, which 
are products of Borland International. 

Ventura Publisher is a registered trademark of Ventura Software Inc. 


@MAIN HEAD = MENU REFERENCE

@SECTION HEAD = Program

@SUBMENU = Register<F128><156><F255>

Information about the program.

@SUBMENU = Colors<F128><156><F255>

Four color sets are available: two different sets for color screens, 
one for full-page and other monitors that represent colors in shades 
of gray, and one for monochrome in case you run the program on a black-and-white 
screen. Your preferred colors are saved in every settings file; save 
DEFAULT.SET after changing the colors and they will come up automatically 
whenever you run the program.

@SUBMENU = Exit

Return to DOS. Any settings not previously saved are lost.

@SECTION HEAD = File

@SUBMENU = Load<F128><156><F255>

Brings up a dialog box to load a text file for viewing and processing. 
You can either type the full filename followed by <F2B>Enter<F255D>, or 
click on a name and then click on <B>[Open]<D>, or double-click on 
a name. To get a different list of files, type a mask in the name 
field, such as <169>*.DOC.<170> To back up in the directory tree, 
double-click on the <169>\..<170> symbol at the end of the list. To 
go forward, double-click on the name of a subdirectory.

Notice that information on the highlighted file is given at the bottom 
of the dialog box.

@SUBMENU = Change dir<F128><156><F255>

This dialog box allows you to change the current directory so that 
file lists will default to that directory when you load and save. 
Changing the current directory does not affect the destination of 
processed files, which are always put in the same directory as the 
originals.

Choose a directory by typing its pathname in the input box, or by 
double-clicking on its name in the tree, or by highlighting it and 
clicking <B>[ChDir]<D>. To change drives, double-click on <169>Drives.<170> 
If you change your mind, click on <B>[Revert]<D> or the window-closing 
icon. Otherwise click on <B>[OK]<D> when the desired directory name 
appears in the input box.

@SUBMENU = Process

Begin processing the last file that was loaded. If you abort by striking 
<F2B>Esc<F255D>, the original file will remain intact.

@SECTION HEAD = Settings

@SUBMENU = Attributes<F128><156><F255>

This dialog box lets you convert text attributes to other attributes 
or combinations of attributes, or delete them altogether.

If no box is checked for a particular attribute, that attribute will 
be deleted. This feature can be handy when headings in the original 
document have been underlined or put in bold face and you do not want 
these embedded attributes to override the attributes you specify in 
the Ventura style sheet.

When you view the file after processing, you may see empty angle brackets 
or redundant codes. These are harmless; Ventura will eliminate them 
when it next formats the file.

@SUBMENU = Options<F128><156><F255>

@DIALOG FIELD = Typographical

<B>Single quotes. <D>Because many typists do not use the back apostrophe 
on the IBM keyboard, VP F<MS>ILE <D>G<MS>ROOMER<D> can convert normal 
apostrophes to opening single quotes where they appear in front of 
a word. (But if it sees an apostrophe before a number, as in <169>a 
'49 Chevrolet,<170> it leaves it alone.)

<B>Double quotes.<D> Although Ventura Publisher (versions 2 and up) 
will convert keyboard double quotes to typographical quotation marks, 
its algorithm can lead to peculiar results. It assumes that you sometimes 
want inch marks, so that an expression like `Come to the <169>Welcome 
2000" party' ends up being set with inch marks, not quotes, after 
the number; moreover, any quotes in the rest of the paragraph may 
now be curling in the wrong direction. Certain punctuation also causes 
problems.

If you choose this VP F<MS>ILE <D>G<MS>ROOMER<D> option, the program 
assumes that you never want to use inch marks, and turns all keyboard 
double quotes into their appropriate typographical equivalent.

When using this option, be sure Ventura has not already been allowed 
to convert quote marks. See the instructions for preparing text for 
processing, above.

<B>Stops inside.<D> Setting this switch causes the program to bring 
periods and commas inside double quotation marks. The switch has no 
effect if you are not converting quotation marks, or if they have 
already been converted.

<B>Fractions.<D> This option will recognize fractions with a numerator 
of less that 10 (in the form <169>3/16<170>) and instruct Ventura 
to set them as typographical fractions. Expressions like <169>90/91<170> 
are ignored. A space or hyphen between a whole number and a fraction 
is eliminated.

This feature can be used only with version 2 or later of Ventura Publisher.

@DIALOG FIELD = Filters

<B>Parafiltr.<D> If this option is checked, the <169>PARAFILTR ON<170> 
tag will be inserted at the beginning of the document, and Ventura 
will strip out blank paragraphs the next time it loads the file. This 
setting does not affect the generation of VP F<MS>ILE <D>G<MS>ROOMER<D> 
style tags based on blank lines.

<B>Initial tabs.<D> This filter will strip up to three tabs from the 
beginning of a paragraph. Generation of style tags based on initial 
tabs is not affected. Tabs in the middle of a paragraph are never 
deleted. This filter is useful for getting rid of tabs originally 
used for paragraph indentation that can clutter up the screen display 
in Ventura.

@DIALOG FIELD = 2 spaces

When the program encounters two spaces in a row, it will either delete 
the second one or leave them as is. The first option is useful for 
text that has been prepared with two spaces between sentences.

@DIALOG FIELD = 3 or more spaces

When the program finds three or more spaces in a row, it will either 
delete all but the first, delete them all, change them to a single 
tab, or leave them as is. The <B>Delete all<D> option can be used 
to strip paragraph indents that were created with spaces rather than 
true tabs.

@DIALOG FIELD = 3 or 4 dots

A string of periods can make an unsatisfactory ellipsis when set in 
type because they are set too close together. You could solve this 
problem by modifying the kerning table for each font you use, but 
VP F<MS>ILE <D>G<MS>ROOMER<D> offers a couple of easier alternatives.

When the <B>Ellipsis<D> option is chosen, the program substitutes 
number 156 in the symbols font for each occurrence of three periods 
in a row. You may prefer the appearance of this ellipsis character 
to that of a string of simple periods. However, if your text contains 
any instances of ellipsis followed by period, the fourth dot may not 
have the same size or spacing as the dots in the ellipsis proper.

To create uniform, custom spacing in each sequence of three or four 
periods, choose <B>Loosen<D>. Modify the default spacing by clicking 
directly on the number and typing in a new one. When you click on
this input box, <B>Loosen<D> is automatically selected.

The custom spacing feature requires version 2 or later of Ventura 
Publisher.

@DIALOG FIELD = 5 or more dots

When the program encounters five or more periods in a row, it will 
either replace them with a single tab (thus allowing a dot leader 
to be created within Ventura) or else do nothing.

@DIALOG FIELD = Hyphens

To supplement Ventura Publisher's limited facility for converting 
hyphens to dashes, VP F<MS>ILE <D>G<MS>ROOMER<D> will convert either 
a single hyphen between spaces or a double hyphen to an em or en dash. 
It also gives you the option of inserting thin spaces around the dashes 
it creates.

If you wish to use the <B>2 hyphens<D> option, be sure Ventura has 
not already been allowed to make an unwanted conversion. See the instructions 
for preparing text, above.

@SUBMENU = Tags<F128><156><F255>

VP F<MS>ILE <D>G<MS>ROOMER<D> will automatically insert style tags 
in the document where it finds certain combinations of carriage returns, 
tabs, etc. You define the tag names in the dialog box. Enter the names 
just as they will appear in the Ventura Publisher tag list.

If you wish, you can refer to a list of tags from a Ventura Publisher 
style sheet and even paste tags from the list into the tag fields. 
Click on <B>[List]<D> to load the style sheet. Use the scroll bar 
to scroll through a long list. To paste an entry from the list into 
a VP F<MS>ILE <D>G<MS>ROOMER<D> tag field, first highlight the entry 
by clicking on it, then select the tag field where you wish the tag 
to appear, and then click on <B>[Paste]<D>.

You can use a tag name in more than one field.

Any tag left blank will produce untagged Body Text, and none of the 
special procedures described below (i.e. deletion of initial hyphen 
or asterisk, and placing of a figure space after a numeral) will take 
place. If you actually put <169>Body Text<170> into the field, such 
procedures will be activated, though the tag itself will not be inserted 
into the text.

When application of a tag depends on a certain character such as a 
hyphen or numeral being the first character in the paragraph, any 
attribute code at the start of the paragraph will prevent the tag 
from being generated.

The need may sometimes arise to strip out attributes in one pass through 
the program, then assign tags in a second pass<197>for example, when 
numbered headings are in bold face but you want to assign the <B>Begins 
with numeral<D> tag to them. To accomplish this, you must reload the 
file into Ventura after the first pass. Make an insignificant change 
in order to force Ventura to rewrite the text file, then save the 
chapter. This procedure will remove redundant angle brackets and codes 
that might otherwise prevent proper tagging.

@DIALOG FIELD = Blank line before

Assigned to a paragraph preceded by an empty paragraph (appearing 
in the viewer as two extra blank lines). If you define this tag, it 
will take precedence over all others; for example, a tabbed paragraph 
after a blank line will be assigned this tag rather than the one you 
define for <B>Single tab<D>.

@DIALOG FIELD = Single tab

A paragraph beginning with just one tab will be given this style. 
The tab itself may be stripped out if you have the <B>Tabs<D> filter 
on, but it will still create the tag.

This and the following tag work only with true tabs, not indents created 
with spaces.

@DIALOG FIELD = Double tab

Applies to a paragraph beginning with two or more tabs. Again, the 
setting of the <B>Tabs<D> filter does not affect the generation of 
this tag.

@DIALOG FIELD = Begins with hyphen

This tag will be created if the first character in the paragraph is 
a hyphen. The hyphen itself (or both, if it is a double hyphen) and 
the following space, if there is one, are deleted. This tag is useful 
for creating bullet styles.

@DIALOG FIELD = Begins with asterisk

Works just like <B>Begins with hyphen<D>.

Note that the asterisk can be used as a sort of macro character in 
text prepared for Ventura Publisher. For example, the typist can be 
instructed to put an asterisk in front of all paragraphs that are 
to be set as indented quotes. This may be less confusing and less 
prone to error than something like <169>@Quotation = <170>.

@DIALOG FIELD = Begins with numeral

Applies to any paragraph whose first character is a numeral. The numeral 
is left intact, but the first following space is converted to a figure 
space, so that spacing after leading numbers will be consistent in
justified paragraphs. This feature enables the easy creation of hanging
indents that line up under the first character of text.

@DIALOG FIELD = Bold face

Any paragraph beginning with the attribute code for bold face is assigned 
this tag. The attribute code must come first, before any tab. The 
presence of another attribute such as underlining will not interfere. 
The tag is generated before any attribute conversions are carried 
out, so you can safely strip out bold face at the same time.

@DIALOG FIELD = All others

Applies to all paragraphs not meeting any of the specifications above, 
i.e. text beginning flush left and not preceded by one of the special 
characters or a blank line.

@SUBMENU = Save as<F128><156><F255>

Save the settings to a disk file. If you save them as DEFAULT.SET, 
the program will load them automatically the next time it is run. 
It looks first in the current directory for this file, then in its 
home directory. If it cannot find DEFAULT.SET, it uses its internal 
defaults.

@SUBMENU = Load from<F128><156><F255>

Load a settings file. The file must have been created with this version 
of VP F<MS>ILE <D>G<MS>ROOMER<D>.

 


