XML Professional Publisher: Transforming Data

for use with XPP 9.3 November 2018 Notice © SDL Group 1999, 2003-2005, 2009, 2012-2018. All rights reserved. Printed in U.S.A. SDL Group has prepared this document for use by its personnel, licensees, and customers. The information contained herein is the property of SDL and shall not, in whole or in part, be reproduced, translated, or converted to any electronic or machine-readable form without prior written approval from SDL. Printed copies are also covered by this notice and subject to any applicable confidentiality agreements. The information contained in this document does not constitute a warranty of performance. Further, SDL reserves the right to revise this document and to make changes from time to time in the content thereof. SDL assumes no liability for losses incurred as a result of out-of-date or incorrect information contained in this document. Trademark Notice See the Trademark file at http://docs.sdl.com for trademark information. U.S. Government Restricted Rights Legend Use, duplication or disclosure by the government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or other similar regulations of other governmental agencies, which designate software and documentation as proprietary. Contractor or manufacturer is SDL Group, 201 Edgewater Drive, Wakefield, MA 01880-6216.

ii Contents

Part I Importing and Transforming Text

Chapter 1 Unicode Support in XPP

Working with text and Unicode ...... 1-2 XML/SGML ...... 1-2 ASCII Text ...... 1-3 XyASCII Text ...... 1-3 XSF Text ...... 1-3 The Xyvision Character Set ...... 1-4

Transforming Content from Earlier XPP Versions ...... 1-5 Running the Transformation Process Manually ...... 1-5 Character Transformation ...... 1-5 Page Transformation ...... 1-7 Style Transformation ...... 1-7 Transforming Between ASCII and Unicode ...... 1-7 ASCII File to XSF Summary ...... 1-8 XSF to ASCII Summary ...... 1-9 Using ASCII Files ...... 1-9

Working with ASCII Files ...... 1-10 Default Naming Conventions ...... 1-10 Edit ASCII File or View File as ASCII ...... 1-10

Using Tag Primitives to Separate Text into Streams ...... 1-12 Understanding Tag Primitives ...... 1-12 Using Stream Diversion in the Export Process ...... 1-14

Transforming Data Contents iii Stream Order ...... 1-14 Stream-End Delimiter ...... 1-14 Using Stream Diversion in the Import Process ...... 1-14 Footnote and Pickup References ...... 1-15 Marking Footnotes in ASCII Text ...... 1-16 Marking Pickups in ASCII Text ...... 1-17 Marking Pickup Elements in ASCII Text ...... 1-19 Arguments for Graphic Tag Primitives ...... 1-20 Arguments for Pickup Element Blocks ...... 1-22 Marking Stories in ASCII Text ...... 1-24 Converting Microns to Standard Units ...... 1-24

XSF Text / ASCII Examples ...... 1-26 Example 1: XSF Text ...... 1-26 Example 2: ASCII Text Strings ...... 1-27

Chapter 2 FromXSF and ToXSF

Overview ...... 2-2

Using FromXSF ...... 2-3 Running FromXSF from PathFinder ...... 2-4 Running FromXSF from the Command Line ...... 2-4 Using FromXSF on Multiple Divisions within a Job ...... 2-4 Inserting Header and Trailer Strings With FromXSF ...... 2-6 Inserting Header and Trailer Strings in XML/SGML Mode . 2-7 /FOOT ...... 2-7 /FOOTPG ...... 2-8 Preserving Editing Traces with FromXSF ...... 2-9 Examining a File Containing Trace Xyps ...... 2-9 Using FromXSF in XML/SGML Mode ...... 2-11 Suppressing XPP PI in XML/SGML Mode ...... 2-11 Selecting Type of Output ...... 2-11 Specifying Units for Layout Field Information ...... 2-12

Using ToXSF ...... 2-13 ToXSF Support ...... 2-13 XyASCII ...... 2-13 CJK Characters ...... 2-13 Autoprocessing ...... 2-13 Numeric Character References ...... 2-13 Running ToXSF ...... 2-14 Running ToXSF from PathFinder ...... 2-14 Running ToXSF from the Command Line ...... 2-16 Replace Modes ...... 2-16 Page Replace/Insert/Append Mode (-Rep and -Ret) ...... 2-17 Replacing Main Pages ...... 2-18

iv Contents Transforming Data Inserting Main Pages ...... 2-18 Appending Main Pages ...... 2-19 Replace/Insert/Append Footnotes, Pickups and Stories ... 2-19 Replacing Split Pickups ...... 2-20 Updating Frozen Pickups ...... 2-20 –Rep versus –Ret ...... 2-20 Page Re-Create Mode (–Rec) ...... 2-20 Page Replace Mode (–Rep and –Ret) and Maximum Page Sizes ...... 2-21 Layout Control Designators (–layout and –nofrills) ...... 2-22 SGML Character Entities (–asc) ...... 2-23 ToXSF and Line Endings ...... 2-23 Loop Processing of Input Text (–Ln) ...... 2-24 ToXSF Error Checking ...... 2-24 Legal Non-printing Control Characters ...... 2-25 Missing Begin/End Tag, Xycode, or Tag Primitive Characters . 2-26 ToXSF Page Formats and Sizes ...... 2-27 Footnote Tag Primitives ...... 2-28 ToXSF Help File ...... 2-28 Tag Primitives Help File ...... 2-28

Restoring Divisions ...... 2-29

Chapter 3 XyChange

Understanding XyChange ...... 3-2 An Overview of the Transformation Process ...... 3-2 XyChange/XSLT ...... 3-3 What Do You Need To Transform? ...... 3-3 Setting Up XyChange Transformation Tables ...... 3-4 Running XyChange ...... 3-4 Transformation Types ...... 3-4 Unconditional Transformation ...... 3-4 Conditional Transformation ...... 3-5 Writing Transformation Tables ...... 3-5

Setting Up XPP Transformation Tables ...... 3-7 Completing the Job Ticket ...... 3-7 Creating Files for Transformation Tables, Scripts, and Style Sheets ...... 3-9 Sample Perl Script ...... 3-9 Accessing a Transformation Table, Script, Style Sheet ...... 3-10 Structure of a Transformation Table ...... 3-11 XPP Transformation Table Fields ...... 3-12

Using Match and Output Strings ...... 3-14 Guidelines for Match and Output Strings ...... 3-14

Transforming Data Contents v Escape Sequences in Match and Output Strings ...... 3-15 Escape Sequence Formats ...... 3-16 XSF Characters and ASCII Strings ...... 3-17 Notes on Translating Special XPP Characters ...... 3-19

Running the XyChange Program ...... 3-21 XyChange Processing Sequence ...... 3-21 Guidelines for Running XyChange ...... 3-22 Running XyChange from PathFinder ...... 3-22 Running XyChange from the Command Line ...... 3-24

Sample XyChange Transformation Process ...... 3-26 ASCII File Before Transformation ...... 3-26 Sample Transformation Table Rules ...... 3-27 ASCII File After Translation ...... 3-29 Composed File in Page Mode ...... 3-30

XyChange with Xalan Processing ...... 3-31

Chapter 4 Advanced XyChange Techniques

Using Wildcards in Transformation Rules ...... 4-2 Single-Character Wildcards in Match Strings ...... 4-2 Guidelines for Using Single-Character Wildcards ...... 4-3 Multiple-Character Wildcards in Match Strings ...... 4-4 Guidelines for Using Multiple-Character Wildcards ...... 4-5 Using Wildcards in Output Strings ...... 4-5

Using If True and Then Do Fields ...... 4-7 Guidelines for the If True Field ...... 4-8 Comparative Operators ...... 4-9 Binary Operators ...... 4-9 Unary Operators ...... 4-10

XyChange Variables ...... 4-11 String Variables ...... 4-11 Numeric Variables ...... 4-11 Wildcard Variables ...... 4-12 Using Variables in Setting Test Conditions ...... 4-12 Comparing Variables in If True Expressions ...... 4-12 Using Wildcard Variables in If True and Then Do Fields ... 4-13 Using Wildcard Variables in Output Strings ...... 4-13 Displaying Variable Values ...... 4-14

Quoted Strings ...... 4-17 Guidelines for Using Quoted Strings ...... 4-17 Transferring Numeric and String Variables ...... 4-17

Using the Reinput Command ...... 4-19

vi Contents Transforming Data Guidelines for Using the Reinput Command ...... 4-19 Avoiding Infinite Loops ...... 4-20

Using the Debug Command ...... 4-21

Chapter 5 XSFChange Program

Understanding XSFChange ...... 5-2

Accessing the XSFChange Program ...... 5-3

Understanding The XSFChange Spec ...... 5-5 Fields in the XSFChange Spec ...... 5-5 Output Order of Text Types ...... 5-6 Type of Pickup Element Blocks ...... 5-7 Miscellaneous Output Information ...... 5-8 Transformation Table Location and Name ...... 5-12

Converting Divisions ...... 5-13 Running XSFChange from PathFinder...... 5-13 Running XSFChange from the Command Line ...... 5-13

Viewing the txsfout File ...... 5-14 Sample ...... 5-14

Part II Importing and Transforming Styles

Chapter 6 Importing and Exporting Page Layouts

Layout Control Designators ...... 6-2

Using ToXSF to Import Page Layouts ...... 6-3 Importing Layout Pages with Text ...... 6-3 Importing Layout Pages Only ...... 6-3 ToXSF Command to Import Layout Pages with/without Text . 6-3

Using FromXSF to Export XPP Page Layouts ...... 6-5 Exporting Pages Containing Text ...... 6-5 Exporting Layout Pages Only (Without Text) ...... 6-5 FromXSF Command to Export Layout Pages with/without Text ...... 6-6 ToXSF/FromXSF Layout Control Statements ...... 6-7 Unit Qualifiers ...... 6-7 Page Layout Designator [PAGE] ...... 6-7 Page Layout Copy Control [CPPAGE] ...... 6-8 Frame Layout Control [FRAME] ...... 6-8

Transforming Data Contents vii Block Layout Control [BLOCK] ...... 6-9 Shape Primitive [SHAPE] ...... 6-10 Examples of Layout Control Statements in ASCII Text ...... 6-11 Creating a Division with Text ...... 6-11 Replacing Two Pages in a Magazine ...... 6-12 Defining a Book ...... 6-13

Hints and Troubleshooting ...... 6-15

Chapter 7 Transforming Style Data in XPP

Examples of Importing and Exporting Styles ...... 7-2 Exporting Styles ...... 7-2 Importing Styles ...... 7-4 Original Page Layout Spec ...... 7-4 ASCII Input File with Page Layout Data ...... 7-5 Modified Page Layout Spec ...... 7-6

Understanding XPP and ASCII Style Data Formats ...... 7-7 Format of XPP Style Data ...... 7-7 Format of ASCII Export File ...... 7-7 Format of ASCII Import File ...... 7-9 Descriptor Format ...... 7-11 Command Format ...... 7-12 Examples of ASCII Import Files ...... 7-13

Creating ASCII Style Files for Import ...... 7-14 Field Contents ...... 7-14 Entering Accented Characters in ASCII Fields ...... 7-15

Using the Style Data Editor ...... 7-17

Importing/Exporting XML Style Files ...... 7-18 Import/Export Process Components ...... 7-18 XML Style Files ...... 7-18 Character Encoding and Conversion ...... 7-19 Schema Support ...... 7-20 The Programs ...... 7-20 Sdedit Program ...... 7-20 I/O Style Program ...... 7-21 iostyle.pl ...... 7-22 Style Data File Modification ...... 7-22

Related XPP Specs ...... 7-23

viii Contents Transforming Data Part III Autoprocessing

Chapter 8 Autoprocessing

Understanding Autoprocessing ...... 8-2 Processing Text Files ...... 8-2 Autoprocessing Limitations ...... 8-2 Matching Time and Date on Networked Systems ...... 8-3 Setup Files ...... 8-3 Setting Up Windows Services ...... 8-3 Autoprocessing Configuration Spec (sap config) ...... 8-3 Background Processing Configuration Spec (bgq config) ... 8-3 Monitoring Input Directories ...... 8-4 Processing Input Files ...... 8-4 Reprocessing Input Files ...... 8-6 Autoprocessing File Management ...... 8-6

Setting Up the Autoprocessing Configuration Spec ...... 8-7 Accessing the Autoprocessing Configuration Spec ...... 8-7 Structure of the Autoprocessing Configuration Spec ...... 8-8 Autoprocessing Configuration Spec Fields ...... 8-8 Creating a New Rule ...... 8-11

Process Command Lines ...... 8-13 Process Command Placement ...... 8-13 Process Commands in the Autoprocessing Config Spec .... 8-13 Splitting Process Commands ...... 8-15

Autoprocessing Text Command Lines ...... 8-17 Text Processing Command Format ...... 8-17 Sample Text Processing Command Entries ...... 8-23 Specifying Transformation Tables ...... 8-24 Specifying Arguments for Secondary Text ...... 8-24 Appending Input Text to Existing Division ...... 8-25 Replacing an Existing Division ...... 8-25 Specifying an Alternate Document Root ...... 8-26

Autoprocessing Error Log ...... 8-27

Autoprocessing Graphics Command Lines ...... 8-28 Graphics Processing Command Format ...... 8-28 Sample Graphics Processing command Entries ...... 8-28 Converting TIFF Files ...... 8-28 Converting EPS Files ...... 8-28

Document Processing Interface ...... 8-29 Purpose of Document Processing Interface ...... 8-29 Definition of commz.pl ...... 8-29

Transforming Data Contents ix Command Line Format ...... 8-30 Supported Options ...... 8-31 Examples for Using commz.pl ...... 8-32 Running ToXSF, Compose, and PSFMTDRV Repeatedly ... 8-32 Customizing Processes for Use with XML ...... 8-33 Calling a Custom Script After Document Creation, Conver- sion, and Composition ...... 8-34

Part IV Transforming Alternate Formats

Chapter 9 Transforming Asian Languages

Overview of Asian Language Support ...... 9-2 Transformation Process for Upgrading Sites ...... 9-2 Entering CJK Characters ...... 9-2 Setting OS Locale Setting in XPP 8.x and later ...... 9-3 Supported Asian Language Formats ...... 9-3 Chinese Hong Kong Character Set ...... 9-4

Running the JPCIN Transformation Utility ...... 9-5 JPCIN Transformation Rules ...... 9-5 JPCIN from the Command Line ...... 9-6 JPCIN from PathFinder ...... 9-7 JPCIN with Autoprocessing ...... 9-8

Chapter 10 Importing and Exporting XML/SGML Data

Importing XML/SGML Instances to XPP ...... 10-2 Performing Other Transformations on Import ...... 10-2 Import Tab ...... 10-2 Transform Tab ...... 10-2 Searching for the catalog.xml file ...... 10-3 The Import Process ...... 10-3 Transforming Content to UTF-8 ...... 10-3 Searching for the omnimark.lib file ...... 10-4 Public or System Identifier ...... 10-4 Parsing the XML/SGML Instance ...... 10-4 Importing the file to XPP ...... 10-5

Options for Importing XML/SGML Instances to XPP ...... 10-10

Enabling XML/SGML Transformation ...... 10-11 XCS Spec ...... 10-11 XCS Header Fields ...... 10-11

x Contents Transforming Data XCS Body Records ...... 10-12 Job Ticket ...... 10-13 Division Ticket ...... 10-13

Transforming a Division to an Output File ...... 10-14 Transforming the XPP Division ...... 10-14 FromXSF Tab ...... 10-14 FromXSF Processing ...... 10-15

FromXSF Options ...... 10-16 Transforming ASCII to Other Formats ...... 10-17 Export Tab ...... 10-17 Transform Tab ...... 10-17

Appendix A Xyps and System Codes

Xyp and System Code Tables ...... A-2 Xyps ...... A-2 System Codes ...... A-6

Xyp and System Code Classes ...... A-8

Line End Types ...... A-9

Appendix B XCS Assignments for XML/ SGML Character Entities

Glossary

Index

Transforming Data Contents xi Figures

3-1 XyChange fields in the Job Ticket ...... 3-7 3-2 Transformation Table ...... 3-11 3-3 ASCII File Before Transformation ...... 3-26 3-4 Transformation Table Rules ...... 3-27 3-5 ASCII File After Transformation ...... 3-29 3-6 Composed File in Page Mode ...... 3-30

5-1 Sample XSFChange Program Spec ...... 5-5 5-2 Sample txsfout File Containing All Codes ...... 5-15 5-3 Sample txsfout File Containing End of Line Codes ...... 5-16 5-4 Sample txsfout File Containing Math Codes ...... 5-17

6-1 ASCII Input File named tsample1 ...... 6-11 6-2 ASCII Input File Named tsample2 ...... 6-12 6-3 ASCII Input File Named tsample3 ...... 6-13

7-1 Sample Item Format Spec ...... 7-2 7-2 ASCII File Containing Exported Item Format Data ...... 7-3 7-3 Sample Page Layout Spec ...... 7-4 7-4 Sample ASCII File to Import Page Layout Style Data ...... 7-5 7-5 Sample Page Layout Spec After Modification ...... 7-6 7-6 Format of ASCII Export File ...... 7-8 7-7 Format of ASCII Input File ...... 7-9 7-8 Vuem Characters ...... 7-16

8-1 Sample Autoprocessing Configuration Spec (SAP) ...... 8-8

xii Contents Transforming Data Tables

1-1 Automatic Transformation of XCS Characters to Unicode ...... 1-6 1-2 List of XPP Tag Primitives in Classic Mode ...... 1-12 1-3 List of XPP Tag Primitives in XML/SGML Mode ...... 1-13 1-4 Footnote and Pickup Anchors ...... 1-15 1-5 Footnote Tag Primitive Arguments ...... 1-16 1-6 Arguments for Pickup Tag Primitives ...... 1-17 1-7 Arguments for Graphic Tag Primitives ...... 1-20 1-8 Arguments for Caption, Annotation, and Title Element Blocks .. 1-22 1-9 Arguments for the Story Tag Primitive ...... 1-24

3-1 XyChange Command Set Characters ...... 3-17 3-2 Xyvision Characters and Their ASCII Sequences ...... 3-17

4-1 Examples of Single-Character Wildcards ...... 4-3 4-2 Format of a Multiple-Character Wildcard ...... 4-4 4-3 Examples of Multiple-Character Wildcards ...... 4-5 4-4 Comparative Operators ...... 4-9 4-5 Binary Operators ...... 4-9 4-6 Unary Operators ...... 4-10 4-7 Examples of Valid If True Tests ...... 4-13 4-8 Format of the Variable Output String ...... 4-14 4-9 Examples of Displaying the Contents of Variables ...... 4-16 4-10 Examples of Quoted Strings in If True and Then Do Fields ..... 4-18 4-11 Examples of the Reinput Command in Then Do Fields ...... 4-19

5-1 Tag Primitives ...... 5-8

6-1 Layout Control Designators ...... 6-2 6-2 Options to Import Page Layouts ...... 6-4 6-3 Switches to Export Page Layouts ...... 6-6 6-4 Problem/Solutions ...... 6-15

7-1 Format of Descriptor Entries ...... 7-11 7-2 Format of Command Entries ...... 7-12 7-3 Character Conversion during XML Style Import/Export ...... 7-19 7-4 XPP Style Spec Mnemonics ...... 7-23

8-1 Options for new-div, convert, compose, and queue ...... 8-18 8-2 Options for convert and compose ...... 8-19 8-3 Options for compose ...... 8-20 8-4 Options for queue ...... 8-21 8-5 Options for Special Occasions ...... 8-23 8-6 Some New Options for commz.pl ...... 8-31

10-1 Comparison of Tag Primitives ...... 10-7

Transforming Data Contents xiii A-1 Xyps ...... A-2 A-2 System Codes ...... A-6 A-3 Xyps and System Code Classes ...... A-8 A-4 Line End Types ...... A-9

xiv Contents Transforming Data About This Manual

Transforming Data describes how to change text, styles, and graphics from formats created on other systems to formats that XPP uses.

This manual addresses the following topics: • Supporting Unicode in XPP • Transforming text with the ToXSF and FromXSF utilities • Transforming text with the XyChange option • Using XSFChange • Importing and exporting page layouts • Transforming styles with the ToStyles/FromStyles functions • Automating the transformation process using autoprocessing • Working with Asian languages • Importing and exporting XML/SGML data

Transforming Data About This Manual xv Where Do I Start?

...... Where Do I Start?

This manual is intended for anyone who needs to import data from elsewhere into XPP. It combines conceptual information with detailed procedures for accomplishing specific tasks.

Before using this manual, you should be familiar with XPP publishing software and its system commands. If you are not familiar with these, refer to the appropriate XPP or system documentation.

If you are . . . Read this... Working with text only Chapter 1 Learning to import and export ASCII text Chapter 2 Learning XyChange techniques Chapter 3 Learning advanced XyChange techniques Chapter 4 Using XSFChange Chapter 5 Importing and exporting page layouts Chapter 6 Importing and exporting style data Chapter 7 Automating the transformation process Chapter 8 Importing Asian Languages Chapter 9 Importing files containing XML/SGML markup Chapter 10

xvi About This Manual Transforming Data Conventions Used in This Manual

...... Conventions Used in This Manual

This manual uses a set of symbolic, typographic, and terminology conventions to categorize specific information. Take a few moments to become familiar with these conventions before you use this manual.

Convention Description Bold Bold type, used in procedures, indicates the object of the action. It may be a menu option, a push button, or a field, and so forth. For example, “select Open” means select the menu option called Open. Position cursor means to move the cursor to a specific location. Enter appropriate information means that you enter information that is appropriate for your site or for the specific job. Bold may be used elsewhere in the manual to denote emphasis. Key Capital first letter and the word “key” indicates a key on the keyboard. Capital first letter and the words “Softkey menu” indicate the menu pad to the right of the XyView. Unless otherwise indicated, this manual assumes that you press the Enter key at the end of a command line. Key+Key This sequence indicates a Shortcut Key combination. Hold down the first key while also pressing the second key, that is ALT+F4 means to hold down the Alt key while also pressing the F4 key. Message A monospaced typeface indicates an application’s response to your action. For example, “the message Enter Value appears” means that the application displays the words “Enter Value.” Italics In running text, an italic typeface indicates a new term; for example, “The replacement string of characters is the output string.” In a system message, a field entry, or an argument to a command, an italic typeface indicates a variable. For example, filename is a variable in the message “Can’t open filename.” Italics are also used for the names of programs, such as Perl. “ ” Quotation marks indicate that you should enter exactly what the instructions tell you to enter. For example, type “yes” means to type the letter y, the letter e, and the letter s. ÒÚ Reverse-video square brackets represent tags in standard XPP. Tags are general-purpose commands defined in the Item Format Spec and embedded in a document. They generally format logical components of text, such as chapter openings, headers, or lists. For example, the tag for beginning a chapter might be Ò chap Ú.

Transforming Data About This Manual xvii Conventions Used in This Manual

Convention Description Ô  Reverse-video angle brackets represent XPP-supplied macros (XyMacros) and user-defined macros. XyMacros are commands embedded in text to set or change formatting or typographic style. For example, the XyMacro to end a page is Ô ep . Reverse-video angle brackets also represent tags when you use XPP in either XML or SGML mode. Note that when in XML or SGML mode, XPP does not use the conventional reverse-video square brackets. Ô?xxx Reverse-video angle brackets with a beginning question mark represent macros when using XPP in SGML mode. Ô?xxx? Reverse-video angle brackets with a beginning and ending question mark represent macros when using XPP in XML mode.

When entering values for some arguments in macros and for some fields in specs, you must qualify the value by specifying a unit of measure. The available unit qualifiers are:

• q — Points • p — Picas • c — Ciceros • d — Didots • i — Inches • m — Millimeters • k — Kyus • n — Microns (XPP units) • z — Centimeters

For example, 6q means 6 points, 4p means 4 picas.

Note: You can also use pc, pt, in, mm, and cm in fields where the system allows the standard ISO unit abbreviations.

xviii About This Manual Transforming Data For More Information

...... For More Information

This manual is part of a comprehensive XPP document set. Other documents describe topics such as:

• Basic skills needed to be productive using XPP. • Tables, document styles, fonts, XyMacros, and system administration. • Optional applications, such as CITI, Loose-leaf, Mark Trace, and Math.

Refer to the XML Professional Publisher: XPP Document List, located on the XPP software CD for UNIX®/Linux® and under /XyEnterprise/XPP/ documentation for Windows®, for complete details on document titles and descriptions.

Transforming Data About This Manual xix xx About This Manual Transforming Data Part I

Importing and Transforming Text

Chapter 1

Unicode Support in XPP

XPP provides full internal support for Unicode.

This chapter discusses the following topics:

• Formats recognized by XPP • Relationship of Unicode to ASCII • ToXSF, the program that transforms ASCII text to Unicode and places the text in an XPP division. • FromXSF, the program that transforms Unicode in an XPP division to an ASCII text file, if required. • Tag primitives, the mechanism XPP uses to separate text into streams

Transforming Data Unicode Support in XPP 1-1 Working with text and Unicode

...... Working with text and Unicode

In previous versions of XPP, using text transfer and conversion utilities that are part of the XPP system (ToXSF, FromXSF, and XyChange), you could transform virtually any text into a form that XPP can use with a minimum of operator intervention.

In those earlier versions, the text in XPP divisions was stored as Xyvision Standard Format (XSF), a proprietary format, consisting of ASCII text characters, additional XPP characters, and XPP-specific format and typographic codes.

XPP provides full internal support for Unicode: XPP stores all characters as Unicode and is able to process Unicode characters directly, regardless of which XPP mode you are using—classic, SGML, XML, or CSS-XML

Unicode is the text encoding that the XML standard specifies. If you are using XML data with XPP, your content moves in and out of XPP using ToXSF and FromXSF. You do not need to be concerned about other formats. If you have used previous versions of XPP and currently process content in classic mode, or have written tools based on XyASCII, you can continue using XPP as you have been accustomed to doing, without disruption.

In addition to Unicode, XPP recognizes the following text formats:

• Standard ASCII text • XyASCII text (for backward compatibility) • Xyvision Standard Format (XSF) text (for backward compatibility) • CJK characters (refer to Chapter 9 in this manual for information)

When you import data into an XPP division, XPP automatically transforms the characters in the file to Unicode, and stores them as UTF-8. Conversely, if you need to transform a division from Unicode to XyASCII, XPP transforms the Unicode characters back to their 1-3 XCS escape sequences.

XML/SGML

XML (eXtensible Markup Language) and SGML (Standardized General Markup Language) are language standards that define how to use sets of tags that describe how to mark up elements found in documents. The default encoding for these tags used in XML and SGML is Unicode. XPP provides a number of features to support working with XML and SGML.

XPP also supports the use of Cascading Style Sheets as a mode to enable CSS formatting of XML content (CSS-XML).

1-2 Unicode Support in XPP Transforming Data Working with text and Unicode

You can locate more information on using XML/SGML in XPP in the XML Professional Publisher: XML/SGML Reference manual and more information on CSS-XML in the XML Professional Publisher: Styling Content with CSS.

ASCII Text ASCII (American Standard Code for Information Interchange) is a standard set of characters that most computer systems use to define textual data and to transfer text between different computer systems. The standard 7-bit ASCII character set contains the following 128 characters:

• 26 uppercase and 26 lowercase alphabetical letters • Decimal digits from 0 to 9 • Punctuation marks and operators • 32 non-displayed control characters

XyASCII Text A XyASCII file is an ASCII file containing text strings that are XPP- compatible, that is, the XPP text import program, ToXSF, recognizes the text strings (also known as escape sequences). When you import a XyASCII file, the ToXSF program identifies the escape sequences and transforms them directly to the correct Unicode character in the Xyvision Character Set Spec.

XyASCII provides a way to represent more characters than standard ASCII can contain. The ability to export and import XyASCII in XPP continues to be a useful way to reproduce content being processed in XPP in a form that can be manipulated with transformation tools like XyChange.

