APPLICATION NOTE #168 USING XYWRITE III PLUS WITH VENTURA PUBLISHER 2.0 Rev. 02 Related files: CONVERT.TBL, VPIMPRT.PGM, VPEXPRT.PGM, VP.TMP, and VPEX.TMP Xerox Ventura Publisher is a desktop publishing package that allows you to electronically lay out the pages of your publication. Most of the text and graphics used by Xerox Ventura Publisher are prepared with other application programs and then imported into Ventura Publisher. XYQUEST has developed a filter program that will import and export XyWrite III Plus files to be read into and out of Ventura Publisher. This application note describes how to use the filters, which require XyWrite III Plus, Version 3.54 or later; it also includes some tips on using XyWrite III Plus so that the conversions are most successful. PROGRAM INSTALLATION The XyWrite/Ventura Publisher filter comprises five files: CONVERT.TBL, VPIMPRT.PGM, VPEXPRT.PGM, VP.TMP, and VPEX.TMP. To use the filter, you need to copy all five files into your working directory on the hard disk. 1. Insert the XyWrite Filters Disk into drive A. 2. Change to your working directory. For example: Type: F5c: Type: F5cd \xy 3. Issue the Copy command. Type: F5copy a:vpexprt.pgm 4. Repeat step 3 for all five files. PROGRAM OPERATION To run either VPIMPRT.PGM or VPEXPRT.PGM, perform the following steps in XyWrite. 1. Be sure the DRIVEPATH settings in CONVERT.TBL are defined correctly. (See "Changing User-Definable Settings" later in this application note.) 2. Switch to the directory that contains the program files. 3. Call the file you want to convert. 4. Make sure that window #9 is blank. (If it's not, the filter program will store the open file.) 5. Run the appropriate program. For example, to run the import program: Type: F5run vpimprt.pgm To run the export filter: Type: F5run vpexprt.pgm Note #1 File Integrity. Both VPIMPRT.PGM and VPEXPRT.PGM modify your original file and save it in the current directory. If you want to keep your original file intact, see "Changing User-Definable Settings" later in this application note. Loading an Import File To load a file created by VPIMPRT.PGM, perform the following steps in Ventura Publisher: 1. Display the Load Text/Picture menu. 2. Select TEXT as the TYPE OF FILE. 3. Select XYWRITE as the TEXT FORMAT. 4. Select the appropriate number of files and destination. Refer to the Load Text procedure in the Xerox Ventura Publisher Reference Guide for more information on loading a text file. Exporting a File to XyWrite If you want to make changes to a Ventura Publisher file in XyWrite, call the file from the Ventura Publisher directory and run VPEXPRT.PGM on it (see Note #1). PROGRAM DESCRIPTION The XYQUEST-developed import/export filter gives you the ability to import XyWrite files to Ventura Publisher and export files from Ventura Publisher back into XyWrite. This import/export filter, which is available on request from XYQUEST's Technical Services Department, converts all of the formatting commands for which there are XyWrite-Ventura Publisher equivalents. These include modes, tabs, styles, footnotes, etc. As noted above, the XyWrite/Ventura Publisher filter comprises five files. The following paragraphs describe the files in more detail. Program Files VPIMPRT.PGM and VPEXPRT.PGM are XyWrite programs. VPIMPRT.PGM converts XyWrite codes to Ventura Publisher codes so you can then import the XyWrite file into Ventura Publisher. VPEXPRT.PGM converts the Ventura Publisher codes to XyWrite codes so you can use a Ventura Publisher file in XyWrite. Both VPIMPRT.PGM and VPEXPRT.PGM use the information in CONVERT.TBL to translate text files between XyWrite and Ventura coding. The translation uses substitution tables created by the two programs and stored in VP.TMP and VPEX.TMP. Conversion Table CONVERT.TBL is an ASCII text file, which means you may go into the table and make changes to suit your needs. Call CONVERT.TBL to the screen. It is divided into three parts. The first section, User-Definable Settings, establishes the default values for some of the XyWrite to Ventura conversions. It is followed by two tables: a command substitution table (labeled COMMAND TABLE) and a character substitution table (labeled CHAR TABLE). Note that both tables have a similar construction. The leftmost column contains the conversion data; the XyWrite code is on the left side of the equal sign, and the Ventura Publisher code is on the right side. The conversion data is followed by a tab. Columns two and three contain comments that explain the codes in the first column. (Everything between a semicolon and a carriage return is considered a comment and is ignored by the conversion programs.) Finally, each table ends with an ET (End Table) command. Each of the tables contains a different type of data. The first table, labeled COMMAND TABLE, contains the conversions for the mode commands and PT (Print Type) commands, as well as for the chapter counter and page number command. The second table, CHAR TABLE, contains special characters and their representations. XyWrite uses the IBM extended ASCII character set, but Xerox Ventura Publisher uses an international character set that differs for ASCII characters 169 through 256. CHAR TABLE allows you to change the character displayed by XyWrite into a different character when displayed by Ventura Publisher (see Note #2). Note #2 Screen Fonts. If you are using screen fonts other than those supplied with Ventura Publisher (e.g., Bitstream fonts), the character sets may vary. You can edit CHAR TABLE so that Ventura Publisher displays the characters provided with your screen fonts. MODIFYING CONVERT.TBL Because CONVERT.TBL is an ASCII text file, you can alter the default conversions or change the display of other ASCII characters if you want. Each time you change CONVERT.TBL, you must complete the following steps: 1. Call CONVERT.TBL to the screen and make the desired changes. (See the sections below for specific examples.) 2. Search for the line that says MODIFIED=NO, and change it to MODIFIED=YES. 3. Store CONVERT.TBL. Changing User-Definable Settings The first section of CONVERT.TBL contains several lines that establish default values for the filters. The function of each of these lines is described below. STYLES RETAINED--A YES setting means that formatting information within a SS (Save Style) command is converted to hidden text when the file is imported. If you later export the file, the hidden text is restored to XyWrite commands. A NO setting means that the information within the SS command is deleted. (The default is YES.) LINES--A YES enables Ventura Publisher's PARAFILTR setting (@PARAFILTR ON = ). A NO means that PARAFILTR is off. (The default is NO.) If you enable PARAFILTR, double carriage returns are converted to single returns when you import a file; if you later export the file back to XyWrite, the extra carriage returns are not restored. Refer to Appendix D in the Xerox Ventura Publisher Reference Guide for more information about @PARAFILTR. DRIVEPATH IMPORT and DRIVEPATH EXPORT--Define where VPIMPRT.PGM and VPEXPRT.PGM will store converted files. (The default locations, which are selected by leaving the line undefined, are the current drive and path.) If you choose to use the default, the filter programs modify your original file. If you specify a different drive and path, the filter programs copy your original file to the specified location and modify the copy. HEADERS-FOOTERS--A YES means that the text of headers and footers is transferred to Ventura Publisher, although the RHA and RFA commands are transmitted as hidden text. A NO setting means that RHA and RFA commands and the text within them are transmitted as hidden text. (The default is NO.) MODIFIED--A YES means that CONVERT.TBL has been modified since the last time VPIMPRT.PGM and VPEXPRT.PGM were run. A NO means that the table has not been modified. (The default is NO.) Let's take a look at an example. VPIMPRT.PGM and VPEXPRT.PGM convert the commands in the displayed file to Ventura Publisher or XyWrite format, respectively. The programs then store the converted file in the current drive and path, overwriting your original file. If you modify the DRIVEPATH line in CONVERT.TBL to include a file location, you can create automatic backups of your files. Your original file will be stored on disk in the current directory, and the converted file will be stored in the directory defined in the DRIVEPATH setting. To make this change: 1. Call CONVERT.TBL to the screen. Type: F5call convert.tbl 2. Move the cursor to the line DRIVEPATH=. Type: F5se /drivepath=/ 3. On the right of the equal sign, enter the name of the drive and path you want to use. For example: Type: c:\xy 4. Complete steps 2 and 3 of the procedure defined in "Modifying CONVERT.TBL." Adding a Display Mode A typical modification to CONVERT.TBL is the addition of a numbered character display mode. For example, your printer file may be customized so that MD 32 is associated with 8-point Helvetica. (Refer to the XyWrite III Plus Reference Guide for information on display modes.) If you want the filter to convert that information into Ventura Publisher format, modify COMMAND TABLE as described below. 1. Call CONVERT.TBL to the screen. 2. Move the cursor to COMMAND TABLE. 3. Enter a new definition line. Type the XyWrite command at the start of the line, followed by an equal sign, and then the Ventura Publisher conversion. For our example: Type: MD32= 4. Add comments if you wish; be sure to precede the comments with a semicolon. 5. Complete steps 2 and 3 of the procedure defined in "Modifying CONVERT.TBL." Changing a Character Substitution Another typical modification of CONVERT.TBL is changing the XyWrite character used to represent a Ventura Publisher character. For example, the default conversion establishes line drawing character ASCII 191 as the representation for a trademark symbol. You can change the ASCII character to be anything you want by modifying the CHAR TABLE section of CONVERT.TBL. For example, to change the representation of trademark from ASCII 191 to ASCII 233: 1. Call CONVERT.TBL to the screen. 2. Move the cursor to the line that defines the trademark character. (Type Alt Shift 191 to enter the ASCII character.) 3. Replace the ASCII 191 symbol with the ASCII 233 symbol. 4. Complete steps 2 and 3 of the procedure defined in "Modifying CONVERT.TBL." Result: When the import filter encounters the character ASCII 191 in your XyWrite file, it converts it to display a trademark in the Ventura Publisher file. CONVERTING FILES Both filter programs convert codes for which they find XyWrite or Ventura Publisher equivalents. If the import filter encounters a XyWrite command that is not supported by Ventura Publisher (e.g., column tables), it omits that command. (Commands not discussed in this application note are not converted.) If the export filter encounters a Ventura Publisher text command that is not recognized by XyWrite, the information is stored in an IV (Invisible) command in the XyWrite file. The IV command, which can be seen in expanded mode only, contains the label $VP$ followed by the unrecognized Ventura Publisher command; if you send the file through the Ventura Publisher import filter, that filter will restore the information to Ventura Publisher format. If you plan to convert your file back to Ventura Publisher format, be very careful not to edit or delete the IV commands. If you do, the Ventura Publisher information will be lost (see Note #3). The following paragraphs explain exactly how the XyWrite to Ventura Publisher conversions are handled for specific commands. Unless otherwise noted, the export filter reverses the action described for the import filter. Note #3 Editing Exported Files. If you want to edit a file that you have exported from Ventura Publisher, and plan to import the file back to Ventura Publisher, we recommend that you make your edits in expanded display mode. Because you can see the IV commands in expanded display, you can avoid accidentally deleting one if you define and delete text. Embedded Commands vs. Default Commands In XyWrite, you can establish your format by embedding commands in your document or by using defaults (either system defaults or user-defined defaults). The XyWrite import filter only converts embedded commands, not default commands. That means you must explicitly define the XyWrite formatting commands in the document Ventura Publisher is going to import. Display Modes The import filter converts most of the XyWrite display modes for which there are two-letter commands. The following table defines the Ventura Publisher text attribute associated with each XyWrite mode that is converted. Ventura Publisher XyWrite Mode Attribute Normal (MDNM) Medium weight Bold (MDBO) Bold weight Underline (MDUL) Underline Reverse (MDRV) Italics Bold Underline (MDBU) Bold underline Bold Reverse (MDBR) Bold Italic Superscript (MDSU) Superscript <^> Subscript (MDSD) Subscript Standout (MDSO) Strikethrough Flashing (MDFL) Overscore Flashing Reverse (MDFR) Italic Underline Redlining The import filter invokes a PE (Put Edit) command on redlined text. PT (Print Type) Tables The COMMAND TABLE section of CONVERT.TBL contains information that converts PT table numbers into font and point size information that Ventura can use. CONVERT.TBL contains sample PTs for your use. The eight PTs in this file correspond to the XyWrite printer file 3POSTPLS.PRN. If you are using a different printer file, you need to modify CONVERT.TBL to reflect the PT tables in that file. You only need to complete this procedure once, unless you change printer files. 1. Call your printer file and make a list of the fonts and point sizes associated with each PT table. 2. Abort the printer file. 3. Refer to Appendix K of the Xerox Ventura Publisher Reference Guide for a list of the typeface names and the ID numbers associated with each. For example, Helvetica has the ID number F2, while Times Roman has the ID number F14. 4. Call CONVERT.TBL to the screen and move the cursor to the COMMAND TABLE section. 5. Review each PT definition to see if it is correct for the printer file you are using. Make any changes necessary by entering the correct font ID (from step 3) and point size. This information is always enclosed in angle brackets (< >); the font definition starts with the letter F, while the point size definition starts with a P. For example, if PT1 in your printer file is defined as 14 point Helvetica, change the line so it looks like this: PT1= ;PT1 Font Helvetica, Point Size 12 6. Store CONVERT.TBL. 7. Complete steps 2 and 3 of the procedure defined in "Modifying CONVERT.TBL." PC Number The PC (Printer Control) command can be converted to the color index of Ventura Publisher. The colors and settings available to Ventura Publisher are: White 0 Black 1 Red 2 Green 3 Blue 4 Cyan 5 Yellow 6 Magenta 7 Reset to 255 tag color Example: If you enter a PC 2 command in XyWrite, the color will be set to be red when you import the file to Ventura Publisher. This color will remain in effect until you reset it with another PC command (e.g., PC 255). Labels XyWrite's LB command allows you to store information as hidden text. Hidden text will not display or print in Ventura Publisher. Although the text will not appear in the Ventura Publisher document, it will still be available to edit in XyWrite. Footnotes The import filter passes footnote text that is embedded in an FN1 (Footnote) command to Ventura Publisher. (FN2 and FN3 commands are ignored.) Ventura Publisher numbers the footnotes by page or by chapter, depending on what you select. Footnotes are then automatically placed at the end of each page. Refer to the Xerox Ventura Publisher Reference Guide for instructions on how to turn on footnotes. FM (Footnote Format), FS (Footnote Separators), and FW (Footnote Wrap) commands are not transferred to Ventura Publisher. Ventura Publisher automatically creates a line which separates the body text from the footnotes. (See Note #4.) Indexing Two levels of indexing can be transferred from XyWrite to Ventura Publisher. For the first level, the import filter passes index entries that are embedded in an X1 (Index Marker) command to the Ventura Publisher file. (X2--X9 commands are ignored.) You must enter the index information by issuing an X1 command and typing your entry either into the text window or onto the command line; unlike XyWrite, the filter does not recognize the word that immediately precedes the X1 command or the line that immediately follows it. (See Note #4.) For the second level, the import filter passes Index Marker (X1) information and Index Label (IL) information. Ventura Publisher interprets these commands and the text that follows them as a primary and secondary index entries. Note #4 Formatting Footnotes, Indexes, and Running Headers and Footers. You can pass mode and font information for footnotes, indexes, and running headers and footers to Ventura Publisher by inserting MD and PT commands within the FN, X1, RHA, and RFA commands. You can pass only the modes and PT tables listed in CONVERT.TBL. For running headers and footers, you can also pass page numbers and chapter numbers by inserting the PN and C0 commands within the RHA or RFA command. Other formatting commands cannot be translated into Ventura from within FN, X1, RHA or RFA. Styles You can use XyWrite's style commands to identify the name of the Ventura Publisher tag you want to invoke. Each tag defines a set of font, alignment, spacing, breaks, tab settings, text attributes, and typographic characteristics for a paragraph. You can create styles in XyWrite that match the tags you establish in Ventura Publisher. To use this feature: 1. Make a list of all the Ventura Publisher tags that you use, and note the settings associated with each tag. 2. Use the SS (Save Style) command to create a XyWrite style for every Ventura Publisher tag you are using (see Notes #5 and #6). For example, you might create a standard body style, a standard tables style, and a standard indent style as follows: Type: F5ss body_text,lm=10,rm=70 Type: F5ss tables,lm=15,rm=65,ts=20,35 Type: F5ss small,lm=25,rm=55,ip=5,0 3. Invoke the tag by typing a US (Use Style) command in the XyWrite document. (See Note #7.) For example: Type: F5us body_text Result: When Ventura Publisher imports the file that contains the US command, it checks to see if a tag of that name exists. If it does, the appropriate formatting is applied to that paragraph. If it does not, Ventura Publisher creates a tag with the specified name, but it does not define any attributes for that tag. Note #5 Style Contents. If you are not interested in formatting your XyWrite document so it resembles the final Ventura Publisher output as closely as possible, you can create a "dummy" style that establishes a tag name but does not contain any formatting commands. Note #6 Style Names. Ventura Publisher allows you to use two words when naming tags. If you want to use this naming convention in XyWrite, use the underscore character ( _ ) as the word separator. Note #7 Style Command Placement. You can enter only one US (Use Style) command per paragraph, and it must be the first thing in the paragraph. If there is text or another formatting command before it (even a mode command which does not appear as an embedded triangle), the filter will ignore the US command. If more than one US command appears on a line, only the first one is recognized. Note #8 Shortcut. For ease of use, you might want to create a file that contains the SS commands (with their associated settings) for all of the tags that you frequently use in Ventura Publisher. This file can then be stored as a Save/Get so you can easily insert all of the available style names in your file. Refer to Chapter 3 of the XyWrite III Plus Reference Guide for instructions on how to create Save/Gets. Chapter Numbering and Page Numbering When you format a XyWrite file, you use the C0 counter for chapter numbering and the PN command for page numbering. Typically, you insert your chapter number or page number in a running header or footer commands (RHA and RFA). It is not possible to directly transfer the RHA or RFA commands to Ventura Publisher's headers and footers, but the information can be transferred if you use styles, and follow this procedure. 1. Make sure CONVERT.TBL contains the setting HEADERS- FOOTERS=YES. (Refer to "Changing User-Definable Settings" for more information.) 2. In XyWrite, use the SS (Save Style) command to create a style name for headers and footers at the beginning of the document. For example: Type: F5ss header Type: F5ss footer These are "dummy" style names; they do not contain any format information. 3. Enter the RHA command to create a running header. Type: F5rha Result: A text window opens on the screen. 4. Enter the US (Use Style) command to invoke the style for your header. For example: Type: F5us header Result: The import filter will convert this style name into a Ventura Publisher tag name. 5. Immediately after the embedded triangle for the US command, enter your header information. For example, if your header is "Chapter #1, Getting Started:" Type: Chapter # Press: F5c0 Type: , Getting Started 6. Close the text window. Press: F3 7. Enter the RFA command to create a running footer. Type: F5rfa Result: A text window opens on the screen. 8. Enter the US (Use Style) command to invoke the style for your footer. For example: Type: F5us footer Result: The import filter will convert this style name into a Ventura Publisher tag name. 9. Immediately after the embedded triangle for the US command, enter your footer information. For example, if your footer contains the word "Page" followed by the page number: Type: Page Press: F5pn 10. Close the text window. Press: F3 Result: In expanded mode, your file should look like this: <>Chapter #<>, Getting Started>> <>Page <>>> 11. With the file still displayed on the screen, run the filter program VPIMPRT.PRG. Result: The filter converts the US commands to tags, the C0 command to the chapter number, and the PN command to the page number. It also transfers the text of the header and footer to Ventura Publisher. When you have loaded the import file into Ventura Publisher, select the Headers and Footers dialog box, and then follow the procedure for automatic section headings described in the Xerox Ventura Publisher Reference Guide. When you've completed that procedure, you'll see that the text you entered after the US commands (in steps 5 and 9 above) appears properly in the Ventura Publisher file as headers and footers. Note that on the first page of the Ventura Publisher file, the header and footer text also appears at the beginning of the body text. You need to delete it from that location before finalizing your document. (See Note #9.) Note #9 Exporting Headers and Footers. If you modify the text of either a running header or footer while you are in Ventura Publisher, that modification will not be reflected if you export the file back to XyWrite. Tab Settings Both XyWrite and Ventura Publisher measure tab settings in inches, and both support left, right, center, and decimal tabs. One difference is that placement of tabs in Ventura Publisher is measured relative to the left margin or column edge rather than the page edge. You might want to change XyWrite's relative tab setting so that your XyWrite document more closely resembles the Ventura Publisher publication. You do this by embedding the RT (Relative Tabs) command in the document you want to import: Type: F5rt 1 There are two methods of using tabs in a XyWrite file that is going to be transferred to Xerox Ventura Publisher. The recommended method, which is also the easier one, is to establish tab settings with a tag. For example, in the XyWrite file you could create a style named TABS that contains the tab settings you want to use (F5ss tabs,ts=5,10,15,24 ) and then use this style. Don't forget to create a tag in Ventura Publisher that contains the same tab settings. The second method is to type tab characters in your XyWrite file and then transfer the file to Ventura Publisher. You will see the graphic representation of a tab character, but the text may not be positioned correctly on the screen. If you type your text and press the tab key, and then type the next few words, there will be enough information for Ventura Publisher to know that there is a tab between words. When you import the file, you will see word˙1Aword˙1A. Then you can identify the type of tab and its location in Ventura Publisher from the Paragraph menu. Refer to the Xerox Ventura Publisher Reference Guide for information on setting tabs. Hyphenation Hyphenation in Ventura Publisher can be turned on or off for any paragraph tag. The default installation sets the hyphenation for US English. Xerox Ventura Publisher's user hyphenation dictionary, called HYPHUSER.DIC, overrides the system hyphenation. XyWrite's hyphenation exception dictionary is a straight ASCII text file. With a few modifications, you can load it into Ventura Publisher so that both products use the same hyphenation exception dictionary. To do this: 1. Call DICTION from your XyWrite directory. 2. Delete the first line (;HY;) 3. Remove all of the asterisks (*) from the file. Type: F5ci /*// 4. Store the file as HYPHUSER.DIC in the Ventura Publisher directory. This will replace the user dictionary supplied by Ventura Publisher. Type: F5st \ventura\hyphuser.dic Result: Ventura Publisher automatically loads this file into memory. (Refer to Appendix B of the Ventura Publisher Reference Guide for hyphenation information.) USING XYWRITE TO CALCULATE PUBLICATION LENGTH When creating a XyWrite file that will eventually be transferred to Ventura Publisher, be sure to load a printer file that contains PT (Print Type) tables for the typefaces and point sizes you plan to use in Ventura Publisher. (See Note #10.) Although the XyWrite/Ventura Publisher filter does not directly transfer all formatting commands, it is possible to use the XyWrite commands (such as leading, hyphenation, line spacing, etc.) to get a close approximation of what your line endings and page breaks will be when Ventura Publisher formats your publication. This is useful if you have to write copy to fit in a certain area or number of pages. Vertical Measurement. XyWrite measures vertically in pages and lines. By default, XyWrite uses six lines per inch. To convert the value in the P-L counter to inches, divide the number of lines by 6. For example, if the P-L counter displays a value of 1-30, it means that the cursor is on page 1, five inches from the top of the page (30/6=5). Note #10 Character Widths. If you are concerned about reviewing line endings in XyWrite, you should modify your printer file's width tables to include widths for the Ventura Publisher characters defined in the CHAR TABLE section of CONVERT.TBL. For example, you need to define the width of the trademark character by assigning its width value to ASCII character 191. Refer to Chapter 6 of the XyWrite III Plus Reference Guide for information on how to modify width tables. ###