XSF Text Xyvision Standard Format (XSF) is a proprietary format that consists of XPP specific codes and characters in addition to ASCII characters. Xyvision Character Set (XCS) is the name given to these XSF codes and characters. They are defined in the XCS Spec, located in the syslib library. The XCS Spec provides the link between Unicode character numbers and the XSF numbers.

Transforming Data Unicode Support in XPP 1-3 Working with text and Unicode

The Xyvision Character Set

The XCS Spec defines standard alphanumeric characters, accents, foreign characters, math and chemical symbols, special characters such as company logos, and format codes such as tags, macros, text stream elements, and entities, all mapped to their Unicode values. Any characters not represented in the official Unicode standard are mapped to a user-defined area set aside for just that purpose by the Unicode standard.

When you transform a text file to or from Unicode, the transformation program refers to the XCS Spec to perform the following tasks:

• To support the initial transformation of XSF divisions to the Unicode- based application • To look up character entity names • To back up the XyASCII 3-letter escape sequences

To examine the Xyvision Character Set Spec from PathFinder:

• Click Style Libraries (Tree View) > Lsyslib (Tree View) > Xyvision Character Set (Tree View) > Specific spec (List View) For additional information on the Xyvision Character Spec or for an explanation of the spec, refer to XML Professional Publisher: Fonts.

1-4 Unicode Support in XPP Transforming Data Transforming Content from Earlier XPP Versions

...... Transforming Content from Earlier XPP Versions

XPP contains automatic transformers to change XCS numbers to their Unicode equivalents. Opening style files or division pages for the first time in XPP triggers the automatic transformers. Once transformed, XPP stores and displays all XCS characters as Unicode.

Although this dynamic transformation happens automatically each time you open an XPP job, division, or spec that existed in a previous version of XPP, it happens quickly. However, if you wish to transform your content from earlier XPP versions all at once, you can elect to run the transformation process manually.

Running the Transformation Process Manually

By scheduling the transformation process for off-peak hours, you can save some initial startup time when editing or batch composing previous XPP version’s untransformed documents.

To run the Transformation Process manually:

• Enter cnv_tree on the command line. XPP batch transforms the documents as follows:

• If you are at the document root handle or top-level spec library directory, cnv_tree transforms all the data below. • If you are in a specific job or library, cnv_tree transforms all the divisions of that particular job, or all the specs in that library. • If you are in a division, cnv_tree transforms only that division.

Character Transformation

XPP 8.x and later transforms all XCS characters to Unicode by looking up the Unicode value in the XCS Spec. There may be XCS numbers that do not have Unicode equivalents. In this case, XPP maps the XCS numbers to the Unicode Private Use Area-A (0xF0000-0xF7FFF).

The Private Use Area is a reserved range of Unicode characters that an application can use for its own purposes. Mapping XCS into this range means that these unmapped XCS characters without Unicode equivalents are effectively a subset of Unicode. This transformation ensures that all non-standard or unmapped XCS characters can reliably flow through the system as Unicode and maintain their proper glove output. For example, if XCS #146 (florin) does not have a Unicode equivalent, XPP transforms it to 0xF0092, which is 0xF0000+0x92, where 0x92 is 146 decimal.

Transforming Data Unicode Support in XPP 1-5 Transforming Content from Earlier XPP Versions

XPP automatically transforms a few XCS characters to their Unicode number, regardless of whether they are in the XCS default Spec. For example, text minus has been moved to its Unicode position and the XCS hyphen has been moved to the ASCII position. The following table documents this transformation:

Table 1-1 Automatic Transformation of XCS Characters to Unicode

Former XCS # (decimal) Name New Unicode (hex)

23 EN Dash x2013

24 EM Dash x2014

25 Hyphen x2d (d45)

26 Unit Space x200a

27 Figure Space x2007

28 Thin Space x2009

29 EN Space x2002

30 EM Space x2003

45 Text Minus 2212

1219 Spacing Circumflex x5e (d94)

1218 Spacing Tilde x7e (d126)

SDL recommends that, when upgrading from pre-XPP 8.0, you use the delivered XCS Spec. If you have added custom characters to your XCS Spec over time, you should add these to the newly delivered XCS Spec.

It is possible to use your existing XCS Spec, but over time you will want the complete mapping of Unicode characters SDL delivers. Taking the time to add your custom characters to the delivered XCS Spec now ensures your ability to handle the full Unicode character set as your work flow evolves to include more Unicode content.

For best results, you should merge custom characters into the delivered XCS file (or merge the latest updated XCS Spec into your real XCS Spec) before you upgrade from pre-XPP 8.0. Refer to XML Professional Publisher: XPP Installation and Upgrade Guide for Windows or XML Professional Publisher: XPP Installation and Upgrade Guide for UNIX/Linux for information on upgrading your XCS Spec.

1-6 Unicode Support in XPP Transforming Data Transforming Content from Earlier XPP Versions

Page Transformation

When you first access a pre-XPP 8.x division, XPP transforms each page in the document to Unicode. XPP transforms all XCS characters on each line to Unicode, using the algorithm stated in the “Character Transformation” section on page 1-5.

Style Transformation

When you first access any style file containing XCS characters, XPP automatically transforms the XCS characters to Unicode. The Style files have two basic uses for XCS numbers:

• XSF strings (IF, KB, PL, PS, RP, T5, XX, XY, MX, CI Specs) • XCS numbers (PSF, PTS, FGX, EDG, HJ, KP, MG, MS, T4, KB, HT, PSN Specs)

In either case, XPP transforms each XCS number to Unicode and places it back into the field within its Style file. Following the transformation, all references to XCS characters are based on its new 32-bit Unicode number, there are no visible changes when displaying XCS string data.

Transforming Between ASCII and Unicode When you transform an XPP Unicode division to an ASCII file, the FromXSF program (From XSF to ASCII) transforms Unicode characters to corresponding XyASCII strings, consisting of one, two, or three characters, or, if in XML/SGML mode, into Entities as defined in the XCS Spec. For example:

• The uppercase letter A (x41) transforms to an uppercase letter A in ASCII. • The em-dash (— or x2014) transforms to \M in ASCII. • The one-half symbol (½ or xbd) transforms to |n$ in ASCII. • The ampersand (& or d38) transforms to the entity amp.

The reverse occurs when you transform text from ASCII to Unicode—the ToXSF program turns XyASCII strings into Unicode characters. For example:

• The ASCII uppercase letter A transforms to an uppercase letter A (x41). • The ASCII string \M transforms to an em-dash (— or x2014).

Transforming Data Unicode Support in XPP 1-7 Transforming Content from Earlier XPP Versions

• The ASCII string |n$ transforms to a one-half symbol (½ or xbd). • The entity amp transforms to the ampersonad (& or d38).

XPP uses the XCS Spec to assign special functions to certain ASCII characters. For example:

• The ASCII percent sign (%) transforms to a Pgraf mark (¶), XCS 16. • The two-character ASCII string, backslash percent sign (\%), transforms to a percent sign (% or x25). • The ASCII less-than character (<) transforms to a begin macro symbol (Ô), XCS 18. • The three-character ASCII string, pipe uppercase L lowercase d, (|Ld) transforms to a math less-than symbol (<), XCS 992.

If the ASCII file contains a string that does not appear in the XCS Spec, the ToXSF program cannot transform the string. When this happens, the program continues to process the file and outputs a message telling you the file contains an invalid escape sequence.

When XPP completes the transformation process, you can edit the division, using the XyView to locate and correct the invalid escape sequences. You can also correct the source file using the ASCII editor of your choice.

ASCII File to XSF Summary The ToXSF transformation process consists of three basic steps:

1. Examine the ASCII file to identify the characters and format codes. You can examine the file by viewing, printing or editing it.

2. If the file contains characters and codes that XPP does not recognize, that is, the ASCII strings do not appear in the Xyvision Character Set Spec, run the XyChange translation program to transform the strings to XyASCII.

3. Run the ToXSF program to transform the XyASCII strings to Unicode characters and codes and place the text in an XPP division. You can run the ToXSF program by issuing the toxsf command at the operating system command line or by using the Import process from PathFinder. For additional information concerning the Import process using PathFinder, please refer to XML Professional Publisher: User Guide.

1-8 Unicode Support in XPP Transforming Data Transforming Content from Earlier XPP Versions

XSF to ASCII Summary The FromXSF transformation process consists of two basic steps:

1. Run the FromXSF program to transform Unicode characters and codes into XyASCII strings, and place the text in an ASCII file in the division directory.

2. Run the XyChange translation program to send the ASCII file into a different format to transform the ASCII strings into coding and character access codes recognized by another application. You can run FromXSF by issuing the fromxsf command at the operat- ing system command line or by using the Export process from PathFinder. For additional information concerning the Export process using PathFinder, please refer to XML Professional Publisher: User Guide.

Using ASCII Files

If you are using ASCII files to import content into XPP, the following sections describe the constructs necessary to achieve specific formatting results in XPP.

Transforming Data Unicode Support in XPP 1-9 Working with ASCII Files

...... Working with ASCII Files

You can bring files into XPP using the file transfer method of your choice. You can place these files in any location; and, you can name the ASCII files whatever you choose. However, when working with ASCII files, SDL suggests that you use the default naming conventions.

Default Naming Conventions

Although you can name your ASCII file following any convention, SDL suggests that you use one of the following default conventions:

• t*.* • t* • *.txt • *.log

These naming conventions display automatically in the Files of Type field in the Browse list box in PathFinder. Following one of these suggested naming conventions allows you to locate your file more easily.

Note: If you choose to use a naming convention other than the ones suggested here, be sure to change the Files of Type text box to “All Types” so you can view your files when you use the Browse list box.

Edit ASCII File or View File as ASCII Through PathFinder, you can:

• Edit ASCII File • View File as ASCII

When you choose Edit ASCII File, you directly edit the chosen file without any conversion of control codes (binary data). It is expected that the chosen file will be ASCI (or Unicode if using the Notepad editor).

When you choose View File as ASCII, XPP uses the ttinput program to transform the chosen file to a temporary file. having converted the control codes (binary data) to ttinput ASCII representations so you can view them. Since the ttinput program converts all control codes, including new line codes, such as carriage returns, in Notepad, to ttinput representations, you should not use View File as ASCII to edit files. XPP deletes the temporary file that was created when you exit the editor. . You can also edit the file when you choose to view the text as ASCII.

1-10 Unicode Support in XPP Transforming Data Working with ASCII Files

To select Edit ASCII File or View File as ASCII from PathFinder:

1. Right-click the division containing the file you want to edit in the PathFinder List View (right pane). XPP displays a pop-up menu.

2. Click Division Tools. XPP displays a submenu.

3. Click Edit ASCII File—to directly edit the file. —or— Click View Text as ASCII—to display the text with the control codes visible. XPP displays the Select File dialog box. 4. Select the file you want to open. On UNIX, XPP opens the ASCII file in Notepad. On Windows, XPP opens the program associated with the ″Open″ function of the file extension of the file you select. For the .txt extension, this is usually Notepad.

Note: When using Edit ASCII File with a file that contains control codes (binary data), whether the control codes display in the editor depends on the editor program you use.

Transforming Data Unicode Support in XPP 1-11 Using Tag Primitives to Separate Text into Streams

...... Using Tag Primitives to Separate Text into Streams

XPP uses the concept of streams to separate the various elements of a document, which include main, footnote, story, and pickup. Main is the default stream. You can also send parts of files into footnote, story, or pickup streams. And, within a pickup stream, you can further specify that an element is a caption, annotation, title, or graphic. ToXSF puts these appropriately identified elements into their respective streams.

XPP uses special tags called tag primitives to create these various types of streams.

Understanding Tag Primitives Tag primitives are not the same type of tags as IF tags that give formatting instructions to XPP. Nor are they XML or SGML tags. Rather, they are tags that allow XPP to assign different components of a file—main, story, footnote, pickup— to their appropriate streams. They can be considered processing instructions in XML or SGML. You can recognize a tag primitive by its particular construction:

• The name begins with a slash (/) in classic mode or, in XML/SGML mode, it occurs as an XPP processing instruction. • It is written in uppercase letters.

The following is an example of a tag primitive in classic mode: {/PICK;...}

The following are examples of a tag primitive in XML mode: and

XPP recognizes the following tag primitives:

Table 1-2 List of XPP Tag Primitives in Classic Mode

Tag Primitive Marks the start of: End Delimiter

/MAIN Main text stream (optional). \. (optional) Use /MAIN with special page replacement options.

/FOOT Footnote stream \.

1-12 Unicode Support in XPP Transforming Data Using Tag Primitives to Separate Text into Streams

Table 1-2 List of XPP Tag Primitives in Classic Mode (Continued)

Tag Primitive Marks the start of: End Delimiter

/PICK Pickup stream \.

/CAPT Caption element in the Pickup stream N/A

/ANNT Annotation element in the Pickup N/A stream

/TITL Title element in the Pickup stream N/A

/GRAPH Graphic element in the Pickup stream N/A

/STORY Story stream \.

Note: /CAPT, /ANNT, /TITL, and /GRAPH must be nested inside /PICK and its closing (\.).

Table 1-3 List of XPP Tag Primitives in XML/SGML Mode

Tag Primitive Marks the start of: End Delimiter

xpp MAIN Use xpp MAIN with special page xpp /MAIN replacement options. (optional)

xpp FOOT Footnote stream xpp/FOOT

xpp PICK Pickup stream xpp/PICK

xpp CAPT Caption element in the Pickup stream N/A

xpp ANNT Annotation element in the Pickup N/A stream

xpp TITL Title element in the Pickup stream N/A

xpp GRAPH Graphic element in the Pickup stream N/A

/xpp STORY Story stream xpp /Story

Note: xpp CAPT, xpp ANNT, xpp TITL, and xpp GRAPH must be nested inside xpp PICK and its closing (xpp /PICK).

XPP uses this concept of streams in both the Export and Import processes when using XPP in standard mode as well as in XML/SGML mode.

Transforming Data Unicode Support in XPP 1-13 Using Tag Primitives to Separate Text into Streams

Using Stream Diversion in the Export Process

When you export a division from XPP by running FromXSF, the program inserts tag primitives into the XyASCII file that identify the type of stream to which the document element should go. FromXSF also places a stream- end delimiter at the end of the text.

Stream Order The default behavior of the FromXSF program is to output streams in the following order:

1. Main text

2. Stories

3. Footnotes

4. Pickups — including all pickup elements

You can set FromXSF options to control the order of text streams either from the command line or in the Command Options text box on the FromXSF tab of the Export dialog box.

For additional information on running FromXSF from the command line, refer to the manual XML Professional Publisher: Command Line Utilities.

For additional information on running FromXSF from PathFinder, refer to the manual XML Professional Publisher: User Guide.

Stream-End Delimiter In classic mode, XPP uses a backslash followed by a period (\ .) to mark the end of a stream in an ASCII file.

In XML/SGML mode, XPP uses an ″end″ processing instruction macro to mark the end of a stream.

When you run FromXSF, the program inserts a stream-end delimiter at the end of each footnote, pickup, and story to separate one footnote, pickup, or story from the next one.

Using Stream Diversion in the Import Process

When you import a document by running ToXSF, the file must already have the elements—main, story, footnote, pickup— properly identified by tag primitives and separated by stream delimiters.

1-14 Unicode Support in XPP Transforming Data Using Tag Primitives to Separate Text into Streams

ToXSF creates a division with the identified elements and continues sending text to a stream until it encounters a stream-end delimiter or a new tag primitive.

Note: ToXSF checks the input file for missing begin/end characters and outputs an appropriate message. Please see the section “ToXSF Error Checking” in Chapter 2 of this manual for a complete list of the error messages. When you run ToXSF, streams in the input file can be in any order.

If you are working in XML/SGML mode, XPP continues to use the concept of streams to separate the various elements of an instance. In the case of importing an XML/SGML instance, the document has its own markup to indicate whether an element is main text, a footnote, a pickup, or a story. Please refer to the section “Tag Primitives” in Chapter 10, “Importing and Exporting XML/SGML Data”, for information on the appropriate markup.

Footnote and Pickup References To place footnotes and pickups in a division, insert ASCII strings in main text that correspond to Ô foot  and Ô pick  reference XyMacros.

• Compose places footnotes at the bottom of the block or page, as defined in the Pagination Style (PS) Spec. • Compose places pickups according to the anchor in the pickup reference XyMacro, or according to the /PICK x-position and y- position (for frozen pickups) in classic mode.

The format of these reference XyMacros in classic mode is: Ô foot;name;ref-style  Ô pick;name;ref-style;anchor;1stTry/2ndTry/3rdTry/4thTry 

Table 1-4 Footnote and Pickup Anchors

Argument Description Valid Entries

name Footnote or pickup name Up to 64 characters for the name of the footnote or pickup (required)

[ref-style] Print style for reference • none (default for pickups) mark • an (default for footnotes) • character string

Transforming Data Unicode Support in XPP 1-15 Using Tag Primitives to Separate Text into Streams

Table 1-4 Footnote and Pickup Anchors (Continued)

Argument Description Valid Entries

[anchor] Type of pickup anchor • 0 or float • 1 or here • 2 or before • 3 or suspend • 4 or bound • 5 or bfloat • 6 or bhere • 8 or bsuspend • 10 or bbfloat

[1st/2nd 1st, 2nd, 3rd and 4th • def (use default PS rule) /3rd/4th] preferred placement • 3-char string locations for the pickup.

Marking Footnotes in ASCII Text To send text to the footnote stream in classic mode, insert a /FOOT or /FOOTPG tag primitive at the start of the text in the ASCII file. For each footnote tag primitive, insert a \. (stream-end delimiter) at the end of the text. If you do not specify a name, the program generates default footnote names — f1, f2 and so on. (Best practice is to supply your own unique name.) The track argument is optional and corresponds to the field in the XPP footnote creation window. There are two Track fields in the Pagination and Styles Spec. You can use both fields, having each Track field number footnotes independently and/or place them differently, using different separators. The format of a footnote tag primitive in classic mode is: {/FOOT; name; track} or {/FOOTPG; name; ppos; track}

Table 1-5 Footnote Tag Primitive Arguments

Argument Description Valid Entries

[name] Footnote name Up to 64 characters (uppercase, lowercase, numbers, and # + - _) that uniquely name the footnote. If you do not assign a name, the program generates default names, for example, f1, f2 and so on.

1-16 Unicode Support in XPP Transforming Data Using Tag Primitives to Separate Text into Streams

Table 1-5 Footnote Tag Primitive Arguments (Continued)

Argument Description Valid Entries

[ppos] Footnote page position. This argument causes the output of This is the second the footnote text associated with the argument for /FOOTPG. /FOOTPG to occur on the same page as it does in the original division.

[track] Footnote track number Independent numbering sequences for each track. • 1 (default) • 2

Marking Pickups in ASCII Text To send text to the pickup stream in classic mode, insert a /PICK tag primitive at the start of the stream in the ASCII file. A pickup is a text exclusion area only; enter text and graphics in element blocks within the pickup stream. For each /PICK tag primitive, insert a stream-end delimiter (\.) at the end of the stream, after all the pickup elements. If you do not specify a name, the program generates default pickup names — p1, p2 and so on. (Best practice is to supply your own unique name.) Other arguments are optional and correspond to fields in the XPP pickup creation window and the PS Spec. The format of the pickup tag primitive in classic mode is: {/PICK; name; width; depth; scope; 1stTry; 2ndTry; keepout; order; track; x-orig; y-orig; pg-froz; rot-amt; rot-dir; PS#;3rdTry;4thTry}

Table 1-6 Arguments for Pickup Tag Primitives

Argument Position Description Valid Entries

[name] 1 Name of the pickup Up to 64 characters (uppercase, lowercase, numbers, and # + - _) that uniquely name the pickup. If you do not assign a name, the program generates default pickup names, for example, p1, p2 and so on.

[width] 2 Width of the pickup • full (default) • comptd • qualified number

Transforming Data Unicode Support in XPP 1-17 Using Tag Primitives to Separate Text into Streams

Table 1-6 Arguments for Pickup Tag Primitives (Continued)

Argument Position Description Valid Entries

[depth] 3 Depth of the pickup • comptd (default) • qualified number

[scope] 4 Placement of • block (default) pickup relative to • page the block or page

[1st-try] 5 Preferred placement • default (default) of the pickup • 3-character string (ex: alt) Block/page: a (any), c (current), n (next), r (right), l (left) Horizontal: l (left), c (center), r (right), i (inside), o (outside) Vertical: t (top), c (center), b (bottom) • xxx - force placement to next block or page.

[2nd-try] 6 Second preferred See 1stTry field. placement of the pickup

[keepout] 7 Keepout area (white • default (default) space) of • ss, fs, sf, or ff surrounding text and other pickups

[order] 8 Place pickups in the • no (default) order requested by • yes the reference XyMacro

[track] 9 Pickup track Independent numbering sequences number for each track. • 1 (default) • 2, 3, 4, or 5

[x-orig] 10 X-position • 0 (default) (horizontal • qualified number (frozen pickup placement) of a only) frozen pickup

[y-orig] 11 Y-position (vertical • 0 (default) placement) of a • qualified number (frozen pickup frozen pickup only)

1-18 Unicode Support in XPP Transforming Data Using Tag Primitives to Separate Text into Streams

Table 1-6 Arguments for Pickup Tag Primitives (Continued)

Argument Position Description Valid Entries

[pg-froz] 12 Page number for a For frozen pickups, an integer from frozen pickup 1 (default) to the maximum number of pages in the division. For a frozen pickup, the X-orig and Y-orig fields must contain a value.

[rot-amt] 13 Degree of rotation • 0 (default) for the pickup • 90, 180, or 270

[rot-dir] 14 Direction of • cw — Rotates the pickup rotation for the clockwise (default) pickup • cc — Rotates the pickup counter- clockwise

[PS#] 15 An exception page A Pagination Style (PS) rule layout for a number full-page pickup • no (default) • integer

[3rdTry] 16 Third preferred See 1stTry field. placement of the pickup

[4thTry] 17 Fourth preferred See 1stTry field. placement of the pickup

Marking Pickup Elements in ASCII Text Use the following guidelines to mark pickup elements in ASCII text:

• A pickup stream can contain four elements — captions, annotations, titles, and graphics. Captions, annotations, and titles contain text; a graphic contains an image name and no text. • A pickup can have only one caption and one title, but it can have multiple annotations and graphics. • The pickup tag primitive must precede pickup element tag primitives. For each pickup tag primitive, insert a stream-end delimiter after all the pickup elements. • Use a semi-colon to separate arguments. If you omit an argument, XPP provides default values according to the argument’s position. • You must enter a unique name for graphics. • To stack elements within a pickup, enter 1n as the y-origin argument.

Transforming Data Unicode Support in XPP 1-19 Using Tag Primitives to Separate Text into Streams

Arguments for Graphic Tag Primitives The tag primitive format for graphic pickup elements in classic mode is: {/GRAPH; name; width; depth; x-orig; y-orig; gutter; rot-amt; rot-dir; color; screen-method; crop-xorig; crop-yorig; crop-width; crop-depth; scale; prior; trace; session}

The following table shows the arguments for graphic element tag primitives.

Table 1-7 Arguments for Graphic Tag Primitives

Argument Position Description Valid Entries

[name] 1 Name of an image Up to 64 characters (uppercase, in the graphic lowercase, numbers, or . # + - ) library for image name. Do not use + or - as first character in an image name. Defaults to -hole-.

[width] 2 Width of the • full (default) element • comptd • qualified number

[depth] 3 Depth of the • comptd (default) element • full • qualified number

[x-orig] 4 X-position • left (default) (horizontal) of the • center, right, lalign, calign, element block ralign, stack, match, flip, 0 relative to the pickup • qualified number (frozen elements only)

[y-orig] 5 Y-position (vertical) • stack (default) of the element block • top, center, bottom, talign, relative to the calign, balign, match, flip, 0 pickup • qualified number (frozen elements only)

[gutter] 6 Gutter between • 0 (default) elements that are • qualified number stacked

[rot- 7 Degree of rotation • 0 (default) amt] for the element • 90, 180, or 270

1-20 Unicode Support in XPP Transforming Data Using Tag Primitives to Separate Text into Streams

Table 1-7 Arguments for Graphic Tag Primitives (Continued)

Argument Position Description Valid Entries

[rot-dir] 8 Direction of • cw — Rotates the pickup rotation for the clockwise (default) element • cc — Rotates the pickup counter- clockwise

[color] 9 Color of the graphic A rule from the Color Control Spec: element (for • 0 “normal” color of block color-separated (default) masters) • 1 – 65535

[screen- 10 Table number in the Controls the device and screening method] $XYV EXECS/sys/ method entry for Contone TIFF od/ps ctrl file (Class G), EPSF, JPEG, PDF, SVG, CGM, PNG, BMP, and GIF images. • 0 (default) • opaque (forces the image to be opaque) • integer

[crop- 11 Crops the • 0 (default) xorig] document image • qualified number only; not the master (horizontal)

[crop- 12 Crops the • 0 (default) yorig] document image • qualified number only; not the master (vertical)

[crop- 13 Crops the • 0 (edge) (default) width] document image • qualified number only; not the master (horizontal)

[crop- 14 Crops the • 0 (edge) (default) depth] document image • qualified number only; not the master (vertical)

[scale] 15 Scales the Scales the image to fit within the document image graphic block: only; not the master • width • depth • best • none • positive integer (%)

Transforming Data Unicode Support in XPP 1-21 Using Tag Primitives to Separate Text into Streams

Table 1-7 Arguments for Graphic Tag Primitives (Continued)

Argument Position Description Valid Entries

[priority] 16 Output priority for An integer (i) in the range a graphic image -127 through 127 which specifies the image’s output priority. The default value is 0.

[trace] 17 Image is marked for yes, no edit trace The default value is no.

[session] 18 Image edit trace An integer. session number The default value is 0.

Arguments for Pickup Element Blocks The tag primitive formats for caption, annotation, and title pickup elements in classic mode are:

{/CAPT; width; depth; x-orig; y-orig; gutter; rot-amt; rot-dir; text-color; text-pat; bgrnd-color; bgrnd-pat}

{/ANNT; width; depth; x-orig; y-orig; gutter; rot-amt; rot-dir; text-color; text-pat; bgrnd-color; bgrnd-pat}

{/TITL; width; depth; x-orig; y-orig; gutter; rot-amt; rot-dir; text-color; text-pat; bgrnd-color; bgrnd-pat}

Table 1-8 Arguments for Caption, Annotation, and Title Element Blocks

Argument Position Description Valid Entries

[width] 1 Width of the • full (default) element • comptd • qualified number

[depth] 2 Depth of the • comptd (default) element • full • qualified number

[x-orig] 3 X-position • left (default) (horizontal) of the • center, right, lalign, calign, element block ralign, stack, match, flip, 0 relative to the pickup • qualified number (frozen elements only)

1-22 Unicode Support in XPP Transforming Data Using Tag Primitives to Separate Text into Streams

Table 1-8 Arguments for Caption, Annotation, and Title Element Blocks (Continued)

Argument Position Description Valid Entries

[y-orig] 4 Y-position (vertical) • stack (default) of the element block • top, center, bottom, talign, relative to the calign, balign, match, flip, 0 pickup • qualified number (frozen elements only)

[gutter] 5 Gutter between • 0 (default) elements that are • qualified number stacked

[rot- 6 Degree of rotation • 0 (default) amt] for the element • 90, 180, or 270

[rot-dir] 7 Direction of • cw — Rotates the pickup rotation for the clockwise (default) element • cc — Rotates the pickup counter- clockwise

[text- 8 Color of text A rule from the Color Control Spec: color] • 0 “normal” color of block (default) • 1 – 65535

[text- 9 Pattern of text A rule from the Special Effects pat] Pattern (SEP) Spec: • 0 A solid color (default) • 1 – 100 Lower numbers produce lighter shades; higher numbers produce darker shades.

[bgrnd- 10 Color of the A rule from the Color Control Spec: color] background • 0 “normal” color of block (default) • 1 – 65535

[bgrnd- 11 Pattern of the A rule from the Special Effects pat] background Pattern (SEP) Spec: • 0 A solid color (default) • 1 – 100 Lower numbers produce lighter shades; higher numbers produce darker shades.

Transforming Data Unicode Support in XPP 1-23 Using Tag Primitives to Separate Text into Streams

Marking Stories in ASCII Text To send text to the story stream in classic mode, insert a /STORY tag primitive at the start of the stream in the ASCII file. For each /STORY tag primitive, insert a stream-end delimiter (\.) at the end of the stream. When ToXSF encounters a story tag primitive in an ASCII file, the program: • Transforms the ASCII text into an Unicode-based story. • Places the story on one or more pages in the galley section. • Assigns the story a unique name (if you do not specify a name)—s1, s2 and so on. (Best practice is to supply your own unique name.)

The format of the /STORY tag primitive in classic mode is:

{/STORY; name; gmeas; glayout}

Table 1-9 Arguments for the Story Tag Primitive

Argument Description Valid entries

[name] Name of the story Up to 64 characters (uppercase, lowercase, numbers and # + - _ ) that uniquely name the story. If you do not assign a name, the program generates default story names, for example, s1, s2 and so on.

[gmeas] Line measure to use on • qualified integer galley pages for a story For example, {/STORY;newstory;30p} to output newstory in a 30-pica column.

[glayout] Page layout to use when • Name of a layout in the Page formatting galley pages Layout (PL) Spec. for a story

Converting Microns to Standard Units XPP stores numeric values in microns. When you run FromXSF from the Export process in PathFinder or from the command line (without the –unit or –arg options), the program outputs micron values in the ASCII file. A micron is qualified by the letter n, for example, 1686n. To convert microns to standard units, refer to the following table:

1-24 Unicode Support in XPP Transforming Data Using Tag Primitives to Separate Text into Streams

To convert microns to: Divide by: Inches (i) 25400 Picas (p) 4224 Points (q) 352 Millimeters (m) 1000 Didots (d) 376 Ciceros (c) 4512 Kyus (k) 250 Centimeters (z) 10000

For example, in an ASCII file, you can convert the microns in a tag primitive to picas. If the tag primitive is:

{/CAPT;84480n;;16896n;33792n},

using the above table, you can determine the following:

• The caption is 20 picas wide (84480 ÷ 4224). • Its x-position is 4 picas (16896 ÷ 4224). • Its y-position is 8 picas (33792 ÷ 4224).

You can also convert the microns in a tag primitive by running the utility ucon at the Command Line.

For additional information on this utility, type the following at the command line: xyhelp ucon

—or— Refer to the manual XML Professional Publisher: Command Line Utilities.

Transforming Data Unicode Support in XPP 1-25 XSF Text / ASCII Examples

...... XSF Text / ASCII Examples

Example 1 shows XSF text in a division in classic mode with main text and a pickup (the table is in the annotation block of the pickup).

Example 1: XSF Text

Grammatical Properties of Pronouns

Case: Pronouns have forms to show the subjective, objective, or possessive case, as the following table shows.

Table 1-1 First, Second and Third Person Pronouns Subjective Objective Possessive 1st person singular I me my, mine 2nd person singular you you your, yours 3rd person singular he him his she her her, hers it it its 1st person plural we us our, ours 2nd person plural you you your, yours 3rd person plural they them their, theirs

1-26 Unicode Support in XPP Transforming Data XSF Text / ASCII Examples

Example 2 shows the ASCII file created by running FromXSF on the division.

Example 2: ASCII Text Strings

{h3}Grammatical Properties of Pronouns\ {text}Case: Pronouns have forms to show the subjective, objective, or possessive case, as the following table shows. {/PICK;p2;;;block;;;;no;1;22098n;42648n} {/ANNT;;;left;stack;;;;} {tab} First, Second and Third Person Pronouns \nSubjectiveObjective Possessive1st person singularImemy, mine2nd person singular you youyour, yours 3rd person singular hehim his\nsheher her, hers\nititits1st person plural weusour, ours2nd person plural you youyour, yours3rd person plural theythemtheir, theirs \.

Transforming Data Unicode Support in XPP 1-27 1-28 Unicode Support in XPP Transforming Data Chapter 2

FromXSF and ToXSF

This chapter provides an overview of the FromXSF and ToXSF programs:

• How the programs operate • When and why you would use them

Transforming Data FromXSF and ToXSF 2-1 Overview

...... Overview

The FromXSF and ToXSF programs include a wide variety of processing options for exporting and importing data in ASCII format.

Using PathFinder, you can access a basic set of options available through FromXSF and ToXSF. PathFinder also lets you enter command line options for additional features.

Using the command line or running from a script, you can access the full range of options by specifying the options you want on the command line.

For detailed information about specific FromXSF and ToXSF options, consult XML Professional Publisher: Command Line Utilities.

For information regarding how to run the programs from PathFinder, consult XML Professional Publisher: User Guide.

2-2 FromXSF and ToXSF Transforming Data Using FromXSF

...... Using FromXSF

FromXSF is Unicode aware, that is, in the Export process, under the following circumstances, it is able to perform these tasks: • Non-ML Divisions —Exports XyASCII by transforming the Unicode characters back to their 1-3 character XCS escape sequence. —Exports CJK characters (not in XCS Spec) using @xxxx syntax. • XML/SGML—Exports character entities and numeric character references in order to maintain backward compatibility. Writes out a UTF-8 encoded file, using the –utf8 option. Using PathFinder, you can specify this option by checking a box on the FromXSF tab in the Export Dialog. Note: If you import a character as a numeric character reference or character entity, From XSF preserves its format in the UTF-8 output stream.

The FromXSF program converts Unicode to ASCII or UTF-8 format. You can run FromXSF:

• From PathFinder • From the command line

With FromXSF, there are a number of options you can use to specify output to the ASCII file. For example, you can do any of the following:

• Run the program on Multiple Divisions • Insert Header and Trailer Strings • Insert Tag Primitives • Preserve Edit Traces • Use FromXSF in XML/SGML mode • Specify a unit for output from within layout information

Transforming Data FromXSF and ToXSF 2-3 Using FromXSF

Running FromXSF from PathFinder FromXSF is part of the Export process. To run FromXSF:

1. Right-click the division on which you want to run FromXSF. PathFinder displays a pop-up menu.

2. Select Process > Export from the pop-up menu and submenu. PathFinder displays the Export dialog box.

3. Enter a name or accept the default file name in the Output File Name text box on the Export tab. 4. Click text types—all or selected—in the Text Content section of the FromXSF tab.

5. Enter additional command options in the Additional Command Options text box if you want to use processing options that are not included on the FromXSF tab.

6. Click the Run button.

For complete information on running FromXSF, please refer to XML Professional Publisher: User Guide.

Running FromXSF from the Command Line To run fromxsf from the operating system command line, issue the command with options in the following general format: fromxsf [–sw1] [–sw2] ... [–cd pathname][outfile]

Note: The argument for [outfile] may be only the outfile name, or it may be the full path to some other location.

For more information about fromxsf command line options, refer to the XPP document XML Professional Publisher: Command Line Utilities .

Using FromXSF on Multiple Divisions within a Job You can run fromxsf at the command line to process one or more divisions in a job (job processing mode):

• To run fromxsf on multiple divisions, you must be at the job level or use the –cd option to specify the job path. • To invoke job processing, also use the –job (job processing) option.

2-4 FromXSF and ToXSF Transforming Data Using FromXSF

• Default job processing processes MAIN divisions listed in the Document Assembly Ticket in the order specified. Note: MAIN is used in two different ways:

1. In the DA Ticket, main refers to the type of data division you want XPP to process.

2. In toxsf/fromsxf, MAIN refers to the tag primitive and uses {/Main;...}...\. as a format in classic mode. • Use the –da colname option (–job is also required) where colname is the name of a field in the Document Assembly Ticket. This restricts processing to divisions listed in the DA Ticket in cases where the specified field contains yes. • To ignore the DA Ticket and process all divisions in a job (all directories with a DIV_ prefix), use the –all option. • To select one or more divisions to process (overriding those listed in the Document Assembly Ticket), use the –div option. You must use the –job option with the –div option. • At least one division name must follow the –div option. You can specify division names with or without a DIV prefix. If the division names contain special characters, enclose the division list in double quotes (“ ”). • Valid division name characters are A-Z, a-z, 0-9, _ + − and #. Use commas to separate names within the list. • By default, job processing creates a separate ASCII file in each division. If you do not specify a file name, XPP uses trawz to name the output file(s). • To create a single ASCII output file that contains the concatenated text from all processed divisions, use the –cat option. XPP creates the ASCII output file at the job level. • Job processing works in conjunction with other fromxsf options. For example, use –a to append to an existing output file(s) during job processing. If a particular combination of options is not valid, a detailed error message is output and the program quits.

The following command runs fromxsf on divisions in the job named memos: fromxsf –job –cd /node1/alljobz/CLS doc/GRP tech/JOB memos

XPP looks at the Document Assembly Ticket for the names of MAIN divisions to convert to ASCII text. It processes each, placing the output file named trawz at each respective division level.

Transforming Data FromXSF and ToXSF 2-5 Using FromXSF

The following command runs fromxsf on three divisions in the job named memos: fromxsf –job –cd /node1/alljobz/CLS doc/GRP tech/JOB memos –cat –div sect1,sect2,sect3 tjob

XPP concatenates the ASCII text from the processed divisions and creates one ASCII file named tjob at the job level.

Inserting Header and Trailer Strings With FromXSF You can specify header and trailer text strings for fromxsf to insert at the start and end of the ASCII output file. These strings are most useful when you are processing jobs (with the –job and –cat options). You can use the –hdr “prestring” and/or –trl “poststring” option to indicate where the text from one division ends and another begins when outputting multiple divisions to a single file. Note that the lowercase options indicate that you are working at the division level. You can use the –HDR “prestring” and –TRL “poststring” options to output a job message at the beginning and/or end of the ASCII output file. Note that the uppercase options indicate that you are working at the job level. Rules for inserting header and trailer strings include:

• The strings can contain any characters, such as tags, codes, or standard text. • Enclose the strings in single or double quotes. Use double quotes when using classic XPP. Use single quotes when you are in XML/SGML mode to prevent conflict with the double quotes in the DTD/schema name. • Use one of the following four escape sequences to output the name of the division and/or job in the header or trailer:

• %D Output the current division name, including the DIV prefix. • %d Output the current division name, without the DIV prefix. • %J Output the current job/division name, including the JOB / DIV prefix. • %j Output the current job/division name, without the JOB / DIV prefix.

Note: Do not use %D and %d escape sequences in –HDR and –TRL strings. %D and %d refer to division names, while the uppercase options –HDR and –TRL refer to job messages.

2-6 FromXSF and ToXSF Transforming Data Using FromXSF

The following command runs fromxsf on three divisions in the job named memos and adds the header “prestring”: fromxsf –job –cd /jobs/node1/alljobz/CLS doc/GRP tech /JOB memos –cat –div sect1,sect2,sect3 –hdr“%D” tjob

XPP concatenates the text from the processed divisions, creates one ASCII file named tjob at the job level, and inserts the name of each division, including the DIV_ prefix, before adding the division to the previous text.

Inserting Header and Trailer Strings in XML/SGML Mode

When in XML/SGML mode, the process of inserting header and trailer strings with FromXSF is the same as it is for classic XPP. However, there are two notable points:

• Use single quotes (rather than double quotes) around the entire header string to prevent conflict with the double quotes in the DTD/schema name. • There is an exclamation (!) mark before the DOCTYPE Declaration. Be sure to precede the exclamation mark with a backslash (\) because it is a XyChange command set character. Refer to XyChange, chapter 3 in this manual, for additional information. .

If you enter the following fromxsf command with these header and trailer options: fromxsf –hdr ‘<\!DOCTYPE HTML SYSTEM “html.dtd”> ’–trl ‘’

the following strings appear at the start and end of the ASCII output file:

... Footnote Tag Primitives

The FromXSF program can output two types of footnote tag primitives: • /FOOT • /FOOTPG

/FOOT

By default, the tag primitive output for all footnotes in classic mode is: {/FOOT;name;track} . . . text . . . \.

Transforming Data FromXSF and ToXSF 2-7 Using FromXSF

If a footnote breaks across multiple columns on a page, or across multiple pages, the text of all the blocks is concatenated and fromxsf outputs one /FOOT per footnote.

If you enter the –foot option on the command line, you are specifying the output of /FOOT tag primitives only in classic mode.

/FOOTPG If you specify the –foofftpg option on the command line, the tag primitive output for all footnotes in classic mode is: {/FOOTPG;name;pagepos;track} . . . text . . . \. If a footnote breaks across multiple columns on a page, or across multiple pages, the text of all the columns on each page is concatenated and fromxsf outputs one /FOOTPG per page per footnote. The pagepos field identifies the page position within the division containing that piece of the footnote. The –ftpg option, which is usually used in conjunction with the –Rep or –rep option, is intended mainly for replacing individual pieces of footnotes in an auto looseleaf environment. If you specify the –pend option in addition to –ftpg and –Rep or –rep, fromxsf outputs all /FOOTPG pieces of a footnote sequentially, following the Main text of the first reference to the footnote. For example, if footnote “footone” breaks across pages 2, 3 and 4, the output of the following command: fromxsf –rep –ftpg –pend

is: {/MAIN;1}Main text from Page 1\. {/MAIN;2}Main text from Page 2\. {/FOOTPG;footone;2;1}First piece of the footnote on Page 2\. {/FOOTPG;footone;3;1}Second piece of the footnote on Page 3\. {/FOOTPG;footone;4;1}Third piece of the footnote on Page 4\. {/MAIN;3}Main text from Page 3\. {/MAIN;4}Main text from Page 4\.

For testing, you may want to include the –c option, which produces a tag primitive outline without the text.

The FromXSF program always outputs all /FOOT or all /FOOTPG tag primitives, depending on its –ftpg option.

2-8 FromXSF and ToXSF Transforming Data Using FromXSF

Preserving Editing Traces with FromXSF

The format of the FromXSF command to preserve editing traces is: fromxsf –xyp1 –arg q –cd /pubs/alljobz/CLS menu/GRP entree /JOB pasta/DIV recipes trecipes

In the fromxsf command above: • –cd /usr/app/xyvision/jobs/pubs/alljobz/CLS menu/GRP entree /JOB pasta/DIV recipes transforms the division named recipes to ASCII. • –xyp1 preserves all xyps (special XPP codes; see below) in the file during transformation. • –arg q outputs argument values in points. • trecipes writes the ASCII text to the file trecipes in the division directory.

Examining a File Containing Trace Xyps

Once an ASCII file is created, you can examine the file using an ASCII editor.

fromxsf places special codes or Xyps (pronounced zips) in the output ASCII file. These special characters exist in Xyvision Standard Format, to control the behavior of composition.

Xyps follow the following format:

• System Xyps are delimited by square brackets. • Variables are separated by semicolons.

The following format is an example of a Xyp for edit trace in ASCII text: [TRACE;type;suppression;session#;original session#]

Transforming Data FromXSF and ToXSF 2-9 Using FromXSF

In the Xyp format above:

• type marks the beginning or end of different kinds of edit trace text, including edit trace inserts, edit trace deletions, and strike-through text. Valid entries for type are: soi Start edit trace insert eoi End edit trace insert del Delete trace sod Start strike-through delete eod End strike-through delete • suppression designates a specific suppression code, a single digit entry that indicates whether to suppress the display of this trace and/or the change bar for this individual trace ; that is, you can have traces in a division, but not allow the traces or change bars to display. Valid suppression entries are: 0 Does not suppress this trace or its change bar 1 Suppresses change bar only for this trace 2 Suppresses insert and delete traces only for this trace 3 Suppresses insert and delete traces and change bars (only strike-through traces display) for this trace 4 Suppresses insert and delete traces and change bars (only strike-through traces display); same results as #3. 5 Suppresses insert and delete traces and change bars (only strike-through traces display); same results as #3. 6 Suppresses insert and delete traces and change bars (only strike-through traces display); same results as #3. 7 Suppresses insert and delete traces and change bars (only strike-through traces display); same results as #3. Note: There are actually only three different suppression results: #1 through #3. The other suppression values in a Trace Xyp—#4 through #7—may occur as a result of manipulating edit traces in a division, such as using the divtrhid program, which has features to suppress or reveal edit traces. • session# is the editing session in which the editing traces were made. • original session# is the session number of the original version from which the edit trace deletion was made when text in an insert trace is deleted in a later session.. This applies only to the del type of edit trace (delete trace). Note: You not only see the session number of the original version when you use the –del option with XyDiff, but you can also cause them by deleting text.

2-10 FromXSF and ToXSF Transforming Data Using FromXSF

The following formats are examples of Edit Trace Xyps:

• [TRACE;soi;0;1]— marks the beginning of an edit trace insert area in which all new traces were visible during editing session 1 of the division. • [TRACE;sod;3;1]—marks the beginning of a strike-through delete area in which strike-through text only was visible during the first editing session. • [TRACE;eod]— marks the end of a strike-through delete area.

Using FromXSF in XML/SGML Mode

If you are running the FromXSF program in XML/SGML mode, you can do the following:

• Decide whether to suppress XML/SGML processing instructions. • Select the type of output you want: ASCII, Entity, Unicode.

Suppressing XPP PI in XML/SGML Mode

If you are in XML/SGML mode, XPP enables the Suppress XML/SGML processing instructions field. This field is located on the FromXSF tab in the Export dialog box through PathFinder. This option allows you to decide whether you want XPP to include the processing instructions in the output data. If you check this box, XPP excludes the processing instructions.

Selecting Type of Output

If you specify –UTF-8, XPP outputs all characters at UTF-8. Otherwise, by default, the FromXSF program uses the value you specify in the Default Output: field of the XCS Spec. You can select any one of the following:

• ASCII—Outputs the regular one-to-three character XyASCII escape sequences from the ASCII field of each rule in the XCS Spec, ignoring the contents of the Entity field. This is the default when using XPP in classic mode. In XML/SGML mode, ASCII outputs regular ASCII characters unchanged except for the less than (<), greater than (>), and ampersand (&) characters. • Entity—Outputs the contents of any non-blank Entity field, which is the same as running fromxsf –udec –ent. Entity only outputs character entities if there is no Unicode; otherwise it outputs a decimal numeric character reference. The output of <, >, and & , when entered from the keyboard as raw ASCII, not as entities, depends on the XML/SGML setting in the Job Ticket.

Transforming Data FromXSF and ToXSF 2-11 Using FromXSF

• In SGML, these three characters are output as is. If you want an entity, you must create one using the Shift + Compose keyboard sequence. • In XML or (non-ml) these three characters are output as entites, that is, less than (<), greater than (>), and ampersand (&). In fields where the Entity is blank: • Entity—Outputs the contents of ASCII. • Unihex—Outputs a Unicode hexadecimal numeric character if there is a Unicode equivalent of a character in the XCS Spec. • Unidec—Outputs a Unicode decimal numeric character if there is a Unicode equivalent of a character in the XCS Spec.

Specifying Units for Layout Field Information

Using –lunit followed by a valid unit qualifier allows you to specify which unit XPP should use when outputting fields within layout information. Without this option, the default is to output all unit fields in microns (n). This option also automatically forces on the –layout option.

2-12 FromXSF and ToXSF Transforming Data Using ToXSF

...... Using ToXSF

The ToXSF program is Unicode aware, and takes in UTF-8, UTF-16, and UTF-32 encoded files, using its autodetect process and/or the ″encoding″ attribute in the tag. It automatically stores the Unicode values in XPP as UTF-8. In non-XML files, ToXSF only takes in UTF-8 and XyASCII.

ToXSF Support

ToXSF in XPP 8.x and later maintains support for the following:

• XyASCII • CJK characters • Autoprocessing • Numeric character references

XyASCII

ToXSF continues to support XyASCII. However, since ToXSF automatically detects UTF-8 encoding within XyASCII, it is permissible to embed UTF-8 multi-byte sequences in XyASCII. All other forms of encoding (UTF-16 and UTF-32) only work with XML divisions.

CJK Characters

ToXSF supports CJK characters using hex notation, that is, @xxxx, where xxxx is four hex digits representing an Asian character that is not defined in the XCS Spec because its number falls out of the XCS character range. The @xxxx notation was developed to represent Asian characters in earlier versions of XPP. With XPP 8.0 and later, Unicode references to Asian characters are fully supported.

Autoprocessing

ToXSF continues to support autoprocessing and importing UTF-8. However, since XPP automatically imports Unicode, ToXSF ignores the JPCIN option. JPCIN was used prior to XPP 8.x to transform Asian characters from several standard encodings into the @xxxx notation used by earlier versions of XPP.

Numeric Character References

For non-ML divisions, ToXSF continues to support numeric character references as an extension to XyASCII.

Transforming Data FromXSF and ToXSF 2-13 Using ToXSF

Running ToXSF

You can run toxsf: • From PathFinder • From the Command Line

There are also a number of options you can use that specify what and how you want to import the text. For example, you can use any of the following:

• Replace Modes • Page Replace/Insert/Append Mode • Page Re-Create Mode • Page Replace Mode and Maximum Page Sizes • Layout Control Designators • XML/SGML Character Entities • Line Endings • Loop Processing of Input Text • ToXSF Error Checking • Legal Nonprinting Control Characters • Missing Begin/End Tag, Xycode of Tag Primitive • Page Formats and Sizes • Footnote Tag primitives • Help File

Each of these options is described in the following sections.

Running ToXSF from PathFinder

The ToXSF program is part of the Import process.

To run toxsf: 1. Right-click the division on which you want to run ToXSF. PathFinder displays a pop-up menu.

2. Select Process > Import from the pop-up menu and submenu. PathFinder displays the Import dialog box.

3. Enter the appropriate information on the Import tab of the Import Dialog.

2-14 FromXSF and ToXSF Transforming Data Using ToXSF

4. Enter the appropriate information on the Transform tab of the Import Dialog.

5. Click the ToXSF tab on the Import Dialog. Import displays the ToXSF dialog box containing two sections:

• Append/Replace • Additional Command Options

6. Click one radio button in front of the append/replace options: • New Division (the default) • Append only [-a] • Append main text, Replace other streams [-aA]

7. Enter additional command options if you need additional processing options that are not available through the Import Dialog.

8. Click the Run button when you have made your choices. If you checked the Preview command check box on the Import tab, Import displays a message box containing the commands you selected for the Import process along with the option to continue. • Click No. XPP closes the message box and cancels the process. —or— • Click Yes. Import processes the division according to your specifications, or with the default settings, and displays import messages in the text box to the right of the dialog box.

For detailed information on the Import process, refer to XML Professional Publisher: User Guide.

For information on the additional options that you can add to the Additional Command Options text box, refer to XML Professional Publisher: Command Line Utilities manual.

For additional information on the Append/Replace options, see the section below entitled “Replace Modes”.

Transforming Data FromXSF and ToXSF 2-15 Using ToXSF

Running ToXSF from the Command Line To run toxsf from the operating system command line, issue the command with options in the following general format: toxsf [–sw1] [–sw2] ... [–cd pathname][infile]

Note: For detailed information about toxsf command line options see the XML Professional Publisher: Command Line Utilities manual.

Replace Modes

The replace modes (–aA and –A) options are actually combinations of append and replace. If the name of any FOOT, FOOTPG, PICK or STORY in the new XyASCII raw file matches the name of an existing entry in the XSF data base, the text of the old entry is deleted and replaced by the new text. Otherwise, the new entry is appended as usual with the –a option.

Main text also may be replaced but this is an exception. The –aA option, which is available from PathFinder, always appends new main text to any existing main text.

The super replace option, –A, is only available from the command line since it can be dangerous. With –A, if one or more characters of main text is present in the new raw file, all the existing XSF main text is deleted and replaced by the new text. Existing main text is retained if the raw file begins with a FOOT, FOOTPG, PICK or STORY tag primitive and no main text is present between any tag primitive end delimiter and the next tag primitive. However, empty blank lines are permitted between the primitives (for clarity) and are not considered to be (new) main text.

If the replacing, that is, deleting of the old text, causes a Lost and Found type page to become empty, the page is deleted. Main type pages are never deleted. The exact behavior differs depending on the type of entry deleted:

Type Description FOOT The footnote block(s) and all its lines are deleted. FOOTPG The footnote piece block and all its lines are deleted. PICK The pickup stream and all its element blocks are deleted. If a pickup is split across columns and/or pages, all of its pieces are removed. STORY The story stream lines only are deleted from main type pages thus retaining the stream and block header’s layout size information. Lost and Found galley pages are always killed since they contain one story per page.

2-16 FromXSF and ToXSF Transforming Data Using ToXSF

The Import Dialog, available from PathFinder, has a selection on the ToXSF tab that supports the –aA append/replace mode function. Note that this feature is designed to be used in conjunction with the FromXSF {From Story} and {From Pickup} options (see fromxsf, text types, and name list selection sections in this chapter for details).

Whenever you run toxsf, regardless of the mode, the progress message output is: Convert to XSF Page n

where n is the page type/number being written to by toxsf. This can be slightly confusing when running in replace mode. Since replaced Lost and Found pages are deleted dynamically on the fly and replaced main pages are only deleted at end-of-job time, n is rather erratic, repeating itself, etc. Don’t worry about it; the end result is as described above.

When the -Rep or -Ret option is specified (but not -Rec), the message: Insert after Page # means that toxsf first converted an existing page referenced by the {/MAIN} tag primitive in the input file and that page then ″overflowed″ and toxsf ″inserted″ another page (or pages) after the referenced page. When the Page Sheet Style is double-sided, every other inserted page due to such an ″overflow″ is indicated by toxsf as: Extra after Page # (i.e. an ″extra″ page inserted after the referenced page), which means the same thing as ″Insert after Page #″.

This is also indicated at the end of the toxsf process with the following messages (note second message): There were ## Main Pages text replaced There were # Main Pages text inserted

Page Replace/Insert/Append Mode (-Rep and -Ret)

For automatic loose-leaf, a different type of replace is implemented. However, it is a standard feature and may be used by anybody for any purpose. In this mode, the files of an existing division are being modified; they must already exist or the program aborts. The text of specified main pages is replaced and footnotes and pickups are replaced on the same Instance page where the orignal DLD entry lived.

(Normally, when you run toxsf from custom scripts or Web Services, the –Rep or –Ret option is included but not the –laf option. Refer to the XPP document XML Professional Publisher: Command Line Utilities for an explanation of the –laf option.)

Transforming Data FromXSF and ToXSF 2-17 Using ToXSF

The tag primitive {/MAIN} (classic mode format) must be present to indicate the start of each main page. This tag primitive may be generated by the FromXSF program by using either the –rep or –Rep option (normally, the fromxsf –pend option is also included in custom scripts and Web Services). This tag primitive has the form: {/MAIN;pagepos;p1;p2;p3;p4;p5;p6}

where argument 1 is the page position whose text is to be replaced and arguments 2 through 6 are the multipart page number to be used.

Replacing Main Pages

To replace the text of a page, the page position (argument 1) must be specified. Optionally, any portion of arguments 2 - 6, the multi-part page number, may be specified. If one or more parts is included, all six parts are replaced; otherwise, they are left as is.

If the page position does not exist, a new page(s) is appended to the end of the division.

If the new text overflows the page buffer (as specified in the Max Page Size field in the Job Ticket ), the page is written and a new page(s) is automatically inserted. The ToXSF program keeps track of which pages are original pages and which are inserted pages so that all subsequent replace/ insert specifications are handled properly.

Optionally, the new main text may end with the \. tag primitive end delimiter (classic mode format) or simply terminate because of a {/. . .} indicating the start of another tag primitive.

Only the text is replaced. Line header information and end-of-line codes are retained to assure composition integrity.

A /MAIN tag primitive can be empty, i.e., have no text between the } tag end and the \. text end. This means to delete all the existing main text from the page.

Inserting Main Pages

The page position argument of the MAIN tag primitive may be preceded by a minus (–) or plus (+) sign indicating to insert the new page(s) before or after the specified page position, e.g.,

{/MAIN;–1} Insert new page before Page 1

{/MAIN;+5; ... } Insert new page after Page 5

2-18 FromXSF and ToXSF Transforming Data Using ToXSF

In any loose-leaf environment, inserting before page 1 is undefined. Composition behavior may be unexpected and unpredictable.

If the inserted text overflows the page buffer, multiple insert pages are created.

Again, only the original pages are counted to determine this position and not any of the (previously) inserted pages.

If the specified page position does not exist, the new page(s) is appended to the end of the division.

Appending Main Pages

If a {/MAIN} tag primitive (classic mode format) has no arguments, a new page(s) is appended to the end of the division.

The same thing happens whenever a page position argument is specified but the page position did not exist (as an original page).

Replace/Insert/Append Footnotes, Pickups and Stories

Whenever a {/FOOT;name}, {/FOOTPG;name;pagepos}, {/PICK;name} or {/STORY;name} tag primitive (classic mode format) is encountered, the ToXSF program checks to see if the named item already exists in the DLD.

If a FOOT, FOOTPG, or PICK exists and the –m option is not specified, the program determines the instance page of the original and replaces it on the same page. If the –m option is specified, the FOOT, FOOTPG, or PICK is moved from its current instance page to, possibly, a new page. That is, the old instance is removed from the DLD and the new instance is placed on the last MAIN page encountered. For Footnotes and Pickups, this instance page position is always saved.

If a STORY exists, the original item is deleted and the new item is always appended as a new “Galley” (Lost and Found) page(s).

If a FOOT, FOOTPG, or PICK item does not exist (i.e., it is an Insert) the program places the new item on the saved page number where the last MAIN text or replaced FOOT, FOOTPG, or PICK was found. This default behavior can be overridden by specifying the –laf option mentioned above; the inserted FOOT, FOOTPG, or PICK is then placed on a Lost and Found page(s) of the appropriate type. STORYs are always inserted on their own Lost and Found “Galley” page(s).

A FOOT, FOOTPG, PICK or STORY tag primitive can be empty, i.e., have no text between the } tag end and the \. text end (classic mode format). This indicates to delete the existing named item from the DLD.

Transforming Data FromXSF and ToXSF 2-19 Using ToXSF

Replacing Split Pickups

If a pickup exists and is split across columns and/or pages, the DLD entries and page data for all pieces except the first are removed. All the new text replaces the text of the first piece on the same page.

Updating Frozen Pickups

The PICK tag primitive has three fields associated with freezing a pickup:

• Field 10 — Frozen x value • Field 11 — Frozen y value • Field 12 — Frozen page position

When –Rep or –Ret is specified and the named pickup already exists, the ToXSF program checks the new page position field. If the new page position field is blank, the original frozen x, y and page position are left as is. If the new page position field is non-blank, the three fields are replaced with their new values.

A new page position value of ;0; (zero) can be specified to thaw the pickup. See the Tag Primitives Help File section on page 2-28.

–Rep versus –Ret

–Rep is used when old edit traces are being retained during the fromxsf operation. –Ret is used when old edit traces are not being retained during fromxsf. –Ret regenerates start and end trace marks when a trace is continued across a page boundary. Examples are:

fromxsf –xyp4 . . . (old edit traces retained) toxsf –Rep . . . fromxsf . . . (old edit traces not retained) toxsf –Ret . . .

Page Re-Create Mode (–Rec)

If the XSF pages in the division exist, overwrite them. If they do not exist, create them from scratch.

Whenever a new {/MAIN ... } tag primitive (classic mode format) is encountered, close the current main page and create a new page. In this mode, any page position (first) argument is ignored but validation is performed, i.e., must be either blank (;;) or a decimal number. Multipart page number arguments (2 through 7), if any, are validated and stored.

2-20 FromXSF and ToXSF Transforming Data Using ToXSF

Essentially, we are in “append” mode wherein we are appending new pages to new division files.

Footnotes, pickups and stories are appended to their own “Lost and Found” page type as in the normal toxsf operation.

Note: If {/MAIN . . . } tag primitives (classic mode format) are encountered when not in –Rep, –Ret or –Rec mode, toxsf simply ignores them and proceeds with its normal operation.

Page Replace Mode (–Rep and –Ret) and Maximum Page Sizes

When toxsf is run in normal mode, XSF pages are created according to the size specified in the ″Max Page Size″ field of the Job Ticket. This value affects two allocations:

1. The total number of bytes allocated for each page. This amount is dynamic and changes whenever the “Max Page Size” field in the Job Ticket is modified.

2. A percentage of the page size is used to allocate a pointer table within each page containing a fixed number of pointers to the data chunks on each page. This value is fixed at the time each page is originally allocated.

In –Rep or –Ret mode, the text of existing pages is replaced; pages are not replaced. This means the maximum number of pointers available on a given page never changes.

If the replacement text contains more lines than the original text (e.g., a large table has been inserted), the page can run out of pointers , the following message is output, and toxsf aborts:

Page Buffer Overflow creating XXXX (err=2)

where XXX is STREAM, BLOCK, LINE, etc. The (err=2) is significant; the page ran out of pointers, as opposed to running out of data space.

To fix the pointer problem, execute the following steps:

1. Increase the size of the Max Page Size field in the Job Ticket.

2. –> fromxsf –Rep . . . tfromrep

3. –> toxsf –Rec tfromrep

4. –> compose (i.e., compose whole division) 5. Rerun the toxsf –Rep (or) –Ret . . . command that failed.

Transforming Data FromXSF and ToXSF 2-21 Using ToXSF

Running toxsf in –Rec (recreate) mode recreates pages with a greater number of pointers but still honors the MAIN tag primitives to break pages at the same places. To determine the maximum pointers available for pages in a division: showxsf –V –p# –P#

If the replacement text contains more data characters than the original text, the page can run out of page buffer space, the following message is output, and toxsf aborts: Page Buffer Overflow creating XXXX (err=1)

where XXX is STREAM, BLOCK, LINE, etc. To correct an (err=1) problem, increase the Max Page Size in the Job Ticket and rerun the toxsf –Rep (or) –Ret . . . command that failed.

Layout Control Designators (–layout and –nofrills)

You can input page/block layout information along with the ASCII text. Following are the layout designators processed if the –layout option (and, optionally, –nofrills options) is specified. If the –layout option (and, optionally, the –nofrills options) is specified, either the –Rep, –Ret or the –Rec option must also be included.

The –nofrills option, used with the –layout option, suppresses the input of Block layout information for Frill blocks, that is, treats Frill blocks as if the –layout option had not been used.

Note that if an ASCII file is submitted to the ToXSF program without specifying the –layout option, any of the following designators found cause an Illegal Xyp message to be output.

• [PAGE ...] contains a page’s X/Y coordinates, width, depth and rotation information. • [FRAME...] contains width and depth information of a page frame. • [BLOCK ...] contains a block’s X/Y coordinates, width, depth, type, name, rotation and color information. • [SHAPE ...] contains X/Y points information of an exclusion shape. • [CPPAGE] contains the number of a page from which to copy page and block geometry (but not the text).

2-22 FromXSF and ToXSF Transforming Data Using ToXSF

SGML Character Entities (–asc)

By default, the ToXSF program accepts as input both one-to-three character XyASCII escape sequences, XML/SGML character entity strings, and Unicode as specified in the xcs_default spec located in the syslib library. The following fields in the xcs_default Spec are used to define these character sequences:

• ASCII—Contains one-to-three character XyASCII input/output escape sequences. • Entity Delimiters—Begin and End characters used to delimit the entity strings entered in rule records. • Entity— XML/SGML character entity string(s) used as alternate input/output to the Ascii rule field. • Unicode—contains either Unihex (hex numeric) or Unidec (decimal numeric) character references.

Use the –asc option to look up XyASCII escape sequences only, i.e., ignore any strings specified in the Entity field of rule records.

Refer to fromxsf, genxcs, and showxcs in the XML Professional Publisher: Command Line Utilities manual for additional information.

ToXSF and Line Endings

The XyASCII input file for the ToXSF program can contain either UNIX style or DOS style line endings. UNIX lines end with a single new line (line feed) character, while DOS (Windows) lines end with a carriage return/line feed pair. The ToXSF program handles the following end line sequences on a mix-and-match basis: • Carriage Return—A single carriage return character (\r) not followed by a line feed is treated as a line end. • New Line—A single new line (line feed \n) character not preceded by a carriage return is treated as a line end. • Return/Line Feed—A carriage return/line feed (\r\n) pair is treated as the end of a single line.

Transforming Data FromXSF and ToXSF 2-23 Using ToXSF

Loop Processing of Input Text (–Ln)

The –Ln option can be used to loop through all the input text, reprocessing it n times. It can be used to create either a template division or a dummy division to recreate a possible error condition. The program reprocesses all the text in the input file, or all the text specified in the –t textstring option, n times. Examples of its use are:

1. Create a division with 100 main pages: toxsf –Rec –L100 –t “{/MAIN}Single line per page.\.”

2. Create a division with 250 uniquely named footnotes (f1, f2, . . .): toxsf –L250 –t “{/FOOT}Single line each footnote.\.”

3. Create a division with 510 uniquely named pickups, each referencing the same graphic (named -hole-): toxsf –L510 tpksgraf where the input file tpksgraf contains the text {/PICK}{/GRAPH}\.

ToXSF Error Checking

The ToXSF program checks the input file for the following:

• Invalid nonprinting control characters • Invalid two or three character escape sequences • Start of tag with no end, or vice versa • Start of xycode with no end, or vice versa • Tag primitive that had no tag primitive end delimiter before the next tag primitive is encountered • Lost and Found (DLD) items that are empty (Warning - may be OK) • Tag primitive end delimiters encountered when not processing a Lost and Found item. • Unidentified text when in –Rep, –Ret or –Rec mode, i.e., text that is “outside” of any tag primitive. • A /FOOTPG tag primitive that specified a page position, not containing a piece of the named footnote, when in –Rep or –Ret mode.

2-24 FromXSF and ToXSF Transforming Data Using ToXSF

For every occurrence of the first two conditions, a string is generated in the XSF output to pinpoint exactly what is wrong. For missing begin/end characters, the matching character is generated. At end-of-job, toxsf outputs one or more of the following messages if that error condition is found: “There are n Invalid Nonprinting codes” “There are n Invalid ASCII Escape sequences” “There were n missing Tag Starts” “There were n missing Tag Ends” “There were n missing Xycode Starts” “There were n missing Xycode Ends” “There were n missing DLD Entry Ends” “There were n Empty DLD Entries” (Warning - may be OK) “There were n Illegal DLD Entry Ends” “There were n Unidentified text blocks” “There were n Error Xyps” “There were n Footnote Page errors”

where n is the total number of each kind of error. For each invalid character error, the output contains a string of the general form: X[ ... ]

where X is the Rubout character (hex 7f) and the error character string is enclosed within brackets. If the error character(s) is nonprintable, their hexidecimal equivalent is output. The five possible cases are the following:

• X[00xx]—Nonprintable single Control character, hex xx. • X[xx00]—Nonprintable two-character \ Escape sequence character, hex xx. • X[xxyy]—Non-printable three-character Escape sequence, hex xx and hex yy. • X[c]—Printable two-character \ Escape sequence character, c. • X[cc]—Printable three-character Escape sequence characters, cc.

You can use the XyView to locate and correct any of the types of error strings described above, You can also correct the source file using the ASCII editor of your choice.

Legal Non-printing Control Characters

The following are the only non-printing control characters, i.e., those that are less than space (hex 20), that are considered legal:

• NULL—Zero (hex 00) characters are always discarded. • Tab—Tab (hex 09) characters are always converted to variable spaces. • Return—Carriage returns (hex 0d) are converted to end-of-line codes or to variable spaces (depending on the –l or –i options).

Transforming Data FromXSF and ToXSF 2-25 Using ToXSF

• New Line—Same as above (hex 0a). • End-of-File—EOF (–1) is always converted to the internal end-of-job code.

Missing Begin/End Tag, Xycode, or Tag Primitive Characters

1. A “Missing Tag (or) Xycode Start” error message is output whenever an end code is seen that is not preceded by the corresponding start. A start code is generated and output directly preceding the end code.

2. A “Missing Tag (or) Xycode End” error message is output whenever:

• An end-of-line code is seen • The 65535-character maximum is exceeded • The same start code is seen again • The opposite type of begin/end code is seen (e.g., an end xycode is found following a start tag, a start tag following a start xycode). A matching end code is generated at this point. 3. A “Missing DLD Entry End” error message is output when, while processing a tag primitive (FOOT, FOOTPG, PICK, STORY), another tag primitive is encountered without having found the tag primitive end Delimiter to terminate the original entry. The original entry is forced to be terminated and processing of the new tag primitive begins. The argument in the error message is the identity of the new DLD entry.

4. An “Empty DLD Entry” warning message is output whenever a tag primitive is directly followed by the tag primitive end delimiter, i.e., the entry has no text whatsoever. This may or may not be an error. It is intended to warn the user that, perhaps, the entry’s text was inadver- tently deleted or left out.

5. An “Illegal DLD Entry End” error message is output when a tag primitive end is encountered when not processing a non-main type, i.e., in the middle of main text. It may be that a tag primitive specified previously is misspelled. The delimiter is ignored, and deleted.

6. A “ ... text outside Tag Primitive” error message is output when in –Rep, –Ret or –Rec mode and unidentified text is encountered, i.e., it is not within any tag primitive at all. If the –erc option is specified, the program continues; otherwise, the program aborts.

7. A “Cannot find /FOOT;name” error message is output when in –Rep or –Ret mode and the named footnote does not exist.

2-26 FromXSF and ToXSF Transforming Data Using ToXSF

8. A “Cannot find /FOOTPG;name Page n” error message is output when in –Rep or –Ret mode and the named footnote exists but no piece of the footnote exists on the page position specified.

ToXSF Page Formats and Sizes

This section describes normal ToXSF behavior when creating a new division, i.e., when the –Rep or –Ret option is not specified.

• The first main page is a unique short depth of 46 lines, a size that fits nicely on the XyView screen along with its top of the page Frill. The maximum depth used for all other main and Lost and Found pages is dynamically computed using the Max Page Size field specified in the Job Ticket. The intent is to create pages that are approximately 65% full, i.e., have 35% free space if one were to edit before composing. • All main pages consist of a single block within a single stream of MAIN stream and one block within a single stream of FRILLS stream. • Each tag primitive type FOOT, FOOTPG, PICK and STORY is created on its own separate Lost and Found page type and is processed as follows: a. FOOT;name and FOOTPG;name;pagepos items reside on a separate page type, each with a single stream containing multiple blocks. Each footnote or footnote piece occupies a separate block with pages breaking at the computed depth mentioned above. b. PICK;name items reside on a separate page type, each page having multiple streams containing multiple element blocks. Each pickup occupies a separate stream with pages breaking at the computed depth mentioned above. The PICK tag has no text of its own. The pickup element block types are: ANNT —Annotation block with its text CAPT —Caption block with its text TITL —Title block with its text GRAPH;name—Graphic image block (no text) c. STORY;name items reside on a separate page type, each page consisting of a single block within a single stream without any FRILLS turf. Each story may reside on multiple, contiguous pages of this type. • The ToXSF program runs more efficiently if each of the four types of text are grouped together, e.g., all FOOTs, then all PICKs, etc., rather than alternating back and forth between types. The order of the groups makes no difference; whatever makes the most sense to the user is fine.

Transforming Data FromXSF and ToXSF 2-27 Using ToXSF

Footnote Tag Primitives

The ToXSF program can process two types of footnote tag primitives on a mix-and-match basis. (See the –foot and –ftpg options on page 2-7.) The following examples are in classic mode format. {/FOOT;name;track} . . . text . . . \. {/FOOTPG;name;pagepos;track} . . . text . . . \.

The latter is used, usually with the –Rep or –Ret options in an auto loose- leaf environment, to replace individual pieces of multipage footnotes. The pagepos argument specifies the page position instance within the division where a piece of the named footnote resides.

If the existing footnote is split across multiple columns (i.e., blocks), all the old blocks on the pagepos are replaced with a single new block. If the named footnote does not exist, or, if no piece of the footnote exists on the specified pagepos, an appropriate error message is output and the new footnote piece is appended to the current Lost and Found ″f″ page. A final total message is output with the number of ″Footnote Page″ errors, if any.

ToXSF Help File The ASCII file $XYV_EXECS/help/toxsf.txt is available to provide the user with a brief summary of toxsf options. To display this file, type the following at the command line: xyhelp toxsf

You may also print this file.

You can also refer to ToXSF in the XML Professional Publisher: Command Line Utilities for information on the ToXSF options.

Tag Primitives Help File

The ASCII file $XYV_EXECS/help/TAG_prims.txt is available to provide the user with a brief summary of the tag primitives and the arguments that are recognized by the ToXSF program, as well as other XPP applications.

To display this file, type the following on the command line: xyhelp TAG_prims

You may also print this file.

2-28 FromXSF and ToXSF Transforming Data Restoring Divisions

...... Restoring Divisions

If you run the ToXSF program and overwrite a division by mistake, you can recover the division by completing the following steps:

1. Select the job in the PathFinder Tree View that contains the division you want to recover. XPP displays, in the List View, the divisions the job contains.

2. Right-click the division in the List View that you want to recover. XPP displays a pop-up menu. 3. Click Manage Division from the pop-up menu. XPP displays a submenu.

4. Select Sessions from the submenu. XPP displays a second submenu.

5. Select Go to Previous from the second submenu. XPP displays a Go To Previous message box, asking you to confirm that you want to replace the current editing session.

6. Click No to cancel replacing the current editing session. XPP closes the message box and returns to PathFinder. —or— Click Yes to replace the current editing session of the division with the previous editing session. XPP restores the division to the state it was in prior to running ToXSF.

If your system is configured to save only one previous session, it is important to restore the division before taking any other action on it. The Sessions Saved field in the Job Ticket must have a value of at least 1 for you to be able to restore a previous session.

Transforming Data FromXSF and ToXSF 2-29 2-30 FromXSF and ToXSF Transforming Data Chapter 3

XyChange

XyChange is a powerful XPP transformation program that, in and of itself, provides a way to modify your content using a sophisticated pattern matching language. It also serves as a coordinating hub to allow you to use other transformation tools as you move content into or out of XPP.

This chapter describes:

• The XyChange program • An overview of the transformation process • The process of setting up XPP transformation tables • An overview of XPP transformation table fields • Basic match and output strings • The procedure for running the XyChange program • A sample transformation

For information on tools available to fine-tune your transformation tables (such as wildcards and variables), refer to Chapter 4, “Advanced XyChange Techniques.”

Transforming Data XyChange 3-1 Understanding XyChange

...... Understanding XyChange

With XyChange, you can transform text to a format appropriate for your needs. You can also choose the tool appropriate for your task. XyChange can be used to launch Perl or OmniMark scripts, or XSLT style sheets. Each transformation technology has its strengths and weaknesses:

• XyChange offers fast pattern matching. • Perl offers strong string processing capability, ways to work with XML structure, and strong UTF-8 support. • OmniMark offers the ability to program using the structure of an SGML or XML instance. • XSLT gives you a standard way to work with XML, transforming it as required.

XyChange is a powerful XPP program that performs the following tasks:

• Checks the Input and Output tables fields in the Job Ticket or the Table names field on the Transform tab of the Import/Export Dialog for specific table names to use when translating input or output files. • Based on the type of table (determined by its filename extension), invokes the appropriate transformation engine(s), such as Perl scripts (.pl), OmniMark scripts (.xom), or XSLT style sheets (.xsl), necessary to transform the input or output file. Programmer’s Note: When using .pl, .xom, and/or .xsl transformations, the XyChange program calls the appropriate executable. When that transformation engine finishes, it returns its exit code to xychange, which in turn returns its own exit code. Therefore, when your script checks for the return status, it gets the return status from xychange, and not from Perl, OmniMark, or whichever transformation engine you are using. • Processes the input/output file using a XyChange transformation table if the table types do not match those listed above.

An Overview of the Transformation Process XPP accepts text data from a variety of different sources. However, once text is brought into an XPP division, it is stored as Unicode/UTF-8.

XyChange was originally used to transform content into XyASCII to be imported into XPP. It serves today to find and change text strings in your content stream as you bring the content into XPP. For example, you could transform all occurrences of the abbreviation ″St.″ to ″Street″ to conform to your site’s style.

3-2 XyChange Transforming Data Understanding XyChange

The transformation process involves:

• Determining what you need to transform • Creating transformation tables, scripts, and style sheets • Running the XyChange program

Note: The rest of this chapter describes xychange using its native transformation tables (tt-Specs). For transformations using .pl, .xom, and .xsl files, consult the appropriate vendor documentation. For launching perl, OmniMark, or XSLT through XyChange, refer to Setting Up Transformation Tables on page 3-7.

XyChange/XSLT

What Do You Need To Transform? Because transformation can be very complex, it is important that you plan for it from the beginning. Before you create a transformation table or run xychange, you should know what you want the transformation to accomplish.

The XyChange program uses a pattern matching process, matching patterns in the input file against rules that tell it what to write into the output file.

To perform a successful transformation, you need to examine your input files carefully and note the codes and characters you find there. You need to create a table that matches each input pattern to the desired output string.

If your site often creates ASCII files that become part of XPP documents, you may want to set up a list of codes that word processing users can enter and easily transform into the required result for publishing in XPP.

For example, ask yourself questions such as: • Does ^B mean bold in your ASCII word processing file? • What is the result you want to see in XPP? • Do you want bold word processing text to become a processing instruction or do you want to assign a specific tag to it? • Are there abbreviations in the word processing files that need to be spelled out in your XPP document? • Should multiple space bands be deleted or become a tab call?

From a series of questions like these, you can determine the kinds of rules you want in your XyChange table.

Transforming Data XyChange 3-3 Understanding XyChange

Setting Up XyChange Transformation Tables After you identify what you need to translate, you set up transformation tables. A transformation table is an XPP spec that contains a set of rules. Each rule has information for translating one string of characters.

Note: For the transformation process, you may also use Perl and OmniMark scripts or XSLT style sheets in any combination. Please refer to the vendor documentation for information on writing these scripts.

XyChange rules can be simple or complex. They can set a one-to-one correspondence or they can impose conditions and use variables to specify exact cases for the transformation.

With the XyChange program, you can create and use multiple transformation tables for the same set of files.

Running XyChange When you know what you want to translate and you have written the rules for doing so, you run xychange. Using the transformation tables, xychange can perform any transformation, from a simple eight-bit character code transformation of raw text to a complex code structure-to-code structure transformation.

Transformation Types There are two types of transformations you can specify in transformation table rules: unconditional and conditional.

Unconditional Transformation An unconditional transformation tells xychange to replace one string of char- acters with another string of characters. To specify an unconditional trans- formation in a transformation table, you enter:

• The character string that xychange looks for in the input text, or match string. • The replacement string of characters, or output string.

For example, you might want to replace all the ASCII ^B character strings with a processing instruction .

3-4 XyChange Transforming Data Understanding XyChange

Conditional Transformation A conditional transformation tells xychange to replace one string of characters with another string of characters if certain conditions are true. To specify a conditional transformation in a transformation table, you specify:

• The string xychange looks for, or match string. • The conditions that must exist before the transformation occurs. • Any processing that should take place before the transformation occurs. • The replacement string of characters, or output string.

For example, your word processor begins bold text with the ^B command and ends bold text with the same command. In an XPP document, begin bold text and end bold text are two different commands. During the transformation, you want some of the ^Bs to mark the start of the bold text and others to mark the end of it.

With a conditional transformation, you can use a transformation variable to alternate codes. When the variable is zero, XPP replaces an ASCII ^B with and sets the variable to one. When the variable is one, XPP replaces an ASCII ^B with and sets the variable to zero.

Writing Transformation Tables The following points are important to keep in mind as you develop transformation tables: • Plan ahead. Analyze the original document and visualize the transformed document. • Translate only the codes being used in the current ASCII file. If you need to transform other functions, you can do so later. • Use comments so others can understand your transformation tables when they use or modify the tables later. Comments also help you to define and understand the logic of each rule and how the rules in a table work together to perform the transformation. • Use several small transformation tables rather than one large one. You might use one table for formatting codes, another for type-related codes, and a third to strip out unnecessary characters. Note: The order in which you list the tables is important. Xychange invokes the transformation engines in the order in which they are listed in the Input Tran and Output Tran fields. Reordering just two transformation engines could have very unexpected results.

Transforming Data XyChange 3-5 Understanding XyChange

• Set up separate tables to transform the coding specific to each device. For example, set up one table to transform IBM™ PC coding and another to transform Apple Macintosh™ coding. You can include rules to transform coding that are not specific to a device in these tables or in a separate table. • Assign descriptive names to transformation tables. For example, ibm for an IBM PC table, apple for an Apple transformation table, or johnson for a table associated with an author named Johnson.

The following factors may affect the efficiency of the XyChange process:

• Using a wildcard as the first character of a match string may impact the speed of the transformation process. • Limit the maximum length of wildcard match strings. • Try to make all match strings unique so that xychange does not have to evaluate the If True expressions of multiple rules with identical match strings. • If the match strings of several rules are identical, xychange evaluates the If True expressions of each rule to determine which rule is the best match. The best match is the match string that matches the longest text string in the input file.

3-6 XyChange Transforming Data Setting Up XPP Transformation Tables

...... Setting Up XPP Transformation Tables

To set up a transformation table: 1. Edit the Job Ticket to specify the name of the library containing the appropriate transformation tables.

2. Access the transformation table(s) by entering the name(s) in the Input/Output Tran fields.

3. Complete the transformation table rules.

Completing the Job Ticket Before running xychange, fill in the XyChange Library field in the Job Ticket with the name of the library containing the transformation tables, script(s), and style sheet(s) you are using. You can add tables to the std-tran library (the default entry for the XyChange Library field) or you can set up tables in your spec library. The following figure shows the XyChange fields in the Job Ticket.

Figure 3-1 XyChange fields in the Job Ticket

Transforming Data XyChange 3-7 Setting Up XPP Transformation Tables

Field Entry XyChange Library: Enter the name of the library containing the transformation tables to use when running xychange. Valid Entries: string A name containing as many as eight alphanumeric characters, including uppercase and lowercase letters, spaces, symbols (such as $, &, /), and the integers 0 through 9. Do not include the “L” that precedes the library name. This is required only for XPP to be able to display the library through PathFinder. std-tran The SDL-delivered library containing sample transformation tables (default). Input Tran 1–6 Enter the names of as many as six transformation tables that are located in the library named in the XyChange Library field or at the current job level. The tables listed in Input Tran are normally used to transform ASCII to XSF. A transformation table name can contain as many as eight alphanumeric characters, including uppercase and lowercase letters, spaces, symbols (such as $, &, /), and the integers 0 through 9. Order of entry is important. xychange default behavior runs the text files through each specified transformation table in the order in which they appear in these fields. Fields may be left empty. xychange checks each field, taking no action when it finds an empty one, progressing to the next field until all six are checked. If all six fields are empty, the message No Transformation tables in Job Ticket appears and xychange terminates. Note: If you use OmniMark and/or Perl scripts for the transformation process, it is not necessary to enter the .xom or .pl extensions. Output Tran 1–6 Enter the names of as many as six transformation tables that can be used as alternates or in addition to the tables specified in the Input Tran fields. Again, order of entry is important. All the same parameters apply to the Output Tran fields as do the Input Tran fields. To access the contents of the Output Tran fields, you can enter the –alt or the –both switch on the XyChange command line. In PathFinder, you can access the contents of the Output Tran fields by selecting Use Job Ticket radio button and Use both input and output tables check box on the Transform tab of the Import or Export dialog box.

3-8 XyChange Transforming Data Setting Up XPP Transformation Tables

Creating Files for Transformation Tables, Scripts, and Style Sheets Transformation tables, scripts, and style sheets can exist at the library level or at the job level. This section describes how to create XyChange transformation tables in XPP or the files for Perl and OmniMark scripts and the XSLT style sheets. To write OmniMark scripts, Perl scripts, and XSLT style sheets, please refer to the OmniMark, Perl, or XSLT documentation. For a sample Perl script, refer to the next section. To create a file for a new transformation table, script, and style sheet:

1. Open PathFinder.

2. Double-click the Style Libraries icon in the PathFinder Tree View. XPP displays a list of style libraries. 3. Right-click the library in the Tree View you specified in the Job Ticket. XPP displays a pop-up menu.

4. Select New. XPP displays a submenu containing the possible types of style library files you can create.

5. Click the type of file you want to create. XPP creates a new spec under the appropriate style type if you select Transformation Tables. If you select OmniMark, Perl, or XSLT, XPP creates a new style file and also opens Notepad with the appropriate file name.

Sample Perl Script

The following is an example of a Perl transformation script. It can be used as a template to write your own scripts.

# !/etc/xyvision/common/perl/bin/perl # This is a sample PERL script that can be used as a starting template when # a ‘.pl’ file is found for XyChange. # The Perl script is called with a regular translation name (i.e. perltest) and # the script ″perltest.pl″ lives at the Job level/Translation library. # The Perl file is called as: # perltest.pl InputFile OutputFile # where: InputFile is the source file and OutputFile is the destination file. # NOTE: It is the users responsibility to write the output file.

Transforming Data XyChange 3-9 Setting Up XPP Transformation Tables

# This simple example opens the source file line by line and converts # “Xyvision Enterprise” to “SDL” and then writes the output file. # It does not handle missing arguments or other severe errors. use strict; my $line; open (IN, ″$ARGV[0]″) or die ″Cannot open file $ARGV[0]″; open (OUT, ″>$ARGV[1]″) or die ″Cannot open file $ARGV[1]″; while ($line = ) { $line =~ s/Xyvision\sEnterprise/SDL/g; print OUT $line; } close IN; close OUT; exit 0;

Accessing a Transformation Table, Script, Style Sheet

You can access a transformation table, script, or style sheet either at the job level or the library level using PathFinder.

To access an existing transformation table, script, style sheet:

1. Open PathFinder.

2. Navigate to the job or library that contains the table, script, or style sheet you want to access. 3. Click the plus icon in front of the job or style library you want in the PathFinder Tree View. XPP displays the files or containers that the job or style library contains.

4. Select OmniMark, Perl, Transformation Tables, or XSLT. XPP displays a list of appropriate files or specs in the List View. 5. Double-click the file or spec in the List View that you want to use. XPP opens:

• The tt Spec if you selected Transformation Tables. • Notepad with the appropriate file if you selected OmniMark, Perl, or XSLT.

3-10 XyChange Transforming Data Setting Up XPP Transformation Tables

Structure of a Transformation Table A transformation table contains a header record and one or more rules. Each rule tells xychange how to transform codes and characters. The following figure shows a sample transformation table.

Figure 3-2 Transformation Table

Transforming Data XyChange 3-11 Setting Up XPP Transformation Tables

XPP Transformation Table Fields The following fields in a transformation table describe the values you can enter in those fields.

File Comment Enter a comment about the transformation table, such as the date it was last modified.

A comment can be as long as 71⁄2 lines (512 characters).

Table Comment Enter a comment about the transformation table, such as the type of exter- nal device that generated the text, the name of the job you are translating, and the date you created the table.

A comment can be as long as 71⁄2 lines (512 characters).

Enable debug Indicate whether xychange executes debug commands specified in the trans- formation table rules.

Entry Description yes Execute the debug commands. no Do not execute the debug commands.

Refer To For more information on the debug command, refer to Chapter 4, “Advanced XyChange Techniques.”

Match Enter character sequences, called match strings, that you want to change in the input text file. A match string can consist of characters, escape sequences, and wildcards:

• Characters represent themselves (for example, f, Y, 1, or ;). • Escape sequences represent characters that would otherwise have special meaning or that cannot be displayed on the screen (for example, ˆN for new line). • Wildcards are special characters that represent text strings other than themselves. For example, a question mark (?) matches a single character.

The XyChange program searches forward through the input file for strings identical to the match strings. When the program finds an exact match, it replaces the match string with the output string.

3-12 XyChange Transforming Data Setting Up XPP Transformation Tables

XyChange prioritizes rules according to the length of the match string; the longest match string is processed first. However, if two rules have the same match string length for the same type of information, then the order in which the rule is entered in the table is important. Since XPP processes the rules in the order in which they appear, rule one matches before rule two.

Refer To For information on entering match strings, refer to “Completing Match and Output Strings” later in this chapter. For information on using wildcards in match strings, refer to Chapter 4, “Advanced XyChange Techniques.”

Output Enter replacement text, or output string, for the match string. An output string can consist of characters, escape sequences, and variables:

• Characters represent themselves (for example, f, Y, 1, or ;). • Escape sequences represent characters that have special meaning or that are not displayed on the screen (for example, ˆN for new line). • Variables allow you to print the contents of numeric and string variables.

You can also output the contents of the match strings, if you desire.

Note: XyChange checks that the format of the field entry is valid. For example, if you use a bracket ([) in an Output field, xychange reminds you to use a caret (ˆ) before the bracket ([).

Refer To For information on entering output strings, refer to “Completing Match and Output Strings” later in this chapter. For information on using variables in output strings, refer to Chapter 4, “Advanced XyChange Techniques.”

If True Enter conditions that must be true before xychange transforms the input text.

Refer To For information on specifying conditions in the If True field, refer to Chapter 4, “Advanced XyChange Techniques.”

Then Do Enter operations for xychange to perform after translating text.

Refer To For information on specifying operations in the Then Do field, refer to Chapter 4, “Advanced XyChange Techniques.”

Comment Enter a comment that describes the purpose of the rule. A comment can be as long as 3 lines (256 characters).

Transforming Data XyChange 3-13 Using Match and Output Strings

...... Using Match and Output Strings

All basic XyChange transformation tables must include match and output strings.

This section describes:

• Guidelines for entering match and output strings • Escape sequences • XSF characters and corresponding escape sequences • Translating special function XPP characters

Guidelines for Match and Output Strings • Match strings are case sensitive. Be precise when entering uppercase and lowercase letters in a match string. For example, xychange does not match the string title A to the text title a. If you are unsure whether a character is lowercase or uppercase, you can insert several match string variations in different rules or use a wildcard to represent an unknown character. Using a wild card, xychange matches the string title ? to title A and title a, as well as to title followed by a space and any other character. • Use spacebands to limit matches to complete words. Xychange searches for characters that are the same as match strings; it does not distinguish between complete words and sequences within words unless you insert beginning and/or ending spacebands. For example, to limit a match to the word and, insert spacebands before and after the string. Otherwise, these sequences would match: Sandra, andiron, incandescent, and so on. • Use a caret after a trailing spaceband. When a variable spaceband is the last character in a Match or Output field, you must insert a caret (ˆ) after the spaceband, or the spec editor strips out the spaceband. Do not insert a caret when a spaceband is not the last character in a field.

3-14 XyChange Transforming Data Using Match and Output Strings

For example, the following rule uses a caret after trailing spacebands in the Match field:

Match o ˆ If True Then Do Output 〈bullet〉 Comment Change an “o” preceded by five spaces and followed by four spaces into a “bullet” macro. Because the field ends in a spaceband, insert a caret at the end of the match string.

• xychange matches file text to the longest matching string in a transformation table. This allows you to distinguish between similar strings. For example, xychange tries to match text to in10ˆR before trying to match text to in10. • The order in which rules appear in a transformation table is important. When input text of the same length matches two rules in a table, xychange selects the rule that appears first in the table. • To delete a string from an input file, specify the string in a Match field and then leave the Output field blank. This feature is useful when you want to strip a text sequence out of a file. For example, this rule tells xychange to strip codes from the input file:

Match .mt9ˆRˆN.mb9ˆRˆN If True Then Do Output Comment Match and delete codes defining top and bottom page margins.

• Use a caret (ˆ) in a match or output string when the following character is a special character.

Escape Sequences in Match and Output Strings Match and output strings can contain escape sequences. An escape sequence represents characters that would otherwise have special meaning or that cannot be displayed on the screen. In ASCII files generated by the XPP FromXSF program, escape sequences represent special characters, punctuation marks, and symbols that are XPP special characters or XyChange commands.

Transforming Data XyChange 3-15 Using Match and Output Strings

Escape Sequence Formats An escape sequence consists of a caret (ˆ) followed by a letter, a hexadeci- mal code, or a special character, for example, ˆ13, ˆ0b, ˆN, and ˆ*. The XyChange program uses three categories of escape sequences:

• Two-character hexadecimal codes. These codes represent a foreign device’s format commands and character access coding. For example: ˆ0A — Line feed or new line ˆ01 — soh (start of header) ˆ08 — bs (backspace) When a caret precedes two hexadecimal digits, the sequence repre- sents the character whose value is that hexadecimal number. Use an escape sequence to represent non-displayable hexadecimal codes in the format ˆxx (values 00–1f). These are all the ASCII codes with a value less than that of the space bar (20). Hexadecimal format codes are often transmitted with the text file. For example, ˆ02, ˆ1E, and ˆ0A are hexadecimal codes that an IBM PC uses. • Mnemonic representations of four common hexadecimal codes. You can enter the mnemonic or its corresponding hexadecimal code, but generally mnemonics are shorter and easier to use. The format of mnemonics is ˆX (where X is an uppercase letter). For example: ˆN — Line feed or new line (hexadecimal 0A) ˆR — Carriage return (hexadecimal 0D) ˆT — Tab (hexadecimal 09) ˆF — Form feed (hexadecimal 0C) • Characters from the XyChange command set. Use an escape sequence for punctuation marks and symbols that are part of the XyChange command set. To literally represent characters from the XyChange command set, insert a caret (^) before the characters when they appear in a match string or an output string. For example, a caret followed by an asterisk (^*) represents an asterisk while a single asterisk (*) represents a multiple-character wildcard. The following list of characters are from the XyChange command set. You must precede these characters with a caret when you enter them in a Match or Output field.

3-16 XyChange Transforming Data Using Match and Output Strings

Table 3-1 XyChange Command Set Characters

Literal Character XyChange Command

ˆ & & Ampersand Delimits variables in output strings

ˆ ! ! Exclamation point Delimits string variables

ˆ * * Asterisk A multiple-character wildcard

ˆ ? ? Question mark A single-character wildcard

ˆ [ [ Left bracket The beginning delimiter of wildcard character sets

ˆ ] ] Right bracket The end delimiter of wildcard character sets

ˆ ˆ ˆ Caret Marks escape sequences

^ - - hyphen Defines wildcard character ranges

^ ∼ ∼ tilde Negates the meaning of character sets (means NOT)

^ ; ; semicolon Marks the end of a wildcard character set

XSF Characters and ASCII Strings The following table shows some frequently used characters and their corresponding ASCII sequences. The table includes the escape character caret (ˆ) before those characters requiring it for the Match and Output fields.

Table 3-2 Xyvision Characters and Their ASCII Sequences

Xyvision Symbol ASCII XSF Unicode Character XyChange Number Number Sequence

Apostrophe ’ ’ 39 x28

At sign @ \@ 64 x40

Backslash \ \ / 92 x5c

Transforming Data XyChange 3-17 Using Match and Output Strings

Table 3-2 Xyvision Characters and Their ASCII Sequences (Continued)

Xyvision Symbol ASCII XSF Unicode Character XyChange Number Number Sequence

Begin single ‘ \‘ 128 x2018 quote

Begin tag Ò { 20 symbol

Begin XyMacro Ô 〈 18 symbol

Dagger † \^ 140 x2020

Double prime ′′ ′′ 34 x22

Em dash — \M 24 x2014

Em space \m 30 x2003

En dash – \N 23 x2013

En space \n 29 x2002

End of stream \. 5

End single ’ \’ 129 x2019 quote

End tag Ú } 19 symbol

End XyMacro  〉 17 symbol

Figure space \f 27 x2007

Greater than 〉 \g 62 x3e

Hard return \E 10

Left curly { |Pˆ[ 123 x7b brace

Left square [ \ˆ[ 91 x5b brace

Less than 〈 \h 60 x3e

Percent sign % \% 37 x25

Pgraf Ó % 16

Prime ′ ‘ 96 x60

3-18 XyChange Transforming Data Using Match and Output Strings

Table 3-2 Xyvision Characters and Their ASCII Sequences (Continued)

Xyvision Symbol ASCII XSF Unicode Character XyChange Number Number Sequence

Right curly } |Pˆ] 125 x7d brace

Right square ] \ˆ] 93 x5d brace

Slash / / 47 x2f

Thin space \t 28 x2009

Notes on Translating Special XPP Characters

If you are transforming ASCII files in classic XPP mode, the following information will be helpful.

XPP assigns special functions to some standard ASCII characters.

• XPP does not highlight the special function characters when you view or print an ASCII file. • You do not precede these characters with a caret (ˆ) when you use them in match and output strings. • Include these special function characters in transformation tables to ensure that they convert correctly to XSF format. • For example, a percent sign (%) is the ASCII code for a pgraf (Ó). A file that uses percent signs in mathematical formulas has been sent to the XPP application. Because you do not want to convert the percent signs to pgrafs (Ó), you transform a % into the ASCII sequence for a percent sign, that is \%. When you transform the file to XSF format, \% transforms to a percent sign (%) and % transforms into a pgraf (Ó).

Note: For a complete listing of characters that have special functions in the XPP application, refer to the Xyvision Character Set Spec at your site.

Transforming Data XyChange 3-19 Using Match and Output Strings

The following are transformation rules for some common characters that have special functions in XPP and that require transformation:

Match { Output | Pˆ[ Comment { is the code for a begin tag character. | P[ is the ASCII sequence for a left curly brace. [ is a character in the XyChange command set that you must precede with a caret.

Match } Output | Pˆ] Comment } is the code for an end tag character. | P] is the ASCII sequence for a right curly brace. ] is a character in the XyChange command set that you must precede with a caret.

3-20 XyChange Transforming Data Running the XyChange Program

...... Running the XyChange Program

This section describes the XyChange processing sequence, provides a checklist of tasks to complete before running xychange, and explains how to perform a XyChange transformation.

You can run xychange:

• From PathFinder using the Transform tab on the Import/Export Dialog. • From the operating system command line by entering the xychange command.

XyChange Processing Sequence xychange does not alter or delete text in the input file. Instead, XPP creates a new output file with the name you specify. Some files require only one transformation pass to accomplish the desired results. Other files require multiple transformations. You can run an ASCII text file through as many as twelve transformation passes automatically from XPP (if you elect to use both the Input/Output Tran fields) or as many transformation passes as you need from the operating system command line. When you start the transformation process, xychange performs the following tasks: 1. Looks for the transformation table, first, at the job level first, next, in the library named in the Job Ticket. Note:When running an Import or Export process from PathFinder, xychange runs with the –e switch. If the program is unable to find the specified transformation table in either location, this switch causes the transformation process to fail and xychange reports that it is unable to find “tt_somename” transformation table.

2. Invokes the XyChange transformation table or the appropriate transformation engine for Perl or OmniMark scripts, or XSLT style sheets. 3. Runs the files through successive transformation passes if you have specified multiple tables, scripts, and style sheets in the Job Ticket or on the command line. Note: xychange performs one transformation pass.

4. Monitors the transformation process and displays error messages on the screen for your review.

5. Informs you when the process is complete.

Transforming Data XyChange 3-21 Running the XyChange Program

Guidelines for Running XyChange Before performing a xychange transformation, check the following: • Know where the input file you want to transform is located. • Be sure that the Job Ticket lists the name of the XyChange library that contains the transformation tables. If the Job Ticket does not list the XyChange library, refer to the section “Completing the Job Ticket” on page 3-7. • Be sure to fill in the appropriate transformation table fields in the Job Ticket or list the transformation tables on the operating system command line if you intend to run a file through successive xychange passes automatically. • Select the Use Job Ticket radio button and the Use both input and output tables check box on the Transform tab of the Import or Export Dialog if you want to use all the transformation tables. You can also run xychange from the operating system command line. Please refer to the section “Running XyChange from the Command Line” later in this chapter. • Be sure the transformation tables contain rules that tell the XyChange program how to convert input text. • Know that the transformation tables exist either at the job level or at the library level on the system.

Running XyChange from PathFinder To run xychange from PathFinder:

1. Right-click the division on which you want to run the transformation. XPP displays a pop-up menu.

2. Select Process. XPP displays a submenu. 3. Click Import or Export, depending on the process you want XPP to perform. XPP displays the appropriate dialog box, consisting of three tabs.

4. Fill in the appropriate fields on the Import/Export tab.

5. Fill in the appropriate fields on the FromXSF/ToXSF tab.

6. Click the Transform tab. XPP displays the Transform dialog box, consisting of two sections: Transformation Tables and Additional Command Options.

3-22 XyChange Transforming Data Running the XyChange Program

7. Click one radio button in the Transformation Tables frame: Use Job Ticket XPP enables the Use both input and output tables check box if you want XPP to use both the input and output tables listed in the Job Ticket. Otherwise, XPP uses only the output tables for exporting and only the input tables for importing.

—OR—

Table name(s) XPP enables the Table Names text box. Enter the name of the table(s) you want for the output file. If you enter more than one name, separate them with a space or a comma. If you choose to use the Job Ticket, xychange begins with field 1 of the appropriate Input/Output Tran, proceeds to field 2, etc. Empty fields are skipped, that is, xychange takes no action. If only field 6 contains an entry, xychange checks but takes no action on fields 1 through 5 and processes the table in field 6. If you choose to specify table names, xychange uses only the transformation tables that you specify. The tables you specify, however, must exist in the XyChange library named in the Job Ticket or at the job level, but do not themselves have to be named in the Job Ticket.

8. Click the Run button. If you checked the Preview command check box on the Import or Export tab, XPP displays a message box containing the commands you selected for the Import/Export process along with the option to continue: • Click No. XPP closes the message box and cancels the process, allowing you to make changes to the commands. —or— • Click Yes. Export/Import processes the division according to your specifications, or with the default settings, and displays Import/ Export processing messages in the text box to the right of the dialog box.

For more detailed information concerning the Import or Export process, please refer to XML Professional Publisher: User Guide.

Transforming Data XyChange 3-23 Running the XyChange Program

To examine the output file that xychange created:

1. Right-click the division that contains the XyChange file. XPP displays a pop-up menu. 2. Click Division Tools on the pop-up menu. XPP displays a submenu.

3. Click View File as ASCII on the submenu. XPP displays a Select File To View as ASCII dialog box.

4. Select the ASCII file you want to view. XPP opens Notepad and displays the file.

Note: You can run a file through multiple transformations by selecting transformation tables interactively and using the output file from the previous transformation as the input file for the next transformation.

Running XyChange from the Command Line If you have access to the operating system, you can run xychange directly from the command line. The format of the xychange command is: xychange[–cd path] [–alt] [–both] [–l ttname1 ttname2 ...] infile outfile

The following example, xychange intext trantext says:

• Use the current division level directory • Translate data in the file named intext using the transformation tables named in the Input Tran Table fields of the Job Ticket • Generate a file named trantext

The next example, xychange –alt intext trantext

says:

• Use the current division level directory • Translate data in the file named intext • Use the transformation tables named in the Output Tran Table fields of the Job Ticket • Generate a file named trantext

3-24 XyChange Transforming Data Running the XyChange Program

This example, xychange –l trantab intext trantext –debug

says:

• Use the current directory • Use a transformation table named trantab • Translate data in the file intext • Generate a file named trantext • Enable debugging

Note: For detailed information on running xychange from the command line, see XML Professional Publisher: Command Line Utilities.

Transforming Data XyChange 3-25 Sample XyChange Transformation Process

...... Sample XyChange Transformation Process

This section describes a sample transformation process, including: • An ASCII file before transformation • Sample rules from a transformation table • The ASCII file after transformation • The composed file in page mode

ASCII File Before Transformation The following figure shows how a word processing file might be repre- sented. You can see codes in the ASCII file that must be converted, for example, the codes ˆRˆN and .MDNM/.

Figure 3-3 ASCII File Before Transformation

3-26 XyChange Transforming Data Sample XyChange Transformation Process

Sample Transformation Table Rules The transformation table rules in the following figure convert ASCII coding to coding that XPP can understand.

Rule 1

Rule 2

Rule 3

Rule 4

Figure 3-4 Transformation Table Rules Following are descriptions of the rules for the figure above:

1. Searches for and strips codes from the beginning of the ASCII file and saves the book title in a register for use in a frill block. The rule searches for a 1- to 50-character wildcard (*) and outputs this character string between a Print Cancel (px) XyMacro and a Print Allow (pa) XyMacro. The string is saved in text register 18.

2. Converts the strings [chapnum] and [chap] to {chapnum} and {chap}. (The ToXSF program transforms the open brace [{] and close brace [}] characters to the begin tag [Ò] and end tag [Ú] characters.) This rule outputs the chapter number and title.

Transforming Data XyChange 3-27 Sample XyChange Transformation Process

The caret (ˆ) precedes each square bracket because square bracket characters have special meanings in XyChange rules.

3. Converts the [b] string into . (The ToXSF program transforms the greater-than [ <] and less-than [> ] characters to the begin XyMacro and end XyMacro Ô  characters.)

4. Creates a sidenote to be used before a pickup. This rule searches for the string .MDBU/[sidenote]*.MDNM/, where the * represents a 1- to 50-character string. The rule outputs:

• Pickup placement XyMacro. • {/PICK} tag primitive to create and place the pickup block. Because unique names are not specified in the tag primitive name argument, pickups are named sequentially as p1, p2, p3, and so on. • {/ANNT} tag primitive to create and place an annotation block. • Converts the [sidenote] string to {sidenote}. • The contents of string variable !1 (The text matched by the 1 to 50 char wildcard). • Backslash followed by a period (\.) to mark the end of the pickup stream.

3-28 XyChange Transforming Data Sample XyChange Transformation Process

ASCII File After Translation The following figure shows the ASCII file after it has been transformed. The ASCII codes are transformed into XPP codes, and you can see the pickup XyMacros and tags.

Note: To convert the ASCII file to Xyvision Standard Format, ToXSF was run on the file after running xychange.

The discovery of the Titanic{chapnum}CHAP TER ONE{chap}The Night Lives On{intro}Just 20 minute s short of midnight,April 14, 1912, the great new White S tar Liner Titantic, making her maiden voyage from Southam ton to New York, had a rendezvous with ice in the calm, dark waters of the North Atlantic. She brushed the berg so gently that many on board didn’t notice it, but so let hally that she was instantly doomed. %By midnight Captain Edward J. Smith knew the worst, and ordered the lifeboats filled and lowered.{/PICK;p1;9p;;page;cot;co b}{/ANNT;left;top}{sidenote}By midnight Captain Smith kn ew the worst\.There were distressingly few of these,enough for only a third of the ship’s company. The rule was, of course,\’\’women and children first.\’\’ At 12:15 A.M. the Titanic sent her first distress call. At 12:45 she be gan firing rockets, for there was a light on the horizon, tantalizingly near. The light remained motionless.%

Figure 3-5 ASCII File After Transformation

Transforming Data XyChange 3-29 Sample XyChange Transformation Process

Composed File in Page Mode The following figure shows the effect of the XPP coding on the composed file in page mode. The title of the article is centered and uses the format in the Ò chap Ú tag. The transformation/conversion process is now complete.

Figure 3-6 Composed File in Page Mode

3-30 XyChange Transforming Data XyChange with Xalan Processing

...... XyChange with Xalan Processing

This section will give details and examples of the syntax of the xychange command when an Xalan argument that requires being surrounded by single quotes is being specified in the xychange command.

The -p option is an option specifically to the Xalan XSLT 1.0 processor, it is not a XyChange option. This detailed information about using -p does not apply to the xppxslt XSLT 2.0 processor (which is used when the -xsl2 option, and possibly the -xslauto option, is used with xychange), only to the (default) XSLT 1.0 engine (Xalan).

Note: The format of the Xalan -p option is ″-p name expression″. The -p option expression argument for the Xalan XSLT processor can be an alphabetic value (e.g. the name of a month). When the expression argument is an alphabetic value, the Xalan program requires that this argument be surrounded by single quotes.

If using XyChange to invoke the Xalan processor, it is necessaray to use the right syntax so that the required single quotes are not stripped before the Xalan command is executed by XyChange.

The right syntax depends on what ″shell″ or script language is being used to invoke the XyChange command and the specific way the XyChange command is being invoked. Here are some examples (with spaces added around the single and double quotes only for clarity; the spaces would need to be removed for the real commands).

Windows bat file: set month=June xychange ... -xsl -p month ″ \″ ’ %month% ’ \″″ -xyend ...

Perl (the syntax in order to work on both UNIX and Windows): my $cmd = q/xychange ... -xsl -p month ″ \″ ’June’ \″″ -xyend .../; system(″$cmd″); OR my $month = ″June″; my $s = q/ ″ \″ ’ /; my $e = q/ ’ \″″ /; my $arg = ″$s$month$e″; system(″xychange ... -xsl -p month $arg -xyend ...″); It is necessary to split the command into parts as shown if you need to use any variables in the command.

ksh/sh: month=June xychange ... -xsl -p month ’ ″ ’ ″ ’ ″$month″ ’ ″ ’ ″ ’ -xyend ...

Transforming Data XyChange 3-31 XyChange with Xalan Processing

csh: set month=June xychange ... -xsl -p month ’ ″ ’ ″ ’ ″$month″ ’ ″ ’ ″ ’ -xyend ...

3-32 XyChange Transforming Data Chapter 4

Advanced XyChange Techniques

When you are familiar with the transformation process and the basic features of the XyChange program, you may want to use some more advanced XyChange features to fine-tune your transformation tables.

This chapter describes features you can use to make the XyChange program more powerful, including:

• Using wildcards in match and output strings • The If True and Then Do fields • XyChange variables • Quoted strings • Using the reinput and debug commands

Before reading this chapter, you should be familiar with the information in Chapter 3, “XyChange.”

Transforming Data Advanced XyChange Techniques 4-1 Using Wildcards in Transformation Rules

...... Using Wildcards in Transformation Rules

Wildcards are special characters that represent variable-length sequences of characters. They enable you to use a shorthand notation when specifying match and output strings.

Use wildcards to create string substitution rules to cover expected and unexpected cases that follow the same pattern.

For example, you can use wildcards to convert all tabbing commands in a document into a different format, even though the values (arguments) of those codes vary in each instance.

Follow these general guidelines:

• Use a single-character wildcard to match any single character in the input text, and a multiple-character wildcard to match multiple characters in the input text. • In a match string, you can use a wildcard character alone or followed by a wildcard character set enclosed in square brackets. A wildcard character set limits the characters from which the matching input can come. • In an output string, you can use the wildcard alone or use a wildcard variable. You cannot use a wildcard character set in an output string. • The maximum number of wildcard characters that can appear in a match string is 204.

Single-Character Wildcards in Match Strings A single question mark (?) matches any single character in the input text. The general format of a single-character wildcard in a match string is: ?[character set]

The format indicates the following: ?—Denotes a single-character wildcard. [—Indicates the beginning of a wildcard character set. character set—Defines the set of characters from which the matching input must come. ] —Indicates the end of a wildcard character set.

4-2 Advanced XyChange Techniques Transforming Data Using Wildcards in Transformation Rules

Guidelines for Using Single-Character Wildcards

• Use the question mark (?) in a match string to match a single character in the input text. You can use a question mark alone or followed by a wildcard character set enclosed in square brackets. • A wildcard character set can consist of any characters that are valid in the match string — standard characters and escape sequences. • You can type each character in the set or you can indicate a range of characters by typing the begin and end characters separated by a hyphen (-). • When you indicate a range of characters, xychange matches characters whose ASCII hexadecimal values fall within that range. (The match string is an ASCII field, not an XSF field, so a range is based on ASCII values and not Unicode values.) For example, ?[a-z] means all characters greater than or equal to a and less than or equal to z (all lowercase letters). • To negate or reverse the meaning of a character set, use a tilde (∼) as the first character in the set. The tilde indicates the set of characters that the matching input string cannot include. • Use an escape sequence to represent the hyphen (-), tilde (∼), and semicolon (;) when they are in a wildcard character set. For information on escape sequences, refer to “XyChange”, chapter 3.

The following table contains examples of single-character wildcards.

Table 4-1 Examples of Single-Character Wildcards

Wildcard Matches

? Any single character

?[0-9] Any single decimal digit

?[ cd] A single spaceband or the lowercase letter c or d

?[ˆ-13] A hyphen (-), or either digit 1 or 3

Transforming Data Advanced XyChange Techniques 4-3 Using Wildcards in Transformation Rules

Multiple-Character Wildcards in Match Strings Multiple-character wildcards represent strings of characters in the input text. The format of a multiple-character wildcard in a match string is: *[character set;min,max]

The following table contains the format for multiple-character wild cards.

Table 4-2 Format of a Multiple-Character Wildcard

Element Description

* Denotes a multiple-character wildcard.

[ Indicates the beginning of the wildcard character set.

character set Defines the set of characters from which the matching input must come.

; Terminates the character set.

min Represents the minimum length of the matching string. This value can be an integer from 0 through 16384.

, Separates the minimum and maximum values.

max Represents the maximum length of the matching string. This value can be an integer from 0 through 16384.

] Indicates the end of the wildcard character set.

To shorten the multiple-character wildcard format, you can omit certain parameters:

• If the wildcard sequence can be any character, you can omit the character set, for example, *[;1,8]. • You can omit the maximum value; xychange assumes a maximum of 100 characters, for example, *[;1,]. • You can omit both the maximum value and the comma, for example, *[;5]. xychange assumes that the maximum value equals the minimum value, that is, the matching string is a fixed length. • You can specify only the character set and omit the minimum value, the maximum value, the comma, and the semicolon (for example, *[a-z]). The minimum and maximum values are assumed to be 1 and 100 respectively. • You can omit the entire qualifying string, including the brackets, for example, *. The minimum and maximum values are assumed to be 1 and 100 respectively, and the matching input sequence can be any character(s), including none. • A match string can capture a total of 16384 characters.

4-4 Advanced XyChange Techniques Transforming Data Using Wildcards in Transformation Rules

The following table lists some examples of multiple-character wildcards.

Table 4-3 Examples of Multiple-Character Wildcards

Wildcard Matches

* Any one to 100 characters

*[a-z] Any series of lowercase letters, from 1 to 100 characters.

*[0-9;2] Any 2-digit number

*[0-9;1,4] Any 1- to 4-digit number

*[;1,5] Any string of 1 to 5 characters

*[∼a-zA-Z;1,10] 1 to 10 non-alphabetic characters

*[∼5Aˆ?] Any characters, except 5, A, and ?, from 1 to 100 characters.

Guidelines for Using Multiple-Character Wildcards The rules and guidelines for multiple-character wildcards are the same as those for single-character wildcards, plus the following:

• A multiple-character wildcard usually matches the smallest possible character string in the input text. For example, if the match string is a*b and if the input text contains the characters acbcb, xychange matches acb and not acbcb. • When a wildcard is at the end of a match string, xychange matches the longest input string. For example, if the match string was go to page *[0-9] and the input text contained the characters go to page 100, the match string would match go to page 100 instead of go to page 1.

Note: Entering a wildcard character as the first character in a match string can affect the speed of the transformation process.

Using Wildcards in Output Strings In an output string, a wildcard represents text from the input file.

• The total number of characters that can be output in the output string is 20000. • Use a wildcard in an output string when you want to output the characters that matched a wildcard in the match string of the same rule. • Use a question mark (?) in the output string to denote a corresponding single-character wildcard in a match string.

Transforming Data Advanced XyChange Techniques 4-5 Using Wildcards in Transformation Rules

• Use an asterisk (*) in the output string to denote a corresponding multiple-character wildcard. • The first question mark (?) in the output string refers to the character that matched the first ? wildcard in the input string. The second question mark in an output string refers to the character that matched the second ? wildcard in the input string, and so on. The same correspondence applies to the multiple-character (*) wildcard. • Alternatively, you may use string variables to output match strings. &!1 outputs the first match string, &!2 outputs the second match string, and so on. If you have more than 9 match strings, you would use the following syntax: &![10] to reference the tenth, and so on.

4-6 Advanced XyChange Techniques Transforming Data Using If True and Then Do Fields

...... Using If True and Then Do Fields

The following describes how to enter data in the If True and Then Do fields:

• An If True field can contain one or more tests. Use a semicolon (;) to separate multiple tests. A test is an arithmetic expression which is considered true if it has a non-zero value and false if it has a zero value. Expressions are composed of arithmetic terms (such as + and –) and logical terms (such as NOT). • A Then Do field contains one or more statements. Use a semicolon (;) to separate multiple statements. A statement assigns the value of an arithmetic expression to a variable. • One of the If True and Then Do fields may contain an entry while the other field is empty. • xychange ignores spacebands that appear between operators and variables in an expression. You can insert spacebands to make an expression easier to read. • The equal sign (=) means different things in If True and Then Do fields. In the If True field, the equal sign is a comparative operator that tests whether values are equal. In the Then Do field, the equal sign assigns the value on the right of the equal sign to the variable on the left. • The variable to which you assign the new value must be the first character in the expression. • Valid expression: T=x*y • Invalid expression: x*y=T

The following are valid If True and Then Do field entry components:

• Integers — in the range -32768 through 32767. • Variables — uppercase and lowercase letters, (a–z and A–Z). All variables are initially set to 0 (false). Set variables to other values by using statements in the Then Do field. • Operators, constants, and quoted strings

Transforming Data Advanced XyChange Techniques 4-7 Using If True and Then Do Fields

The following example shows how to use the If True and Then Do fields:

Match Dr. Smith If True A=0;y=0 Then Do A=2;y=9 Output Dr. Jones Comment change Smith to Jones Match ?[A-Z] If True a=0 Then Do b=#!1+32 Output &#b Comment change upper case to lower case Match ?[A-Z] If True a=1 Then Do a=0 Output ? Comment first letter after space, don’t change Match ^ If True Then Do a=1 Output ^ Comment spaceband, set a=1 so next letter won’t change case

Guidelines for the If True Field To determine whether or not to use the current input string as a match, xychange evaluates If True expressions that appear in a rule. • An If True field can contain more than one expression. • Use a semicolon (;) to separate multiple expressions. • If there is more than one condition, all conditions must be true (non-zero) for xychange to consider the string a match. • If True expressions can consist of variables (numeric, string, and wildcard values), operators, constants, and quoted strings.

You can use three types of operators in an If True expression: comparative, binary, and unary.

4-8 Advanced XyChange Techniques Transforming Data Using If True and Then Do Fields

Comparative Operators Comparative operators compare two values to determine whether one value is equal to, less than, or greater than the other, for example, 3 < 4. Use comparative operators with either string or numeric variables. The following table lists valid comparative operators.

Table 4-4 Comparative Operators

Operator Meaning

= Equal to

> = Greater than or equal to

< = Less than or equal to

< > Not equal to

< Less than

> Greater than

Binary Operators Binary operators work on two or more values, for example, 12 * 5. Use binary and unary operators only with numeric variables. The following table lists valid binary operators in order of precedence.

Table 4-5 Binary Operators

Operator Meaning

* Multiply

/ Divide

% Modulo (remainder of a divide)

+ Plus

– Minus

& Logical AND

| Logical OR (vertical bar)

Transforming Data Advanced XyChange Techniques 4-9 Using If True and Then Do Fields

Unary Operators Unary operators work on only one value, for example, NOT 7. Use unary operators with numeric variables to invert the value of a variable in an expression. If the value of a variable is 0, inserting a tilde (∼) or the word NOT changes the value to 1. You can use the words TRUE and FALSE to represent the values 1 and 0, respectively. You can use a number sign (#) as a unary operator to convert the first character of a string variable to a numeric value. This enables you to manipulate the hexadecimal values of the input characters. The following table lists valid unary operators.

Table 4-6 Unary Operators

Operator Meaning

∼ Tilde (logical NOT)

NOT Unary word not

# Converts the first character of a string to a numeric value

4-10 Advanced XyChange Techniques Transforming Data XyChange Variables

...... XyChange Variables

Variables enable you to perform functions such as: • Storing text and numeric values • Performing arithmetic operations on numeric values • Setting test conditions

The XyChange program uses three types of variable to perform these functions:

• String • Numeric • Wildcard

You can display the contents of a string variable, a numeric variable, or a wildcard variable by using a variable output string.

String Variables

When the XyChange program begins its transformation process, all string variables are empty.

You can use a string variable to store as many as 16384 characters of any kind. You can also use a string variable to store a wildcard value for later use. However, you cannot perform arithmetic operations on string variables.

You represent a string variable by an exclamation point followed by one uppercase or lowercase letter, for example, !a or !Q.

Numeric Variables

When the XyChange program begins its transformation process, all numeric values are set to zero.

You can perform arithmetic operations on numeric variables. You can also use a numeric variable to set a test condition in an If True field.

You represent a numeric variable by one uppercase or lowercase letter, for example, c or Z.

A numeric variable can store only a numeric value. That value must be an integer within the range of -2,147,483,647 through 2,147,483,647.

Transforming Data Advanced XyChange Techniques 4-11 XyChange Variables

Wildcard Variables

A wildcard variable is a special type of string variable that can store as many as 16384 characters. You cannot perform arithmetic operations on wildcard variables.

You can use a wildcard variable in an output string if you first define the variable by using the wildcard character in the match string of the same rule. You can use multiple wildcards in match strings and reference them in output strings by using the syntax of an exclamation point followed by a single digit for wildcards 1-9 and by an exclamation point followed by double digits enclosed in brackets as delimiters for wildcards above the 9th.

A wildcard variable is represented by an exclamation point followed by a single digit from 1 through 9, for example, !1 – !9. When using more than nine wildcard variables, the syntax is ![##]. You can also use the format ![#] to access single digit wildcard variables. The number in a wildcard variable refers to the order in which the wildcard appears in the match string. For example, the wildcard variable !3 refers to the third wildcard in the match string and ![23] refers to the twenty-third wildcard in the match string.

Using Variables in Setting Test Conditions

You can use variables in If True, Then Do, and Output fields. You can test the current value of a variable by including the variable in an If True expression. To change the value of a variable, use the variable in a Then Do expression. You can also use wildcards in If True, Then do, and in Output fields. You cannot use variables in a Match field.

Comparing Variables in If True Expressions

You can use an If True expression to compare values of different variables using the following rules:

• To compare variables of the same type, such as string-to-string or numeric-to-numeric, use comparative operators. • To compare different types of variables, such as string-to-numeric or numeric-to-string, you must use quoted strings. • When comparing numeric variables, the XyChange program uses their arithmetic values; for example, 57 > 45. • When comparing string variables, the XyChange program compares the standard ASCII character set. For example, tan < tin evaluates to true because the word tan occurs before the word tin in a dictionary (transforms into a lower ASCII value).

4-12 Advanced XyChange Techniques Transforming Data XyChange Variables

The following table displays examples of valid If True tests:

Table 4-7 Examples of Valid If True Tests

If True Expression Test

d=1;T>=2 Tests whether or not numeric variable d equals 1 and numeric variable T is greater than or equal to 2.

!2=!F Tests whether or not the wildcard variable !2 contains the same text as string variable !F.

d = TRUE Tests whether or not numeric variable d equals 1.

d = FALSE Tests whether or not numeric variable d equals 0.

NOT d If d is 0, then NOT d equals 1.

∼d If d is 0, then ∼d equals 1.

Using Wildcard Variables in If True and Then Do Fields You can use wildcard variables in If True and Then Do fields. Do not insert an ampersand (&) before the wildcard variable in these fields since the amper- sand is used to begin a variable output string.

Using Wildcard Variables in Output Strings When xychange matches input text to a match string containing wildcards, xychange places the matching text sequences into special wildcard variables according to their match sequence. For example, if you have three wildcard variables in the match string, their contents go into wildcard variables !1, !2, and !3. To output the contents of a wildcard by its order in the match string, use a wildcard variable in an output string. For example, !1 refers to the value of the first wild card in the match string and ![11] refers to the eleventh wild card in the match string. Following is the format of a wildcard variable in output strings:

For single digits: &!digit or &![#]

For multiple digits: &![##]

In this example: &—Marks the beginning of a variable in an output string. ! —Marks the next sequence as a wildcard variable. digit, [#], or [##]—Indicates the order in which the wildcard text appears in the input string.

Transforming Data Advanced XyChange Techniques 4-13 XyChange Variables

Each wildcard character counts as a separate string. For example, ?[0-9]* counts as two wildcards.

The special wildcard variable !0 always refers to the entire string of characters that matched the input string. For example:

• This is a geometry test appears in the match string. • You insert Note: &!0 in the output string • The output text would read Note: This is a geometry test.

You can use a wildcard variable to change the order of input and output text strings. For example:

• The match string is ? plus ? equals *[0-9]. • The input text is 7 plus 3 equals 10. • The output string is &!2 plus &!1 equals &!3, • The output text would read: 3 plus 7 equals 10.

Displaying Variable Values To display the value of a numeric, string, or wildcard variable in an output string, use a variable output string. The format of a variable output string is: &justify sign-control [pad]width base variable

The ampersand (&) and the variable are required entries in a variable output string. The other parameters are optional, and tell xychange how to format the contents of the variable. The following table contains the format for the variable output string:

Table 4-8 Format of the Variable Output String

Entry Description

& Begins a variable output string. If you do not enter an ampersand at the beginning of the string, xychange does not know that you are referring to a variable.

justify Specify whether to right-justify or left-justify the variable. xychange justifies the variable within the field width, which is specified in the field width parameter. Valid entries: – Left-justify the variable. no entry Right-justify the variable (default).

4-14 Advanced XyChange Techniques Transforming Data XyChange Variables

Table 4-8 Format of the Variable Output String (Continued)

Entry Description

sign-control Specify whether to output a positive or negative sign. Use this only with numeric variables. Valid entries: + A number always begins with a sign, either plus (+) or minus (-). no entry A negative number begins with a minus sign (-) and a positive number has no sign.

[pad] Specify a character used to pad the field if the field is not filled by the output variable. Enclose a pad character in square brackets [ ]. If you do not specify a pad character, xychange pads the field with spacebands.

width Specify the number of characters to output. If there are too few digits or characters in a numeric or string variable to fill a field, the xychange pads the field on the left or right with the pad character, depending on the justification. If the output string is too large to fit within the field width, xychange truncates the output string, on the left or right, depending on the justification character. The maximum field width is 255 characters. If you do not specify the field width, xychange does not pad or truncate the variable.

base Specifies the number base to use when outputting a numeric variable. Do not use a number base with a string variable. Valid entries: % Specifies hexadecimal conversion. The characters output will be 0 through 9 and A through F. $ Specifies octal (base 8) conversion. # Specifies to interpret a numeric variable as a character. xychange outputs the ASCII character corresponding to the decimal code. no entry Specifies decimal (base 10) conversion.

variable The name of the variable contents to display. One uppercase or lowercase letter, such as M or d specifies a numeric variable. An exclamation point followed by one uppercase or lowercase letter, such as !M or !d specifies a string variable. An exclamation point followed by a single digit from 1 to 9, !digit or ![#], such as !9 or ![9] specifies a single digit wildcard variable and ![##] specifies a double digit wildcard variable.

Transforming Data Advanced XyChange Techniques 4-15 XyChange Variables

The following table demonstrates how to use variable output strings to display the content of variables.

Table 4-9 Examples of Displaying the Contents of Variables

This Variable Displays: Output String:

&c Contents of numeric variable c.

&!d Contents of the string variable !d.

&%c Contents of numeric variable c as a hexadecimal number.

&-10!d Contents of string variable d left justified in a field of ten characters, with the field padded with spaces.

&-[*]10!d Contents of string variable d left justified in a field of ten characters, with the field padded with asterisks.

&[0]4c Contents of numeric variable c as a four-digit number with leading zeros if necessary.

Note: After expansion of a variable output string, the total length of the output string cannot exceed 20000 characters.

4-16 Advanced XyChange Techniques Transforming Data Quoted Strings

...... Quoted Strings

A quoted string is a text string enclosed in double quotes (“ ”).

The XyChange program treats a quoted string literally, as it does a variable output string. It converts the quoted string to an output string before it assigns a value or compares the string to another variable.

A quoted string follows the same format as a variable output string.

Guidelines for Using Quoted Strings

If you want to indicate the literal meaning of double quotes (“) within a quoted string, insert a caret (^) before the double quotes (^“).

You can use quoted strings:

• In an If True expression when comparing unlike variables; for example, when comparing string-to-numeric or numeric-to-string. • In a Then Do expression to concatenate string variables, to display a numeric variable in a string variable, or to insert literal characters in a variable.

When comparing variables, xychange orders them by their hexadecimal values. For example, you compare the numeric value 5 (which has an ASCII hexadecimal value of 35) to the string value five (where the letter f has an ASCII hexadecimal value of 66),

The result is: 5 < five (hex 35 comes before hex 66).

Transferring Numeric and String Variables

If a string variable contains a number, you can transfer the number to a numeric variable so that you can perform arithmetic computations.

You can also transfer the value of a numeric variable to a string variable. But you cannot transfer a numeric variable to a string variable directly. You must convert the value of the numeric variable by using a quoted string. For example, !x = “&d”

sets the string variable x equal to the digit string representing the numeric value of d.

Transforming Data Advanced XyChange Techniques 4-17 Quoted Strings

The following table provides examples of quoted strings in If True and Then Do fields.

Table 4-10 Examples of Quoted Strings in If True and Then Do Fields

Quoted String Meaning in If True Field Meaning in Then Do Field

!c = “&d” Is true if string variable c Sets string variable c equal to contains the string the value of the digits stored in representing the value of d. numeric variable d.

!d = “&!c&!2” Is true if string variable d is Sets string variable d equal to equal to the contents of string the contents of string variable c variable c followed by the followed by the contents of the contents of the second second wildcard in the match wildcard in the match string. string.

!h= Tests whether or not string Stores the word “Friday” “ ˆ“Fridayˆ” ” variable h contains the word (including quotes) in string “Friday” (in quotes). (Use an variable h. escape sequence when quotation marks appear within a quoted string.)

4-18 Advanced XyChange Techniques Transforming Data Using the Reinput Command

...... Using the Reinput Command

To tell xychange to reprocess a string of characters output by a rule during processing, use the reinput command in the Then Do field.

xychange inserts the contents of the output string into the input text immediately before the next input text character. The characters then run through the transformation program again.

• Inserting a reinput command in the Then Do field of a transformation record tells xychange to treat output string text as potential match string text in any transformation rule — either the current rule or a different rule. • When the Then Do field contains a reinput command, xychange replaces match string text with output string text, then continues to search for matching text. The search includes the just-replaced text string.

Table 4-11 Examples of the Reinput Command in Then Do Fields

Command Effect

reinput “hello” Inserts the word hello into the input text stream.

reinput !c Inserts contents of string variable c into the input text stream.

reinput !1 Inserts character string that matched the first wildcard in the match string into the input text stream.

reinput Does match and replaces, then continues search; search includes just-replaced text.

Guidelines for Using the Reinput Command

The following guidelines are helpful in determining when and how to use the reinput command: • The reinput command can appear anywhere in a Then Do field. Use a semicolon (;) to separate the reinput command from other arithmetic statements that appear in the same field. • The reinput command does not affect wildcard strings or other conditional tests or statements. xychange processes the reinput command after it replaces match string text with output string text. • The reinput command does not force xychange to make any changes to text that is reinput.

Transforming Data Advanced XyChange Techniques 4-19 Using the Reinput Command

It simply tells xychange to consider output string text that has just been transformed as xychange searches for matching sequences. • Before reprocessing can occur, xychange must be able to match output text with the match string of a transformation rule. For example, you transform the input string “one thousand” into the output text “1,000” and use the reinput command. xychange does not automatically reprocess “1,000,” but it does look through all rules for a match string that matches “1,000.” • You can insert a string variable or a quoted string immediately after the reinput command. When a string variable follows reinput, xychange places the contents of the variable into the input text stream. When a quoted string follows reinput, xychange expands the quoted string (if necessary) before placing it into the input text. • The maximum number of characters that can be backed up in the input stream is 20000 characters.

Avoiding Infinite Loops Sometimes the reinput command causes too much data to become backed up in the input text stream by continuously reinputting more characters than are being converted. If the reinput string of a rule exactly matches the match string of the same rule, the XyChange program could enter an infinite loop. If xychange detects an infinite loop, the transformation program stops and displays an error message. This example shows an infinite loop condition because this transformation rule will continuously find the yy in the match string, and replace it with another yy.

Match yy Then Do reinput Output yyy

4-20 Advanced XyChange Techniques Transforming Data Using the Debug Command

...... Using the Debug Command

To help test transformation tables, you can use the Debug command in the Then Do field of a rule. The Debug command tells xychange to display the contents of wildcard, string, or numeric variables, or quoted strings in the output text.

• To turn debugging on, enter yes in the Enable debug field of the header. To turn debugging messages off, enter no in the Enable debug field. Debug inserts a message where the transformation rule takes effect. This enables you to test a particular rule. If the rule is not working, the debug message will not appear. • When the Enable debug field is set to yes, this rule displays the text

Match (HEAD1) Then Do debug ″Rule 3, Table 1″ Output {h1}

Rule 3, Table 1 wherever it outputs the output string. This enables you to see if the rule is working. • You must follow the word debug with a variable or a quoted string. The contents of this variable or quoted string will be placed in the output stream whenever the transformation rule is used. • When the transformation works properly, change the entry in the Enable debug field to no and run xychange; the message disappears.

There are also some options that can be used when running xychange to interactively turn debugging messages on or off (no matter what the Enable debug field is set to in the tt spec). • The –autodebug option causes xychange to execute an implicit debug command on every matched rule as follows (as if it was the first command in every Then Do field): debug ″*** Matched rule # ***″ where ’#’ is replaced with the tt rule number. The –autodebug option can be combined with –debug or –nodebug to control whether the debug commands that are entered in the tt file are also output or not. • The –debug option enables debug commands even when tt specs have the Enable debug setting set to no. • The –nodebug option disables debug commands even when tt specs have the Enable debug setting set to yes.

Transforming Data Advanced XyChange Techniques 4-21 4-22 Advanced XyChange Techniques Transforming Data Chapter 5

XSFChange Program

The XSFChange program lets you run a XyChange transformation on a job or single division and produce data in ASCII format that can be transported to external systems.

This chapter contains the following information:

• Understanding XSFChange • Accessing the XSFChange program • Understanding the XSFChange Spec • Converting divisions • Viewing the txsfout File

Transforming Data XSFChange Program 5-1 Understanding XSFChange

...... Understanding XSFChange

The XSFChange program scans each page in an XPP division sequentially. The program creates an ASCII file that contains text types, streams, pickup elements, and codes on a page-by-page basis. Next, the program sends the ASCII file through a user-defined XyChange transformation table. The transformation table can exist in a library or at the job level.

You can run XSFChange to convert one division at a time, or you can convert all divisions in a job. The result of the XSFChange program is an ASCII file named txsfout that exists in the division directory; the source division is not affected. You can export the txsfout file to a remote system.

Using PathFinder, you can examine the txsfout file before transporting it. You cannot run ToXSF, Add ToXSF or Replace XSF on a txsfout file.

The following steps outline how to use the XSFChange program:

1. Set up a transformation table. Before running the XSFChange program, you must set up a transformation table; the program does not include a default transformation table. Refer to Chapter 3 in this manual, XyChange, for setting up a XyChange transformation table.

2. Edit the XSFChange Program Spec. The xsc config Spec allows you to specify which data types to include in the ASCII output file and in what order to output the data. The spec also contains fields where you specify a transformation table and indicate whether the table is at the job level or in a library. For descriptions of the fields in the xsc config Spec, refer to the section “The XSFChange Program Spec” on page 5-5.

3. Run the XSFChange program on a division or on all divisions in the job. To determine the contents and format of the ASCII file, the program looks for the xsc config Spec at the job level first, and then it looks in the syslib library. If specs exist in both the library and at the job level, the program uses the local version.

4. Exit the XSFChange program. You return to PathFinder.

5-2 XSFChange Program Transforming Data Accessing the XSFChange Program

...... Accessing the XSFChange Program

You access XSFChange from PathFinder.

To select the XSFChange program:

1. Right-click the job whose divisions you want to convert. PathFinder displays a pop-up menu.

2. Select More Tools > xsfchange.pl from the series of pop-up menus.

PathFinder displays the Xsfchange option box.

3. From the Xsfchange option box, select one of the following tasks:

Option Description Convert DIV(s) Allows you to run XSFChange on one, several, or all divisions in a job. Edit Job Spec Allows you to edit the XSFChange Program Spec, xsc config, at the job level. The xsc config Spec can exist at the job level or in the syslib library. If a spec does not exist at the job level, the program creates a new spec containing standard entries.

Transforming Data XSFChange Program 5-3 Accessing the XSFChange Program

Option Description Edit Master Spec Allows you to edit the master version of the xsc config Spec in the syslib library. Delete Job Spec Removes the local version of the spec; it does not affect the master version in the syslib library. Copy Master Allows you to copy the master version to the job. If a Spec spec exists at the job level, the program displays a message asking if you want to overwrite the local spec. Copy Job Spec Allows you to copy an xsc config Spec from the job to the syslib library. The program displays a message asking if you want to overwrite the master spec. Exit Allows you to exit the Xsfchange options box.

Note: If you want to copy an xsc config Spec from one job to another, you can use regular PathFinder copy and paste operations to do so.

5-4 XSFChange Program Transforming Data Understanding The XSFChange Spec

...... Understanding The XSFChange Spec

The xsc config Spec controls the data contained in the output file. You can edit, copy, or delete the xsf config Spec using the Xsfchange options box or regular PathFinder operations. Refer to the previous section.

To display the XSFChange Spec, select Edit Job Spec or Edit Master Spec from the Xsfchange option box.

Figure 5-1 Sample XSFChange Program Spec

Fields in the XSFChange Spec

The data in the xsc config Spec is divided into the following categories:

• Output Order of Text Types • Type of Pickup Element Blocks • Miscellaneous output information • Transformation table location and name

Transforming Data XSFChange Program 5-5 Understanding The XSFChange Spec

Output Order of Text Types The following table lists the five fields that specify which text types the txsfout file includes.

Entry Description main Specifies main text. stories Specifies story text. footnotes Specifies footnotes. pickups Specifies pickup text. frills Specifies frills text. layout Specifies layout text. none If entered in all five Type fields, the text types appear in the txsfout file in the order they appear in the original XPP division. If entered in four or fewer of the Type fields, only the text types specified appear in the txsfout file (in the order they are listed in the Type fields).

The following table describes the order in which the text types appear in the file.

Text Type Description Field 1st Type Specifies the type of text that displays at the top of each page of data in the output file. For example, frills in this field means that frills text appears at the top of each page. 2nd Type Specifies the type of text that appears second in each “page” of the output file. For example, main means that main text follows frills text. 3rd Type Specifies the type of text that appears third in each “page” of the output file. For example, stories means that story text follows main text. 4th Type Specifies the type of text that appears fourth in each “page” of the output file. For example, footnotes means that footnote text follows story text. 5th Type Specifies the type of text that appears fifth in each “page” of the output file. For example, pickups means that pickup text and elements appear at the bottom of each output “page.”

5-6 XSFChange Program Transforming Data Understanding The XSFChange Spec

Type of Pickup Element Blocks The following four fields specify which type of pickup element blocks to include in the txsfout file. The XSFChange program includes pickup elements in the order in which they appear in the XPP division; you cannot change the order. For example, one pickup may contain a graphics block followed by a title. In another pickup, the title may be the first element in the pickup stream. titles Specifies whether the output file contains data from title blocks of a pickup.

Entry Description yes The output file contains data from pickup title blocks. no The output file does not contain data from pickup title blocks. graphics Specifies whether the output file contains data from graphics blocks of a pickup. Note that text does not appear in a graphics block.

Entry Description yes The output file contains data from pickup graphics blocks. no The output file does not contain data from pickup graphics blocks. annotations Specifies whether the output file contains data from annotation blocks of a pickup.

Entry Description yes The output file contains data from pickup annotation blocks. no The output file does not contain data from pickup annotation blocks.

Transforming Data XSFChange Program 5-7 Understanding The XSFChange Spec captions Specifies whether the output file contains data from caption blocks of a pickup.

Entry Description yes The output file contains data from pickup caption blocks. no The output file does not contain data from pickup caption blocks.

Miscellaneous Output Information

The following fields ask for information concerning the output of page numbers, tag primitives, line numbers, edit traces, and specified System Codes.

Output Page Number Specifies whether to output a computer-generated number to identify the position of each page of data in the txsfout file.

Entry Description yes The output file includes a page position tag primitive. For example, /PG;1, /PG;2, /PG;3. no The output file does not include a page position tag primitive.

Output Tag Primitives Specifies whether to generate tag primitives to identify the various types of text on a page.

Entry Description yes The output file contains tag primitives. For example, /MN;n for main text, /ST;name for stories, and /PK;name for pickups. no The output file does not contain tag primitives; the file contains only text data.

The following table lists the tag primitives output by XSFChange.

Table 5-1 Tag Primitives

Name Block or Stream Description

/AN Pickup Annotation Identifies each annotation block in a pickup stream.

5-8 XSFChange Program Transforming Data Understanding The XSFChange Spec

Table 5-1 Tag Primitives (Continued)

Name Block or Stream Description

/CP Pickup Caption Identifies each caption block in a pickup stream.

/FR;n Frill Identifies the start of each frill block. The n indicates the number of the frill block.

/FT Footnote Separator Identifies the start of each footnote separator block. This is the first block on each page and it has no name.

/FT;name Footnote Identifies the start of each footnote block.

/GR;name Pickup Graphic Identifies each graphic block in a pickup stream. The name is the assigned name that appears in the XPP division.

/LA;n Layout Identifies the start of each layout block. The n indicates the number of the layout block

/MN;n Main Text Identifies the start of each main text block. The n indicates the number of the block and is reset on a page basis.

/PG;n Page Identifies the start of a page. The n indicates the page position. An extra blank line precedes the page position tag primitive.

/PK;name Pickup Identifies the start of each pickup stream. The name is the assigned name that appears in the XPP division.

/ST;name Story Identifies the start of each story stream. The name is the assigned name that appears in the XPP division. An /SB tag is also generated to identify each block within the story stream.

/TL Pickup Title Identifies each title block in a pickup stream.

Transforming Data XSFChange Program 5-9 Understanding The XSFChange Spec

Output Line Numbers - Reset by Specifies whether to output computer-generated line numbers at the begin- ning of each line of text.

Entry Description none The output file does not contain line numbers. page The first line on each page is numbered 1, regardless of the type of text (that is, frills, main text, pickup, and so on). turf Line numbers reset at the start of each text type (turf). There are six text types (turfs): main text, stories, footnotes, pickups, layout, and frills. If you reset by text type, the first line in each text type is numbered 1 and the numbers continue to increment within each text type. stream Line numbers reset at the start of each stream. Pickup and story types can contain multiple streams; each new pickup and each new story starts a new stream. Turfs for main text, footnotes, layout, and frills each contain only one stream. block Line numbers reset at the start of each block. For example, each block of main text begins with line number 1. strm & blk Line numbers reset according to the type of text being output. Pickups and stories renumber by stream. Footnotes, main text, layout, and frills renumber by blocks.

Output Edit Traced Lines Only Specifies whether the output file includes only lines containing Edit Trace codes, including Strikethru Deletes.

Entry Description yes The output file contains only lines containing Edit Trace codes. no The output file contains all text (lines with and without Edit Trace codes).

Output Specified System Codes Specifies whether the output file includes System Codes and Xyps. The sys- tem uses these computer-generated codes for internal tracking and process- ing and does not display them in the XPP Division. However, they may be useful as Match strings when you build a XyChange table. Refer to Appen- dix A , “Xyps and System Codes”, at the end of this manual.

5-10 XSFChange Program Transforming Data Understanding The XSFChange Spec

Entry Description none The output file does not contain System Codes and Xyps. all codes The output file contains all System Codes and Xyps. All codes are enclosed in square brackets. Xyps begin with the letter X; System Codes begin with the letter S. For example, the Xyp [X ER:0400] indicates an error; the Xyp [X FV:0100] indicates a font variant change. The Sys- tem Code [S EL2:01] indicates a type of end-of-line. End of Line The output file contains only End of Line System Codes; other codes do not appear. Edit Trace The output file contains only Edit Trace System Codes (including Strikethru Delete); other codes do not appear. For example, [S TRAC:0203] indicates the presence of an Edit Trace code. EOL & ET The output file contains End-of-Line codes and Edit Trace codes; other codes do not appear. Math codes The output file contains only Math Xyps; other codes do not appear. For example, [X MA:05] is an internal Xyp that indicates the presence of a Math expression. EOL & Math The output file contains End-of-Line codes and Math Xyps; other codes do not appear. ET & Math The output file contains Edit Trace codes and Math Xyps. EOL, ET & Math The output file contains End-of-Line, Edit Trace, and Math Xyps; other codes do not appear.

Transforming Data XSFChange Program 5-11 Understanding The XSFChange Spec

Transformation Table Location and Name

The following fields ask for transformation information.

Transformation Table Location Specifies the XyChange transformation table that the XSFChange program uses. The transformation table can exist at the job level or it can exist in a library.

Entry Description job Use a job level transformation table. library Use a transformation table in the library, for example, std-tran.

Transformation Table Name Specifies the name of the transformation table that the XSFChange program uses. You set up a transformation table of your choice; the XSFChange program does not include a default transformation table. Before running the XSFChange program, enter rules in the table that meet the needs of your installation.

Entry Description –none– You do not require a transformation table. trantable Use the transformation table specified. (If the transforma- tion table does not exist, the XSFChange program aborts.)

5-12 XSFChange Program Transforming Data Converting Divisions

...... Converting Divisions

You can run the XSFChange program on one, several, or all divisions in one job. You can run the program from PathFinder or from the command line.

Running XSFChange from PathFinder.

To convert division(s):

1. Access XSFChange from PathFinder. (refer to page 5-3.)

2. Select the Convert DIV(s) option from the Xsfchange option box. The program displays the Directory Selection box.

3. Select the division(s) you want to convert. If you want to select multiple divisions, hold down the Ctrl key while selecting subsequent divisions. The program displays progress messages on the screen and creates a file named txsfout in the division directory. If you are converting multiple divisions, the XSFChange program creates a file named txsfout in each division directory. When processing is complete, the program displays the Xsfchange options box. You can select another function, or press Cancel to exit.

Running XSFChange from the Command Line

You can run the XSFChange program from the command line using the following format:

xsfchange [param1] [param2] ...

For a complete list of options for xsfchange, refer to XML Professional Publisher: Command Line Utilities

Transforming Data XSFChange Program 5-13 Viewing the txsfout File

...... Viewing the txsfout File

You can view the txsfout file from PathFinder.

To examine the txsfout file created by the XSFChange program:

1. Right-click the division in the PathFinder Tree View whose txsfout file you want to view. PathFinder displays a pop-up menu. 2. Select Division Tools > View File as ASCII from the sequence of pop-up menus. PathFinder displays the ASCII selection box.

3. Select txsfout and press the Open button. XPP displays the file in Notepad or your specified ASCII editor. You can print the file from the ASCII editor.

Sample txsfout Files The following sample txsfout files contain:

• All codes • End of Line codes • Math codes

5-14 XSFChange Program Transforming Data Viewing the txsfout File

All Codes The following figure shows a txsfout file containing all codes.

^N {/PG;1}^N {/FR;1}^N 1: {folior}^[X_ULIN:00^]^[X_SH:c00d^]^[X_SW:c00d^]^[S_EL2:03^]^N {/MN;1}^N 2: {cn}^[X_ULIN:00^]^[X_FV:0100^]^[X_SH:8010^]^[X_SW:8010^]^[X_RLW:c09c0000^] ^[X_RLD:b0000000^]^[X_RLI:0000000000000000^]^[S_EL2:03^]^N 3: ^[X_CGS^]^[X_SH:c018^]^[X_SW:c018^]CHAPTER^[S_EL2:03^]^N 4: ^[X_CGS^]^^[X_SH:0042^]^[X _SW:0042^]1^[S_EL2:03^]^N 5: ^[X_CGS^]^[X_RLW:c09c0000^]^[X_RLD:b0000000^]^[ X_RLI:0000000000000000^]^[X_CGE^]^[S_EL2:3^]^N 6: ^{ct}[X_ULIN:00^]%^[X_ULIN:00^]^[X_SH:c018^]^[X_SW:c018^]INCOMPRES SIBLE^[S_EL2:03^]^N 7: %^[X_ULIN:00^]VISCOUS^[S_EL2:03^]^N 8: %^[X_ULIN:00^]FLOW^[S_EL2:03^]^N 9: %^[X_ULIN:00^]THROUGH^[S_EL2:03^]^N 10: %^[X_ULIN:00^]PIPES^[S_EL2:03^]^N 11: %^[X_ULIN:00^]{1a}^[X_ULIN:00^]^[X_SH:200f^]^[X_SW:200f^]PART A^[S_EL2:03^ ]^N 12: %^[X_ULIN:00^]GENERAL COMPARISON OF LAMINAR^[S_EL2:03^]^N 13: %^[X_ULIN:00^]AND TURBULENT FLOWS^[S_EL2:03^]^N 14:%^[X_ULIN:00^]^[X_RLW:80de0100^]^[X_RLD:b0000000^]^[X_RLI:0000000000000000 ^]^[S_EL2:03^]^N 15: {l}^[X_ULIN:00^]^[X_CGS^]1.1\m^[X_CGE^]INTRODUCTION^[S_EL2:03^]^N 16: %^[X_ULIN:00^]^[X_FV:0000^]^[X_SH:c00d^]^[X_SW:c00d^]An important topic wh ich we must discuss is concerned with the question of when^[S_EL2:01^]^N 17: viscous effects are significant to a degree which dictates a shift from ir rotational flow^[S_EL2:01^]^N 18: to an approach taking friction into account. For this purpose it is useful to distinguish ^[S_EL2:01^]^N 19: between two broad classes of flow. The flows around bodies such as airfoil s, rockets, ^[S_EL2:01^]^N 20: and surface vessels are called ^[X_FV:0200^]external flows ^[X_ FV:0000^]when other boundaries of the flow, such^[S_EL2:01^]^N 21: as the earth\’s surface, are comparatively distant from the body. Flows wh ich are ^[S_EL2:01^]^N 22: enclosed by boundaries of interest will be called ^[X_FV:0200^]inter nal flows^[X_FV:0000^]. Examples of internal ^[S_EL2:01^]^N 23: flows include the flow through pipes, ducts, and nozzles. ^[S_EL2:01^]^N 24: ^[S_EL2:03^]^N 25:^[X_SH:c00d^]^[X_SW:c00d^]^[X_FF:0000^]^[X_FV:0400^]^[X_MA9:026 d31000000000000^]^[S_IG^]^[S_IG^]^[S_IG^]^[X_LG:0102^]\^[|M^[|gL^X_LG:0102^]\ ^]|M^]^[X_MA:05^]^[X_SH:c00d^]^[X_SW:c00d^]^[X_FF:0000^]^[X_FV:0000^]^[X_FV :0000^]^[S_EL2:03^]^N 26: ^[X_FV:0400^]|m.\n^[S_EL2:03^]^N 27: ^[X_FV:0000^]0^[S_EL2:03^]^N 28: i^[S_EL2:03^]^N

Figure 5-2 Sample txsfout File Containing All Codes

Transforming Data XSFChange Program 5-15 Viewing the txsfout File

End of Line Codes The following figure shows a txsfout file containing End of Line codes.

^N {/PG;1}^N {/FR;1}^N 1: {folior}^[S_EL2:03^]^N {/MN;1}^N 2: {cn}^[S_EL2:03^]^N 3: CHAPTER^[S_EL2:03^]^N 4: 1^[S_EL2:03^]^N 5: ^[S_EL2:3^]^N 6: {ct}%INCOMPRESSIBLE^[S_EL2:03^]^N 7: %VISCOUS^[S_EL2:03^]^N 8: %FLOW^[S_EL2:03^]^N 9: %THROUGH^[S_EL2:03^]^N 10: %PIPES^[S_EL2:03^]^N 11: %{1a}PART A^[S_EL2:03^]^N 12: %GENERAL COMPARISON OF LAMINAR^[S_EL2:03^]^N 13: %AND TURBULENT FLOWS^[S_EL2:03^]^N 14:% ^[S_EL2:03^]^N 15: {l}1.1\mINTRODUCTION^[S_EL2:03^]^N 16: %An important topic which we must discuss is concerned with the question o f when^[S_EL2:01^]^N 17: viscous effects are significant to a degree which dictates a shift from ir rotational flow^[S_EL2:01^]^N 18: to an approach taking friction into account. For this purpose it is useful to distinguish ^[S_EL2:01^]^N 19: between two broad classes of flow. The flows around bodies such as airfoil s, rockets, ^[S_EL2:01^]^N 20: and surface vessels are called external flows when other bounda ries of the flow, such^[S_EL2:01^]^N 21: as the earth\’s surface, are comparatively distant from the body. Flows wh ich are ^[S_EL2:01^]^N 22: enclosed by boundaries of interest will be called internal flows. Examples of internal ^[S_EL2:01^]^N 23: flows include the flow through pipes, ducts, and nozzles. ^[S_EL2:01^]^N 24: ^[S_EL2:03^]^N 25:^ [|gL^] ^[S_EL2:03^]^N 26: |m.\n^[S_EL2:03^]^N 27: 0^[S_EL2:03^]^N 28: i^[S_EL2:03^]^N

Figure 5-3 Sample txsfout File Containing End of Line Codes

5-16 XSFChange Program Transforming Data Viewing the txsfout File

Math codes The following figure shows a txsfout file containing Math codes.

^N {/PG;1}^N {/FR;1}^N 1: {folior}^N 2: {cn}^N 3: CHAPTER^N 4: 1^N 5: ^N 6: {ct}%INCOMPRESSIBLE^N 7: %VISCOUS^N 8: %FLOW^N 9: %THROUGH^N 10: %PIPES^N 11: %{1a}PART A^N 12: %GENERAL COMPARISON OF LAMINAR^N 13: %AND TURBULENT FLOWS^N 14:%^N 15: {l}1.1\m INTRODUCTION^N 16: %An important topic which we must discuss is concerned with the question o f when^N 17: viscous effects are significant to a degree which dictates a shift from ir rotational flow^N 18: to an approach taking friction into account. For this purpose it is useful to distinguish^N 19: between two broad classes of flow. The flows around bodies such as airfoil s, rockets,^N 20: and surface vessels are called external flows when other bounda ries of the flow, such^N 21: as the earth\’s surface, are comparatively distant from the body. Flows wh ich are^N 22: enclosed by boundaries of interest will be called internal flows. Examples of internal^N 23: flows include the flow through pipes, ducts, and nozzles.^N 24: ^N 25: ^[X_MA9:026d31000000000000^]^[TR^] |m= ^[\t\t\t;\^;blank>^[X_MA:05^]^N 26:\t^N 27: i^N 28: \t^N 29: j^N 30: ^[X_MA9:026d31000000000000^]\t\t\t ov>\t^]^[X_MA:05^]^N 31: \t^N 32: ^[X_MA9:026d31000000000000^]^[|gL^]^[X_MA:05^]^N 33: |m.\n^N 34: 0^N 35: i^N 36: |m-^N 37: |m.\n^N 38: |m-^N 39: 0^N 40: |m.\n^N 41: ^[X_MA9:026d31000000000000^]^[|gL^]^[X_MA:05^]^N 42: j^N

Figure 5-4 Sample txsfout File Containing Math Codes

Transforming Data XSFChange Program 5-17 5-18 XSFChange Program Transforming Data Part II

Importing and Transforming Styles

Chapter 6

Importing and Exporting Page Layouts

You can pass information about pages, blocks, and shapes between XPP divisions and ASCII files by running the ToXSF and FromXSF programs with the –layout option.

You can transfer made-up pages (layout blocks and text together), or you can create pages and blocks separately and pour text onto the pages later.

This chapter describes how to perform these functions if you are running XPP in standard mode, and provides examples. If you are running XPP in XML/SGML mode, please refer to Chapter 10 “Importing and Exporting XML/SGML Data”.

Transforming Data Importing and Exporting Page Layouts 6-1 Layout Control Designators

...... Layout Control Designators

The ToXSF and FromXSF programs recognize five layout control designators:

Table 6-1 Layout Control Designators

Layout Control Description Designator

[PAGE] Specifies the X and Y coordinates relative to the page frame, as well as the width, depth, and rotation of a page.

[FRAME] Contains width and depth information of a page frame (optional).

[BLOCK] Specifies the X and Y coordinates relative to the page, as well as the width, depth, type, name, rotation, and color of a block.

[SHAPE] Specifies the X and Y points of an exclusion shape relative to its position on the page.

[CPPAGE] Specifies the page and block geometry to copy from one page to another.

6-2 Importing and Exporting Page Layouts Transforming Data Using ToXSF to Import Page Layouts

...... Using ToXSF to Import Page Layouts

You can use the ToXSF program to create frozen layout pages, blocks, and shapes based on layout controls in an ASCII file.

You can import pages that include both layout blocks and text, or you can import the page and block layouts first, and bring in the text later.

Running ToXSF with the –layout option produces a division with frozen page layouts. After running ToXSF, you can save the frozen page layouts in the Page Layout (PL) Spec by selecting the sequence Menu > Layout > Pages > Store to PL Spec on the Softkey menu.

Importing Layout Pages with Text To import page layouts with text, insert a {/MAIN} tag primitive in the ASCII file at the start of each new page—a page ends when ToXSF encounters another {/MAIN} tag primitive or an end delimiter (\.). To specify the layout geometry, insert [PAGE], [FRAME], [BLOCK], and [SHAPE] layout designators. Insert text for each block immediately after the [BLOCK] designator. After running ToXSF on the ASCII file, the text is in an XPP division in an uncomposed format. Text appears in blocks on frozen layout pages.

Importing Layout Pages Only To import page layouts only (without text), insert a {/MAIN} tag primitive in the ASCII file at the start of each new page—a page ends when ToXSF encounters another {/MAIN} tag primitive or an end delimiter (\.). To specify layout geometry, insert [PAGE], [FRAME], [BLOCK], and [SHAPE] layout designators only. After running ToXSF on the ASCII file, the division contains frozen layout pages without text. To add text later, run ToXSF with [–a, –A or –aA] append/replace options that maintain the current page layouts.

ToXSF Command to Import Layout Pages with/without Text To tell ToXSF to process page breaks and interpret layout control statements in the ASCII file, use the –layout option with either the –Rep, –Ret, or –Rec option, the –nofrills option (optional), and the input filename.

Transforming Data Importing and Exporting Page Layouts 6-3 Using ToXSF to Import Page Layouts

The command line is: toxsf –layout –Rep (or –Rec or –Ret) [–nofrills] input-file

The following table describes the command line options.

Table 6-2 Options to Import Page Layouts

Option Description

–layout Process page layout and block control statements. Use with –Rep, –Ret, or –Rec option to create page, blocks, and shapes based on layout designation in the ASCII file.

–Rep Replace/insert/append individual main text pages; replace footnotes and pickups. The –Rep option tells ToXSF to honor {/MAIN} tag primitives, including page position and multpart page numbers, and to recognize optional end markers (\.) at the end of each text page. Footnote and pickup tag primitives cause the named footnote or pickup to be replaced on its original page. If a {/MAIN} tag primitive does not have a page position argument or has an invalid page position, ToXSF appends the text to the end of the division.

–Ret Same as –Rep option, plus regenerates edit traces not retained during fromxsf. Use in place of the –Rep option in cases where you run fromxsf without a –xyp4 option.

–Rec Recreate all main pages in a division; ToXSF creates a new division or overwrites an existing division. The –Rec option recognizes the {/MAIN} text tag primitive in the ASCII file that indicates the start of a new main page. It stores multipart page number arguments but ignores page positions.

–nofrills Excludes Frill blocks from layout processing. Use with the –layout option. ToXSF treats frill blocks as though the –layout option was not specified.

input-file Name of the ASCII file containing text and layout information.

6-4 Importing and Exporting Page Layouts Transforming Data Using FromXSF to Export XPP Page Layouts

...... Using FromXSF to Export XPP Page Layouts

You can use the FromXSF program to generate an ASCII file that defines layout pages, frames, blocks, and shapes based on the information contained in the XPP page database.

Running FromXSF with the –layout plus –Rep or –rep options produces an ASCII file where each main text page is marked with a {/MAIN} tag primitive, followed by the layout control statements for pages, frames, blocks, and shapes. Text associated with the block immediately follows the [BLOCK] designator.

FromXSF generates an ASCII file that can be resubmitted to ToXSF. There is no difference between frozen and thawed pages in an ASCII file, but when ToXSF is complete, all the pages are frozen.

You can export made up pages that include layouts and text, or you can export page layouts only.

Exporting Pages Containing Text To export XPP pages containing text, issue the FromXSF command without the –c (cancel text) option. FromXSF generates an ASCII file that contains the text, {/MAIN} tag primitives, and [PAGE], [FRAME], [BLOCK] and [SHAPE] designators. To specify a range of pages containing text to extract, use the –p and/or –P options. FromXSF creates [BLOCK] designators for different types of blocks — Main text, Stories, Frills, and Layout. Text contained in each block immediately follows the block designator.

Exporting Layout Pages Only (Without Text) To export XPP page layouts only (without text), issue the FromXSF command with the –c (cancel text) option included. FromXSF generates an ASCII file that contains {/MAIN} tag primitives, and [PAGE], [FRAME], [BLOCK], and [SHAPE] designators for each page in the division. The ASCII file does not contain text.

Transforming Data Importing and Exporting Page Layouts 6-5 Using FromXSF to Export XPP Page Layouts

FromXSF Command to Export Layout Pages with/without Text Enter the fromxsf –layout command with either the –Rep or –rep option, and the –nofrills option (optional), and the output filename. The command line is: fromxsf –layout –Rep (or –rep) [–nofrills] [–c] [–lunit ?] trawz

The following table describes command line options.

Table 6-3 Switches to Export Page Layouts

Option Description

–layout Generate page, frame, block, and shape control statements.

–Rep Replace main text pages specified by the {/MAIN} tag primitive. The –Rep option inserts the {/MAIN;page position;p1;p2;p3;p4;p5;p6} tag primitive at the start of each main text page and a delimiter (\.) at the end of each page. In the tag primitive, argument1 is the page position, and arguments 2-7 are multipart page numbers.

–rep Replace main text pages specified by the {/MAIN} tag primitive. The –rep option inserts the {/MAIN;pagepos} tag primitive at the start of the page, and a delimiter (\.) at the end of each page. The tag primitive includes one argument that indicates the page position within a division.

–nofrills To exclude Frill blocks from layout processing. Use with the –layout option. FromXSF treats frill blocks as though the –layout option was not specified.

–c Cancel the output of text characters; output tag primitives only. Use for troubleshooting and to produce a text outline.

–lunit ? Specify which unit to use when outputting fields within layout information. Without this option, the default is to output all unit fields in microns (n). See valid unit qualifiers on page 6-7. –lunit automatically forces on the –layout option.

trawz Name of the ASCII file to create containing the layout information.

6-6 Importing and Exporting Page Layouts Transforming Data Using FromXSF to Export XPP Page Layouts

ToXSF/FromXSF Layout Control Statements Tag primitives and layout control statements can appear on a single line in an ASCII file, or can be broken with a “new line.” Following are two examples of valid control statements in an ASCII file:

{/MAIN}[PAGE;...;..][BLOCK;.;..;....]text[BLOCK]text\.

{/MAIN}[PAGE;...;..][BLOCK;.;..;....]text [BLOCK]text\.

Unit Qualifiers Valid unit qualifiers for layout designators include:

Valid Unit Qualifiers p (picas) c (ciceros) k (kyu; 1/4 millimeter) q (points) d (didots) n (XPP micron units) i (inches) m (millimeters) z (centimeters)

Page Layout Designator [PAGE] Use the [PAGE] layout designator to change the X and Y coordinates, width, depth, and rotation of an existing page. When ToXSF encounters a [PAGE] layout designator, it deletes the contents of the page and changes the page geometry to reflect the new values. The format of the page layout designator is:

[PAGE; x-origin; y-origin; width; depth; rotation]

where:

Variable Description x-origin X origin of the page relative to the page frame. A number followed by a unit qualifier; defaults to 0 if no value is specified. y-origin Y origin of the page relative to the page frame. A number followed by a unit qualifier; defaults to 0 if no value is specified. width Absolute width of the page. A number followed by a unit qualifier; defaults to 8.5i if no value is specified. depth Absolute depth of the page. A number followed by a unit qualifier; defaults to 11i if no value is specified.

Transforming Data Importing and Exporting Page Layouts 6-7 Using FromXSF to Export XPP Page Layouts

Variable Description rotation Degrees to rotate the page on output. Legal values are: 0, ±90, ±180; defaults to 0 if no value is specified.

Page Layout Copy Control [CPPAGE] You can use the [CPPAGE] layout designator to copy the layout from another page, rather than redefining the page and block layout. The copypage control statement assumes that a page has already been created with the {/MAIN} tag primitive. ToXSF copies the page and block geometry of the source page to the new page, but it does not copy the text. You cannot use the [CPPAGE] designator when text is to be poured onto the page; ToXSF cannot associate the text with different types of blocks. The format of the copy page layout control statement is: [CPPAGE; copy from page number]

where:

Variable Description copy from A page position number (a number from 1-n) from page number which to copy. Defaults to the previously defined page layout if a value is not specified.

Frame Layout Control [FRAME]

You can use the [FRAME] layout control designator to adjust the page frame size on the fly. Frame size must be different from page size.

The format of the frame layout designator statement is:

[FRAME; width; depth]

where:

Variable Description width Horizontal size of the page frame. A number (not zero) followed by a unit qualifier that is different from (i.e. larger than) the width of page. depth Vertical size of the page frame. A number (not zero) followed by a unit qualifier that is different from (i.e. larger than) the depth of the page.

6-8 Importing and Exporting Page Layouts Transforming Data Using FromXSF to Export XPP Page Layouts

Block Layout Control [BLOCK] Use the [BLOCK] control statement to define the X and Y coordinates, width, depth, type, rotation, and color of a block. ToXSF assumes that a page has already been created by the {/MAIN} tag primitive. Block sequence is established by the order that the blocks are created. ToXSF creates a specific block type (main, frill, story, layout) for every [BLOCK] control statement in the ASCII text, and flows text into the newly created blocks. The format of the block control statement is: [BLOCK; x-origin; y-origin; width; depth; type; name; sequence; rotation; color]

where:

Variable Description x-origin Distance from left edge of page to the origin of this block. A number followed by a unit qualifier; defaults to 0 if no value is specified. y-origin Distance from top edge of page to the origin of this block. A number followed by a unit qualifier; defaults to 0 if no value is specified. width Horizontal extent of this block to establish the default text measure. A number followed by a unit qualifier; defaults to 0 if a value is not specified. depth Vertical extent of this block to control depth of the text. A number followed by a unit qualifier; defaults to 0 if no value is specified. type The type of the block. Valid entries are: main, story, frill, layout, or frame; defaults to main if no value is specified. name Used for two different purposes: • If type field is “story”, the name field specifies the name of a story whose text is to flow in this block. • If type field is “frame”, the name field specifies the frame block ID number for the frame block you want to print. If type field is empty or has any entry other than story or frame, the name field remains empty (i.e. ;;) and you use layout options to assign a name to the block. sequence Which block on the page to work with. This field is reserved for future enhancements. rotation Degrees to rotate the block around its origin. Valid entries are: 0, ±90, ±180; defaults to 0 if no value is specified. color Color of the block. Valid entries are: 0 - 65534; defaults to 0 (black) if no value is specified.

Transforming Data Importing and Exporting Page Layouts 6-9 Using FromXSF to Export XPP Page Layouts

Shape Primitive [SHAPE] ToXSF creates an exclusion shape for every [SHAPE] designator encoun- tered. It assumes that a page has already been created by the {/MAIN} tag primitive. The [SHAPE] control statement defines the text exclusion area on the page. The shape ends when ToXSF encounters another shape control statement, block control statement, page control statement, or an end delimiter (\.). Shape sequence is established by the order that the shapes are created. The format of the shape control statement is:

[SHAPE; sequence; box x-pos; box y-pos; box width; box depth; x-pos1; y-pos1; ...; x-posn; y-posn] where:

Variable Description sequence Which shape on the page to work with. This field is reserved for future enhancements. box x-pos The X coordinate of the bounding box that encompasses the shape. A number followed by a unit qualifier; defaults to 0 if no value is specified. box y-pos The Y coordinate of the bounding box that encompasses the shape. A number followed by a unit qualifier; defaults to 0 if no value is specified. box width The width of the bounding box that encompasses the shape. A number followed by a unit qualifier; defaults to 0 if no value is specified. box depth The depth of the bounding box that encompasses the shape. A number followed by a unit qualifier; defaults to 0 if no value is specified.

x-posn The X coordinate of a vertex point of the shape, where n is a number followed by a unit qualifier; defaults to 0 if no value is specified. A shape can have an unlimited number of x-pos points.

y-posn Y coordinate of a vertex point of the shape, where n is a number followed by a unit qualifier; defaults to 0 if no value is specified. A shape can have an unlimited number of y-pos points.

6-10 Importing and Exporting Page Layouts Transforming Data Using FromXSF to Export XPP Page Layouts

Examples of Layout Control Statements in ASCII Text This section contains three examples of layout control statements in ASCII: • Creating a Division with Text • Replacing Two Pages in a Magazine • Defining a book

Creating a Division with Text Running ToXSF on this sample file produces a two page division containing text. The command line is: toxsf –layout –Rec tsample1

{/MAIN;1} [PAGE] [BLOCK; 5p ;5p ;36p ;50p ] {text}This is text in the only main text block on page 1. [BLOCK; 4p ; 58p ; 38p ; 1p ;frill ] {rnftr}This is a running footer in the frill.\. {/MAIN;2} [PAGE] [BLOCK; 4p ;7p ;38p ;52p] {text}This is text in the only main text block on page 2. [BLOCK; 4p ; 4p ; 38p ; 1p ; frill ] {rnhdr}This is a running header in the frill.\.

Figure 6-1 ASCII Input File named tsample1 • The [PAGE] designator calls out default values. The X and Y coordinates of each page start at 0, 0. The page size is 8.5 x 11 inches, with no rotation. • Page 1 has one main block whose X and Y coordinates are 5p, 5p; the block size is 36 picas x 50 picas. • Page 1 contains a frill block below the main block, with X and Y coordinates of 4p, 58p. The frill block size is 38 picas x 1 pica. • Page 2 is similar to the first page, with a main block and a frill block, but the dimensions differ and the frill block is above the main text block.

Note: To create a two page division without text, you can use the same command, but omit the text.

Transforming Data Importing and Exporting Page Layouts 6-11 Using FromXSF to Export XPP Page Layouts

Replacing Two Pages in a Magazine The following figure is an example of a division containing a magazine whose layout has already been defined. Last minute changes done on an external page layout system require you to replace the layout of pages 4 and 8.

{/MAIN;4} [PAGE ; ; ;17i ;11i ] [BLOCK; 5p ; 5p ; 36p ; 50p ] [BLOCK; 6p ; 7p ; 15p ; 24p ; story ; s1] [BLOCK; 25p ; 7p ;15p ; 24p ; story ; s1 ] [BLOCK; 6p ; 34p ; 34p ; 20p ; story ; s2 ] [BLOCK; 4p ; 58p ; 38p ; 1p ; frill ]\. {/MAIN;8} [PAGE; ; ; 17i ; 11i ] [BLOCK; 6p ; 10p ; 15p ; 24p ; story ; s1 ] [BLOCK; 6p ; 37p ; 34p ; 20p ; story ; s2 ] [BLOCK; 25p ; 10p ; 15p ; 24p ; story ; s3 ] [BLOCK; 6p ; 7p ; 34p ; 1p ; frill ]\. [SHAPE ; ; 2p ; 2p ; 8p ; 2p ; 8p ; 8p ; 2p ; 8p]

Figure 6-2 ASCII Input File Named tsample2

Running ToXSF on the ASCII file “tsample2” produces a division with new layouts on pages 4 and 8.

The command line is: toxsf –layout –Rep tsample2

• Page 4 uses default dimensions; the page starts at 0, 0; its dimensions are 17 x 11 inches, with no rotation. • Page 4 has one main block, with X and Y coordinates of 5p, 5p; block size is 36 x 50 picas. • Page 4 has three story blocks: • Story s1—two blocks: a. One block starts at 6p, 7p; block size is 15p x 24p. b. The other block starts at 25p, 7p; block size is 15p x 24p. • Story s2: one block, X and Y coordinates of 6p, 34p; block size is 34p x 20p. • Page 4 also has one frill block at the bottom of the page. • Page 8 is a pullout page that starts at 0, 0; page size is 17 x 11 inches, with no rotation.

6-12 Importing and Exporting Page Layouts Transforming Data Using FromXSF to Export XPP Page Layouts

• Page 8 has three story blocks: • Story s1: one block, X and Y coordinates of 6p, 10p; block size is 15p x 24p. • Story s2: one block, X and Y coordinates of 6p, 37p; block size is 34p x 20p. • Story s3: one block, with X and Y coordinates of 25p, 10p; block size is 15p x 24p. • Page 8 has one frill block at 6p, 7p; block size is 34p x 1p. • Page 8 also has a shape on it, which is an 8p x 8p square that starts at 2p, 2p.

Defining a Book

The following figure is an example of layout control statements that define a book. The first page is a title page, the second is a left page and the third page is a right page. Subsequent pages are created using the [CPPAGE] (copy page) designator.

{/MAIN;1;0;4;1;0;0} [PAGE] [BLOCK; 5p ; 5p ; 36p ; 50p } [BLOCK; 4p ; 58p ; 38p ; 1p ;frill ]\. {/MAIN;2;0;4;2;0;0} [PAGE] [BLOCK; 2p ; 7p ; 38p ; 52p ] [BLOCK; 2p ; 4p ; 38p ; 1p ; frill ]\. {/MAIN;3;0;4;3;0;0} [PAGE] [BLOCK; 6p ; 7p ; 38p ; 52p ] [BLOCK; 6p ; 4p ; 38p ; 1p ;frill ]\. {/MAIN;4;0;4;4;0;0} [CPPAGE; 2]\. {/MAIN;5;0;4;5;0;0} [CPPAGE; 3]\. {/MAIN;6;0;4;6;0;0} [CPPAGE; 2]\. {/MAIN;7;0;4;7;0;0} [CPPAGE; 3]\. {/MAIN;8;0;4;8;0;0} [CPPAGE; 2]\. {/MAIN;9;0;4;9;0;0} [CPPAGE; 3]\.

Figure 6-3 ASCII Input File Named tsample3 Running ToXSF on this file produces a nine page division without text.

Transforming Data Importing and Exporting Page Layouts 6-13 Using FromXSF to Export XPP Page Layouts

The command line is: toxsf –layout –Rec tsample3

• Each page starts at 0, 0; block size is 8.5 x 11 inches, with no rotation. • Each pages has one main block and one frill block with slightly different positions and dimensions.

6-14 Importing and Exporting Page Layouts Transforming Data Hints and Troubleshooting

...... Hints and Troubleshooting

The following table describes hints and troubleshooting tips.

Table 6-4 Problem/Solutions

Problem Description

Block and shape geometry too large The ToXSF program does not check for blocks and shapes that extend beyond page boundaries; if this happens, the results are unpredictable.

Missing –Rep or –Rec options If the ASCII text contains [PAGE] and [BLOCK] designators, but the command line does not include the –Rep or –Rec option, ToXSF modifies the current page that is being processed.

Invalid [CPPAGE] page number If the [CPPAGE;pagenumber] control statement calls out a page number that does not exist, ToXSF uses the previously defined page layout.

Missing –layout option If you do not use the –layout option when running ToXSF on a file containing layout control statements, XPP outputs “Illegal Xyps” error messages for every [PAGE], [FRAME], [BLOCK], [SHAPE], or [CPPAGE] designator in the file.

Using the –layout command with a If you use the –layout option when non-layout file running ToXSF on a file that does not contain layout control statements, XPP processes the file using standard page/text capabilities.

Transforming Data Importing and Exporting Page Layouts 6-15 6-16 Importing and Exporting Page Layouts Transforming Data Chapter 7

Transforming Style Data in XPP

You can use import and export styles from XPP in two formats:

• XML • ASCII

Once you have an XML or ASCII version of a style, you can modify it and import it back into XPP. These two formats allow you to do the following:

• Import style data generated by a third-party text processing or publishing system into XPP. • Export XPP style data to ASCII files for use with third-party text processing and publishing systems. • Use an ASCII editor to create style data files for import.

This chapter describes:

• Examples of XPP style data and ASCII style files. • Format of ASCII files for exported style data. • Format of ASCII files for importing style data. • Guidelines for creating and understanding ASCII style files. • Running ToStyle/FromStyle (the Style Data Editor sdedit command with the –ain or –aout options). • Importing/exporting XML style files.

Refer to the XPP document XML Professional Publisher: Managing Document Styles for descriptions of fields in style specs and information on editing specs.

Transforming Data Transforming Style Data in XPP 7-1 Examples of Importing and Exporting Styles

...... Examples of Importing and Exporting Styles

This section shows sample XPP style specs and corresponding ASCII style files.

Refer to the section “Understanding XPP and ASCII Style Data Formats” on page 7-7 for information about syntax.

Exporting Styles

The following figure shows a sample table from the local Item Format Spec.

Figure 7-1 Sample Item Format Spec The ASCII output file uses internal names for the spec fields. For example, the Tag Name field on the Item Format Spec appears in the ASCII output file as the nm field.

7-2 Transforming Style Data in XPP Transforming Data Examples of Importing and Exporting Styles

The following figure shows the ASCII output file containing the style data exported from the xybase2 Spec.

FILE {type : if} FILEHDR { File_Comment : ″Item Format Spec Sample -- xybase2″ } HEADER 1: { _std_comment : ″14 pt. head″ nm : h14 Tag Name field in IF post : ″″ Spec ppriority : 2nd pmaxwhite : 6q } BODY 1:1 { endval : line End Previous field in IF Spec priority : 1st ffamily : 1 fvariant : 1 fheight : 14q fwidth : same maxwhite : 1p prelead : 1p ldasc : normal lindent : 0 pgindent : 0 lnmeas : active ldextra : 2q lddesc : normal qdtbl : rr hjtbl : 7 pgsplit : head lpabove : 0 lpbelow : 3 laabove : 0 labelow : 2 language : 1 capmode : no Capitalization field in IF Spec kernnum : 2 spotcolor : normal psrnum : active ipcrnum : active pair_kern : yes pre : ″″ repeat : repeat pgrful : none httbl : none pattern : none } END

Figure 7-2 ASCII File Containing Exported Item Format Data

Transforming Data Transforming Style Data in XPP 7-3 Examples of Importing and Exporting Styles

Importing Styles This section contains examples of using an ASCII input file to modify a Page Layout (PL) Spec.

Original Page Layout Spec The following figure shows a sample table from a Page Layout Spec named memos before modification.

Figure 7-3 Sample Page Layout Spec

7-4 Transforming Style Data in XPP Transforming Data Examples of Importing and Exporting Styles

ASCII Input File with Page Layout Data

The following figure shows a sample ASCII input file for modifying the memos Page Layout Spec.

FILE { type: pl} HEADER name=″any″: DELBODY { name : ″any″ px : 1p py : 1p maxx : 50p maxy : 65p } BODY @ :+ { cclass : ″frill″ bx : 4p by : 4.4p bsx : 38p bsy : 54p amount : 0 direction : ″clock″ cstring : ″″ } END

Figure 7-4 Sample ASCII File to Import Page Layout Style Data The file:

1. Tells the ToStyles processing to delete all body records (rules) in the table named any.

2. Changes several field entries in the table header record.

3. Creates a body record (rule) under the any header and fills in field entries.

Transforming Data Transforming Style Data in XPP 7-5 Examples of Importing and Exporting Styles

Modified Page Layout Spec

The following figure shows the memos Page Layout Spec after modification.

Figure 7-5 Sample Page Layout Spec After Modification

7-6 Transforming Style Data in XPP Transforming Data Understanding XPP and ASCII Style Data Formats

...... Understanding XPP and ASCII Style Data Formats

Before importing or exporting style data, you must understand the format of XPP style data files and ASCII style files.

Format of XPP Style Data

XPP arranges style data in a structured format.

• XPP uses the term style specs to refer to XPP style data files that define the document style and control the composition and pagination parameters for a job. • The File Comment field is the first entry in a style spec, followed by one or more tables. • A table is a complete unit of information consisting of a header record and one or more rules (body records). • Each spec ends with an End of File marker. • The number of tables in a spec and the number of fields in a record vary from spec to spec. • XPP requires specific types of entries for certain fields and supplies initial (default) entries for many fields. • Each field has an external label that appears on the screen and an internal label that is used by XPP programs. When you convert XPP style specs to ASCII format, the internal label appears in the ASCII file. • For information about field entries in XPP style specs, refer to the XPP documentation that describes that spec or select the Help option when the cursor is in a field. • Each style spec is identified by a two- or three-character type and a name, consisting of up to eight characters. For example, if xybase2 refers to the Item Format (IF) Spec named xybase2. Please refer to the section “XPP Style Specs” on page 7-23 for a list of style spec types.

Format of ASCII Export File Use FromStyle (the sdedit command with the –aout option) to export XPP style data for use with third-party text processing and publishing systems. You can also use operating system tools and utilities to compare the contents of exported style files.

Transforming Data Transforming Style Data in XPP 7-7 Understanding XPP and ASCII Style Data Formats

Note: The –aout option says: “If file is –(hyphen), the ASCII text is displayed on the screen.” This hypen option is valid on UNIX platforms only; not on the Windows® platform.

FromStyle generates an ASCII export file, containing style information from the spec you specify.

The following figure shows the format of the ASCII export file.

FILE {type : spec-type} FILEHDR { field-name : contents } HEADER header-record-number:{ field-name : contents field-name : contents field-name : contents (for each field in header record) } BODY header-record-number : body-record-number { field-name : contents field-name : contents field-name : contents (for each field in body record) } ... (for each table and rule in the file) END

Figure 7-6 Format of ASCII Export File In the ASCII output file:

• FILE spec-type is a two- or three-character mnemonic for the style data type. For example, Figure 7-2 shows a spec-type of if (Item Format Spec). • The FILEHDR field contains style file comments. For example, Figure 7-2 contains the comment:

Item Format Spec Sample -- xybase2 • The HEADER and BODY field-names correspond to internal field names, not to field names you see when editing a spec. For example, in Figure 7-1, the Tag Name field of the Item Format Spec, corresponds to the internal field name nm ( Figure 7.2). • The header-record-number and body-record-number refer to the table and rule numbers (for example, “Table 3 of 10, Rule 1 of 2”). In Figure 7-2, there is one table (HEADER 1) and one rule (BODY 1:1) • The field contents is in quotation marks if it is a comment or user- defined string, such as in the Poststring and Prestring fields in the IF Spec.

7-8 Transforming Style Data in XPP Transforming Data Understanding XPP and ASCII Style Data Formats

For example, in Figure 7-2, the contents of both comment fields (File_Comment and _std_comment) are enclosed in quotes. The Poststring (post) and Prestring (pre) fields are empty except for quotes. • END marks the end-of-file.

Format of ASCII Import File Use ToStyle (the sdedit command with the –ain option) to create a new style spec, to add or delete tables and records in existing specs, and/or modify individual fields. The ASCII input format is the same as the output format except that there are commands for specifying which records to change and how they will be changed. The following figure shows the format of the ASCII input file.

FILE {type : spec-type} FILEHDR { field-name : contents } HEADER descriptor: command { field-name : contents field-name : contents field-name : contents (for fields to change in header) } BODY descriptor : descriptor command { field-name : contents field-name : contents field-name : contents (for fields to change in body) } ... (for each table and rule to change in the file) END

Figure 7-7 Format of ASCII Input File In the ASCII input file:

• FILE spec-type is a two- or three-character mnemonic for the style data type. For example, if (Item Format), tt (Translation Table), pts (Phototypesetter). Figure 7-4 shows a spec-type of pl (Page Layout Spec). • If you are modifying an existing style spec, you can omit the FILE line from the ASCII input file. It is used to verify that the data type matches the sdedit file type.

Transforming Data Transforming Style Data in XPP 7-9 Understanding XPP and ASCII Style Data Formats

• The FILEHDR line is optional. Use it to set the file comment. In Figure 7-4, there is no FILEHDR line. • The descriptor specifies which header (table) or body record (rule) to modify or where to insert a new record. In Figure 7-4, the HEADER line name=“any” specifies that the any table is the one to modify. In the BODY line, @ specifies the current body record (rule) of the last header that was modified. Refer to page 7-11, “Descriptor Format.” • The command specifies what operation will happen to the matching record. In Figure 7-4, the HEADER line command DELBODY specifies to delete all body records in the table, but not the header itself. In the BODY line, the + command specifies to create a new body record (rule). Refer to the section “Command Format” on page 7-12. • Insert a HEADER descriptor : command line for each HEADER (table) field to add or modify. If you are not modifying a table header field, you can omit the HEADER line. • Insert a BODY descriptor : descriptor command for each body record (rule) field to add or modify. If you are not modifying a rule field, you can omit the BODY line. • In the BODY descriptor : descriptor command line, the descriptor to the left of the colon matches a table. Use the descriptor to the right of the colon to match a rule. For example, this command applies to an Item Format Spec. It changes the “Font Family” field in the tag named “head1” from “0” to “2.” BODY nm = ″head1″ : ffamily = ″0″ { ffamily : 2 } • The HEADER and BODY field-names correspond to internal field names, not to field names you see when editing a spec. For example, in Figure 6-4, the Block Type field on the Page Layout Spec corresponds to the internal field name cclass. To list the internal field names for a spec, use FromStyle (the sdedit command with the –aout option). Refer to the section “Using the Style Data Editor (sdedit)” on page 7-17. • Enclose the field contents in quotation marks if the field contains XSF (XyASCII) strings, non-printing characters, or special punctuation marks : { } + * = \ ″ that have special meaning on import. Examples are comments and user-defined strings. Fields with predefined contents do not have to be enclosed in quotes. When in doubt, it is always safe to use quotes. For example, in Figure 7-4, the contents of all non-numeric fields are enclosed in quotes, even though some have predefined contents, such as the cclass (Block Type) field. • END marks the end-of-file.

7-10 Transforming Style Data in XPP Transforming Data Understanding XPP and ASCII Style Data Formats

Descriptor Format In the ASCII input file, the HEADER (table) and BODY (rule) fields contain a descriptor, in the form:

Table 7-1 Format of Descriptor Entries

Descriptor Function

Omitting the descriptor creates a new header or body record. The program creates records following the last record that was modified. If a new SD file is being created, then the first header and body record are not created since a new header and body record are created with the file.

fieldname = Searches for the first header or body record (rule) whose field ″string″ name matches ″string″. If both a header and body record string match are given, then a corresponding body record for a matching header record must be found. Only the first record that matches will be modified. Do not use wild card characters in the string. Quote the string if it contains any special characters.

* Matches any record. Used to search all header records for a body record that matches the body descriptor.

+ Used to create a new header record (table) at the end of the file, or a new body record (rule) at the end of the body records for a given header.

@ Matches the current header or body record. Usually used to match a body record of the last header record modified.

rec-number Matches the header or body record number. If the number is one higher than the number of header or body records, then a new record is created. This allows importing of an ASCII file generated by an export operation (and possibly modified) to create a new SD file.

Transforming Data Transforming Style Data in XPP 7-11 Understanding XPP and ASCII Style Data Formats

Command Format In the ASCII input file, the HEADER (table) and BODY (rule) fields contain a command, in the form:

Table 7-2 Format of Command Entries

Command Function

Only specified fields are modified; other fields are left unaltered. If a new record is being created, unspecified fields get the same default values as if the record had been created interactively.

ZAP All fields whose contents are not specified are set to their default values. ZAP has the same effect as using the –azap option with the sdedit command. Refer to “Using the Style Data Editor (sdedit) ” on page 7-17.

COPY or Record is duplicated before being modified, leaving the old record COPYALL untouched. If COPYALL is specified, then all body records of the matched header record are duplicated as well.

DEL Deletes matching record. If the matching record is a header record (table), then all its body records (rules) are deleted also. You cannot delete a header or body record if it is the only record in the file. At least one header and body record must remain.

DELBODY Deletes all the body records of the matching header record, but not the header record itself.

7-12 Transforming Style Data in XPP Transforming Data Understanding XPP and ASCII Style Data Formats

Examples of ASCII Import Files This section shows examples of ASCII input files to modify one field in the Typesetter Font Map (TSF) Spec. Each import file updates the Xy-Font field (xyfont) for one rule (BODY) in the TSF Spec. The rule is identified by the Font Name field (tsname).

FILE {type : tsf}

FILEHDR { File_Comment : “Font Mapping file for PostScript font numbers to names” }

HEADER 1: { _std_comment : “order matches fv spec XYLmike. Created Tue Jun 27 14:50:58 1995” }

BODY 1 : tsname = “BellCentennialBT-SubCaption” { xyfont : 5363 tsname : BellCentennialBT-SubCaption } END

FILE {type : tsf}

FILEHDR { File_Comment : “Font Mapping file for PostScript font numbers to names” }

HEADER 1: { _std_comment : “order matches fv spec XYLmike. Created Tue Jun 27 14:50:58 1995” }

BODY 1 : tsname = “FuturaBT-BookItalic” { xyfont : 5158 tsname : FuturaBT-BookItalic } END

Transforming Data Transforming Style Data in XPP 7-13 Creating ASCII Style Files for Import

...... Creating ASCII Style Files for Import

When creating ASCII style data files for import into XPP, follow these guidelines:

• Spacing in the ASCII file is free form. Use spacebands, tabs, and new lines to make the file easier to read. White space (spacebands, new lines, or tabs) is not necessary to separate special characters from preceding or following text. • When you create an ASCII style file for import, use the internal field labels. To see the internal labels, issue the sdedit command with the –aout option for the spec type you want to create. • You must quote field names or contents that contain white space or special characters, including: left curly brace ({), right curly brace (}), colon (:), ampersand (&), plus sign (+), asterisk (*), equals sign (=), backslash (\) and quotes (“”). • You can quote field names and contents whether or not they contain white space or special characters. • Insert a backslash (\) before special characters in a field name or contents. • Insert a backslash (\) before quote characters in a field contents to prevent interpreting it as a terminating quote. • Insert a hash mark (#) character at the beginning of a line to indicate a comment line that will be ignored by the import program.

Field Contents When you enter data in fields for importing ASCII style data: • All field entries undergo the same verification as entries in the XPP Style Data editor. If an error occurs, the program displays a message. • To help you correct problems, the line number and current input word is included with all error messages. • If the contents of a field is longer than the screen field length, the entry is truncated on the right and a warning message appears. • If a “too-long” field contains a qualified numeric entry with a decimal point, the entry is truncated by removing extra zeroes to the right of the decimal point; the decimal point itself is truncated if the fractional part is zero. For example: 12.q Ä 12q 18.00q Ä 18q 34.500q Ä 34.5q

7-14 Transforming Style Data in XPP Transforming Data Creating ASCII Style Files for Import

Entering Accented Characters in ASCII Fields

If you need to enter accented characters in ASCII fields via an ASCII file, XPP provides a way to do this using the XPP VUEM character set.

For any non-XSF field where you want an accented or other special character that is not a regular ASCII character but is available in the VUEM character set, enter the octal value for the character from the VUEM character set preceded by a single backslash. For example:

\337

The above example would specify the é character. This is not an ASCII character, but XPP can display it because it is in the VUEM character set.

This feature provides a way for non-English speaking users to display text, e.g., in comment fields. in XPP specs in languages other than English but that use the Roman alphabet.

For more information on the VUEM character set, please see the figure on the next page.

Note: If you want to enter accented characters in XSF fields in specs, you can enter the special characters by doing any one of the following: selecting an XPP keyboard, using the Shift + F1 or Shift + PI keys, or by directly entering a hex Unicode value using the Shift + F2 keys. The following figure displays the vuem character set:

Transforming Data Transforming Style Data in XPP 7-15 -6Tasomn tl aai XPP in Data Style Transforming 7-16 Import for Files Style ASCII Creating rnfrigData Transforming

Figure 7-8 Vuem Characters Using the Style Data Editor

...... Using the Style Data Editor

When you access style specs from XPP, the Style Data editor, sdedit, runs in interactive mode. The spec appears on the screen where you can fill in field entries and select options to add, delete, or copy records.

When you import and export style data, use the sdedit command at the command line to run the style data editor in non-interactive mode.

To import or export style data:

1. Change to the XPP style library or job directory where you want to import or export the style data. For example, to change to the std-fmt library, issue this command: cd $XYV STYLES/Lstd-fmt

2. Enter the following XPP style data editor sdedit command at the com- mand line: sdedit type name [sw1] [sw2]

The arguments type (spec type) and name (bundle name) are required. Other choices are optional. The following example exports style data to the pagestyle ASCII file for the Page Layout spec named xybase2, enter: sdedit pl xybase2 –aout pagestyle

The following example imports style data from the file newtags into the Item Format Spec xybase2: sdedit if xybase2 –ain newtags

Note: For detailed information on the options available when running sdedit from the operating system see the XML Professional Publisher: Command Line Utilities manual.

Transforming Data Transforming Style Data in XPP 7-17 Importing/Exporting XML Style Files

...... Importing/Exporting XML Style Files

Using the XML Style Import/Export feature, the Sdedit program can import/export individual style files in an XML format. This feature also adds the ability to create a composite XML instance of the complete XPP Style bundle.

Import/Export Process Components

The process includes information pertaining to the following topics:

• XML Style Files • Character encoding and conversion • Schema support • Style validation • Style data compatibility

XML Style Files

By definition, there are three different types of XML Style files:

• Style file—the natural extension of the ‘aout’ format. The XML tags encapsulate the supporting data tables and rules, in a sense, “XMLizing” the flat ASCII version of style data files. The field names are the same as their ″aout″ equivalent; that is, they are dependent on the type of style data file you are exporting. The ,

, and tags are mandatory tags that you use to delimit the header/body records inside every style data file. • Style Bundle—a collection of Style File ‘files’ in the same format as the XML Style File, linked together by a wrapper XML tag called