Miramo®
Automated Publishing
Reference Guide
VERSION 9.2 Copyright © 2000 - 2012 Datazone Ltd. All rights reserved. Miramo® and mmChart are trademarks of Datazone Ltd. All other trademarks are the property of their respective owners. Readers of this documentation should note that its contents are intended for guidance only, and do not con- stitute formal offers or undertakings. ‘License Agreement’ This software, called Miramo, is licensed for use by the user subject to the terms of a License Agreement between the user and Datazone Ltd. Use of this software outside the terms of this license agreement is strictly prohibited. Unless agreed otherwise, this License Agreement grants a non-exclusive, non-transfer- able license to use the software programs and related documentation in this package (collectively referred to as Miramo) on licensed computers only. Any attempted sublicense, assignment, rental, sale or other transfer of the software or the rights or obligations of the License Agreement without prior written consent of Datazone shall be void. In the case of a Miramo Development License, it shall be used to develop appli- cations only and no attempt shall be made to remove the associated watermark included in output docu- ments by any automated method. The documentation accompanying this software must not be copied or re-distributed to any third-party in either printed, photocopied, scanned or electronic form. The software and documentation are copyrighted. Unless otherwise agreed in writing, copies of the soft- ware may be made only for backup and archival purposes. Unauthorized copying, reverse engineering, decompiling, disassembling, and creating derivative works based on the software are prohibited. This notice is provided for information only, and does not constitute a License Agreement. Datazone does not warrant that the software will be free from error or will meet your specific require- ments. You assume complete responsibility for decisions made or actions taken based on information obtained using the software. Any statements made concerning the utility of the software are not to be con- strued as unexpressed or implied warranties. Trademarks FrameMaker, FrameMaker+SGML, Acrobat, Adobe, PostScript, Adobe Illustrator and TIFF are trade- marks of Adobe Systems Inc. Macintosh is a trademark of Apple Computer Inc. Windows NT is a trade- mark of Microsoft Corporation. PANTONE is a registered trademark of Pantone Incorporated. Miramo is a Registered Trademark of Datazone Ltd (see above).
Miramo includes software developed by the Apache Software Foundation (http://www.apache.org/).
Datazone Limited Palm Gate, Greenane, Killarney, Co. Kerry, Ireland. Tel: +353 64 66 289 64 Fax: +353 64 66 289 65 Email: [email protected] www.miramo.com
13.09.17 920p21 User & Reference Guides Contents
User Guide Contents...... U-v Getting started ...... U-1 Tables ...... U-13 Anchored frames and images ...... U-37 Text formatting ...... U-57 Books, TOCs and indexes ...... U-65 Cross-references and hypertext ...... U-77 Controlling page layouts ...... U-81 General Index ...... IX-93
Reference Guide Contents...... R-v Introduction ...... R-1 Running Miramo ...... R-3 Inline markup codes ...... R-37 Format definitions ...... R-299 Miramo DTD and XML codes ...... R-415 mmpp ...... R-463 Appendix 1: Pen and fill patterns and colors ...... R-531 Appendix 2: Output device control [Unix only] ...... R-533 Appendix 3: Running API clients ...... R-537 Appendix 4: List of inline markup codes and options ...... R-541 Appendix 5: List of format definition markup codes and options...... R-561 General Index ...... IX-571 mmDraw Drawing Guide Contents...... MD-i
Miramo [ v 9.2 ] Contents-i User & Reference Guides contents
Introduction ...... MD-1 Drawing markup codes ...... MD-3 Appendix 1: List of drawing markup codes and options ...... MD-51 General Index ...... IX-57 mmServer Guide Contents ...... MS-v Introduction ...... MS-1 mmServer control and status reporting ...... MS-3 Configuring the mmConnect service ...... MS-19 Using rmmcmd ...... MS-23 mmVisor graphical interface ...... MS-31 mmChart Inline Charting Guide Contents ...... CG-i Introduction ...... CG-1 Getting started with charts ...... CG-1 Bar charts...... CG-7 Pie and ring charts ...... CG-21 Line charts ...... CG-33 Area charts ...... CG-41 High-low, candle and bubble charts...... CG-49 Chart images and shading ...... CG-55 Charting inline markup codes ...... CG-59 Appendix 1: mmChart built-in colors ...... CG-151 Appendix 2: List of mmChart markup codes and options...... CG-159 General Index ...... IX-167
Character Reference Guide Contents ...... CH-i
Contents-ii Miramo [ v 9.2 ] User & Reference Guides contents
Introduction ...... CH-1 Character sets, encodings and entities ...... CH-3 Multi-script fonts ...... CH-17 East European and Russian fonts ...... CH-71 Non-text fonts ...... CH-77 Arabic fonts...... CH-109 SIL fonts ...... CH-131 Simplified Chinese ...... CH-151 Appendix 1: Index of built-in character entities ...... CH-421 Appendix 2: Index of Unicode characters ...... CH-429 General Index ...... IX-747
Miramo [ v 9.2 ] Contents-iii User & Reference Guides contents
Contents-iv Miramo [ v 9.2 ] Reference Guide Contents
Introduction R-1
Running Miramo R-3 Summary ...... R-3 Basic command line usage ...... R-3 Basic API usage...... R-4 Command line options syntax summary ...... R-4 API syntax summary ...... R-5 List of job processing and other options ...... R-5 Command line examples ...... R-21 Environment variables...... R-21 Exit codes ...... R-23 Using the built-in Miramo X-server (Unix only) ...... R-25 Configuring Miramo as a Frame input filter (Unix only) ...... R-26 mmxslt pre-processor ...... R-27 mmunimap utility...... R-29 Batch printing...... R-29 mmprint utility ...... R-30 fmps2eps utility (Unix only) ...... R-30 Printing color separations...... R-31 PDF .joboptions files (Windows only) ...... R-32 PDF notes, bookmarks and cross-references...... R-33 Controlling bookmark levels using a ‘config’ file ...... R-34
Inline markup codes R-37 Usage rules for inline markup codes ...... R-37 Summary of inline markup codes ...... R-38 Option names...... R-40 Option values and value types ...... R-40 Escape, control and special characters ...... R-42
Miramo Reference Guide [ v 9.2 ] R-v Reference Guide contents
...... R-220 R-vi Miramo Reference Guide [ v 9.2 ] Reference Guide contents Format definitions R-299 Summary of format definition codes ...... R-299 Structure of format definitions...... R-300 Where format definitions may be used...... R-301 Property inheritance ...... R-302 Precedence ...... R-302 Miramo DTD and XML codes R-415 The declaration ...... R-415 The Miramo Reference Guide [ v 9.2 ] R-vii Reference Guide contents The processing instruction ...... R-415 code ...... R-415 Using XSLT stylesheets ...... R-416 Entity references and mmxslt ...... R-417 Accessing mmxslt extension functions ...... R-419 mmxslt extension functions for image processing ...... R-420 mmxslt extension functions for PDF file import ...... R-421 Miscellaneous mmxslt extension functions ...... R-422 Miramo DTD ...... R-422 R-viii Miramo Reference Guide [ v 9.2 ] Reference Guide contents Processing ‘fixed field width’ files using <@readfile>( ) ...... R-497 Miscellaneous transformation functions ...... R-499 X macros ...... R-500 Defining X macros ...... R-500 Calling X macros ...... R-502 X macro examples (content free) ...... R-504 X macro examples (with content) ...... R-505 X macros to create decorated headings ...... R-506 X macros to create decorated headings—‘mkBox’ macro ...... R-506 X macros to create decorated headings—‘BoxHead’ macro ...... R-508 X macros to create decorated headings—‘BoxHeadRow’ macro ...... R-512 Summary of built-in macros and functions ...... R-516 Appendix 1: Pen and fill patterns and colors R-531 Pen and fill patterns ...... R-531 Colors and separations ...... R-532 Pantone colors ...... R-532 Appendix 2: Output device control [Unix only] R-533 Introduction...... R-533 Using the code ‘PSF’ option to control output devices...... R-533 Using the PSF ‘+n’ and ‘*’ flags ...... R-534 Default device control commands ...... R-534 Changing the appearance of pages...... R-535 Restrictions ...... R-536 Simple example...... R-536 Appendix 3: Running API clients R-537 How Miramo invokes the custom API client ...... R-537 Writing a custom API client...... R-537 Sample API client - myapi...... R-538 Registering myapi [Unix]...... R-538 Registering myapi [Windows NT] ...... R-538 Running Miramo with the -userapi flag ...... R-539 myapi - source listing ...... R-539 Miramo Reference Guide [ v 9.2 ] R-ix Reference Guide contents Appendix 4: List of inline markup codes and options R-541 Appendix 5: List of format definition markup codes and options R-561 General Index IX-571 R-x Miramo Reference Guide [ v 9.2 ] CHAPTER 1 Introduction This Miramo Reference Guide contains a detailed description of all features of the Miramo automated publishing package. Miramo comprises a set of markup codes for formatting documents. It supports many import formats for text and graphics. The Miramo package includes a powerful macro preprocessor, mmpp, which enables the presentation of data in XML or other input encod- ings for highly complex output formats to be greatly simplified. Alternatively, for XML encoded input only, the mmxslt processor is included to enable transformation from XML markup to Miramo markup. A summary of the different sections which comprise the Miramo Reference Guide is given below: • Installing Miramo and Running Miramo The first two chapters contain detailed instructions for installing Miramo, as well as a comprehensive description of the command line options for running Miramo. If Miramo is already installed on the host system the chapter containing the installation instructions may be ignored. However the chapter entitled Running Miramo is essential reading (see Chapter 2, on pages R-3–35). • Inline markup codes The inline markup codes comprise the core of Miramo. Using these codes, along with the ‘-Tfile’ (template name) command line option, will enables the power of Miramo to be unleashed. Using mmpp or mmxslt in addition is likely to simplify formatting large quantities of structured data. Inline codes may also be used to change the local appearance of text, insert the values of variables, as well as for cross-referencing and hypertext linking. An alphabetical listing of inline markup codes is contained in Chapter 3, on pages R-37–297. • Format definitions In general if document layouts, paragraph, font, color and other formats are defined using a FrameMaker template document then it is not necessary to consult this section of the Miramo Reference Guide. An alphabetical listing of format definition codes is contained in Chapter 4, on pages R-299–413. • mmpp - Miramo macro pre-processor mmpp is a macro pre-processor specially designed to streamline Miramo data presentation. All Miramo implementations other than the most simple should use Miramo Reference Guide [ v 9.2 ] R-1 Introduction CHAPTER 1 mmpp, or mmxslt. Examples using mmpp are included in the Miramo User Guide and a full description of mmpp is included in this Reference Guide, Chapter 6, on pages R-463–529. • Miramo built-in characters The diagram below shows the overall operation of Miramo schematically. FrameMaker PDF Graphics files EPS GIF Package JPEG output TIFF and XML . . . WWW Report Writer Doc FrameMaker Defs PostScript / Print R-2 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo Summary This chapter describes the different methods of running Miramo. The topics discussed in this chapter include: • Basic command line and API usage and syntax (pages R-3–5). • The command line and API options for the miramo program (pages R-5–21). • Environment variables used by the miramo program (pages R-22–23). • The command line options for the mmxslt pre-processor (pages R-27–29). • The command line options for the mmprint utility (page R-30). • Using mm_xvfb, the built-in X-Server (Unix only, page R-25). • PDF file generation issues. • Performance optimization. Basic command line usage Miramo may be used simply as a command followed by an output specifier (output file type and output file name) and an input file name: (1) miramo -Ofm outputfile inputfile (2) miramo -Opdf file.pdf inputfile or as an input filter: (3) program | miramo -Ofm outputfile (4) program | miramo -P In the first two examples above inputfile will be a text file containing Miramo mark-up codes. The outputfile will be a Frame document which may be opened using FrameMaker or FrameMaker+SGML on any platform. The file.pdf will be a file in PDF, or ‘Portable Document Format’. The ‘-Ofm’ option produces a binary output document, whereas the ‘-Omif’ option produces a MIF (Maker Interchange Format) output document. If the output from program, in the first input filter example above, is the same as that con- tained in inputfile in the very first example, then the two commands are functionally equivalent. In the second input filter example above, no Frame output document is pro- duced, but the report data is printed using the ‘-P’ command line option. program will typically be a database data extraction program that produces XML encoded data, Miramo or mmpp markup. It could be a simple database report writer piping its output through mmpp or mmxslt and Miramo, or it could be a shell script using basic Unix or Windows data processing tools such as Windows PowerShell, sed, awk or perl to transform a set of Miramo Reference Guide [ v 9.2 ] R-3 Running Miramo CHAPTER 2 ordinary data files into Miramo input format. Automatic printing can always be achieved using the ‘-P’ options, or a Frame output file can be printed subsequently using mmprint (see page R-30, later in this chapter). Basic API usage The IJobProcessor interface class for C++, and the JobProcessor class for .NET and Java, provide a job processing API with an equivalent functionality to that provided by the command line interface. Examples of C++, C# and Java API code corresponding to the foregoing command line examples (1) and (2) are shown in (5) and (6) below. (5) C++ pJobProcessor->setOption(L"Ofm", outputfile); pJobProcessor->run(inputfile); C# jobProcessor.setOption(@"Ofm", outputfile); jobProcessor.run(inputfile); Java jobProcessor.setOption("Ofm", outputfile); jobProcessor.run(inputfile); (6) C++ pJobProcessor->createPdf(inputfile, outputfile); C# jobProcessor.createPdf(inputfile, outputfile); Java jobProcessor.createPdf(inputfile, outputfile); Unless otherwise noted the first parameter supplied to the setOption method supports all the job processing command line options described in this chapter, always omitting the preceding minus sign. The available API functions are documented as follows: • C++ API documentation: %MM_HOME%\api\C++\html\index.html. • Java API documentation: %MM_HOME%\api\java\html\index.html. • .NET API documentation: %MM_HOME%\api\dotnet\html\index.html. Users should check section C++, Java and .NET job processing APIs under SYSTEM REQUIREMENTS on page RN-v in the Miramo Release Notes before developing an API application. The APIs are not available on Unix. Command line options syntax summary To start Miramo with command line options, type miramo followed by a space, an option string preceded by a ‘-’ (minus) character and a value, if required. For example, the ‘-Tfile’ option must be followed by the name of a template file (i.e. a FrameMaker file saved in MIF). The ‘-Tformats’, ‘-TXformats’ and ‘-Tflow’ options are only valid if the ‘-Tfile’ or ‘-Cfile’ options are included, and must also be followed by string values. If a command line option value contains whitespace (one or more tabs or spaces) then the value must be enclosed in double quotation marks,‘"’. R-4 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo API syntax summary The IJobProcessor interface class for C++, and the JobProcessor class for .NET and Java, include the setOption method to allow command line options to be specified programati- cally. The option name supplied to the setOption method is identical with the command line option names documented in Table 2.1 but without the preceding ‘-’, minus, charac- ter. For example, the following Miramo command line: (7) miramo -Tfile template.mif -Xxsl mystylesheet.xsl -Opdf test.pdf test.xml is represented as follows using the C++, .NET and Java APIs: (8) C++ pJobProcessor->setTemplate(L"template.mif"); pJobProcessor->setOption(L"Xxsl", L"mystylesheet.xsl"); pJobProcessor->createPdf(L"test.xml", L"test.pdf"); C# JobProcessor.setTemplate(@"template.mif"); JobProcessor.setOption(@"Xxsl", @"mystylesheet.xsl"); JobProcessor.createPdf(@"test.xml", @"test.pdf"); Java jobProcessor.setTemplate("template.mif"); jobProcessor.setOption("Xxsl", "mystylesheet.xsl"); jobProcessor.createPdf("test.xml", "test.pdf"); List of job processing and other options Table 2.1 contains detailed descriptions of each command line option. Where appropri- ate, default values are given, and any related environment variables are noted. See pages R-21–23 for a list of environment variables and their settings. Table 2.1 miramo options Option Description help options -h Write a concise options ‘usage’ guide to standard error. -v Write version and license details to standard error. -Ohelp Write ‘usage’ information including -O (output) options to standard error. -Thelp Write ‘usage’ information including -T (template) options to standard error. -Phelp Write ‘usage’ information including -P (printing) options to standard error. -PDFhelp Write ‘usage’ information including -PDF (portable document format) options to standard error. -Mhelp Write ‘usage’ information including -M (macroprocessor) options to standard error. -Xhelp Write ‘usage’ information for Miramo mmxslt options to standard error. -Bhelp Write ‘usage’ information including -B (book) options to standard error. mmpp pre-processor options -M Preprocess input using the mmpp macro preprocessor (see Chapter 6, pages R-463–529). The ‘-M’ option is not needed if the ‘-Mfile’ option is used. Miramo Reference Guide [ v 9.2 ] R-5 Running Miramo CHAPTER 2 Table 2.1 miramo options ( Continued ) Option Description -Mfile mmppfile Preprocess input using the mmpp macro preprocessor, prepending the input with the contents of mmppfile. The ‘-M’ option is not needed in addition to the ‘-Mfile’ option. mmxslt pre-processor options Unless either of the first two options below, ‘-X’ or ‘-Xxsl’, is included other ‘-X’ options are ignored. Examples of Miramo mmxslt pre-processor options are show on page R-419 (Example 5.12) in the Miramo Reference Guide. -X Preprocess XML input file using the mmxslt XSLT stylesheet processor. This option assumes that the input file is a well-formed XML file, and either the input contains a reference to a valid XSL stylesheet (see Example 2.2 on page R-28), or a valid XSL stylesheet is referenced using the ‘-Xxsl’ command line option (below). The ‘-X’ option is not needed if the if the ‘-Xxsl’ option is used. -Xxsl file.xsl file.xsl is the name of a file containing a valid XSL stylesheet. This option assumes that the input file is a well-formed XML file. The ‘-Xxsl’ option is always required unless the input XML file includes a reference to the XSLT stylesheet (see Example 2.2 on page R-28). The ‘-X’ option (above) is not needed if the if the ‘-Xxsl’ option is used. -Xctrans hex | decimal | subchar | skip | warn | error Use the ‘-Xctrans’ option to control processing of out of range characters. See the description of the mmxslt ‘-Xctrans’ option in Table 2.4 on page R- 28. -Xparam name expression Set stylesheet parameter name to expression. See the description of the mmxslt ‘-Xparam’ option in Table 2.4 on page R-28 Job processing options (The following job processing options are not applicable on Unix) -jobID string Specify a user or application-generated string to identify jobs and/or job types that are waiting, processing or completed. The value of ‘-jobID’ is stored in the jobRecord ‘jobID’ attribute. See the fourth column in Figure 5.2, mmVisor Status, Settings, Environment and jobRecord screen, on page MS-32 and in Figure 5.6, Log file jobRecord data display, on page MS-34 in the mmServer Guide. string must be enclosed within a pair of quotation mark, ", or apostrophe characters, ', U+0027 APOSTROPHE or U+0022 QUOTATION MARK. string may comprise a set of any characters with the following exceptions: control characters (including newline characters) and the enclosing characters. -maxProcTime seconds Override the default mmServer ‘maxProcTime’ processing channel group value for a job instance. The value of ‘-maxProcTime’ is stored in the jobRecord ‘maxProcTime’ attribute. -maxWaitTime seconds Override the default mmServer ‘maxWaitTime’ processing channel group value for a job instance. The value of ‘-maxWaitTime’ is not stored in a jobRecord ‘maxWaitTime’ attribute. R-6 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo Table 2.1 miramo options ( Continued ) Option Description -processGroup int | name Use the ‘-processGroup’ option to submit a job to a processing channel group other than the default. The ‘-processGroup’ option may have an integer or a name value. If an integer, it refers to the processing channel group number. If a name, it refers to the processing channel group name. If a processing channel group is referenced by name its int value is looked up from the mmserver.xml mmServer configuration file in the %MM_HOME%\config folder. Operating mode options -batch The ‘-batch’ option must be used when the input stream contains one or more Miramo Reference Guide [ v 9.2 ] R-7 Running Miramo CHAPTER 2 Table 2.1 miramo options ( Continued ) Option Description Use the ‘-xvfb’ option in conjunction with the ‘-batch’ option when large batches of documents are to be processed concurrently, to maximize reliability and speed. (For more information about running on hosts without an X-server see Using the built-in Miramo X-server (Unix only), on page R-25.) -stripInput N | tab | nl | all The ‘-stripInput’ command line option, along with the corresponding ‘stripInput’ options on the R-8 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo Table 2.1 miramo options ( Continued ) Option Description all As for tab and nl values above. -priority int (Unix only) -priority Normal | Below | Idle (Windows only) Reduce job scheduling priority. On Unix ‘-priority’ may have a value in the range 0 to 20. 0 is the normal, default priority. 20 runs the job at the lowest possible priority. On Windows ‘-priority’ may have any of the following three values: Normal, Below and Idle. Normal is the default. Below is below Normal and Idle runs the job at the lowest priority. -imageCache N | Y Enable image caching when the Miramo Reference Guide [ v 9.2 ] R-9 Running Miramo CHAPTER 2 Table 2.1 miramo options ( Continued ) Option Description If the Miramo input starts with an XML declaration in the form , the value specified by the XML declaration encoding name overrides the value specified using the ‘-tENC’ option. If the Miramo input starts with an XML declaration, the name value must one of the values supported by the ‘tENC’ option. Other encoding values are not supported. Default: utf-8 Book output options -Bfile file.book Create FrameMaker ‘book’ file.book. By convention a book file name has the suffix ‘.book’, but any valid filename may be used. The ‘-Bfile’ option should be used only if the input contains one or more R-10 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo Table 2.1 miramo options ( Continued ) Option Description N Neither the book file nor the chapters within it are updated. Additional chapters may be added to the book file during a subsequent job. Setting the ‘-Bupdate’ option to N results in significant performance gains in the case where a book contains non-generated chapters with no book-wide numbering or cross references. OQ Same as Y above, except that all chapters in the book are opened before updating, and all changes to the chapters and book file after the update are unsaved. OS Same as OQ above, except that all changes to the chapters in the book and the book file that result from the update are saved. The OQ and OS options are special cases that may be used to address rarely encountered printing issues. For example table rows that are excluded from PDF output when they occur wholly or partly below a textframe. The ‘-Bupdate’ option is effective only if used with the ‘-Bfile’ option, and if the input contains one or more Single-document output options -Omif miffile Create a Frame MIF (Maker Interchange Format) output document. Cannot be used with the ‘-Bfile’ option (see above). -Ofm fmfile Create a Frame binary output document. Cannot be used with the ‘-Bfile’ option. -Oviewmif miffile Create a view-only (locked) Frame MIF output document. Cannot be used with the ‘-Bfile’ command line option. -Oviewfm fmfile Create a view-only (locked) Frame binary output document. Cannot be used with the ‘-Bfile’ option. -Ortf rtffile Create an RTF (Rich Text Format) output file. Cannot be used with the ‘-Bfile’ option. -Ortfj rtffile Create an RTF (Rich Text Format) output file. Cannot be used with the ‘-Bfile’ option. The ‘-Ortfj’ option uses a different export filter to the standard export filter used by the ‘-Ortf’ option (see above). In many cases the results are better. -Ohtml htmlfile Create an HTML (HyperText Markup Language) output file. This option is recommended for use only with simple document formats. Miramo Reference Guide [ v 9.2 ] R-11 Running Miramo CHAPTER 2 Table 2.1 miramo options ( Continued ) Option Description Using the ‘-Ohtml’ option with ‘-Bfile’ option (see page R-10) results in a single HTML file for the whole book. All hypertext links are preserved in the HTML output file. -Oxml xmlfile Create an XML output file. This option is recommended for use only with simple document formats. PDF output options All PDF options are ignored unless either the ‘-Opdf’ (below) or the ‘-PAfile’ (see page R-15) is used. -Opdf file.pdf -Opdf file.pdf, pname (Windows only) Create a PDF (Portable Document Format) output file. The output file name must always have a ‘.pdf’ extension. A PDF file created using the ‘-Opdf’ option always contains default PDF setup information. The structure of this information can be controlled using the ‘-config’ command line option (see page R-15), or by importing paragraph formats from a template document. Using the ‘-Opdf’ option with ‘-Bfile’ option results in a single PDF file for the whole book, unless the ‘-Pmulti’ option is used (see page R-13). All hypertext links and cross references are preserved in the PDF output file. See the the ‘-config’ command line option (page R-15) and the ‘-PDFjobopts’ command line option (page R-14). The ‘-Ppapersize’ option (see page R-17) is ignored when the ‘-Opdf’ option is used. The PDF page width and height (CropBox) is always set to the document page width and height, unless the ‘-Ppapersize’ option is set to a smaller size. In the latter case the PDF output document is cropped to the smaller size. In the case of PDF files created from a book which includes documents with different page sizes, the PDF file will also include differently sized pages, unless they are cropped to a uniform size by setting the ‘-Ppapersize’ option to a value that crops all the pages. In the second case above (Windows only), pname is the name of a PostScript printer whose driver should be used to produce the output file. (pname is the name of the printer as shown under the ‘General’ tab in the printer ‘Properties’ window.) Using the pname qualifier overrides the default printer set using the ‘-Pdefault’ command line option or the user default printer. pname must be separated from the preceding filename by a comma, and must be enclosed in double quotes if it contains space characters. Always use the "Acrobat Distiller" or "Adobe PDF" printer when generating PDF output. (On Windows the "Acrobat Distiller" or "Adobe PDF" printer is recommended for use when creating PDFs as they allow a wide range of paper sizes and support color). Use the ‘-Opdfx’ option and the ‘-Ppapersize’ option (see page R-17) for creating high-resolution print-ready PDF files with cropmarks. R-12 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo Table 2.1 miramo options ( Continued ) Option Description -Opdfx file.pdf -Opdfx file.pdf, pname (Windows only) Same as ‘-Opdf’ above except that the PDF output file does not preserve any hypertext links and cross references, does not include any Acrobat setup information and all PDF page sizes are set to the selected paper size, regardless of document page size. The ‘-Opdfx’ option results in smaller PDF files and enhanced throughput and may be used to create print-ready PDF files with cropmarks. In the second case above (Windows only), pname is the name of a PostScript printer whose driver should be used to produce the output file. (pname is the name of the printer as shown under the ‘General’ tab in the printer ‘Properties’ window.) Using the pname qualifier overrides the default printer set using the ‘-Pdefault’ command line option or the user default printer. pname must be separated from the preceding filename by a comma, and must be enclosed in double quotes if it contains space characters. Always use the "Acrobat Distiller" or "Adobe PDF" printer when generating PDF output. The PDF page width and height is set to the default paper size of the currently selected printer, regardless of the document page size. The output PDF MediaBox and CropBox have identical dimensions when the ‘-Opdfx’ option is used. Use the ‘-Ppapersize’ option (see page R-17) to set the PDF page size, for example to allow room for cropmarks in print-ready PDF files. -Pmulti key Output a PDF file or a PostScript file, or both, for each printable chapter in a -Pmulti key+key book. (See the ‘print’ option on the Miramo Reference Guide [ v 9.2 ] R-13 Running Miramo CHAPTER 2 Table 2.1 miramo options ( Continued ) Option Description The ‘-Pmulti’ command line option may be used in combination with the ‘-Opdf’ command line option, ‘-Opdfx’ command line option, ‘-PAfile’ command line option, or the ‘-Pfile’ command line option. In this case a single PDF output file or a single PostScript file, or one of each, will be produced for the entire book, in addition to a PDF or PostScript file, or both, per printable chapter. -PDFmode normal | saveAs Method to use for creating PDF file. Setting the ‘-PDFmode’ option to normal distills the temporary PostScript file in a single pass. Setting the ‘-PDFmode’ option to saveAs uses the FrameMaker ‘Save As’ method. The ‘-PDFmode’ option must be set to saveAs to include .U3D or .SWF files. If ‘-PDFmode’ is set to saveAs, the ‘-PDFjobopts’ option must use the ‘+’ style of PDF joboptions file referencing. If the ‘-PDFcmyk’ option is set to Y the value of ‘-PDFmode’ is forced to saveAs. Setting the ‘-PDFmode’ option to saveAs increases document processing time. The ‘-PDFmode’ option is not effective when running with versions of FrameMaker prior to version 9. See the R-14 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo Table 2.1 miramo options ( Continued ) Option Description In the second form, file,file, the file following the comma separator is the name of file containing job options settings to use when creating separate PDF output for each chapter in a book, if different settings are required to the settings used when outputting the book as a single PDF file. This form is effective only if a ‘-Pmulti’ option is used (see pages R-13 and R-454). For further notes and guidance relating to .joboptions files see section PDF .joboptions files (Windows only) on page R-32. -PDFbookmarks Default | All | None | int Control bookmark display in output PDF document. Key Description Default Expand bookmarks to the default level. All Expand all bookmark levels. int Expand bookmarks to level int. If the value of int is 0 (zero) only top-level bookmarks are shown. If the value of int is 1 top-level bookmarks and the first sub-level are shown. And so on. None No bookmarks. Default: From template, if specified, otherwise Default. -PDFview Page | Default | Width Control PDF document view on opening. Key Description Page Fit page within window (default). Default Open at current default setting. Width Make document width same as window width. Default: Page -PDFthread N | F | C Control PDF article threads. Key Description N No article threads (default). F Thread by text frame. C Thread by text column. Default: N -PDFopenpage int Set page to display on opening the PDF file. The first page in a document is page 1. -PDFpdests Create a named destination for every paragraph. (Large PDF files result.) -PDFtagged Create ‘Tagged’ PDF. (Slow.) -PDFpnames Include paragraph name in PDF bookmark text. Default: Exclude paragraph names in PDF bookmark text. -config configfile Name of file containing PDF bookmark structure information. Inapplicable when the input stream contains the Miramo Reference Guide [ v 9.2 ] R-15 Running Miramo CHAPTER 2 Table 2.1 miramo options ( Continued ) Option Description Printing and print file output options -Pdefault pname (Windows only) Set default printer name to pname. pname is the name of the printer as it appears in the Windows Printers panel. Document fonts, formatting and page sizes are affected by the printer driver and settings associated with the selected printer. Default: as set by the Windows Printers panel -P Print document on default printer. See -Pdefault above. -Pname pname Print document on PostScript printer pname. -Pfile file.ps -Pfile file.ps, pname (Windows only) Print to PostScript file file.ps. In the second case above (Windows only), pname is the name of a PostScript printer whose driver should be used to produce the output file. (pname is the name of the printer as shown under the ‘General’ tab in the printer ‘Properties’ window.) Using the pname qualifier overrides the default printer set using the ‘-Pdefault’ command line option or the user default printer. pname must be separated from the preceding filename by a comma, and must be enclosed in double quotes if it contains space characters. Always use the "Acrobat Distiller" or "Adobe PDF" printer when generating PDF output. -Pfonts key (Unix only) Scope and method of font inclusion in PostScript output file. key may be any of the following: Key Included fonts none No included fonts (default). X13 All except ‘Standard 13’ and Asian fonts, unless Asian key is included. X35 All except ‘Standard 35’ and Asian fonts, unless Asian key is included. all All fonts except Asian fonts, unless Asian key is included. Asian Asian (CID) fonts. TTFtoT1 Convert TrueType fonts to PostScript Type 1. Multiple key values may be included using ‘,’ (comma) as a separator. In the case of conflict, later values override preceding values. E.g. -Pfonts X13,TTFtoT1,X35 In the above the X13 key value is overridden by the following X35 value. No spaces are allowed in the key string. Default: none -Pcopies n Print n copies of the output file. Ignored when printing to Acrobat PostScript file using the ‘-PAfile’ option. Default: 1 -Pscale npercent Scale document to npercent before printing. Ignored when printing to Acrobat PostScript file using the ‘-PAfile’ option. Default value: 100 R-16 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo Table 2.1 miramo options ( Continued ) Option Description -Preg D | N | W | T Print registration and crop marks. Argument Description D Default, i.e. as set in template document, if any. N No registration marks. This is the default if there is no template document. W Western registration marks. T Tombo registration marks. Registration marks will not be visible unless the printer paper size is set to a value large enough to accommodate them. See the ‘-Ppapersize’ option below. -Pstartpage n Print file, starting from page n. The value of n refers to the page number that may be shown on the printed sheets, not to the sequential sheet number in the document. Default value: first page in document -Pendpage n Print file, ending at page n. The value of n refers to the page number that may be shown on the printed sheets, not to the sequential sheet number in the document. Default value: last page in document -Pstartno n Print file, starting from pagecount number n. The value of n refers to the sequential sheet number in the document (first page = 1), not to the page number that may be shown on the printed sheets. Default value: first page in document -Pendno n Print file, ending at page count number n. The value of n refers to the sequential sheet number in the document (first page = 1), not to the page number that may be shown on the printed sheets. Default value: last page in document -Ppapersize key Select printer paper size, either using a paper size key value default, pagesize, a4, a5, b5, tabloid, legal, letter or by specifying a custom paper size width and height using the form WuHu, for example 9cm20cm or 210mm310mm. The custom paper size value must not include any spaces. The key value pagesize sets the paper size to the page size specified in the document. The ‘-Ppapersize’ option determines the following: – The width and height of the MediaBox in PDF output. – The width and/or height of the CropBox in PDF output, if the paper size has a width or height smaller than the document page width or page height. – The values used for the %%BoundingBox and %%PageBoundingBox (DSC parameters) in PostScript output. In PDF output the CropBox is the apparent size of the document when displayed in a PDF viewer application. If Encapsulated PostScript (EPS, one page at a time only) or PDF output is required then the ‘-Ppapersize’ option must be specified if a non-default paper size is required. Miramo Reference Guide [ v 9.2 ] R-17 Running Miramo CHAPTER 2 Table 2.1 miramo options ( Continued ) Option Description If no ‘-Ppapersize’ option is used, or the ‘-Ppapersize’ has the value default, the paper size, or MediaBox size in the case of PDF, is the default "output paper size" set for the target printing device. On Windows, to set the output paper size for the "Adobe PDF" printer select the printer from the printers control panel, choose Printing Preferences followed by Paper/Quality, click on the Advanced tab and set the required value in Paper/Output Paper Size. Note that setting the "Adobe PDF page size" for the "Adobe PDF" printer also sets the "output paper size" to the same value, and vice-versa. On Unix the default value can be changed using the Maker.paperSizeWidth: and Maker.paperSizeHeight: X-Resources. If the ‘-Ppapersize’ option is set to pagesize, the paper size is set to the document page size. If the PDF file is created from a book, the paper size defaults to the page size of the first chapter in the book. For PDF files created using the ‘-Opdfx’ option, the CropBox for every page in the PDF file is set to the selected paper size, regardless of the document page size, i.e. the PDF CropBox is always set to the same size as the MediaBox. Selecting a paper size larger than the document page size allows room for printed crop marks. For PDF files created using the ‘-Opdf’ option the width and height of the CropBox is set to the document page size unless either the width or height of the paper size is smaller, in which case the smaller value overrides the corresponding page size dimension. In the case of PDF files created from a book using ‘-Opdf’, different chapters may have different PDF page sizes, but all pages will be cropped to the paper size in effect when the PDF file is created. On Windows PDF output pages are clipped to the paper size selected, i.e. the PDF output document has a CropBox specification matching the selected paper size. An illustration of ‘-Ppapersize’ usage is shown in Example 3.59 and Figure 3.46 on page R-190. Default value: default -PpageOrder F | L Specify page order for printing. Argument Description F Print first page first L Print last page first The document is always printed first page first when printing to Acrobat PostScript file using the ‘-PAfile’ option or saving in PDF using the ‘-Opdf’ option, regardless of this command line option. On Unix systems the default value for this setting is specified using the Maker.lastPageFirst: X-Resource. On Windows systems the default is that set for the default system printer driver. -Pseps Print document in 4 CMYK color separated versions. -Pskipblanks (Windows only) Skip blank pages when printing. By default blank pages within a document are always printed. The ‘-Pskipblanks’ command line option suppresses printing of all blank pages. This is often a requirement when printing color separations using the ‘-Pseps’ option (see above). R-18 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo Table 2.1 miramo options ( Continued ) Option Description A blank page is any page that contains no non-white text or graphic elements. -PAfile psfile Generate Acrobat information in PostScript file psfile suitable for conversion to PDF format using the Adobe Distiller, where cross references and hypertext links are preserved. The resulting PDF file may be distributed for online viewing using Adobe Acrobat. (See section PDF .joboptions files (Windows only) on page R-32). The Acrobat PostScript file will always be printed to a file with print settings of 100% scaling, 1 copy, print first page first, and print blank, odd and even pages, regardless of the values of the ‘-Pscale’, ‘-Pcopies’, ‘-Pskipblanks’, ‘-PpageOrder’ command line options. Template options -Cfile filetocopy Copy the contents and all format specifications from filetocopy into the current document immediately before the (optional) text and graphic markup contained in the input stream. This option differs from the ‘-Tfile’ option in that the contents of body pages are copied as well as all formatting specifications. By default, unless the ‘-Toverride’ command line flag is used, any format definition codes included in the input stream will override format specifications with the same name copied from the filetocopy. This includes variable definitions specified using the Miramo Reference Guide [ v 9.2 ] R-19 Running Miramo CHAPTER 2 Table 2.1 miramo options ( Continued ) Option Description -Toverride Allow template format definitions to override those of the same name and type created using format definition codes. By default, format definitions created using format definition codes will override those imported from the template. -Tformats fmts Select formats to be extracted from (‘-Tformats’), or not extracted from -TXformats fmts (‘-TXformats’), the template file given with the ‘-Tfile’ option. The formats to be copied or excluded are specified by a string, fmts, comprising one or more letter keys. The fmts string must contain no space or other separators. (A space is required between the ‘-Tformats’ or ‘-TXformats’ and the fmts string.) An example of a fmts string is: dcpflLRruvtkxTF This will extract (‘-Tformats’), or exclude (‘-TXformats’) all formats from the template file and is equivalent to using no ‘-Tformats’ option. The key letters may be in any order. Note that using ‘-Tformats’ or ‘-TXformats’ without ‘-Tfile’ is not allowed. Apart from the ‘F’, or flowtag, key the letter keys for selecting formats are identical to the options used with the code. The inclusion of a letter key in the formats string is equivalent to setting the corresponding option to Y. The absence of a letter key in the formats string is equivalent to setting the corresponding option to N. Key Document formats d Document formats. c Condition catalog. f Font formats. l Page layouts. L Page layouts and document formats. R Reference pages. r Ruling formats. u Default units. v Variable definitions. t Table formats. k Color definitions. x Cross reference formats. p Paragraph formats. T Table and ruling formats. Equivalent to ‘rt’. F Text flow formats. Assumes text flow ‘A’. To use text flow formats from another text flow, use the ‘-Tflow’ option. -Tflow name Set the name of the main textflow to name. Specific textflow attributes, for feathering, side-head settings and baseline synchronization, are as defined in a template file or by using the R-20 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo Table 2.1 miramo options ( Continued ) Option Description -tplImode normal | bypass If the ‘-tplImode’ command line option is used with the bypass parameter, images in EPS or JPEG format that are imported by reference in a template document or that are imported using the Post-processing options -userapi name Run the Frame API client name on FrameMaker document. The API client must be registered in the appropriate apiclients file (Unix) or in the appropriate maker.ini file (Windows), and its entry must appear before that for the Miramo API client, ‘mmapi.dll’. See Appendix 3 on page R-537, and the Frame Developer's Kit (FDK) documentation for more details. Not effective on FrameMaker generated indexes or tables of contents. For an alternative method of running FDK API clients, and ExtendScript applications, see the Command line examples To check an input file for errors: miramo xmlfile or miramo -M mmfile (The latter example preprocesses ‘mmfile’ using the mmpp macro processor). To import all format definitions from a template file, and to automatically print the docu- ment without creating a permanent output file: miramo -P -Tfile templatefile mmfile Note that this is exactly equivalent to: miramo -P -Tfile templatefile -Tformats dcpflLRrvtkuxTFh mmfile The above uses the FrameMaker user or FrameMaker system default printer (or, on Win- dows, the user default printer—which must be a PostScript® printer) and text flow for- mats from ‘Flow A’ in the template file. Miramo is an input filter, so all the above examples may be re-written to have the form: cat mmfile | miramo flags (Unix) or type mmfile | miramo flags (Windows) Environment variables Miramo environment variables on Windows are primarily a means of accessing informa- Miramo Reference Guide [ v 9.2 ] R-21 Running Miramo CHAPTER 2 tion in a convenient way, e.g. paths for important folders. A few Miramo environment variables may be used to control Miramo's operating mode. In the latter case the host sys- tem must be re-booted for the new value to take effect. On Unix environment variables may be set dynamically, e.g. to change Miramo and FrameMaker versions to be used.1 Certain environment variables may be overridden by command line flags. These are indi- cated in Table 2.2. Table 2.2 Environment variables Name Description FMHOME FrameMaker installation directory, used to locate Frame filter programs and Frame products. FMHOME must be set before running Miramo. On Windows this environment variable is set automatically during installation, from the Windows registry HKEY_LOCAL_MACHINE key: Software\Microsoft\Windows\ CurrentVersion\App Paths\FrameMaker.exe MM_RUNAS_HOME (Windows only) User's home folder. Typically: C:\Documents and Settings\runAs User Account Name or C:\Users\runAs User Account Name MM_HOME Miramo installation directory. MM_HOME must be set before running Miramo. On Windows this environment variable is set automatically during installation. MM_PDF_PREFS (Unix only) Use this environment variable to customize the operation of the ‘-Opdf’ command line option, by setting the MM_PDF_PREFS environment variable to a non-empty string containing command line options to be passed to the Adobe Acrobat distill process which creates the PDF file, in addition to the ‘-pairs file.ps file.pdf’ command line options. For example, to create a PDF file which cannot be printed, set the MM_PDF_PREFS environment variable to the value: -allowprinting NO The command mmdistill.sh -help all will output a concise on-screen listing of the options. Default: -quiet MM_PS_WAIT (Unix only) If PostScript output has been requested, set to Y to force the Miramo process to wait until the PostScript file has been created before terminating or proceeding to the next document. Default: N FM_PS_PROLOG (Unix only) Name of the file to use as the PostScript prolog. Effective only when running with FrameMaker 7.1 or above. Default value: \$FMHOME/fminit/ps_prolog 1. On Unix, environment variables are set using the ‘setenv’ shell property (csh or ksh) or the assignment (=) and ‘export’ shell properties (sh). On Windows, environment variables are set via the System control panel. R-22 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo Table 2.2 Environment variables ( Continued ) Name Description MM_DISPLAY (Unix only) Name of X-display used by the Miramo API client Default: $DISPLAY MM_MAKERNAME (Unix only) Name of Frame product to be used by Miramo. To run Miramo with FrameMaker+SGML, set the MM_MAKERNAME environment variable to makersgml . Default: maker MM_MAKEROPTS (Unix only) Special Miramo runtime options. Default (Unix): "-nosplash -server" MM_ICU_DATA_DIR By default mmxslt looks for binary (.cnv) character mapping tables in the directory $MM_HOME/icu/data. Use $MM_ICU_DATA_DIR to change the location mmxslt looks for binary (*.cnv) character mapping tables. Default: $MM_HOME/icu/data MM_TMPDIR (Unix only) Location for non-document temporary files created by Miramo. On Windows the location of temporary files may be set via the mmVisor Control tab. Default: current directory Exit codes Table 2.3 lists the exit codes that may be returned when jobs terminate. This list of exit codes is also contained in XML encoding in the file %MM_HOME%\config\mmError- Codes.xml. Exit code values are equivalent to statusCode values returned by mmServer and the memAPI. Table 2.3 Exit codes Exit code Description 0 Success 421 Usage error 422 FrameMaker API Error 423 PDF file creation error 424 mmServer or mmConnect not running 425 Timeout on 'maxWaitTime' setting 426 Timeout on 'maxProcTime' setting 427 Job has been cancelled 428 Internal error 429 Invalid license 430 Invalid processing channel group number or name 431 Invalid configuration file 432 Invalid job number 433 Pre-processor failed 434 Invalid username or password supplied for remote host 435 Syntax error in input stream Miramo Reference Guide [ v 9.2 ] R-23 Running Miramo CHAPTER 2 Table 2.3 Exit codes ( Continued ) Exit code Description 436 An attempt was made to create a PDF containing transparency, but the supplied joboptions file does not include /AllowTransparency true or the compatibility level is set to a value less than 1.4 437 mmServer was unable to start FrameMaker. Check FrameMaker installation 438 mmServer was unable to start Acrobat Distiller. Check Acrobat Distiller installation 439 Document failed to print - has a font been installed or deleted? Try restarting mmServer via the mmVisor control tab 440 Document failed to print because the PostScript file is locked by another process. Try restarting the Print Spooler service via the Services control panel 441 Cannot access log folder 442 Invalid command line option 443 Input stream contains R-24 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo Table 2.3 Exit codes ( Continued ) Exit code Description 517 Graphics file import failed 518 Cannot apply TCN option to paragraph 520 Cannot set default printer 521 Print spooler (spoolsv.exe) not running 522 Cannot contact FrameMaker session 523 Cannot contact FrameMaker session due to a hidden dialog box - check FrameMaker installation and try again 524 Maximum licensed number of processing channels has been exceeded. Reconfigure processing channel groups using mmVisor and try again 525 Joboptions file must have a .joboptions suffix 526 Cannot get joboptions folder from registry 527 Job terminated by user 528 Job terminated - FrameMaker process hang 529 Cannot start mmServer service - invalid runAs user name or password 530 Cannot start FrameMaker - has your evaluation period expired? Check FrameMaker installation and try again 531 Cannot start PDF permissions post-processor 532 Cannot access specified Using the built-in Miramo X-server (Unix only) The Miramo installation includes mm_xvfb, a modified version of the X11R6.4 X-Win- dows ‘Xvfb’ (X virtual frame buffer) utility. This enables Miramo to run regardless of whether the host system supports an X-Windows display. By default, unless it is being run with the ‘-xvfb’ command line option (see page R-7), Miramo will use the X-server (display) named by the MM_DISPLAY environment variable or, if this environment variable is not set, it will use the X-server named by the DISPLAY environment variable. If neither of these environment variables are set, Miramo uses the default display name, ‘unix:0’. If Miramo is unable to open the named display, it will exit with an error message. Note that the DISPLAY and MM_DISPLAY environment variables may have different values. Miramo will always use MM_DISPLAY if it is set, and only use DISPLAY if MM_DISPLAY is not set. Other applications will default to using DISPLAY. Miramo Reference Guide [ v 9.2 ] R-25 Running Miramo CHAPTER 2 If the Miramo installation host does not have an X-server installed and an X-server is not reachable on the local network, then either the -xvfb command line flag must be used, or the mm_xvfb server must be started as a permanent background process before running Miramo. mm_xvfb may be started as a permanent background process using one of the following commands: setenv MM_DISPLAY `mmxvfb start` [csh] MM_DISPLAY=`mmxvfb start` ; export MM_DISPLAY [sh & ksh] Alternatively mm_xvfb can be started as part of the system boot procedure by entering the following command within a boot, or ‘rc’, script: MM_DISPLAY=`installdir/bin/mmxvfb nnn` ; export MM_DISPLAY where installdir is the full path name of Miramo installation directory and nnn represents an integer display number. Even if the host system has its own X-server installed and running, or an X-server is acces- sible on the local network, there are significant advantages in using the built-in Miramo X-Server in a production environment. The main advantages are as follows: 1 Reliability is guaranteed when using mm_xvfb. There is no dependence on any other user's actions, e.g. a user may shutdown a GUI-based X-Server being accessed by Miramo. 2 Performance will be significantly higher. This is especially the case when the X- Server must be accessed over a local network. The above advantages, negligible during general development work, become most signifi- cant during high volume processing of short documents in a production environment. When running on Solaris 8 the script file S99xvfb, shown in Example 2.1, should be installed in the /etc/rc2.d directory for execution during system startup. 1 # File: S99xvfb 2 # In: /etc/rc2.d 3 # Create directories and set permissions for Miramo -xvfb 4 # (virtual framebuffer) 5 if [ ! -d /tmp/.X11-pipe ] ; then 6 echo "/etc/rc2.d/S99xvfb: mkdir /tmp/.X11-pipe" 7 mkdir /tmp/.X11-pipe 8 fi 9 if [ ! -d /tmp/.X11-unix ] ; then 10 echo "/etc/rc2.d/S99xvfb: mkdir /tmp/.X11-unix" 11 mkdir /tmp/.X11-unix 12 fi 13 echo "/etc/rc2.d/S99xvfb: chmod 1777 /tmp/.X11-pipe /tmp/.X11-unix" 14 chmod 1777 /tmp/.X11-pipe /tmp/.X11-unix Example 2.1 File Sxvfb Configuring Miramo as a Frame input filter (Unix only) If output files will normally be opened on-screen using FrameMaker or FrameViewer, it may be an advantage to amend the fmimport script in the $FMHOME/fminit directory to include a line of the form: 'DZONMM ') ${MM_HOME}/miramo [options] -Omif $2 $1 ;; R-26 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo and add the following line to the filterlist file in the same directory: <`MM ' DZON Miramo MIF TextImport mm `Miramo'> (Note that 'DZONMM ' and 'MM ' contains exactly two trailing spaces). Doing the above will enable Frame users to click on files ending ‘.mm’ and have them automatically processed by Miramo and then displayed. mmxslt pre-processor The mmxslt pre-processor may be used to map from any XML encoded data to Miramo markup, i.e. to XML which conforms to the Miramo DTD1. mmxslt is an XSLT stylesheet processor which conforms to the W3C XSLT and XPath recommendations2. It is based on the Apache organization's Xalan-C++ and includes a compatible release of the Xerces-C++ XML parser3. The usage summary for mmxslt is as follows: mmxslt options [inputXMLfile [outputXMLfile]] mmxslt may be used as a command followed by an input file and an output file, for exam- ple: mmxslt -Xxsl demo.xsl demo.xml demo.mm or as a filter, reading XML encoded input from an external program and writing Miramo markup direct to Miramo: program | mmxslt -Xxsl demo.xsl | miramo -Opdf demo.pdf Alternatively, mmxslt may be started via the Miramo ‘-X’ or, more commonly, the ‘-Xxsl’ command line options. The second example above is therefore equivalent to: program | miramo -Xxsl demo.xsl -Opdf demo.pdf See page R-6 for a description of the Miramo ‘-X’ and ‘-Xxsl’ command line options. mmxslt must be able to locate a valid XSLT stylesheet. This is usually specified using the mmxslt ‘-Xxsl’ command line option, or the Miramo ‘-Xxsl’ command line option, as illus- trated in the examples above. If neither of these are used, the input XML file must include a reference to the XSLT stylesheet. Table 2.4 contains a description of each mmxslt command line option. Table 2.4 mmxslt command line options Option Description -h Display a brief mmxslt options ‘usage’ guide on standard error. -v Display mmxslt version information on standard error. 1. See pages R-422 to R-447 for a listing of the Miramo DTD. 2. See the W3C web site http://www.w3.org for more information. 3. More information about Xalan-C++ may be found at http://xml.apache.org/xalan-c. This site also includes a section on ‘Getting up to speed with XSLT’ which gives a list of links to background materials, discussion groups, books and tutorials on XSLT. Miramo Reference Guide [ v 9.2 ] R-27 Running Miramo CHAPTER 2 Table 2.4 mmxslt command line options ( Continued ) Option Description -in inputXMLfile Specify XML input file. By default mmxslt reads its input from stdout. -Xxsl file.xsl file is the name of the file containing the XSL stylesheet. This option assumes that the input file is a well-formed XML file. The ‘-Xxsl’ option is always required unless the input XML file includes a reference to the XSL stylesheet, for example: R-28 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo Table 2.4 mmxslt command line options ( Continued ) Option Description -Xencoding encoding Specify output encoding. encoding may be any of the values returned by the command: mmxslt -elist . The -Xencoding option is overridden by a CHARMAP Batch printing Documents may be printed automatically using the ‘-P’ (printing) command line flags (see page R-16). Miramo Reference Guide [ v 9.2 ] R-29 Running Miramo CHAPTER 2 Alternatively, all or part of an existing Frame document or book may be printed on demand using the mmprint utility, described below. mmprint utility mmprint is a standalone utility for printing FrameMaker documents and books. Docu- ments may be in MIF or binary format. Book files may also be in MIF or binary format, but chapters within books must always be in FrameMaker binary format. mmprint incorporates all the Miramo ‘-P’ (printing), ‘-PDF’, the ‘-Opdf’, ‘-Opdfx’, ‘-Blastpage’, and the ‘-Bupdate’ command line options; and also (on Unix only) supports the ‘-pages’ option which displays a page count for a document without printing it. By default mmprint updates books before printing. Set the ‘-Bupdate’ option to N to print a book without a prior update. To start mmprint with command line options, type mmprint followed by a space, then a command line option followed by an option value where appropriate. The name of the Frame document or book to be printed is always the last command line argument. The command-line syntax for mmprint is as follows: mmprint -h | [-pages ] [ otheroptions ] inputfile In the above otheroptions includes the following: • All the Miramo command-line ‘Printing and printfile output options’. See pages R- 16–19. • All the Miramo command-line ‘PDF output options’ except for the ‘-config’ option. See pages R-12–15. •‘-xvfb’ (see page R-7). ‘-Blastpage’ (see page R-10). ‘-Bupdate’ (see page R-10). ‘-userapi’ (see page R-21). (Unix only:) The ‘-pages’ command line option writes the total number of pages contained in the document to standard output. The ‘-pages’ option can be used to incorporate mmprint within a Unix shell script, for example where it is required to print a very large document in sections. The following shell command line sets a shell variable NPAGES to the total number of pages in the Frame document ‘file.fm’: #!/bin/sh NPAGES=` mmprint -pages file.fm` See page R-16 for a description of the ‘-P’ , ‘-O’ , ‘-Blastpage’ and ‘-PDF’ command line flags. fmps2eps utility (Unix only) The fmps2eps utility translates a single page Unix FrameMaker 6.0 or 7.0 conforming PostScript file into Encapsulated PostScript (EPS) format. The EPS file produced has no screen preview but is suitable for subsequent import into a Miramo document. The usage summary for fmps2eps, in conventional Unix synopsis form, is as follows: R-30 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo fmps2eps -h fmps2eps file.ps [file.eps] The ‘-h’ , or ‘-help’ , options display a usage message for fmps2eps. Otherwise, the name of the Unix FrameMaker 6.0 conforming PostScript file must be specified as the first param- eter, followed by an optional output filename for the created EPS file. If no output filename is specified, fmps2eps writes the EPS file to standard output. The following example illustrates using mmprint and fmps2eps to generate a single page EPS graphic from the Frame document ‘sample.fm’: mmprint -Pfile sample.ps sample.fm fmps2eps sample.ps sample.eps fmps2eps fails with exit code 1 and writes an error message to standard error under any of the following circumstances: • The PostScript input file was not created using a Frame product. • The PostScript input file contains more than one page. • The PostScript input file is incomplete or corrupt. Printing color separations The Miramo or mmprint ‘-Pseps’ command line option selects whether color separations are to be printed. Control of print separations is achieved by setting document print options, either by using options on the Miramo 165c color paragraph text - appears on both the Magenta and Yellow process plates Miramo Reference Guide [ v 9.2 ] R-31 Running Miramo CHAPTER 2 Magenta color paragraph text - appears on the Magenta process plate only Yellow color paragraph text - appears on the Yellow process plate only Red color paragraph text - appears on the Magenta and Yellow spot plate only miramo -Pseps -Pfile separations.ps separations then the file ‘separations.ps’ will contain three pages: one for the Magenta process plate, one for the Yellow process plate, and one for the Red spot plate. PDF .joboptions files (Windows only) Joboptions files contain a set of parameters and parameter values that have a major effect on the properties of the PDF output. By default all Miramo jobs are processed using the .joboptions file set via the mmVisor Control tab.1 The default .joboptions file applies to all jobs, regardless of processing channel group. Jobs that need to be processed using different .joboptions files must be run using the ‘-PDFjobopts’ command line option (see page R-14), or the corresponding Windows Vista, Windows 7 and Windows Server 2008 R2: %MM_RUNAS_HOME%\AppData\Roaming\Adobe\Adobe PDF\Settings During Miramo installation all the .joboptions files found in the %ALLUSERSPRO- FILE%\Application Data\Adobe\Adobe PDF\Settings .joboptions folder are copied to the mmUser .joboptions (Adobe PDF\Settings) folder and re-named according to the follow- ing scheme: all spaces are removed from within the .joboptions file names, and each file name is prepended with a ‘mm’ prefix. In the case of Acrobat Distiller 9 the set of default .joboptions files includes the following: High Quality Print.joboptions PDFA1b 2005 CMYK.joboptions PDFA1b 2005 RGB.joboptions Press Quality.joboptions Smallest File Size.joboptions Standard.joboptions Example 2.4 Default All users .joboptions files (Acrobat Distiller 9) 1. The default .joboptions file is stored as the value of the defaultJoboptions attribute (with an added .joboptions extension) in the mmServer.xml configuration file located in the %MM_HOME%\config folder. R-32 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo When the Miramo installer copies the All users .joboptions files to the folder for mmUser .joboptions files, the file names are changed as described above. For example: "High Quality Print.joboptions" is renamed to "mmHighQualityPrint.joboptions" "Standard.joboptions" is renamed to "mmStandard.joboptions" The installer does not over-write pre-existing .joboptions files when new Miramo versions or updates are installed. The default .joboptions file for all Miramo jobs is mmStandard.joboptions. This can be changed by editing the value of the defaultJoboptions entry in the mmServer.xml configura- tion file, located in the %MM_HOME%\config folder. The multi-language description parameter dictionary: /Description << ... multi-language text ... >> has no effect on PDF creation and may be deleted from mmUser .joboptions files using a text editor. If the input includes images with alpha channel transparency (see the PDF notes, bookmarks and cross-references During the conversion process, PDF cross references, bookmarks and notes are created from the input markup as follows: Hypertext alerts are translated to a PDF note. For example, the following input: Miramo Reference Guide [ v 9.2 ] R-33 Running Miramo CHAPTER 2 Controlling bookmark levels using a ‘config’ file In the general case, assuming the specialized PDFBookMarkParaTags N PDFBookMarkLevel 1 "Chapter Title" R-34 Miramo Reference Guide [ v 9.2 ] CHAPTER 2 Running Miramo PDFBookMarkLevel 2 FirstHead1 PDFBookMarkLevel 2 Head1 If the first value following the PDFBookMarkLevel keyword is zero the paragraph will not be included in the PDF bookmarks. This is equivalent to omitting the paragraph from the ‘-config’ file. Paragraph format names containing spaces must be included in double quotes. If bookmark settings are specified in a ‘-config’, file settings contained in a tem- plate file are ignored. The ‘-config’ command line option and the corresponding Miramo Reference Guide [ v 9.2 ] R-35 Running Miramo CHAPTER 2 R-36 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Inline markup codes specify the formatting of the major in-flow elements within a docu- ment, for example paragraphs, tables and anchored frames. Usage rules for inline markup codes All Miramo markup is conformant with the XML standard. However the terminology used in this documentation is slightly different to standard XML terminology. For exam- ple, where this documentation refers to a markup code the standard XML term is an ele- ment. Similarly where this documentation refers to a markup code (element) option the standard XML term is an attribute. Miramo codes and XML elements, and Miramo options and XML attributes are exact equivalents. For historical reasons Miramo syntax also permits a looser syntax than XML. For example it is not mandatory that all attribute/option values are enclosed within quotation marks, though they always can be. Similarly it is not mandatory that all Miramo elements/codes must terminated, though they always can be. The following are some general usage rules for inline markup codes. • All inline codes start with a < character followed by the literal markup code name, followed by zero or more option=value pairs which are terminated by the > character or a /> string. In addition the scope of an inline markup code may be terminated by a character. The following are examples of markup codes: .. • In some cases scope-terminating markup is mandatory. For example, in the following: code may have no option=value pairs, or may have over fifty. The following are examples of option value pairs: • Many inline codes must contain at least one option=value pair. For example, the Miramo Reference Guide [ v 9.2 ] R-37 Inline markup codes CHAPTER 3 Option values may be enclosed within a pair of quotation mark, ", or apostrophe characters, ', U+0027 APOSTROPHE or U+0022 QUOTATION MARK. White space (spaces and tabs) is permitted around the = sign in option=value pairs and option=value pairs may be separated by spaces, tabs and newlines, e.g. Option string or file name values containing spaces must be surrounded by matched apostrophe or quotation mark characters. Options and their values must be on the same line. • Options may be repeated any number of times. Later option values override earlier option values. The following will result in a paragraph text size of 8 points: • In certain cases the order of options is significant. For example, if a ‘fmt’ option appears after override options, the override options will be ineffective. In both the following examples the option preceding the ‘fmt’ option is ineffective: • Some inline codes support no options. Examples of these codes are: Summary of inline markup codes Inline markup codes may be classified loosely under several type categories, according to function, as shown in the table below. Table 3.1 Summary of inline markup codes Code name Page Text codes R-220–230 Book codes Table formatting codes R-38 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Table 3.1 Summary of inline markup codes ( Continued ) Code name Page Graphics related codes File inclusion & system codes R-111–112 In-text codes R-137–142 Indexing codes Hypertext and cross-reference codes Miramo Reference Guide [ v 9.2 ] R-39 Inline markup codes CHAPTER 3 Table 3.1 Summary of inline markup codes ( Continued ) Code name Page Codes for variable values Miscellaneous codes There are 56 inline codes in total. Option names In most cases option names have a short form and an alternative, mnemonic long form. The long form is shown within square brackets immediately below the short form. The two forms are illustrated below. ff [ fontFamily ] In the above, ‘ff’ is the short form and ‘fontFamily’ is the long form. Both forms may be used interchangeably. Option values and value types In all cases option values may be enclosed within a pair of quotation mark, ", or apostro- phe characters, ', U+0027, APOSTROPHE or U+0022, QUOTATION MARK. Most of the value types given in the Syntax sections on the following pages are self-explan- R-40 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes atory. Exceptional items are explained below: Table 3.2 Summary of option value types Value type Description name A name value may comprise any sequence of printable characters, excluding newlines or binary tabs. If a name value contains any of the following characters: space, <, >, or =, the name value must be enclosed within a pair of quotation mark, ", or apostrophe characters, ', U+0027 APOSTROPHE or U+0022 QUOTATION MARK. For name values containing the U+0022 quotation mark character, use apostrophe characters; otherwise, use quotation mark characters where necessary. Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhh;). However if the requested character is not available in the current font, it will be ignored with a warning message. A name value may be the name of a local, user-specified formatting object, e.g. a master page format, condition name or a paragraph format name. In certain cases a name value may refer to an externally defined object, e.g. the name of a font or a font variation. The following are examples of valid names: !@#$% 'Yellow Butterfly' "Angèle's address" namelist A comma separated list of name values of a specified type. A namelist value must be enclosed within a pair of quotation mark, ", or apostrophe characters, ', U+0027 APOSTROPHE or U+0022 QUOTATION MARK. text text may be any sequence of characters in UTF-8 encoding. filename Unless noted otherwise, any valid file name. If a filename value contains one or more space characters, the filename value must be enclosed within a pair of apostrophe (') or or quotation mark (") characters. If the ‘-sendEnv’ command line option is used, environment variables included in filename are expanded provided they are enclosed by opening and closing curly braces. For example ${IMAGES_DIR}/logo.eps See the -sendEnv command line option on page R-7. file Exactly equivalent to filename. cmd Any valid command-line command string. Windows NT and Unix shell environment variables included in cmd are expanded. dim A dim may be any number, optionally followed by a units indicator. The units indicator may be any one of: ‘in’, ‘cm’, ‘mm’, ‘pt’, ‘pc’, ‘dd’, ‘cc’. (‘in’ is inches, ‘mm’ is millimeters, ‘cm’ is centimeters, ‘pt’ is points, ‘pc’ is picas, ‘dd’ is didots and ‘cc’ is ciceros.) The following are examples of using dim options: clm = 3.14mm ctm=8pt crm=.01in pw= .2mm ri=12pc A = "R" textColor='Blue' Miramo Reference Guide [ v 9.2 ] R-41 Inline markup codes CHAPTER 3 Table 3.2 Summary of option value types ( Continued ) Value type Description Note that white space must precede the option name, ‘clm’, ‘ctm’, ‘pw’, ‘ri’, etc., but is not required around the ‘=’ sign. The units indicator must immediately follow the units value. ri=12 pc with a space between the 2 and the pc is an error. A negative value for dim is valid in many cases. e.g. use sa=-14pt to set the space above a paragraph to -14 points. If no units indicator is specified, then the units are assumed to be either the value set by the Integer Any integer between and including the first integer and the last ranges, e.g. integer shown. (0 - 15) percent In the general case, any positive or negative number, optionally ranges, e.g. followed by a percent character, %. In some cases the number (-21.5% - 222%) range may be restricted between 0 and 100, or to positive values only. Escape, control and special characters The following table lists character names and descriptions for special characters. Table 3.3 Escape, control and special characters Character name Input Description & notes Hard return Backslash \ A single backslash, ‘\’, is the mmpp escape character. It has no special meaning within Miramo and is treated as any other printable character. Non-breaking space Any of the strings , and inserts a non-breaking space. NO-BREAK SPACE Non-breaking hyphen ‑ Either of the strings ‑ and ‑ inserts a ‑ non-breaking hyphen. NON-BREAKING HYPHEN R-42 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Table 3.3 Escape, control and special characters ( Continued ) Character name Input Description & notes Em space Either of the strings and inserts an em space. EM SPACE En space Either of the strings and inserts an en space. EN SPACE Tab Discretionary hyphen ‧ Insert either of the strings ‧ or ‧ to ‧ mark a discretionary hyphenation point. HYPHENATION POINT Thin space Insert either of the strings and to produce a thin space (one sixth of an em). THIN SPACE Hair space Insert either of the strings and to produce a hair space (one twelfth of an em). This is the smallest possible space. HAIR SPACE Suppress hyphenation Miramo Reference Guide [ v 9.2 ] R-43 Inline markup codes CHAPTER 3 R-44 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use Syntax Option Value Description Frame dimensions W dim Width of frame. [ frameWidth ] The value of ‘W’ is ignored if ‘wrap’ is set to Y (see ‘wrap’ option below). Default: 25.4 mm H dim Height of frame. [ frameHeight ] The value of ‘H’ is ignored if ‘wrap’ is set to Y (see ‘wrap’ option below). Default: 25.4 mm Content auto wrapping wrap N | Y If ‘wrap’ is set to Y then shrink-wrap the right and bottom [ wrapContent ] edges of the anchored frame to coincide with the right edge of the rightmost image or frame plus the value of ‘rm’ (see ‘rm’ option below), and lower edge of the lowest image, plus the value of ‘bm’ (see ‘bm’ option below), in the anchored frame. The ‘W’ and ‘H’ options are ignored if ‘wrap’ is set to Y. See Note 6" on page R-51, for more information about the operation of the ‘wrap’ option. Default: 25.4 mm rm dim Right side wrap margin. [ rightMargin ] The value of ‘rm’ is ignored unless ‘wrap’ is set to Y (see ‘wrap’ option above). Negative values of ‘rm’ may be used. Default:0 Miramo Reference Guide [ v 9.2 ] R-45 Inline markup codes CHAPTER 3 Option Value Description bm dim Bottom wrap margin. [ bottomMargin ] The value of ‘bm’ is ignored unless ‘wrap’ is set to Y (see ‘wrap’ option above). Negative values of ‘bm’ may be used. Default:0 Frame location options P b | T | B | I Position of anchored frame (or anchored reference frame, [ framePosition ] | R | OC | anchored table frame or anchored text frame) F N | Y Allow the frame to float. [ frameFloat ] Effective only if the ‘P’ option is set to b, T or B. Default:N A L | C | R | Horizontal alignment of frame. [ horizAlign ] nb | fb | Use the ‘A’ option to control horizontal positioning, either np | fp within or outside text columns and text frames. R-46 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description ‘P’ option values have different effects, depending on the value of the ‘P’ option (see above). The ‘P’ option is ignored if the ‘P’ option is set to I. Value Horizontal alignment L If ‘P’ set to b, T or B: at left, inside text column(s) If ‘P’ set to OF: at left, outside text frame If ‘P’ set to OC: at left, outside text column R If ‘P’ set to b, T or B: at right, inside text column(s) If ‘P’ set to OF: at right, outside text frame If ‘P’ set to OC: at right, outside text column C If ‘P’ set to b, T or B: centered, inside text column(s) nb If ‘P’ is set to any value other than I: align on side nearest page binding fb If ‘P’ is set to any value other than I: align on side farthest from page binding np If ‘P’ is set to OF or OC: align on side nearest page edge fp If ‘P’ is set to OF or OC: align on side farthest from page edge Default: C, or L when ‘P’ is set to R, OF or OL. so dim Offset of frame from side of text column or text frame. [ sideOffset ] Effective only if the ‘P’ option is set to OC or OF. Value may be positive or negative. Default:0 bo dim Offset of frame from text baseline. [ baselineOffset ] Effective only if the ‘P’ option is set to OC, OF or I. Value may be positive or negative. Default:0 C N | Y Crop frame to fit in text column. [ frameCrop ] Effective only if the ‘P’ option is set to b, T or B. Default:N RAgap dim Specify the gap between the AFrame and text flowing around [ runAroundGap ] it. The value of dim may be negative. Effective only if the ‘P’ option (see above) is set to R. Default: 6pt Miramo Reference Guide [ v 9.2 ] R-47 Inline markup codes CHAPTER 3 Option Value Description Frame border and fill styles pen 0 - 15 Pen pattern number. [ penNum ] Sixteen pen patterns for borders around anchored frame objects are available, from 0 (black) to 15 (none). (See Appendix 1, page R-531, for a description of fill patterns.) Default:15 pw dim Pen width for border. [ penWidth ] Borders around all types of anchored frame thicken inwards towards the center of the anchored frame. (Note that this is different to the case of borders around a and fill 0 - 15 Fill pattern. As for ‘pen’ above. A ‘fill’ value of 15 makes the [ fillNum ] frame transparent. Default: 7 (opaque no fill) pstyle P | "dim Pen style. Solid or dashed. Setting ‘pstyle’ to P results in a [ penStyle ] dim ..." plain, solid border or line. Setting ‘pstyle’ to a series comprising an even number of dim values sets the border to have a dashed pattern. The first dim value specifies the length of a solid line segment, the next dim value specifies the length of a white segment, and so on. The pen pattern specification must be surrounded by double quotation marks. See Examples 2.14 and 2.15 on pages MD- 34 and MD-35 in the mmDraw Drawing Guide. Default:P Frame border and fill color color name Frame border and fill color. Metadata for graphic object (AFrame) GOid string string may contain up to 512 bytes of metadata associated with this instance of the AFrame code. This metadata is shown in FrameMaker MIF files in the R-48 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description > Required Notes 1 The effectiveness of the ‘F’, ‘A’, ‘so’, ‘bo’, and ‘C’ options is dependent on the setting of the ‘P’ option, as noted in the descriptions above. 2 An empty 4 Multiple Miramo Reference Guide [ v 9.2 ] R-49 Inline markup codes CHAPTER 3 Anchoring multiple frames at the same point may produce undesired results. This possibility is illustrated in Example 3.2. Anchoring two frames at the same point, with the ‘P’ option set to b (below), with one aligned left and one aligned right (A="L" and A="R") outputs The output from Example 3.2 is Anchoring two frames at the same point, with the ‘P’ shown in Figure 3.1. option set to b (below), with one aligned left and one aligned right (A="L" and A="R") outputs the right Anchored frames may be aligned horizontally by placing them in table cells, as illustrated in anchored frame lower than the left anchored frame. Example 3.3. Figure 3.1 Output from Example 3.2 The output from Example 3.3 is shown in Anchored frames in table cells: Figure 3.2. Precise positioning of anchored frames is possible using tables. Alternatively, Figure 3.2 Output from Example 3.3 precise positioning of images may be achieved by using several codes within a single anchored frame. R-50 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes 6 If an The width of the anchored frame, Wa in Wa Figure 3.3, is calculated as follows: Figure 3.3 Parameters determining the Wa = ‘L’ + ‘W’ + ‘rm’ size of an anchored frame when the ‘wrap’ option is set to Y The height of the anchored frame, Ha in Figure 3.3, is calculated as follows: Ha = ‘T’ + ‘H’ + ‘bm’ In the above equations, ‘L’ and ‘T’ represent values of the Examples Several additional examples of anchored frames are included below. Example 3.2 includes an inline anchored frame. And because the breath of flowers is far sweeter in the air (where it comes and goes like the warbling Miramo Reference Guide [ v 9.2 ] R-51 Inline markup codes CHAPTER 3 The output from Example 3.2 is And because the breath of flowers is far shown in Figure 3.1. sweeter in the air (where it comes and goes like Adding an ‘ls’ option, set to P (set the warbling of music) than in the hand, paragraph line spacing to Figure 3.4 Output from Example 3.2 ‘Proportional’, see page R-221), to the code on the first line in Example 3.4 above prevents the anchored frame from overprinting the text above the line containing its anchor point: changes the line spacing to And because the breath of flowers is far accommodate the space occu- sweeter in the air (where it comes and goes like pied by the anchored frame, as shown in Figure 3.5. the warbling of music) than in the hand, Run-in anchored frames result Figure 3.5 Effect of setting code ‘ls’ option to P from setting the ‘P’ option to R (see page R-46). Run-in frames always appear at Tradition says that man was the beginning of the paragraph made by Prometheus, and containing the Anchored frames can be made to Figure 3.6 Run-in anchored frame run-in to the middle of a para- graph by splitting a paragraph into two or more paragraphs (‘sub-paragraphs’). The sub-paragraphs preceding the code ‘Pf’, paragraph placement format, option to R. For exam- ple, the following input: Tradition says that man was made by Prometheus, and made of clay; only that Prometheus took particles from different animals, and mixed them in. He, desiring to benefit and protect his own work, R-52 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes will produce the output shown Tradition says that man was made by Prometheus, in Figure 3.7. and made of clay; only that Prometheus took Run-in paragraph formats particles from different animals, and mixed them in. He, desiring to benefit should nearly always have and protect his own work, space above and space below ★★ and to be regarded not as set to zero. the founder only but also as the amplifier and enlarger of the human race, Auto-sizing anchored stole up to heaven with a bundle of fennel-stalks frames using the ‘wrap’ Figure 3.7 Output from Example 3.5 option The following are some examples illustrating the operation of the ‘wrap’ option. The parameters determining the operation of the ‘wrap’ option are described in Note 6 on page R-51. Examples 3.6 and 3.7 are identical except that the first has the ‘wrap’ option set to N and the second has the ‘wrap’ option set to Y. 1 1 In Example 3.6 the values of the Miramo Reference Guide [ v 9.2 ] R-53 Inline markup codes CHAPTER 3 In both Example 3.6 (line 2) and Example 3.7 (line 2), the ‘T’ ‘T’ ‘L’ ‘L’ ‘rm’ 1-1 1-2 1-3 1-4 1-1 1-2 1-3 1-4 2-1 2-4 2-1 2-4 ‘H’ Ha 3-1 3-2 3-3 3-1 3-2 3-3 4-1 4-2 4-3 4-1 4-2 4-3 ‘bm’ ‘W’ Figure 3.8 Output from Example 3.6 Wa (‘wrap’ set to N) Figure 3.9 Output from Example 3.7 (‘wrap’ set to Y) Example 3.8 shows the simplest case of an auto-wrapped image, i.e. an anchored frame containing a single image with no left or top offsets and no right or bottom margins. 1 The image is in TIFF format, a fully supported 1-1 1-2 1-3 1-4 1-5 1-6 1-7 image file format, and its height is determined auto- 2-1 2-4 2-5 2-6 2-7 matically from the given width (‘W’ value). 3-1 3-2 3-3 3-7 1. See page U-37 for a description of ‘fully’ and ‘partially’ supported graphic file formats. R-54 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Example 3.9 shows a combination of auto-wrap- 2-4 2-5 2-6 ping and image scaling using 1 Output from Example 3.9 is shown in Figure 3.11 above right. Note that the orig- inal aspect ratio of the image remains unchanged. Example 3.10 shows auto-wrapping multiple objects, compris- ing two frames and an image. 1 4 4-1 4-2 4-3 6 Figure 3.12 Output 7 from Example 3.10 8 Output from Example 3.10 is shown in Figure 3.12. See also Chapter 3, ‘Anchored frames and images’, in the Miramo User Guide, pages U-37–56, for further examples and discussion on using Miramo Reference Guide [ v 9.2 ] R-55 Inline markup codes CHAPTER 3 Summary Use Syntax Option Value Description Reference frame and file names fmt name Required. [ frameName ] name is name of the reference frame to be included from the file specified using the ‘file’ option (see below). file filename Required [ filename ] filename is the relative or absolute file name of a MIF file containing the reference frame named above. Files may be referenced using environment variables, as in ${FILENAME}. In this case environment variable names must be surrounded by curly braces. See the ‘-sendEnv’ command line option on page R-7. Reference frame position L dim Distance of left side of reference frame from left side of [ frameLeft ] enclosing anchored frame. T dim Distance of top side reference frame from top side of [ frameTop ] enclosing anchored frame. Anchored frame dimensions W dim Width of anchored frame. Default value is the width of the [ frameWidth ] reference frame name in filename (see ‘fmt’ and ‘file’ options above). H dim Height of anchored frame. [ frameHeight ] Default value is the height of the reference frame name in filename (see ‘fmt’ and ‘file’ options above). R-56 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Frame location options P b | T | B | I Position of anchored frame (or anchored reference frame, [ framePosition ] | R | OC | anchored table frame or anchored text frame) F N | Y Allow the anchored reference frame to float. [ frameFloat ] Effective only if the ‘P’ option is set to b, T or B. Default:N A L | C | R | Horizontal alignment of anchored reference frame. [ horizAlign ] nb | fb | Use the ‘A’ option to control horizontal positioning, either np | fp within or outside text columns and text frames. ‘P’ option values have different effects, depending on the value of the ‘P’ option (see above). The ‘P’ option is ignored if the ‘P’ option is set to I. Miramo Reference Guide [ v 9.2 ] R-57 Inline markup codes CHAPTER 3 Option Value Description Value Horizontal alignment L If ‘P’ set to b, T or B: at left, inside text column(s) If ‘P’ set to OF: at left, outside text frame If ‘P’ set to OC: at left, outside text column R If ‘P’ set to b, T or B: at right, inside text column(s) If ‘P’ set to OF: at right, outside text frame If ‘P’ set to OC: at right, outside text column C If ‘P’ set to b, T or B: centered, inside text column(s) nb If ‘P’ is set to any value other than I: align on side nearest page binding fb If ‘P’ is set to any value other than I: align on side farthest from page binding np If ‘P’ is set to OF or OC: align on side nearest page edge fp If ‘P’ is set to OF or OC: align on side farthest from page edge Default: C, or L when ‘P’ is set to R, OF or OL. so dim Offset of anchored reference frame from side of text column [ sideOffset ] or text frame. Effective only if the ‘P’ option is set to OC or OF. Value may be positive or negative. Default:0 bo dim Offset of anchored reference frame from text baseline. [ baselineOffset ] Effective only if the ‘P’ option is set to OC, OF or I. Value may be positive or negative. Default:0 C N | Y Crop anchored reference frame to fit in text column. [ frameCrop ] Effective only if the ‘P’ option is set to b, T or B. Default:N RAgap dim Specify the gap between the ARFrame and text flowing [ runAroundGap ] around it. The value of dim may be negative. Effective only if the ‘P’ option (see above) is set to R. Default: 6pt R-58 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Frame border and fill styles pen 0 - 15 Pen pattern number. [ penNum ] Sixteen pen patterns for borders around anchored frame objects are available, from 0 (black) to 15 (none). (See Appendix 1, page R-531, for a description of fill patterns.) Default:15 pw dim Pen width for border. [ penWidth ] Borders around all types of anchored frame thicken inwards towards the center of the anchored frame. (Note that this is different to the case of borders around a and fill 0 - 15 Fill pattern. As for ‘pen’ above. A ‘fill’ value of 15 makes the [ fillNum ] frame transparent. Default: 7 (opaque no fill) pstyle P | "dim Pen style. Solid or dashed. Setting ‘pstyle’ to P results in a [ penStyle ] dim ..." plain, solid border or line. Setting ‘pstyle’ to a series comprising an even number of dim values sets the border to have a dashed pattern. The first dim value specifies the length of a solid line segment, the next dim value specifies the length of a white segment, and so on. The pen pattern specification must be surrounded by double quotation marks. See Examples 2.14 and 2.15 on pages MD- 34 and MD-35 in the mmDraw Drawing Guide. Default:P Frame border and fill color color name Frame border and fill color. Metadata for graphic object (ARFrame) GOid string string may contain up to 512 bytes of metadata associated with this instance of the ARFrame code. This metadata is shown in FrameMaker MIF files in the Miramo Reference Guide [ v 9.2 ] R-59 Inline markup codes CHAPTER 3 Option Value Description /> Required Notes 1 The Anchored frame options are the same as the equivalent options listed under R-60 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes is possible. Examples The file ‘xt2.mif’ contains a reference frame named ‘Computer monitor’ created on the first reference page. This reference frame contains a drawing of a computer monitor. The reference frame itself is outlined by setting its pen to ‘black’ and the pen width to 3pt in the original file. Figure 3.13 Output from Example 3.11 Miramo Reference Guide [ v 9.2 ] R-61 Inline markup codes CHAPTER 3 Summary Use Syntax Option Value Description Overall dimensions W dim Overall width of anchored text frame, including margins. [ frameWidth ] Default: 200pt minh dim Minimum height of frame. [ minHeight ] Default: 15pt maxh dim Maximum height of frame. [ maxHeight ] Default: 300pt Frame location options P b | T | B | I Position of anchored frame (or anchored reference frame, [ framePosition ] | R | OC | anchored table frame or anchored text frame) 1. To achieve the effect of a single-column, ‘shrink-wrapped’ text frame, use R-62 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description When the ‘P’ option is set to any of the above values apart from I, the horizontal position of the frame may be controlled using the ‘A’, alignment, option (see below). When ‘P’ is set to I, OC or OF the horizontal position of the frame may be further adjusted using the ‘so’ option (see below). When ‘P’ is set to R the top of the frame is aligned with the top of the text (at caps height) in the first line of the paragraph. When the ‘P’ option is set to I, OF or OC the bottom of the frame is aligned with the baseline of the text containing the anchor, plus or minus the distance specified using the ‘bo’ baseline offset option (see below), unless this would cause the top of the frame to be higher than the top of the text column containing the anchor. In the latter case the top of the text column acts as a ceiling. An exception to this rule occurs when ‘P’ is set to I and the paragraph line spacing is set to be ‘fixed’. In this case top of the frame may extend above the top of the text column. F N | Y Allow the frame to float. [ frameFloat ] Effective only if the ‘P’ option is set to b, T or B. Default:N A L | C | R | Horizontal alignment of frame. [ horizAlign ] nb | fb | Use the ‘A’ option to control horizontal positioning, either np | fp within or outside text columns and text frames. ‘P’ option values have different effects, depending on the value of the ‘P’ option (see above). The ‘P’ option is ignored if the ‘P’ option is set to I. Value Horizontal alignment L If ‘P’ set to b, T or B: at left, inside text column(s) If ‘P’ set to OF: at left, outside text frame If ‘P’ set to OC: at left, outside text column R If ‘P’ set to b, T or B: at right, inside text column(s) If ‘P’ set to OF: at right, outside text frame If ‘P’ set to OC: at right, outside text column C If ‘P’ set to b, T or B: centered, inside text column(s) nb If ‘P’ is set to any value other than I: align on side nearest page binding Miramo Reference Guide [ v 9.2 ] R-63 Inline markup codes CHAPTER 3 Option Value Description fb If ‘P’ is set to any value other than I: align on side farthest from page binding np If ‘P’ is set to OF or OC: align on side nearest page edge fp If ‘P’ is set to OF or OC: align on side farthest from page edge Default: C, or L when ‘P’ is set to R, OF or OL. so dim Offset of frame from side of text column or text frame. [ sideOffset ] Effective only if the ‘P’ option is set to OC or OF. Value may be positive or negative. Default:0 bo dim Offset of frame from text baseline. [ baselineOffset ] Effective only if the ‘P’ option is set to OC, OF or I. Value may be positive or negative. Default:0 C N | Y Crop frame to fit in text column. [ frameCrop ] Effective only if the ‘P’ option is set to b, T or B. Default:N RAgap dim Specify the gap between the ATextFrame and text flowing [ runAroundGap ] around it. The value of dim may be negative. Effective only if the ‘P’ option (see above) is set to R. Default: 6pt Frame border and fill styles pen 0 - 15 Pen pattern number. [ penNum ] Sixteen pen patterns for borders around anchored frame objects are available, from 0 (black) to 15 (none). (See Appendix 1, page R-531, for a description of fill patterns.) Default:15 pw dim Pen width for border. [ penWidth ] Borders around all types of anchored frame thicken inwards towards the center of the anchored frame. (Note that this is different to the case of borders around a and fill 0 - 15 Fill pattern. As for ‘pen’ above. A ‘fill’ value of 15 makes the [ fillNum ] frame transparent. Default: 7 (opaque no fill) pstyle P | "dim Pen style. Solid or dashed. Setting ‘pstyle’ to P results in a [ penStyle ] dim ..." plain, solid border or line. R-64 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Setting ‘pstyle’ to a series comprising an even number of dim values sets the border to have a dashed pattern. The first dim value specifies the length of a solid line segment, the next dim value specifies the length of a white segment, and so on. The pen pattern specification must be surrounded by double quotation marks. See Examples 2.14 and 2.15 on pages MD- 34 and MD-35 in the mmDraw Drawing Guide. Default:P Frame border and fill color color name Frame border and fill color. Text frame margin options tfm dim All text frame margins. Placing a ‘tflm’, ‘tftm’, ‘tfrm’, or [ allMargins ] ‘tfbm’ option after the ‘tfm’ option overrides the corresponding ‘tfm’ setting. The ‘tfm’ option overrides a preceding ‘tflm’, ‘tftm’, ‘tfrm’, or ‘tfbm’ option. Default: 4pt tflm dim Text frame left margin. [ leftMargin ] Default: 4pt tftm dim Text frame top margin. [ topMargin ] Default: 4pt tfrm dim Text frame right margin. [ rightMargin ] Default: 4pt tfbm dim Text frame bottom margin. [ bottomMargin ] Default: 4pt Multi-column layout options cn int Number of equally sized sub-columns within this text frame. If [ numColumns ] this option has a value of 2 or greater the gap between sub- columns is determined by the ‘cg’ option (see below). Default:2 cg dim Gap between sub-columns within this text frame. This value is [ columnGap ] only effective if the value of the ‘cn’ option (see above) is set to 2 or greater. Default: 18pt Feathering & side-head settings sh N | Y Allow room for side-heads in this text flow. The side-head [ sideheads ] width, gap and location are specified using the ‘sg’, ‘sw’ and ‘sp’ options above. Miramo Reference Guide [ v 9.2 ] R-65 Inline markup codes CHAPTER 3 Option Value Description For details of how to specify paragraphs as side-head or run- in heads, see the code ‘Pf’ option (described on page R-225). Default:N sw dim Side-head column width. Effective only when room for side- [ sideheadWidth ] heads is switched on (see ‘sh’ option below). sg dim Gap between side-head column and main text column(s) [ sideheadGap ] within text frame. Effective only when room for side-heads is switched on (see ‘sh’ option below). sp L | R | I | O Specify side-head placement within text frame. L=left side, [ sideheadPosition ] R = Right side, I = Inside and O = Outside of text frame. Outside refers to the side nearest the page edge in the case of double-sided documents. Effective only when room for side- heads is switched on (see ‘sh’ option below). Feathering options f N | Y Feather text within this text flow. [ feather ] Default:N maxp dim Maximum inter-paragraph padding when feathering is [ maxPgfPad ] switched on. Default: 6pt maxl dim Maximum inter-line padding when feathering is switched on. [ maxLinePad ] Default: 2pt Baseline synchronization b N | Y Baseline synchronization of lines across multiple sub-columns. [ alignBaselines ] If b = Y, the baselines of text in adjacent columns are synchronized. The ‘b’ option is effective only if the ‘cn’ option has a value of 2 or greater. bl dim Line spacing for synchronized baselines. [ baselineSpace ] bh dim Maximum character height for synchronization of the first line [ maxCharHeight ] in the text column; if characters exceed this height, the first line is not synchronized Metadata for graphic object (ATextFrame) GOid string string may contain up to 512 bytes of metadata associated with this instance of the ATextFrame code. This metadata is shown in FrameMaker MIF files in the R-66 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description The ‘GOid’ option is shorthand for Notes 1 Using the code must follow immediately after the The width of the text frame, WTF , is calculated as follows: WTF = ‘W’ – (‘tflm’ + ‘tfrm’) The width of each text column, Wc, is calculated as follows: Wc = (WTF – (‘cg’ × (‘nc’ – 1) ) ) / ‘nc’ 4 If a Examples Example 3.12 below shows an 1 3 Country full of Swedes 4 Miramo Reference Guide [ v 9.2 ] R-67 Inline markup codes CHAPTER 3 5 Adapted from Country full of Swedes 6 by Erskine Caldwell 8 Now, you take the Finns; there's any number of them around in the 9 woods, where you least expect to see them, logging and such. 10 11 When a Finn crew breaks a woods camp, it looks like there's a Finn 12 for every tree in the whole state, but you don't see them going around 13 making the noise that Swedes do, with all their yelling and shouting 14 and shooting off guns. 15 Example 3.12 Near-default output from The output from Country full of the woods, where you don't see them going Example 3.12 is Swedes1 least expect to see around making the shown in Figure them, logging and such. noise that Swedes do, Now, you take the with all their yelling 3.14. Note that the When a Finn crew Finns; there's any num- and shouting and breaks a woods camp, it footnote spans a ber of them around in shooting off guns. single column only. looks like there's a Finn for every tree in the This is because the 1. Adapted from Country full of Swedes by Erskine Caldwell whole state, but you paragraph in which the footnote occurs Figure 3.14 Output from Example 3.12 is a ‘normal’ in-column paragraph. This can be overridden by following the code having a paragraph setting of ‘across all col- umns’ (or by adding a ‘Pf’ option set to S at the end of line 4 in Example 3.12). Example 3.13 is identical to Example 3.12, except that the header paragraph and footnote are set to straddle all columns: 1 3 Country full of Swedes 4 8 Now, you take the Finns; there's any number of them around in the 9 woods, where you least expect to see them, 10 logging and such. 11 12 13 When a Finn crew breaks a woods camp, it looks like there's a Finn 14 for every tree in the whole state, but you don't see them going around 15 making the noise that Swedes do, with all their yelling and shouting 16 and shooting off guns. 17 R-68 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes If a footnote is in a Country full of Swedes1 paragraph which Now, you take the When a Finn crew around making the straddles all col- Finns; there's any num- breaks a woods camp, it noise that Swedes do, umns, the footnote ber of them around in looks like there's a Finn with all their yelling itself must be set to the woods, where you for every tree in the and shouting and straddle all col- least expect to see whole state, but you shooting off guns. them, logging and such. don't see them going umns. If the default footnote paragraph 1. Adapted from Country full of Swedes by Erskine Caldwell format is not set to be ‘across all col- Figure 3.15 Output from Example 3.13 umns', this can be done by using the 1 10 Country full of Swedes 11 12 Now, you take the Finns; there's any number of them around in the 13 woods, where you least expect to see them, logging and such. 14 15 16 When a Finn crew breaks a woods camp, it looks like there's a Finn 17 18 28 Miramo Reference Guide [ v 9.2 ] R-69 Inline markup codes CHAPTER 3 30 31 The output from Example 3.14 is shown in Figure 3.16 below. Column 1 Column 2 Column 1 Country full of When a Finn crew going around making Swedes breaks a woods camp, the noise that Swedes do, with all their yelling Now, you take the it looks like there's a and shouting and Finns; there's any num- Finn for every tree in shooting off guns. ber of them around in A Finns the woods, where you B Swedes least expect to see them, logging and the whole state, but such. you don't see them Figure 3.16 Output from Example 3.14 Note the cell margin and cell ruling settings specified on line 6 in Example 3.14. In the case of the cell margin settings (‘clm’, ‘ctm’, ‘crm’ and ‘cbm’), the values are true dimensions. In the case of the cell ruling settings (‘lr’, ‘tr’, ‘rr’ and ‘br’) the val- ues are name identifiers of ruling formats which happen to have ruling width val- ues which correspond with the format names. The cell margins of the table cell containing the R-70 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the Syntax Option Value Description Metadata name string | The ‘name’ option may have any string value. Three values [ attributeName ] GOid | AT have special meaning: | Alt Value Description GOid Object identification string. Default. See Note 3 on page R-72. string Any string up to 56 bytes long. Alt The text between Notes 1 With the exception of Miramo Reference Guide [ v 9.2 ] R-71 Inline markup codes CHAPTER 3 (binary) files, or post-processed, using a custom API to access the FP_ObjectAttributes property. The attribute names and values associated with an anchored frame, created using the R-72 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Line 3 in Example 3.15 contains an , Examples Usage of the 1 Miramo Reference Guide [ v 9.2 ] R-73 Inline markup codes CHAPTER 3 Summary Use the , Syntax Option Value Description Paragraph autonumbering options label key key is any single upper or lower case alphabetic ASCII [ seriesLabel ] character specifying a ‘series label’ for this autonumber. In this way, several numbering series such as table numbering and figure numbering may be maintained within a single document. Default:"" fmt name name is the name of a character format for the autonumber [ fontFormat ] text. Default:"" P B | E Position autonumber text at beginning (B) or end (E) of [ position ] paragraph. Default:B > Building blocks The following building blocks may be used between deftext deftext consists of text, newline characters and binary tabs. All newlines are mapped to space characters. Binary tabs are preserved unless the ‘-striptabs’ command line option is used. Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhhhh;). However if the requested character is not available in the current font, it will be ignored with a warning message. R-74 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Notes 1 The Examples Example 3.16 sets up a ‘salutation’ paragraph tag, which prepends the text "Dear " to any paragraph which references it. 1 Miramo Reference Guide [ v 9.2 ] R-75 Inline markup codes CHAPTER 3 5 6 Confucius Example 3.16 Autonumber for salutation Example 3.16 produces the output shown in Figure Dear Confucius 3.17. Example 3.17 shows using 1 2 Jumped. Paragraph F 12 Fox. Over the lazy. Paragraph G 13 Dog. Paragraph H 14 Jumped. 15 Figure 3.18 Output from Example 3.17 16 Over the lazy. 17 18 Dog. Example 3.17 Autonumbered paragraphs (1) The output from Example 3.17 is shown in Figure 3.18. Multiple numbering series may be maintained within a single document using the 1 2 16 Find key. 17 18 Find door. 19 20 Place key in lock. 21 R-76 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes 22 ... Illustration showing key in lock ... 23 24 Turn through 360 degrees. 25 26 ... Illustration showing key turning... 27 28 Push the door. Example 3.18 Autonumbered paragraphs (2) The output from Example 3.18 is Step 1.0: Find key. shown in Figure 3.19. Step 1.1: Find door. See Example 3.89 on page R-249 for Step 1.2: Place key in lock. Figure 1.1: ... Illustration showing key in lock ... an illustration of using the Step 1.3: Turn through 360 degrees. Miramo Reference Guide [ v 9.2 ] R-77 Inline markup codes CHAPTER 3 Summary Use Syntax Option Value Description Marker text for background (e.g. header/footer) text frame fmt 1 | 2 Setting ‘fmt’ to 1 results in the marker text being expanded in [ bgMarkerNum ] the R-78 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Building blocks The following building blocks may be used between deftext deftext consists of text, newline characters and binary tabs. All newlines are mapped to space characters. Binary tabs are preserved unless the ‘-striptabs’ command line option is used. Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhhhh;). However if the requested character is not available in the current font, it will be ignored with a warning message. Notes 1 Neither nor Examples The following illustrates setting up a background variable definition for use in running header/footer text:1 1. This variable definition corresponds with the default definition for the "Running H/F 3" variable defini- tion included in the set of FrameMaker templates included with the Frame product. Miramo Reference Guide [ v 9.2 ] R-79 Inline markup codes CHAPTER 3 A Alligators in Florida Cats in City Pandas in China produces a running header like that illustrated in Figure 3.20. Cats Page 2 (This assumes that the ‘Title’ Figure 3.20 Running header produced by Example 3.20 paragraph format used in Exam- ple 3.20 is set to start at the top of a page.) R-80 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use Syntax Option Value Description Background variable number fmt 1 - 12 Identifying number for the background ‘running text’ [ varNum ] variable. Twelve corresponding variable format definitions are always defined in a FrameMaker template file, as follows: Value FrameMaker variable name 1 ‘Running H/F 1’ 2 ‘Running H/F 2’ 3 ‘Running H/F 3’ n ‘Running H/F n’ Default:1 /> Required Notes 1 See the Miramo Reference Guide [ v 9.2 ] R-81 Inline markup codes CHAPTER 3 shown below, expressed using the equivalent Miramo Examples Example 3.19 on page R-80 illustrates using the R-82 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use code (see Note 1, on page R-86, for a list of the exceptions). Any text or inline code except the code, for example: .. Syntax Option Value Description Cell fill and color fill 0 - 15 Fill pattern. When used with the color name Background color. When used with the Cell border rulings lr name Left ruling. The ruling designations (left, right, top and [ leftRule ] bottom) are unaffected if the cell is rotated, ie. cell rotation using the ‘a’ option changes the orientation of the cell contents, not its edge rulings. Miramo Reference Guide [ v 9.2 ] R-83 Inline markup codes CHAPTER 3 Option Value Description name is the name of a ruling format in a referenced FrameMaker template, or defined using the tr name Top ruling. See ‘lr’ above. [ topRule ] rr name Right ruling. See ‘lr’ above. [ rightRule ] br name Bottom ruling. See ‘lr’ above. [ bottomRule ] Cell text and margin rotation a 0 | 270 | Orientation of text in cell. Rotation is clockwise. [ cellOrientation ] 90 | 180 Note that the placement orientation of cell rulings (as specified by the ‘lr’, ‘tr’, ‘rr’ and ‘br’ options) always remains fixed regardless of cell text orientation. Cell margins, as specified by both the Vertical alignment of cell text Ca T | M | B Cell vertical alignment of paragraph contents within cell: [ verticalTextAlign ] T = top of cell, M = middle of cell, B = bottom of cell. The orientation for ‘T’ (top) and ‘B’ (bottom) changes with cell rotation. For example, if Column and row span options cs int | R Horizontal (column) straddle. int is the number of columns to [ columnSpan ] straddle in this row, from this cell rightwards. Setting ‘cs’ to 1 has no effect. Setting ‘cs’ to 2 creates a horizontal span rightwards from the cell to the next cell, and so on. If ‘cs’ is set to R, all remaining columns in the row are straddled. Default: 1 (no straddle) R-84 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description rs int Vertical (row) span. Number of rows to straddle in this [ rowSpan ] column, from this cell down. Setting ‘rs’ to 1 has no effect. Setting ‘rs’ to 2 creates a vertical span downwards in the current column to the next row, and so on. The corresponding Cell margins (see Note 5, on page R-87) cm dim All cell margins, i.e. left, top, right and bottom, for all cells in [ allMargins ] table. Overrides the default margin specified in the table format, if any. If the ‘cm’ option is used in conjunction with any of the ‘clm’, ‘ctm’, ‘crm’ or ‘cbm’ cell margin options (see below), the latter will be ineffective unless it follows the ‘cm’ option. Default units are points. clm dim Cell left margin, for all cells in table. [ leftMargin ] Overrides the default left margin specified in the table format, if any. Default units are points. Text will not cross the left side of the cell when a negative dimension is given. ctm dim Cell top margin. [ topMargin ] Overrides the default top margin specified in the table format, if any. Default units are points. A negative top margin dimension may cause text to move above the top of the cell. crm dim Cell right margin. [ rightMargin ] Overrides the default margin specified in the table format, if any. Default units are points. Text will not cross the right side of the cell when a negative dimension is given. cbm dim Cell bottom margin. [ bottomMargin ] Overrides the default bottom margin specified in the table format, if any. Default units are points. A negative bottom margin dimension may cause text to move below the bottom of the cell. Miramo Reference Guide [ v 9.2 ] R-85 Inline markup codes CHAPTER 3 Option Value Description Metadata options IDstring string string may contain up to 512 bytes of metadata associated with this instance of the Cell code. This metadata is shown in FrameMaker MIF files in the Notes 1 All options may be used on the code options is shown on pages R-220–228. 2 A code. Thus either of the following: Bees please code precedes text in a R-86 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes 4 If a table row ends with one or more empty cells, no Examples Example 3.21 illustrates using the 1 Span 2 cols 8 Miramo Reference Guide [ v 9.2 ] R-87 Inline markup codes CHAPTER 3 The output from Example 3.21 is shown in Figure 3.21. Note Span 2 cols ABC that lower level codes override higher level codes. This is illus- trated by the code with ‘fcolor’ set to Fill3 Blue (see lines 6 and 7). In this context the code is at a Figure 3.21 Output from Example 3.21 lower level than the Fill3 Figure 3.22 Output from Example 3.21 (‘fmt’ set to none) R-88 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the Syntax Option Value Description Chapter file name file filename Required [ chapterName ] Name of document file (chapter) to create and add to current book. filename is either the basename of the file (in which case it may not contain the file path separator characters, ‘/’ or ‘\<#csq>) or the absolute (full path) name of the file. Relative file names are not allowed. 1. Using the Miramo Reference Guide [ v 9.2 ] R-89 Inline markup codes CHAPTER 3 Option Value Description Where the basename form of filename is given, the book chapter file filename is created in the directory which contains the FrameMaker book, specified using the ‘-Bfile’ command line flag (see page R-10), or the ‘Bfile’ option on the Chapter file type type STD | INC Specifies the type of document to be added to the book. [ chapterType ] | PDF When ‘type’ is set to STD the document data comes from the input stream following the Template options (All template options are ignored if the ‘type’ option is set to INC.) Cfile filename Copy all body pages and format specifications from filename [ tplCopyFile ] to the beginning of the current document. filename must be a FrameMaker document saved in MIF format. The ‘Cfile’ and ‘Tfile’ options are mutually exclusive: if both are used, the later option takes precedence over the earlier option. The ‘Cfile’ option differs from the ‘Tfile’ option in that the contents of the body pages are copied from the specified file, and all formatting specifications are always copied from the specified file. (The ‘Tflow’, ‘Tformats’ and ‘TXformats’ options are ignored). The ‘Cfile’ option takes precedence over the ‘-Cfile’ command line option (described in Chapter 2, ‘Running Miramo’, R-19). Default: from ‘-Cfile’ command line option Tfile filename Use filename as the source for formatting specifications. [ tplFile ] filename must be a FrameMaker document saved in MIF format. R-90 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description The ‘Cfile’ and ‘Tfile’ options are mutually exclusive: if both are used, the later option takes precedence over the earlier option. If neither the ‘Tformats’ nor the ‘TXformats’ option is used, then all formats in the template are imported. The ‘Tfile’ option takes precedence over the ‘-Tfile’ command line option (described in Chapter 2, ‘Running Miramo’, R-19). Default: from ‘-Tfile’ command line option Toverride N | Y Allow template format definitions to override Miramo format [ tplOverride ] definition code markup. Default: from ‘-Toverride’ command line option, or N if none given Tformats key Specify formats to be extracted from the template file given [ tplImportFormats ] with the ‘Tfile’ option. The formats to be included are specified by a key string comprising one or more characters from the following set: dcpflLRruvtkxTF The formats denoted by the key characters are described in Chapter 2 , ‘Running Miramo’ (see the description of the ‘-Tformats’ and ‘-TXformats’ command line options on page R-20). Note that the ‘F’ format flag copies text flow formats from text flow ‘A’ of the template file. To copy text flow formats from a different text flow, use the ‘Tflow’ option described below. Default: from ‘-Tformats’ command line option TXformats key Specify formats to be excluded from the template file given [ tplExFormats ] with the ‘Tfile’ option. The formats to be excluded are specified by a key string comprising one or more characters from the following set: dcpflLRruvtkxTF The formats denoted by the key characters are described in Chapter 2, ‘Running Miramo’ (see the description of the ‘-Tformats’ and ‘-TXformats’ command line options on page R-20). Default: from ‘-TXformats’ command line option Tflow name Set the name of the main textflow to name. Specific textflow [ textFlow ] attributes, for feathering, side-head settings and baseline synchronization, are as defined in a template file or by using the Miramo Reference Guide [ v 9.2 ] R-91 Inline markup codes CHAPTER 3 Option Value Description If there is no textflow name defined either in a referenced template file or within a Template image processing mode tplImode normal | If the ‘-tplImode’ command-line option is set to bypass, any bypass images in EPS, JPEG, PNG or TIFF format that are imported by reference in a template document or that are imported using the Volume numbering options The following options set up the VN Cont | How to compute volume number. [ volNum ] Same | Value Description File Cont Continue from previous book component. Aliases: cont, Continued and continued. Same Same as previous book component. File Read from file. If the ‘VN’ option is used, the ‘VNstyle’, ‘VNstring’ and ‘VNstart’ options are ignored. The default is determined by the ‘VNstyle’, ‘VNstring’ and ‘VNstart’ options. To restart numbering from 1, use the ‘VNstart’ option. VNstyle A | UA | Sets volume number style. [ volNumStyle ] LA | UR | Value Description LR | C A Arabic. UA Uppercase alpha. LA Lowercase alpha. UR Uppercase roman. LR Lowercase roman. C Custom. R-92 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description If ‘VNstyle’ is set to C the value of ‘VNstring’ is used for the VNstring string Set custom volume number string. [ volNumString ] ‘VNstring’ is ignored if the ‘VN’ option is used, Ignored unless ‘VNstyle’ is set to C. VNstart int Set volume number. [ volNumStart ] ‘VNstart’ is ignored if the ‘VN’ option is used, or if ‘VNstyle’ is set to C. Default:1 Chapter numbering options The following options set up the CN Cont | How to compute chapter number. [ chapNum ] Same | Value Description File Cont Continue from previous book component. Aliases: cont, Continued and continued. Same Same as previous book component. File Read from file. If the ‘CN’ option is used, the ‘CNstyle’, ‘CNstring’ and ‘CNstart’ options are ignored. The default chapter number is determined by the ‘CNstyle’, ‘CNstring’ and ‘CNstart’ options. To restart chapter numbering from 1, use the ‘CNstart’ option. CNstyle A | UA | Sets chapter number style. [ chapNumStyle ] LA | UR | Value Description LR | C A Arabic. UA Uppercase alpha. LA Lowercase alpha. UR Uppercase roman. LR Lowercase roman. C Custom. Miramo Reference Guide [ v 9.2 ] R-93 Inline markup codes CHAPTER 3 Option Value Description If ‘CNstyle’ is set to C the value of ‘CNstring’ is used for the CNstring string Set custom chapter number string. [ chapNumString ] ‘CNstring’ is ignored if the ‘CN’ option is used. Ignored unless ‘CNstyle’ is set to C. CNstart int Set chapter number. [ chapNumStart ] ‘CNstart’ is ignored if the ‘CN’ option is used, or if ‘CNstyle’ is set to C. Default:1 Page numbering options For setting up the document starting page number. N Cont | Specifies how to compute sequential page number values. [ pageNum ] Restart | Value Description File Cont Continue from previous book component (file). Both the numeric value and numbering style are derived from the previous document (chapter/file) in the book. The ‘Nstart’ option is ignored and document numbering styles set up within the file (template) are ignored. Aliases: cont, Continued and continued. Restart Restart using the value assigned to the ‘Nstart’ option, or 1 if the ‘Nstart’ option is not set. File Read value and numbering style from file (template). The ‘Nstart’ option is ignored. Default: Restart Nstyle A | UA | Sets page number style. [ pageNumStyle ] LA | UR | Value Description LR A Arabic. UA Uppercase alpha. LA Lowercase alpha. UR Uppercase roman. LR Lowercase roman. Default:A Nstart int Specifies a fixed numeric value, int, for the R-94 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Paragraph numbering options PN Cont | Paragraph numbering. [ pgfNum ] Restart | Value Description File Cont Continue. Aliases: cont, Continued and continued. Restart Restart from 1. File Read from file. Default: Restart Footnote numbering options FN PerPage | Specifies how to compute sequential footnote number values. [ FNoteNum ] PerFlow | Value Description Cont | File PerPage Restart footnote numbering on every page, using the value assigned to the ‘FNstart’ option, or 1 if the ‘FNstart’ option is not set. PerFlow Restart footnote numbering at the beginning of every flow, using the value assigned to the ‘FNstart’ option, or 1 if the ‘FNstart’ option is not set. Cont Continue from previous chapter. Both the numeric value and numbering style are derived from the previous chapter in the book. The ‘FNstart’ option is ignored and footnote numbering styles set up within the file (template) are ignored. Aliases: cont, Continued and continued. File Read value and numbering style from file (template). The ‘FNstart’ and ‘FNstyle’ options are ignored. Default: PerPage FNstyle A | UA | Sets footnote number style. If ‘FNstyle’ is set to C, characters [ FNoteStyle ] LA | UR | from the string value of ‘FNstring’ option (if set, see below) LR | C are used for custom footnote numbering. If ‘FNStyle’ is set to A, UA, LA, UR or LR, the (integer) value of the ‘FNstart’ option (see below) is used. Value Description A Arabic. UA Uppercase alpha. LA Lowercase alpha. UR Uppercase roman. LR Lowercase roman. C Custom. The ‘FNstyle’ option is ignored if the ‘FN’ option is set to Cont or File. Default:A Miramo Reference Guide [ v 9.2 ] R-95 Inline markup codes CHAPTER 3 Option Value Description FNstart int Specifies a fixed numeric value, int, for the footnote starting [ FNoteStart ] number or, if ‘FNstyle’ is set to C, specifies the character offset of the first character to be used from the custom footnote number string. The ‘FNstart’ option is ignored if the ‘FN’ option is set to Cont or File. (See Notes 6 and 7 , starting on page R-102). Default:1 FNstring string string is an array of characters to be used for a custom [ FNoteSymbols ] footnote numbering sequence (see Note 6 on page R-102). The ‘FNstring’ option is effective only ‘FNstyle’ option is set to C (custom) and the ‘FN’ option is set to PerPage or PerFlow. Table footnote numbering options TFN Restart | Specifies how to compute sequential table footnote number [ tblFNoteNum ] File values. Value Description Restart Restart table footnote numbering using the values specified by the ‘TFNstyle’ option, or its default. File Read footnote numbering style from file (template). Default: Restart TFNstyle A | UA | Sets footnote number style. If ‘TFNstyle’ is set to C, the value [ tblFNoteStyle ] LA | UR | of the ‘TFNstring’ option, or its default, is used for the table LR | C footnote numbering style. (See Notes 6 and 7 , starting on page R-102). Value Description A Arabic. UA Uppercase alpha. LA Lowercase alpha. UR Uppercase roman. LR Lowercase roman. C Custom. The ‘TFNstyle’ option is effective only if the ‘TFN’ option is set to Restart. Default:A TFNstring string string is an array of characters to be used for sequential table [ tblFNoteSymbols ] footnote numbering (see Note 6 on page R-102). Ignored if the ‘TFNstyle’ option is set to C or the ‘TFN’ option is set to File. Default: "* \e0 " R-96 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Page starting side StartSide Left | Starting page side. [ startSide ] Right | Value Description Next | File Left Left page. Right Right page. Next Next available side. File Read from file. The ‘StartSide’ option is ignored (the starting page side is always ‘Right’) unless the document is set to be double- sided, either by importing document formats from a double- sided template file1 or, if the ‘type’ option is set to STD, by setting the Pre- and post-processing options print Y | N Include this chapter file in the list of files to be printed. [ printThisFile ] Default:Y PDF file import The following options are ignored unless the ‘type’ option (see page R-90) is set to PDF. pdfFile filename filename is the name of a PDF file to include as this chapter in [ pdfFilename ] the book. pdfL dim Left offset of left edge of included PDF document from left of [ pdfLeftMargin ] page. Default:0 pdfT dim Top offset of top edge of included PDF document from top of [ pdfTopMargin ] page. Default:0 pdfW dim Width of included PDF document. [ pdfWidth ] If neither the ‘pdfW’ option nor the ‘pdfScale’ option is set, the width of the included PDF document is unchanged from its original size unless the ‘pdfH’ option is set, in which case the width of the included PDF document is set to the height of the included PDF document times its aspect ratio. pdfH dim Height of included PDF document. [ pdfHeight ] If neither the ‘pdfH’ option nor the ‘pdfScale’ option is set, the height of the included PDF document is unchanged from its original size unless the ‘pdfW’ option is set, in which case the height of the included PDF document is set to the width of the included PDF document divided by its aspect ratio. Miramo Reference Guide [ v 9.2 ] R-97 Inline markup codes CHAPTER 3 Option Value Description pdfScale percent Scale the width and height of the included PDF document. The ‘pdfScale’ option is ignored if either the ‘pdfW’ option or the ‘pdfH’ option is set. pdfStart int The number of the first page in the PDF document to include. [ pdfStartPageNum ] If the value given to ‘pdfStart’ is greater than the number of pages in the PDF file, the last page in the file is assumed. The first page in a PDF document is always 1. Default:1 pdfEnd int The number of the last page in the PDF document to include. [ pdfEndPageNum ] If the value given to ‘pdfEnd’ is greater than the number of pages in the PDF file, the last page in the file is assumed. Default: last page in PDF document pdfDS N | Y Set to Y to include PDF document as double-sided. Ignored [ pdfDoubleSided ] unless the ‘type’ option is set to PDF (see page R-90). Default:N Specify PDF bookmark hierarchy config filename file is name of a configuration file specifying Acrobat [ configFile ] bookmark levels. See the section entitled Controlling bookmark levels using a ‘config’ file in ‘Running Miramo’, on page R-34, for a description of how to set up a bookmark configuration file. Default: from the command line, if the ‘-config’ command line option is used (see page R-15). Operating mode options stripInput N | tab | Enable special processing of text containing binary tab, nl | all newline and carriage return characters. Value Description N No action (default). tab Strip occurrences of the character U+0009, HORIZONTAL TABULATION, from input text content. (By default binary tab characters are treated as printable tab characters.) Binary tab control characters may be included using the R-98 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description See the ‘-stripInput’ command line option on page R-8 for further details. Default: As per the ‘-stripInput’ command line option (see page R-8), or N if not set. imageCache N | Y Enable image caching when the tENC utf-8 | Specify the default document text processing mode. The [ textEncoding ] wcp-1252 option values may be in either uppercase or lowercase. See | us-ascii | the description of the ‘-tENC’ command line option on page iso-8859-1 R-9 for details. Default: utf-8 userapi string Name of user API client to run prior to print/save. See the ‘-userapi’ command line option on page R-21. Default: from -userapi command line option > Required Miramo Reference Guide [ v 9.2 ] R-99 Inline markup codes CHAPTER 3 Option Value Description Optional A 1. See the ‘-Tfile’ and ‘-Cfile’ command line options on page R-19, and the Notes 1 The process of generating a book file from input data containing embedded Only a restricted set of R-100 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes An alternative method of miramo -Bfile abc.book -Tfile abc.tpl -Opdf abc.pdf Report on the Nature of the Universe Albert Peacock er.fm October 28th. 2004 TOC.fm er.fm When did it all start? TOC.fm The evidence on this question p1.fm is highly confusing, not to say contradictory. A TOC.fm How will it continue? p1.fm Here we create an ordinary file called chap2.fm p2.fm which uses its own special template file ‘different.mif’ ------ TOC.fm APPENDIX 1 p1.fm If you are adding an Appendix you will probably want many special settings. p2.fm For example to restart page numbering set the N=”R” option. x1.fm It makes sense to reset paragraph numbers also, using PN=”R”. ------er.fm ------TOC.fm p1.fm DX.fm INDEX This text will appear at the beginning of the generated index document. The other paragraphs in the document are taken from index (fmt=Index) marker entries inserted in the chapters of the book using e book and print (occurs automatically) Figure 3.23 Basic usage of the Miramo Reference Guide [ v 9.2 ] R-101 Inline markup codes CHAPTER 3 the ‘Cfile’ option provides a limited form of mail-merge capability (variable definitions may be a maximum of 255 characters in length). 4 With the exception of the 5 Format definitions included at the component files. If all files should use additional markup & text, etc the same format definitions then these . . . each definitions which should be applied to additional markup & text, etc . . . each chapter in the book. The above markup can be made less cumbersome Example 3.24 Including format definition codes by encapsulating it within a mmpp macro. miramo -Bfile world.book -Tfile world.mif world.in Example 3.25 Command line for Example 3.24 6 The ‘FNstring’ option, described on page R-96, is used to specify an array, or circular list, of characters to be used as custom footnote identifiers. When there are more footnotes on the page or in the flow than the number of characters in the array footnote numbering begins again at the first character in the array, this time using two instances of the character to number the footnote. This cycle is repeated until all footnotes have been assigned a unique identifying string. For example, if the ‘FNstyle’ option (see page R-95) is set to C (for custom) and the ‘FNstring’ option (see page R-96) is set to ‘AB’, successive footnotes will be labeled as follows: A, B, AA, BB, AAA, BBB, AAAA, etc. 7 The ‘FNstart’ option (see page R-96) specifies the starting position for the first footnote identifying string. For example, in the case of custom footnotes, if the ‘FNstyle’ option is set to C (for custom), the ‘FNstring’ option is set to ‘AB’ and the ‘FNstart’ option is set to 2, successive footnotes will be labeled as follows: B, AA, BB, AAA, and so on. If the ‘FNstart’ option is set to 8 in the previous R-102 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes example, successive footnotes will be labeled as follows: AAAA, BBBB, AAAAA, and so on. Table footnotes always start at 1, or the equivalent in another style (see the ‘TFNstyle’ option on page R-96), or with the first character in a custom table footnote string. Examples Example 3.26 shows the simplest possible Using the stream. In Example 3.28 the additional markup & text, etc . . . additional markup & text, etc . . . file. Miramo Reference Guide [ v 9.2 ] R-103 Inline markup codes CHAPTER 3 It is easy to include front matter, back matter and automatically generated docu- ments within books. This is illustrated in Example 3.29. In Example 3.29 the same variable definitions are repeated after each All variable definitions, as tions, need to be repeated in this way. In such situations it Then the input shown in Example 3.29 could be simplified to look like that shown in Example 3.31. <|SetEd> 3 <|Chapter> A <|Chapter> B Example 3.31 Simplified input, using mmpp R-104 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary The Syntax Description ... any text and data Required Every Notes 1 Miramo Reference Guide [ v 9.2 ] R-105 Inline markup codes CHAPTER 3 Summary Use the Syntax Description ... any text or mark-up codes
Any of the strings
,
,
and
inserts a hard return in the output.
LINE FEED
LINE SEPARATOR
Inserts hard return in definition text.
Inserts hard return in definition text.
Notes 1 The markup pair may be used in place of
Examples The following is an example of using comments:
R-106 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes
Summary
Use the
Syntax
Option Value Description
Apply condition(s) fmt namelist Required [ conditionName ] names is a comma separated list of condition tag(s) to be applied. The tags may have been set up within the definitions section using the Notes 1 The Miramo Reference Guide [ v 9.2 ] R-107 Inline markup codes CHAPTER 3 3 Spaces within the comma separated list of tag names are included as part of the tag name, thus the following Miramo code: Examples Conditional text may be used to produce several different versions of a document, such as a US-English or UK-English language version of a manual which contains classified (Top Secret) information. The example below shows how the word ‘color’ (or ‘colour’) could be tagged as ‘US’ or ‘UK’ conditional text as appropriate for the country of distribution using inline markup codes. The second paragraph is marked as conditional in ‘Top Secret’ using the R-108 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes color=Magenta /> The use of Classified information ... Procedure for lowering lifeboats Life jackets will ... Example 3.32 Making text conditional The output from Example 3.32 is shown in Figure 3.24. The use of color is effective in highlighting different escape routes within the vessel. Procedure for lowering lifeboats Life jackets will ... Figure 3.24 Output from Example 3.32 Miramo Reference Guide [ v 9.2 ] R-109 Inline markup codes CHAPTER 3 Summary Use the Syntax Option Value Description Date format fmt ldate | Identifying label for the date format. [ dateFormat ] sdate | Six corresponding date format definitions are always defined lmdate | in a FrameMaker template file, as follows: smdate | lcdate | Value FrameMaker variable name scdate ldate ‘Current Date (Long)’ sdate ‘Current Date (Short)’ lmdate ‘Modification Date (Long)’ smdate ‘Modification Date (Short)’ lcdate ‘Creation Date (Long)’ scdate ‘Creation Date (Short)’ Default: ldate /> Required R-110 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the and Syntax Description command ?> Required . Notes 1 A inline code may be placed anywhere within a Miramo data stream. 2 A common use for is to supply data to an external formatter which can process data into forms unavailable in Miramo itself. Possible examples are for formatting equations and for business and scientific charts. 3 If the output from the code is a graphic image intended for import into the current document, the best results are usually achieved by directing the external formatter's output to Encapsulated PostScript. Miramo Reference Guide [ v 9.2 ] R-111 Inline markup codes CHAPTER 3 4 If Miramo is run with the ‘-m’ option, then all mmpp codes will be processed prior to the data being diverted to the external formatter. In this way it is possible to use standard templates, or configuration formats, required by the external formatter using the mmpp <@include> code. 5 The following example gives an XSLT stylesheet fragment which illustrates how a processing instruction might be constructed using an XSLT stylesheet template: Examples The following, Example 3.33, copies the text contained within the In Example 3.33 the text between R-112 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the Syntax Option Value Description Single document output All, or any subset of, the following may be used concurrently. Ofm filename Name of FrameMaker binary document to create. [ fmFile ] Omif filename Name of FrameMaker MIF (Maker Interchange Format) [ MIFFile ] document to create. Oviewfm filename Name of locked (view-only) FrameMaker binary document to [ fmViewFile ] create. Oviewmif filename Name of locked (view-only) FrameMaker MIF (Maker [ mifViewFile ] Interchange Format) document to create. Ortf filename Name of RTF file to create. [ rtfFile ] Miramo Reference Guide [ v 9.2 ] R-113 Inline markup codes CHAPTER 3 Option Value Description Ortfj filename Name of RTF file to create, using Japanese filter version. [ rtfFileJ ] Ohtml filename Name of HTML file to create. [ htmlFile ] Oxml filename Name of XML file to create. [ xmlFile ] PDF output options Opdf filename [ , pname ] Name of PDF file to create. On NT only, filename may optionally be followed by a comma and then the name, pname, of the printer driver to be used. See Note 8 on page R-123. Opdfx filename [ , pname ] Name of PDF file to create. filename will contain no hypertext links. (Output files will be smaller than those created using the ‘Opdf’ option, and production will be faster.) On NT only, filename may optionally be followed by a comma and then the name, pname, of the printer driver to be used. See Note 8 on page R-123. Pmulti key | Output a PDF file or a PostScript file, or both, for each key+key printable chapter in a book. (See the ‘print’ option on the R-114 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description In the second form, key+key, one key value may be pdf or pdfx and the other key value may be aps or ps. key+key values such as "ps+aps" or "pdfx+pdf" are not effective. The ‘Pmulti’ option is effective only if used with the ‘Bfile’ option. The ‘Pmulti’ option may be used in combination with the ‘Opdf’ option, ‘Opdfx’ option, ‘PAfile’ option, or the ‘Pfile’ option. In this case a single PDF output file or a single PostScript file, or one of each, will be produced for the entire book, in addition to a PDF or PostScript file, or both, per printable chapter. PDFmode normal | Method to use for creating PDF file. saveAs Setting the ‘PDFmode’ option to normal distills the temporary PostScript file in a single pass. Setting the ‘PDFmode’ option to saveAs uses the FrameMaker ‘Save As’ method. The ‘PDFmode’ option must be set to saveAs to include .U3D or .SWF files. If ‘PDFmode’ is set to saveAs, the ‘PDFjobopts’ option must use the ‘+’ style of PDF joboptions file referencing. If the ‘PDFcmyk’ option is set to Y the value of ‘PDFmode’ is forced to saveAs. The ‘PDFmode’ option is not effective when running with versions of FrameMaker prior to version 9. See the ‘-PDFmode’ command line option on page R-14. Default: normal, unless forced to saveAs by setting the ‘PDFcmyk’ option to Y. PDFcmyk N | Y Specify CMYK color model in PDF output. Setting the ‘PDFcmyk’ option to N creates RGB PDF output. Setting the ‘PDFcmyk’ option to Y creates CMYK PDF output. If the ‘PDFcmyk’ option is set to Y the value of ‘PDFmode’ is forced to saveAs. The ‘PDFcmyk’ option is not effective when running with versions of FrameMaker prior to version 9. See the ‘-PDFcmyk’ command line option on page R-14. Default: N PDFjobopts file | Change the .joboptions file used for PDF output for a job. file file,file is name of file containing job options settings. If file contains one or more spaces, file must be surrounded by double quotes, "file name". On Windows a PDF joboptions file must always have a ‘.joboptions’ suffix. If file does not have a ‘.joboptions’ suffix, the suffix is silently assumed. For example, if the file value of the ‘PDFjobopts’ option is set to ‘foo’ this is taken as a shorthand for ‘foo.joboptions’. Miramo Reference Guide [ v 9.2 ] R-115 Inline markup codes CHAPTER 3 Option Value Description In the second form, file,file, the file following the comma separator is the name of file containing job options settings to use when creating separate PDF output for each chapter in a book, if different settings are required to the settings used when outputting the book as a single PDF file. This form is effective only if a ‘-Pmulti’ option is used (see pages R-13 and R-454). See also the ‘-PDFjobopts’ option on page R-14. For further notes and guidance relating to .joboptions files see section PDF .joboptions files (Windows only) on page R-32. PDFbookmarks Default | Set bookmark display in output PDF document. All | None See the ‘-PDFbookmarks’ command line option on page R-15 | int for a description of the option values. Default: From template, if specified, otherwise Default PDFview Page | Set PDF document view on opening. Default | See the ‘-PDFview’ command line option on page R-15 for a Width description of the option values. Default: Page PDFthread N | F | C Set PDF article threads. See the ‘-PDFthread’ command line option on page R-15 for a description of the option values. Default:N PDFopenpage int Set page to display on opening the PDF document. Default:1 PDFpdests N | Y Create a named destination for every paragraph (slow). Default:N PDFtagged N | Y Create ‘Tagged’ PDF (slow). Default:N PDFpnames N | Y Include paragraph tags in bookmark text during Acrobat PostScript file generation. Ignored unless the ‘PAfile’, ‘Opdf’ or ‘Opdfx’ options are used. Printing and print file output options P N | Y Print to default printer. [ Print ] Default: from ‘-P’ command line option, if set, or N Pdefault name Set the default printer to printer named name for this job. [ defaultPrinter ] Applicable when producing PostScript or PDF output. name must be surrounded by double quotation marks if the printer name contains spaces. R-116 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Setting the default printer on a per-job basis should be avoided when high throughput is important. Default: from ‘-Pdefault’ command line option, if set Pname name Print to printer name. [ printerName ] Default: from ‘-Pname’ command line option, if set Pfile filename [, pname ] [ printFile ] Print to named PostScript file. On NT only, filename may optionally be followed by a comma and then the name, pname, of the printer driver to be used. See Note 8 on page R-123. PAfile filename [, pname ] [ printAFile ] Print to named PostScript file, with Acrobat support. Pcopies int Number of copies to be printed. Default: from ‘-Pcopies’ command line option, if set, or 1 On NT only, filename may optionally be followed by a comma and then the name, pname, of the printer driver to be used. See Note 8 on page R-123. Pscale percent Scale document to given percentage before printing. Default: from -Pscale command line option, if set, or 100 Preg D | N | W | Print registration and crop marks. [ printCropMarks ] T Value Description D Default, i.e. as set in template document, if any. N No registration marks. This is the default if there is no template document. W Western registration marks T Tombo registration marks Default: from ‘-Preg’ command line option, if set, or D or N Pstartpage int Print file starting from given page number. The page number refers to the page number variable which may appear on the printed page, not the sheet number within the output document. Default: first page in the document Pendpage int Print file starting ending at given page number. The page number refers to the page number variable which may appear on the printed page, not the sheet number within the output document. Default: last page in the document Miramo Reference Guide [ v 9.2 ] R-117 Inline markup codes CHAPTER 3 Option Value Description Pstartno int Print file starting from given pagecount. The pagecount refers to the sequential sheet number within the file, with the first page numbered as 1, not to the page numbers which may be printed in the document. Default:1 Pendno int Print file ending at given pagecount. The pagecount refers to the sequential sheet number within the file, with the first page numbered as 1, not to the page numbers which may be printed in the document. Default: last page in the document Ppapersize default | Select printer paper size either using a paper size code such as pagesize | a4, or by specifying a custom papersize width and height a3 | a4 | using the form WuHu, for example ‘9cm20cm’ or a5 | b5 | ‘210mm10in’. Note that a custom papersize code may not tabloid | include any spaces. legal | See the description for the ‘-Ppapersize’ command line letter | option, on page R-17, for more details. WuHu Default: default PpageOrder F | L Print first page first Default: F if ‘-PpageOrder’ command line option is not used, or as per ‘-PpageOrder’ command line option (see page R-18). Pseps N | Y Print document in 4 CMYK color separated versions. [ separations ] Default: N unless ‘-Pseps’ command line option is used (see page R-18). Pskipblanks N | Y Suppress printing of blank pages within document. [ printNoBlanks ] Default: N unless ‘-Pskipblanks’ command line option is used (see page R-18). Pfonts none | Fonts to embed in PostScript output. (Unix only) [ printFonts ] x13 | x35 Value Description | all | none No included fonts (default). Asian x13 All except ‘Standard 13’ and Asian fonts. x35 All except ‘Standard 35’ and Asian fonts. all All fonts except Asian fonts. Asian Only Asian fonts. Default: none, unless ‘-Pfonts’ command line option is used (see page R-16). Template options Cfile filename Copy all body pages and format specifications from filename [ tplCopyFile ] to the beginning of the current document. filename must be a FrameMaker document saved in MIF format. R-118 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description The ‘Cfile’ and ‘Tfile’ options are mutually exclusive: if both are used, the later option takes precedence over the earlier option. The ‘Cfile’ option differs from the ‘Tfile’ option in that the contents of the body pages are copied from the specified file, and all formatting specifications are always copied from the specified file. (The ‘Tflow’, ‘Tformats’ and ‘TXformats’ options are ignored). The ‘Cfile’ option takes precedence over the ‘-Cfile’ command line option (described in Chapter 2, ‘Running Miramo’, R-19). Default: from ‘-Cfile’ command line option Tfile filename Use filename as the source for formatting specifications. [ tplFile ] filename must be a FrameMaker document saved in MIF format. The ‘Cfile’ and ‘Tfile’ options are mutually exclusive: if both are used, the later option takes precedence over the earlier option. If neither the ‘Tformats’ nor the ‘TXformats’ option is used, then all formats in the template are imported. The ‘Tfile’ option takes precedence over the ‘-Tfile’ command line option (described in Chapter 2, ‘Running Miramo’, R-19). Default: from ‘-Tfile’ command line option Toverride N | Y Allow template format definitions to override Miramo format [ tplOverride ] definition code markup. Default: from ‘-Toverride’ command line option, or N if none given Tformats key Specify formats to be extracted from the template file given [ tplImportFormats ] with the ‘Tfile’ option. The formats to be included are specified by a key string comprising one or more characters from the following set: dcpflLRruvtkxTF The formats denoted by the key characters are described in Chapter 2 , ‘Running Miramo’ (see the description of the ‘-Tformats’ and ‘-TXformats’ command line options on page R-20). Note that the ‘F’ format flag copies text flow formats from text flow ‘A’ of the template file. To copy text flow formats from a different text flow, use the ‘Tflow’ option described below. Default: from ‘-Tformats’ command line option Miramo Reference Guide [ v 9.2 ] R-119 Inline markup codes CHAPTER 3 Option Value Description TXformats key Specify formats to be excluded from the template file given [ tplExFormats ] with the ‘Tfile’ option. The formats to be excluded are specified by a key string comprising one or more characters from the following set: dcpflLRruvtkxTF The formats denoted by the key characters are described in Chapter 2, ‘Running Miramo’ (see the description of the ‘-Tformats’ and ‘-TXformats’ command line options on page R-20). Default: from ‘-TXformats’ command line option Tflow name Set the name of the main textflow to name. Specific textflow [ textFlow ] attributes, for feathering, side-head settings and baseline synchronization, are as defined in a template file or by using the Template image processing mode tplImode normal | If the ‘-tplImode’ command-line option is set to bypass, any bypass images in EPS, JPEG, PNG or TIFF format that are imported by reference in a template document or that are imported using the Book options Bfile filename Specify name of book file to be created. By convention a book [ bookName ] file name has the suffix ‘.book’, but any valid filename may be used. The ‘Bfile’ option cannot be used with any of the following R-120 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Bappend N | Y N = create a new book file, Y = add to existing book file created by Miramo. Default:N Bupdate Y | N | OQ Set book update mode. | OS Value Description Y Update book chapters and book file, starting with closed book chapters. N No book update. OQ Same as Y above, except that all chapters in the book are opened before updating, and all changes to the chapters and book file after the update are unsaved. OS Same as OQ above, except that all changes to the chapters in the book and the book file that result from the update are saved. See the -Bupdate command-line option on page R-10 for more details. Default:Y Bremove N | Y Remove (delete) a book file and its component documents [ deleteBook ] when finished processing. ‘Brm’ is an alias for ‘Bremove’. See the ‘-Bremove’ command line option, on page R-11. Default: N (see page R-11). Specify PDF bookmark hierarchy config filename file is name of a configuration file specifying Acrobat [ configFile ] bookmark levels. See the section entitled Controlling bookmark levels using a ‘config’ file in ‘Running Miramo’, on page R-34, for a description of how to set up a bookmark configuration file. Default: from the command line, if the ‘-config’ command line option is used (see page R-15). Operating mode options stripInput N | tab | Enable special processing of text containing binary tab, nl | all newline and carriage return characters. Value Description N No action (default). tab Strip occurrences of the character U+0009, HORIZONTAL TABULATION, from input text content. (By default binary tab characters are treated as printable tab characters.) Binary tab control characters may be included using the Miramo Reference Guide [ v 9.2 ] R-121 Inline markup codes CHAPTER 3 Option Value Description nl Strip occurrences of ‘newline characters’, U+000A, LINE FEED (Unix), or adjacent U+000D, CARRIAGE RETURN and U+000A characters (Windows NT), from input text content. all As for tab and nl values above. See the ‘-stripInput’ command line option on page R-8 for further details. Default: As per the ‘-stripInput’ command line option (see page R-8), or N if not set. imageCache N | Y Enable image caching when the tENC utf-8 | Specify the default document text processing mode. The [ textEncoding ] wcp-1252 option values may be in either uppercase or lowercase. See | us-ascii | the description of the ‘-tENC’ command line option on page iso-8859-1 R-9 for details. Default: utf-8 R-122 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description userapi string Name of user API client to run prior to print/save. See the ‘-userapi’ command line option on page R-21. Default: from -userapi command line option > Required Notes 1 Hundreds of thousands of Miramo Reference Guide [ v 9.2 ] R-123 Inline markup codes CHAPTER 3 printer used is the printer set as the default for the processing channel group that processes the job, or the printer named using the ‘-Pdefault’ command line option (see page R-16), or the printer name qualifier appended to the output filename given to the ‘Opdf’, ‘Opdfx’, ‘Pfile’and ‘PAfile’options, as follows: If the filename value is followed by a comma and then by a pname string then Miramo will use the driver associated with the printer pname to format the output document. For example: Examples Example 3.34 illustrates simple 1 Hello Hello Hello If the input shown in Example 3.34 is contained in a file, e.g. hellos.mm, and the following command is run: miramo -batch -PDFbookmarks None -config bookmarks hellos.mm then three PDF output documents will be produced. The second document, 2.pdf, will show bookmarks in PDF viewer applications. The other two docu- ments, 1.pdf and 3.pdf, will have no bookmarks. Example 3.35 produces identical output to Example 3.34. 1 2 Hello Hello Hello R-124 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes If the input shown in Example 3.35 is contained in a file, e.g. hellos.mmxml, and the following command is run: miramo -batch hellos.mmxml then three PDF output documents will be produced as before: the second docu- ment, 2.pdf, will show bookmarks in PDF viewer applications; the other two doc- uments, 1.pdf and 3.pdf, will have no bookmarks. The 1 @------2 @- file: invXmacs.mmp 3 @------4 <@xmacro> newDoc { 5 <#ifndef> fn 10000 @- Initialize file name counter 6 <#def> fn @eval(<#fn> + 1) @- Increment file name counter 7 @- 8 Example 3.37 illustrates an example of the batch input that may be used in con- junction with the macro shown in Example 3.36. 1 Hello Hello Hello Running the command shown in Example 3.38 mmpp -Mfile invXmacs.mmp invBatch_14193.in > invBatch_14193.mm Example 3.38 mmpp command line writes the output shown in Example 3.39 to the file invBatch_14193.mm. Hello Miramo Reference Guide [ v 9.2 ] R-125 Inline markup codes CHAPTER 3 Hello Hello Finally, the contents of the file invBatch_14193.mm, created via the command shown in Example 3.38 may be converted to PDF output files using the command shown in Example 3.40. miramo -batch -Tfile invTemplate.mif -PDFjobopts mmStd invBatch_14193.mm Example 3.40 Miramo batch command line Note that Examples 3.36 through 3.40 illustrate a two-pass process. Two-pass processing is the only way to process R-126 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the Syntax Option Value Description fmt name Apply master page from a FrameMaker template file or a [ masterPage ] master page defined using the P A | B Placement rule for new page. A = After, B = Before any page [ pagePosition ] containing 1. However this master page layout can have any number of fixed, background text frames as well as graphics, imported images, etc. All the text in these text columns, as well as the other objects on the page, will be reproduced in the output disconnected page. This master page layout may also include one or more text frames autoconnected to the main text flow. In this case, that is when this master page layout is applied to a disconnected page, nothing will be contained within these text frames on output. Miramo Reference Guide [ v 9.2 ] R-127 Inline markup codes CHAPTER 3 Option Value Description oddP B | A Placement rule for new page, when the evenP A | B Placement rule for new page, when the Notes 1 The order of the ‘P’, ‘oddP’ and ‘evenP’ options is significant - later options take precedence over earlier ones, so that the following: 2 The special page name ‘Default’ may be used with the ‘fmt’ (master page name) option to apply default ‘Right’ or ‘Left’ page layouts to the new disconnected page. The default page layouts applied to new pages within a Miramo document depend on whether the document is single or double-sided, and whether the document ‘starting page side’ property is ‘Right’ or ‘Left’. ‘Odd numbered pages’ refer to odd numbered pages (i.e. 1,3,5... ), where pages are numbered sequentially starting at ‘1’ for the first page in the document. ‘Even numbered pages’ refer to even numbered pages (i.e. 2,4,6,8 ...) where pages are numbered sequentially starting at ‘1’ for the first page in the document. If the document is single-sided, the default page layout used for both odd and even numbered pages is the ‘Right’ master page layout. R-128 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes If the document is double-sided, and the starting page side is ‘Right’, then the ‘Right’ master page is applied to odd numbered pages, and the ‘Left’ master page is applied to even numbered pages. If the document is double-sided, and the starting page side is ‘Left’, then the ‘Left’ master page is applied to odd numbered pages, and the ‘Right’ master page is applied to even numbered pages. Miramo Reference Guide [ v 9.2 ] R-129 Inline markup codes CHAPTER 3 Summary Use the Syntax Description Notes 1 An Examples Example 3.41 illustrates using the "All right now you boys, clear off. Go on home, or somewhere." Nick shoved the Terminator away from the stove. Example 3.41 Using the The output from Example 3.41 is shown in Fig- "All right now you boys, ure 3.25. clear off. Go on home, or somewhere." Figure 3.25 Output from Example 3.41 R-130 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the Syntax Option Value Description File name format fmt long | Identifying label for the file name format. [ filenameFormat ] short Two corresponding file name format definitions are always defined in a FrameMaker template file, as follows: Value FrameMaker variable name long ‘Filename (Long)’ short ‘Filename (Short)’ /> Required Miramo Reference Guide [ v 9.2 ] R-131 Inline markup codes CHAPTER 3 Summary Use the codes. Syntax Option Value Description Reference pre-defined paragraph format fmt name name is optional paragraph format name (overrides the [ pgfFormat ] default footnote paragraph format). All code options may be used with code options on pages R-220–228). Note however that the code pagination options ‘P’, ‘TCN’, ‘Pf’, ‘rhp’, ‘wo’, ‘wn’ and ‘wp’ have no effect when used with code, then the ‘fmt’ option and any other code options on the space Y | N If set to Y, then a single space is output after the footnote [ spaceAfter ] indicator. Set ‘space’ to N to suppress post footnote space (see Note 4 on page R-133). Default: Y > Required R-132 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Notes 1 A footnote cannot contain a footnote. 2 A footnote cannot contain a codes ahead of individual footnote paragraphs (see Example 3.43 on page R-134). 7 Footnotes may contain cross-references and hypertext links to destinations anywhere within a document or book (see Example 3.44, line 12, on page R- 135). Footnotes may also contain cross-reference and hypertext destinations, accessible from anywhere within a document or book (see Example 3.44, lines 5, 15, 16, 21, 23 and 24, on page R-135). 8 If a footnote starts with a code, then all Footnote text Footnote text Miramo Reference Guide [ v 9.2 ] R-133 Inline markup codes CHAPTER 3 This is because the code immediately following the Examples Example 3.42 contains a simple illustration of using the 1 2 Saturday 3 Custom formatting of footnote paragraphs is illustrated in Example 3.43. 1 2 Greeking is used for layout purposes only. Footnotes 3 5 Footnote paragraphs can be left aligned ... 6 7 ... centered, or ... 8 9 right aligned ... or formatted any way. 10 Example 3.43 produces output like that Greeking is used for layout purposes only. shown in Figure 3.26. Footnotes1 can be added to body text or table cell text. Multiple references to a footnote The ‘Tips and Tricks’ code shown in Example 3.45 and the text and foot- 1. Footnote paragraphs can be left aligned ...... centered, or ... notes in Figure 3.27 illustrate how to right aligned ... or formatted any way. use cross references to implement mul- tiple references to a single footnote and Figure 3.26 Output from Example 3.43 to make cross references between footnotes. The input markup shown in Example 3.45 uses the two cross reference formats defined in Example 3.44. 1 R-134 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes 5 The cross-reference format definitions shown in Example 3.44 are used to refer- ence footnote numbers and their page numbers (see lines 5, 15, 16, 21, 23 and 24 in Example 3.45). 1 2 3 Footnote Tips and Tricks 9 10 To reference an existing footnote 20 There is also a footnote The output from Example 3.45 is shown in Figure 3.27. Miramo Reference Guide [ v 9.2 ] R-135 Inline markup codes CHAPTER 3 To enable multiple refer- Footnote Tips and Tricks1 a hidden cross-reference marker, ences to the same foot- with ‘fn.max_docsize’ as its link To reference an existing footnote2 text. Here are two more footnotes, note, a 1 Further examples of using footnotes are included in the Examples section of the 1. This is a footnote containing a table, created using the R-136 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary The code may be used to control the appearance of text elements within paragraphs. Settable text attributes include style, size, position, emphasis type, inter-character spacing and color. codes, unlike other inline codes, may be nested to any depth when used in normal paragraph text (i.e. codes operate analogously with a LIFO stack). Syntax Option Value Description Reference pre-defined font format fmt name Font format name. name is the name of a font format defined [ fontFormat ] either in a template file using the Character Designer in a FrameMaker template file or by using the Font selection ff name Font family. [ fontFamily ] E.g. the following The next word is Helvetica and ... produces: The next word is Helvetica and ... fa name Font angle. [ fontAngle ] E.g. the following Some italic text ... produces: Some italic text ... Miramo Reference Guide [ v 9.2 ] R-137 Inline markup codes CHAPTER 3 Option Value Description fw name Font weight. [ fontWeight ] Some bold text ... produces: Some bold text ... fv name Font variation. [ fontVariation ] E.g. the following Some text in the Helvetica-Narrow variation produces: Some text in the Helvetica-Narrow variation Alternatively, the following Some text in the Helvetica-Narrow variation also produces: Some text in the Helvetica-Narrow variation Text size and color p dim | Text size. See Note 1 on page R-142. [ textSize ] rdim Default units are points (1/72 inches). An rdim value may have any of the following forms: +20%, 120%, 85%, -4%, +dim and -dim (e.g. +2pt, -1mm). A relative text point size, rdim, value may only be used when the ‘-tENC’ command line option (R-9), or the corresponding option on the fcolor name Font color. [ textColor ] E.g. the following Today is a Red letter day ... produces: Today is a Red letter day ... Underline and overline uline N | S | D | Underline style. [ textUnderline ] M Value Description N No underline. S Single (normal) underline. D Double underline. R-138 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description M Numeric (low) underline. E.g. the following single underline double underline o N | Y Overline. E.g. overline [ textOverline ] Default:N Strike through and change bar t N | Y Strike through. E.g. strike through [ strikeThrough ] Default:N C N | Y Change bar. E.g. change bar [ changeBar ] Default:N Capitalization fc T | S | L | Capitalization. [ textCase ] U Value Description T As typed. S Small caps. L Lower case. U Uppercase. E.g. this input Small caps Small caps Small caps Small caps produces: Small caps SMALL CAPS small caps SMALL CAPS Default:T Vertical and horizontal shift u N | Y Superscript. E.g. superscript [ superscript ] Default:N d N | Y Subscript. E.g. subscript [ subscript ] Default:N Miramo Reference Guide [ v 9.2 ] R-139 Inline markup codes CHAPTER 3 Option Value Description Ky percent Vertical displacement of text. [ vertShift ] percent is the required text downshift expressed as a percentage of an em in the current font size. If percent is preceded by a minus sign the text is upshifted. The upshift or downshift is always relative to the default paragraph baseline. If the paragraph line spacing is set to ‘Fixed’ using the Paragraph Designer in a template file or by setting the code ‘ls’ option to F (see pages R- 360 and R-221), then the shifted text may interfere with text above or below and may also extend above or below the border of a text frame or a table cell. This input Some text down1 down2up1 more text... up1 produces: Some text more text... down1 down2 Note that the up and down shifting is always relative to the default paragraph baseline. Default:0 Kx percent Horizontal text displacement. [ horizShift ] percent is the required text leftshift expressed as a percentage of an em in the current font size. If percent is preceded by a minus sign, then the text is rightshifted. For example This text is shifted||rightwards| (not) R-140 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description |T|| the letters ‘|T|’ are shifted leftwards. They have a falsely small left indent. (not) |T| |the letters ‘|T|’ are shifted leftwards. They have a falsely small left indent. Default:0 Kerning, character spread and stretch K Y | N Enable pair kerning and character spread. Also: enable [ textKern ] ligatures (Unix only). This input AWAY and AWAY produces: AWAY and AWAY fi produces: fi This input fi (Unix only) produces: fi (Unix only) Ks percent Inter-character spread, or tracking. [ textSpread ] percent is relative increase/ decrease in character spread. Negative values reduce character spread. Spread is expressed as a percentage of the font's em space size. The character spread option in fs percent Horizontally expand or compress characters. [ textStretch ] E.g. the following This is expanded text and this is compressed text. produces: This is expanded text and this is compressed text. Default: 100 textBGColor name Apply a background color to text. FrameMaker 10 and above only. Default: no background text color Miramo Reference Guide [ v 9.2 ] R-141 Inline markup codes CHAPTER 3 Option Value Description Text language lang key Language. [ textLanguage ] key may be any one of the following: None, NoLanguage, USEnglish, UKEnglish, German, SwissGerman, French, CanadianFrench, Spanish, Catalan, Italian, Portuguese, Brazilian, Danish, Dutch, Norwegian, Nynorsk, Finnish, Swedish, Japanese, SChinese, SimplifiedChinese, TChinese, TraditionalChinese, Korean. The following additional language key values are supported when running with FrameMaker 8 or above: Bulgarian, Croatian, Czech, Estonian, Finnish, Greek, Hungarian, Latvian, Lithuanian, NewGerman, NewSwissGerman, Polish, Romanian, Russian, Slovak, Slovenian, Turkish. Hyphenation and spell checking is suppressed if the ‘lang’ option is set to None or NoLanguage. > Required . A code may be terminated by a code or by a code. If a code is terminated by a code all font settings in the code stack are cleared. Notes 1A rdim value may have any of the following forms: +20%, 120%, 85%, -4%, +dim and -dim (e.g. +2pt, -1mm). R-142 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary The Syntax Option Value Description Reference pre-defined font format fmt name Required [ fontFormat ] name is the name of a font format defined either in a template file using the Character Designer or by using the Notes 1 The Miramo Reference Guide [ v 9.2 ] R-143 Inline markup codes CHAPTER 3 Examples Consider a standard index where the title of a journal (‘Managing your Money’) is to be displayed in regular text within the body of the document, but in italics in the index. This may be achieved using the markup shown in Example 3.47. 1 2 Mainstream press is famous for 3 bringing out timely and well-constructed 4 journals, such as their flagship 5 publication, If the document containing the index entry shown in Example 3.47 is included as a chapter in a book that also contains a standard index added using markup such as the following: ... Figure 3.28 Sample index entry generated from Example 3.47 R-144 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes [ Summary Use one or more codes within an Syntax Option Value Description Name of frame (when on a reference page) fmt name name is the name of the frame. [ frameName ] Ignored unless the frame is to be placed on a Reference page, using the Frame dimensions W dim Width of frame. [ frameWidth ] H dim Height of frame. [ frameHeight ] Frame offset T dim Distance of top of frame from top of enclosing anchored [ frameTop ] frame or frame. L dim Distance of left side of frame from left side of enclosing [ frameLeft ] anchored frame or frame. Frame border and fill styles pen 0 - 15 Pen pattern number. [ penNum ] Sixteen pen patterns for borders around anchored frame objects are available, from 0 (black) to 15 (none). (See Appendix 1, page R-531, for a description of fill patterns.) Default:15 Miramo Reference Guide [ v 9.2 ] R-145 Inline markup codes CHAPTER 3 [ Option Value Description pw dim Pen width for border. [ penWidth ] Borders around all types of anchored frame thicken inwards towards the center of the anchored frame. (Note that this is different to the case of borders around a and fill 0 - 15 Fill pattern. As for ‘pen’ above. A ‘fill’ value of 15 makes the [ fillNum ] frame transparent. Default: 7 (opaque no fill) pstyle P | "dim Pen style. Solid or dashed. Setting ‘pstyle’ to P results in a [ penStyle ] dim ..." plain, solid border or line. Setting ‘pstyle’ to a series comprising an even number of dim values sets the border to have a dashed pattern. The first dim value specifies the length of a solid line segment, the next dim value specifies the length of a white segment, and so on. The pen pattern specification must be surrounded by double quotation marks. See Examples 2.14 and 2.15 on pages MD- 34 and MD-35 in the mmDraw Drawing Guide. Default:P Frame border and fill color color name Frame border and fill color. Metadata for graphic object (Frame) GOid string string may contain up to 512 bytes of metadata associated with this instance of the Frame code. This metadata is shown in FrameMaker MIF files in the R-146 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes [ Examples See under Miramo Reference Guide [ v 9.2 ] R-147 Inline markup codes CHAPTER 3 Summary Use one or more Syntax Option Value Description Color options color name Required. Name of color used to fill area bounded by container object. Color is either the name of a color definition in a FrameMaker template document or a color defined using a opacity percent Set opacity for blendMode key Set fill blend mode. Ignored if opacity is 100%. The value of key may be any of the following: Normal, ColorDodge, ColorBurn, Darken, Difference, Exclusion, HardLight, Lighten, Multiply, Overlay, Screen, SoftLight. The blend mode setting determines how partly transparent layers are composited. See Note 7 on page R-153 for references to documents that provide information about the effect of blend mode settings. Default: Normal R-148 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description o N | Y Override the overprint and knock out setting for the frame fill [ overprint ] area. Only relevant in a color-separated offset or screen printing environment and the ‘-PDFcmyk’ command line option or the inkIsColor N | Y If the ‘inkIsColor’ option is set to Y, and the referenced color is a spot color, and the opacity option is less than 100%, then the PDF separation name is set from the ‘color’ option value rather than the ink name specified for the referenced color definition. Default: N tint percent Specify color tint. Default: 100% level Below | Place the frame fill area above or below the parent object Above ( Shape options (1) fillShape Rect | Shape used for fill area or for line stroke. The fill area is the Ellipse | area of the container object less the margin area created by Circle | the Miramo Reference Guide [ v 9.2 ] R-149 Inline markup codes CHAPTER 3 Option Value Description borderWidth dim By default a frame fill area shape is filled. If ‘borderWidth’ is set to a value greater than 0 a stroked outline, with a width specified by the value of the ‘borderWidth’ option, is drawn instead. The width of the outline is drawn inwards from the borders of the container object, with allowance for the space set by the Shape options (2) All radius options are silently ignored if the ‘fillShape’ option is set to any value other than Rect. If the value of any radius option is greater than half the smaller of the width and height dimension after margins are applied, the radius value is set to half the smaller dimension. The order of radius options is significant. The application of radius options is illustrated in Note 2 on page R-152. cornerRadius dim Specify all corner radii when the ‘fillShape’ option is set to Rect (rectangle). Default:0 radius1 dim Top left corner radius when the ‘fillShape’ option is set to Rect (rectangle). Default: 0, or as set by the ‘cornerRadius’ option radius2 dim Top right corner radius when the ‘fillShape’ option is set to Rect (rectangle). Default: 0, or as set by ‘cornerRadius’ radius3 dim Bottom right corner radius when the ‘fillShape’ option is set to Rect (rectangle). Default: 0, or as set by ‘cornerRadius’ radius4 dim Bottom left corner radius when the ‘fillShape’ option is set to Rect (rectangle). Default: 0, or as set by ‘cornerRadius’ Margin options Set margins for frame fill area. If margins are too large for the container object, i.e. the sum of the values of ‘leftMargin’ and ‘rightMargin’ is greater than the width or the sum of the values of ‘topMargin’ and ‘bottomMargin’ is greater than the height of the container object the m dim Set all margins to the same size. [ allMargins ] Default: 0 lm dim Set left margin. [ leftMargin ] Default: 0 R-150 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description tm dim Set top margin. [ topMargin ] Default: 0 rm dim Set right margin. [ rightMargin ] Default: 0 bm dim Set bottom margin. [ bottomMargin ] Default: 0 Output mode option PDFonly Y | N Show the output in PDF only. Shading options (1) shadeColor name Name of second color to fill area bounded by container object with a linear gradient. The value of ‘shadeColor’ is either the name of a color definition in a FrameMaker template document or a color defined using a shadeFlow angle | Shading angle. If angle is set to 0, equivalent to a N-S | S-N | setting of S-N, the color gradient transitions angle W-E | linearly from 100% of the color specified by the E-W | value of the Miramo Reference Guide [ v 9.2 ] R-151 Inline markup codes CHAPTER 3 Notes 1 A frame fill area may be placed relative to body page text frame by placing a code in a text flow, as illustrated in Example 3.50 on page R-156. 2 Figure 3.29 illustrates the operation of the ‘topMargin’ When a frame fill is applied to a table Figure 3.31 R-152 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes If any part of the fill area expands outside the table frame area, it is masked (see Note 5). Cell height cell +width The frame fill area may be set to the area within the border rulings using a combination of the Figure 3.33 In the case of a between the Miramo Reference Guide [ v 9.2 ] R-153 Inline markup codes CHAPTER 3 8 Jobs that include objects with any degree of transparency (opacity less than 100%) fail unless the value of the selected joboptions file (either the default joboptions file specified for the mmServer RunAs user or the joboptions file name specified using either the ‘-PDFjobopts’ command line option or the Examples Example 3.48 is a simple illustration of how to use the 1 R-154 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes This apparent discrepancy occurs Description $ per gm because the referenced table format Black diamonds 452.83 definition T_FrameFill1 (line 1 in Example 3.48) defines the white rul- Coramandel rubies 321.02 ing between header and body rows to be twice as thick as the white rulings Klondike gold 20s 123.47 between body rows and rulings are Figure 3.37 Output from modified Example 3.48 centered about cell and row borders. This issue may be avoided by replac- ing cell rulings with color-filled rows and columns. Figure 3.37 shows the output when Example 3.48 is modified as follows. Firstly line 4 in Example 3.48 is replaced with 1 Miramo Reference Guide [ v 9.2 ] R-155 Inline markup codes CHAPTER 3 19 Example 3.50 illustrates applying a frame fill to the body page text frame contain- ing the paragraph instance shown in line 1. 1 2 Any time a code within a text flow the frame fill area is applied to the enclosing text frame. In Example 3.50 the frame fills have negative margins to allow a border around the text. The output from Example 3.50 is shown on this page. Example 3.51 illustrates using 1 16 18 Your retirement plan entitles you to a minimum of three months 19 holiday per year at a choice of destinations: 20 R-156 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes 30 The vacation city you have selected is shown 40 highlighted above. 42 We very much hope that you enjoy your time in your 45 selected vacation city. If you would like to change your vacation city 46 destination next year, 2043, please sign in to your personal account at: www.happyretirement.com Note that the facilities at your selected vacation city destination 49 are contracted to ensure your perpetutal happiness 50 during the period of your sojourn therein. Retirement plan for: The output from Example 3.51 is shown in Figure Ozymandias, King of kings 3.39. Choosing your The input shown in Example 3.51 is not sufficient in vacation city itself to produce the output shown in Figure 3.39: a Your retirement plan entitles you to a minimum of three months holiday per year at a choice of destinations: FrameMaker template document, containing paragraph City destinations & rates (2042) Monthly rate Destination Extra Premium Valpariso, Chile 20% $ 89.53 formats and the table format ‘T_destinationCity’ (see Detroit, MI 0% $ 49.53 Kenmare, IRL 23% $ 94.35 Vancouver, Canada 5% $ 54.35 line 20). The Miramo Reference Guide [ v 9.2 ] R-157 Inline markup codes CHAPTER 3 The output from Example 3.51 is shown in Figure Retirement plan for: Ozymandias, King of kings 3.40. Choosing your vacation city Your retirement plan entitles you to a minimum of three months holiday per year at a choice of destinations: City destinations & rates (2042) Monthly rate Destination Extra Premium Valpariso, Chile 20% $ 89.53 Detroit, MI 0% $ 49.53 Kenmare, IRL 23% $ 94.35 Vancouver, Canada 5% $ 54.35 Paris, TX 2% $ 51.22 Miami, FL 5% $ 54.35 The vacation city you have selected is shown highlighted above. We very much hope that you enjoy your time in your selected vacation city. If you would like to change your vacation city destination next year, 2043, please sign in to your personal account at: www.happyretirement.com Note that the facilities at your selected vacation city destination are contracted to ensure your perpetutal happiness during the period of your sojourn therein. Page 8 Figure 3.40 Output from modified Example 3.51 (scaled to 20%). R-158 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary The Syntax Option Value Description file filename Required [ imgFile ] Relative or absolute file name of image. Image files may be referenced using shell environment variables, as in ${FILENAME} (see the ‘-sendEnv’ command line option on page R-7). In this case environment variable names must be surrounded by curly braces. Lists of supported and partially supported image types are contained in Notes 3 and 6 starting on page R-186. imode R | C By default images are imported by reference. Setting ‘imode’ [ importMode ] to C, results in the image being copied into the output document. When running on Windows, setting the ‘imode’ option to C may be necessary for images to import correctly. See Note 9 on page R-187. /> Required Notes 1 The format of the imported image (i.e. whether PCX, MacPaint, xwd, etc) is recognized automatically. File extensions such as ‘.xwd’, ‘.eps’, etc, may be used for convenience, but are not required. Miramo Reference Guide [ v 9.2 ] R-159 Inline markup codes CHAPTER 3 2 In the case of R-160 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the Syntax Option Value Description Chapter file name file filename Required [ chapterName ] Name of document file (chapter) to create and add to current book. filename is either the basename of the file (in which case it may not contain the file path separator characters, ‘/’ or ‘\<#csq>) or the absolute (full path) name of the file. Relative file names are not allowed. Where the basename form of filename is given, the book chapter file filename is created in the directory which contains the FrameMaker book, specified using the ‘-Bfile’ command line flag (see page R-10), or the ‘Bfile’ option on the 1. Using the Miramo Reference Guide [ v 9.2 ] R-161 Inline markup codes CHAPTER 3 Option Value Description type IX | APL | Specifies the type of document to be added to the book. [ genType ] IOR | TOC The list of generated file types is given below: | LOM | LOR Value Description (Indexes—sorted) IX Index of Template options Cfile filename Copy all body pages and format specifications from filename [ tplCopyFile ] to the beginning of the current document. filename must be a FrameMaker document saved in MIF format. The ‘Cfile’ and ‘Tfile’ options are mutually exclusive: if both are used, the later option takes precedence over the earlier option. The ‘Cfile’ option differs from the ‘Tfile’ option in that the contents of the body pages are copied from the specified file, and all formatting specifications are always copied from the specified file. (The ‘Tflow’, ‘Tformats’ and ‘TXformats’ options are ignored). The ‘Cfile’ option takes precedence over the ‘-Cfile’ command line option (described in Chapter 2, ‘Running Miramo’, R-19). Default: from ‘-Cfile’ command line option Tfile filename Use filename as the source for formatting specifications. [ tplFile ] filename must be a FrameMaker document saved in MIF format. R-162 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description The ‘Cfile’ and ‘Tfile’ options are mutually exclusive: if both are used, the later option takes precedence over the earlier option. If neither the ‘Tformats’ nor the ‘TXformats’ option is used, then all formats in the template are imported. The ‘Tfile’ option takes precedence over the ‘-Tfile’ command line option (described in Chapter 2, ‘Running Miramo’, R-19). Default: from ‘-Tfile’ command line option Toverride N | Y Allow template format definitions to override Miramo format [ tplOverride ] definition code markup. Default: from ‘-Toverride’ command line option, or N if none given Tformats key Specify formats to be extracted from the template file given [ tplImportFormats ] with the ‘Tfile’ option. The formats to be included are specified by a key string comprising one or more characters from the following set: dcpflLRruvtkxTF The formats denoted by the key characters are described in Chapter 2 , ‘Running Miramo’ (see the description of the ‘-Tformats’ and ‘-TXformats’ command line options on page R-20). Note that the ‘F’ format flag copies text flow formats from text flow ‘A’ of the template file. To copy text flow formats from a different text flow, use the ‘Tflow’ option described below. Default: from ‘-Tformats’ command line option TXformats key Specify formats to be excluded from the template file given [ tplExFormats ] with the ‘Tfile’ option. The formats to be excluded are specified by a key string comprising one or more characters from the following set: dcpflLRruvtkxTF The formats denoted by the key characters are described in Chapter 2, ‘Running Miramo’ (see the description of the ‘-Tformats’ and ‘-TXformats’ command line options on page R-20). Default: from ‘-TXformats’ command line option Tflow name Set the name of the main textflow to name. Specific textflow [ textFlow ] attributes, for feathering, side-head settings and baseline synchronization, are as defined in a template file or by using the Miramo Reference Guide [ v 9.2 ] R-163 Inline markup codes CHAPTER 3 Option Value Description If there is no textflow name defined either in a referenced template file or within a Template image processing mode tplImode normal | If the ‘-tplImode’ command-line option is set to bypass, any bypass images in EPS, JPEG, PNG or TIFF format that are imported by reference in a template document or that are imported using the Volume numbering options The following options set up the VN Cont | How to compute volume number. [ volNum ] Same | Value Description File Cont Continue from previous book component. Aliases: cont, Continued and continued. Same Same as previous book component. File Read from file. If the ‘VN’ option is used, the ‘VNstyle’, ‘VNstring’ and ‘VNstart’ options are ignored. The default is determined by the ‘VNstyle’, ‘VNstring’ and ‘VNstart’ options. To restart numbering from 1, use the ‘VNstart’ option. VNstyle A | UA | Sets volume number style. [ volNumStyle ] LA | UR | Value Description LR | C A Arabic. UA Uppercase alpha. LA Lowercase alpha. UR Uppercase roman. LR Lowercase roman. C Custom. R-164 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description If ‘VNstyle’ is set to C the value of ‘VNstring’ is used for the VNstring string Set custom volume number string. [ volNumString ] ‘VNstring’ is ignored if the ‘VN’ option is used, Ignored unless ‘VNstyle’ is set to C. VNstart int Set volume number. [ volNumStart ] ‘VNstart’ is ignored if the ‘VN’ option is used, or if ‘VNstyle’ is set to C. Default:1 Chapter numbering options The following options set up the CN Cont | How to compute chapter number. [ chapNum ] Same | Value Description File Cont Continue from previous book component. Aliases: cont, Continued and continued. Same Same as previous book component. File Read from file. If the ‘CN’ option is used, the ‘CNstyle’, ‘CNstring’ and ‘CNstart’ options are ignored. The default chapter number is determined by the ‘CNstyle’, ‘CNstring’ and ‘CNstart’ options. To restart chapter numbering from 1, use the ‘CNstart’ option. CNstyle A | UA | Sets chapter number style. [ chapNumStyle ] LA | UR | Value Description LR | C A Arabic. UA Uppercase alpha. LA Lowercase alpha. UR Uppercase roman. LR Lowercase roman. C Custom. Miramo Reference Guide [ v 9.2 ] R-165 Inline markup codes CHAPTER 3 Option Value Description If ‘CNstyle’ is set to C the value of ‘CNstring’ is used for the CNstring string Set custom chapter number string. [ chapNumString ] ‘CNstring’ is ignored if the ‘CN’ option is used. Ignored unless ‘CNstyle’ is set to C. CNstart int Set chapter number. [ chapNumStart ] ‘CNstart’ is ignored if the ‘CN’ option is used, or if ‘CNstyle’ is set to C. Default:1 Page numbering options For setting up the document starting page number. N Cont | Specifies how to compute sequential page number values. [ pageNum ] Restart | Value Description File Cont Continue from previous book component (file). Both the numeric value and numbering style are derived from the previous document (chapter/file) in the book. The ‘Nstart’ option is ignored and document numbering styles set up within the file (template) are ignored. Aliases: cont, Continued and continued. Restart Restart using the value assigned to the ‘Nstart’ option, or 1 if the ‘Nstart’ option is not set. File Read value and numbering style from file (template). The ‘Nstart’ option is ignored. Default: Restart Nstyle A | UA | Sets page number style. [ pageNumStyle ] LA | UR | Value Description LR A Arabic. UA Uppercase alpha. LA Lowercase alpha. UR Uppercase roman. LR Lowercase roman. Default:A Nstart int Specifies a fixed numeric value, int, for the R-166 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Paragraph numbering options PN Cont | Paragraph numbering. [ pgfNum ] Restart | Value Description File Cont Continue. Aliases: cont, Continued and continued. Restart Restart from 1. File Read from file. Default: Restart Page starting side StartSide Left | Starting page side. [ startSide ] Right | Value Description Next | File Left Left page. Right Right page. Next Next available side. File Read from file. The ‘StartSide’ option is ignored (the starting page side is always ‘Right’) unless the document is set to be double- sided, either by importing document formats from a double- sided template file1 or, if the ‘type’ option is set to STD, by setting the Pre- and post-processing options print Y | N Include this chapter file in the list of files to be printed. [ printThisFile ] Default:Y Specify PDF bookmark hierarchy config filename file is name of a configuration file specifying Acrobat [ configFile ] bookmark levels. See the section entitled Controlling bookmark levels using a ‘config’ file in ‘Running Miramo’, on page R-34, for a description of how to set up a bookmark configuration file. Default: from the command line, if the ‘-config’ command line option is used (see page R-15). Operating mode options stripInput N | tab | Enable special processing of text containing binary tab, nl | all newline and carriage return characters. Value Description N No action (default). Miramo Reference Guide [ v 9.2 ] R-167 Inline markup codes CHAPTER 3 Option Value Description tab Strip occurrences of the character U+0009, HORIZONTAL TABULATION, from input text content. (By default binary tab characters are treated as printable tab characters.) Binary tab control characters may be included using the imageCache N | Y Enable image caching when the R-168 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description tENC utf-8 | Specify the default document text processing mode. The [ textEncoding ] wcp-1252 option values may be in either uppercase or lowercase. See | us-ascii | the description of the ‘-tENC’ command line option on page iso-8859-1 R-9 for details. Default: utf-8 userapi string Name of user API client to run prior to print/save. See the ‘-userapi’ command line option on page R-21. Default: from -userapi command line option update Y | N Include this chapter file in the list of files to be updated. Default:Y links Y | N Create hypertext links in generated files. [ createLinks ] Default:Y > Required 1. See the ‘-Tfile’ and ‘-Cfile’ command line options on page R-19, and the Notes 1 The process of generating a book file from a Miramo document containing embedded Miramo Reference Guide [ v 9.2 ] R-169 Inline markup codes CHAPTER 3 -x External cross references -ux Unresolved cross references -ut Unresolved text references -f Fonts -g Imported graphics -t Text references In the case of the index of references (type=IOR), the reference text is sorted in alphabetical order. 4 Generated lists (type=TOC, LOM, LOR) contain paragraph, Examples See the R-170 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use one or more Syntax Option Value Description fmt name name is the name of the paragraph, marker or reference to [ includeName ] be included in the generated file. The value of the preceding Miramo Reference Guide [ v 9.2 ] R-171 Inline markup codes CHAPTER 3 Option Value Description /> Required Examples See the R-172 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary The Syntax Option Value Description General hypertext options file filename filename is the name of the file containing the hypertext [ filename ] destination. If filename contains spaces, it must be enclosed within a pair of quotation mark, ", or or apostrophe characters, ', U+0027 APOSTROPHE or U+0022 QUOTATION MARK. The ‘file’ option may be used with either the ‘jumptopage’ option or the ‘jumptodest’ option when the destination is not in the current file. The ‘file’ option is ignored if neither the ‘jumptopage’ nor the ‘jumptodest’ option is used. openURL url url is the URL of a file to open in a browser, for example: See the Miramo Reference Guide [ v 9.2 ] R-173 Inline markup codes CHAPTER 3 Option Value Description jumptopage firstpage | Jump to first, last, previous, next or specified page number in lastpage | the current file or another file. nextpage Value Jump to | firstpage First page (in current file, or document named prevpage by ‘file’ option above). | int lastpage Last page (in current file, or document named by ‘file’ option above). nextpage Next page (current file only). prevpage Previous page (current file only). int Page number int Use the ‘file’ option to specify a destination in another file. Enables a hyperlink in PDF viewer applications. In Windows FrameMaker the page is displayed in the same window if the page is in the current file. If the page is in a different file, it is displayed in a new window. In Unix FrameMaker the page is always displayed in a new window. Page number is the document page number, as shown in running headers/footers. If the specified page number does not exist in the target document, the first page is displayed. See Note 5 on page R-178. jumptodest string string is the destination identification, set using Use the ‘file’ option to specify a destination in another file. Use the ‘fitwin’ and ‘newwin’ options to change the mode of display (in the current window, in a new window and fit to window). This is an example of jumpback Y | N Jump to the location last viewed by the reader. Reference pre-defined font format F name Font format name. See page R-137 in the Miramo Reference [ fontFormat ] Guide R-174 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Font selection ff name Font family. See page R-137 in the Miramo Reference Guide. [ fontFamily ] fa name Font angle. See page R-137 in the Miramo Reference Guide. [ fontAngle ] fw name Font weight. See page R-138 in the Miramo Reference Guide. [ fontWeight ] fv name Font variation. See page R-138 in the Miramo Reference [ fontVariation ] Guide. Text size and color p dim | Text size. See Note 1 on page R-142. [ textSize ] rdim Default units are points (1/72 inches). See page R-138 in the Miramo Reference Guide. fcolor name Font color. See page R-138 in the Miramo Reference Guide. [ textColor ] Underline and overline uline N | S | D | Underline style. [ textUnderline ] M Value Description N No underline. S Single (normal) underline. D Double underline. M Numeric (low) underline. See page R-138 in the Miramo Reference Guide. Default:N o N | Y Overline. See page R-139 in the Miramo Reference Guide. [ textOverline ] Default:N Strike through and change bar t N | Y Strike through. See page R-139 in the Miramo Reference [ strikeThrough ] Guide. Default:N C N | Y Change bar. See page R-139 in the Miramo Reference Guide. [ changeBar ] Default:N Miramo Reference Guide [ v 9.2 ] R-175 Inline markup codes CHAPTER 3 Option Value Description Capitalization fc T | S | L | Capitalization. [ textCase ] U Value Description T As typed. S Small caps. L Lower case. U Uppercase. See page R-139 in the Miramo Reference Guide. Default:T Vertical and horizontal shift u N | Y Superscript. See page R-139 in the Miramo Reference Guide. [ superscript ] Default:N d N | Y Subscript. See page R-139 in the Miramo Reference Guide. [ subscript ] Default:N Ky percent Vertical displacement of text. See page R-140 in the Miramo [ vertShift ] Reference Guide. Default:0 Kx percent Horizontal text displacement. See page R-140 in the Miramo [ horizShift ] Reference Guide. Default:0 Kerning, character spread and stretch K Y | N Enable pair kerning and character spread. Also: enable [ textKern ] ligatures (Unix only). See page R-141 in the Miramo Reference Guide. Ks percent Inter-character spread, or tracking. See page R-141 in the [ textSpread ] Miramo Reference Guide. Default:0 fs percent Horizontally expand or compress characters. See page R-141 [ textStretch ] in the Miramo Reference Guide. Default: 100 textBGColor name Apply a background color to text. FrameMaker 10 and above only. See page R-141 in the Miramo Reference Guide. Default: no background text color Text language lang key Language. See page R-142 in the Miramo Reference Guide. [ textLanguage ] R-176 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description FrameMaker-only hypertext options The following options are effective only when the output format is a FrameMaker document. newwin Y | N View jump target in new window. [ newWindow ] fitwin Y | N Resize page to fit window. [ fitWindow ] system string string="applicationpath" or [ systemCmd ] string="applicationpath,windowstate" [NT only] Launch external application. On Windows NT any one of the following following values may be given for the windowstate: SW_HIDE SW_MAXIMIZE SW_MINIMIZE SW_RESTORE SW_SHOW SW_SHOWDEFAULT SW_SHOWMAXIMIZED SW_SHOWMINIMIZED SW_SHOWMINNOACTIVE SW_SHOWNA SW_SHOWNOACTIVATE SW_SHOWNORMAL See Note 6 on page R-179. exit N | Y Close viewer application. [ exitViewer ] close Y | N | all Y - close current document, all - close all documents, N - [ closeFile ] ignored. > Required Miramo Reference Guide [ v 9.2 ] R-177 Inline markup codes CHAPTER 3 Notes 1 Any combination of the following content is permitted within 1 Two of the most visited web sites are 2 Example 3.53 contains two 1 See the description of the 2 See the reference to See the reference to Louis Armstrong. 6 5 Example 3.55 illustrates the usage of 1 See R-178 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes The output from Example 3.55 is shown in Figure 3.43. 6 Example 3.56 illustrates the usage of 1 Check the The output from Example 3.56 is shown in Figure Figure 3.44 jumptopage action 3.44. If the value of the ‘system’ option contains spaces, e.g. it comprises a command name followed by a command line flag or a file name, then it must be enclosed within a pair of quotation mark, ", or or apostrophe characters, ', U+0027APOSTROPHEor U+0022QUOTATION MARK. If the ‘system’ option contains one or more file names with spaces in them, then the file name must be surrounded by apostrophe characters in the case that the whole command line is surrounded by quotation marks or quotation marks in the case that the whole command line is surrounded by apostrophe characters. Examples are shown below. system="notepad 'C:\my document'" system='notepad "C:\my document"' system="start framemaker 'C:\Catalogs\nuts and bolts\stainless steel.fm'" system="cat '/tmp/a a' '/tmp/b b' > '/tmp/c c'" The ‘system’ option is effective only when the output document is viewed using FrameMaker. Miramo Reference Guide [ v 9.2 ] R-179 Inline markup codes CHAPTER 3 Summary Use the Syntax Option Value Description Import options (1) file filename Required [ imgFile ] Relative or absolute file name of image or structured storage file (see Note 1 on page R-186). Files may be referenced using shell environment variables, as in ${FILENAME} (see the ‘-sendEnv’ command line option on page R-7). In this case environment variable names must be surrounded by curly braces. If filename is a Windows structured storage file (supported on Windows NT only) and the ‘objName’ option (see page R-182) is not used, the included image is the ‘last view on close’ of the creator application. Note 2 on page R-186 describes how to enable embedded application activation. Windows structured storage files containing links to external files cannot be imported, see Note 4 on page R-186. Lists of supported and partially supported image types are contained in Notes 3 and 6 starting on page R-186. If none of the ‘W’, ‘H’ or ‘dpi’ options is set, and if the image contains no basis for determining its absolute dimensions, the image is scaled to fit in a 1 inch × 1 inch rectangle. imode R | C | Import mode. [ importMode ] bypass Value Description R Import image by reference. Alias is Reference. C Import image by copying into intermediate FrameMaker document. Alias is Copy. R-180 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description bypass Import image by reference as for R except that if the image is in EPS, JPEG, PNG or TIFF format, image processing in FrameMaker is bypassed (i.e. the image is processed more compactly and efficiently). If the ‘imode’ option is set to bypass a PostScript text column will be shown in place of the EPS, JPEG, PNG or TIFF image in non-PDF output formats. The text column will have the same dimensions as the image. Alpha channel transparency in images is supported only when the ref NW | N | Keep reference to image file even if file does not exist. [ keepImgRef ] Y | YW Value Description NW No, and issue warning message. N No, no warning message. Y Yes, no warning message. YW Yes, and issue warning message. Default:NW pdfpage int Page number in PDF document to import as an image. The [ pdfPageNum ] first page in the PDF document is always page 1. See mmxslt extension functions for PDF file import, on pages R-421–422, and the mmpp @pdfpages( ) function, on page R- 524, for special functions that return information about referenced PDF files. For importing all or part of a PDF file as a chapter in a book see PDF file import on pages R-97–98. Default:1 Miramo Reference Guide [ v 9.2 ] R-181 Inline markup codes CHAPTER 3 Option Value Description Import options (2) The following options are supported on Windows only. Special system configuration is necessary when running on Windows Server 2008 (and later). See Note 11 on page R-187. oleEMF Y | N If the file referenced by the ‘file’ option is a Windows structured storage file, import the ‘last view on save’ image in EMF format. In this case embedded application activation is not available even when the output is in editable FrameMaker document format. Supported on Windows NT only. The ‘oleEMF’ option is ignored if either the ‘objName’ option is set or the file is not a Windows structured storage file. Default:Y objName name | int If the file referenced by the ‘file’ option is a Windows [ objectName ] structured storage file, name of an application object within the file. Supported on Windows NT only; an EMF image of the named object is copied into the output document. A warning is issued if the file does not contain the named object or the file is not a Windows structured storage file that supports named objects. name may refer to a named chart or picture object in an Excel workbook. int may refer to a slide number a Powerpoint presentation. See Note 12 on page R-188. Image location L dim Distance of left edge of image from left side of enclosing [ imgLeft ] T dim Distance of top edge of image from top side of enclosing [ imgTop ] Image dimensions W dim Image width. If the ‘W’ option is set the ‘dpi’ option (see [ imgWidth ] below) is ignored. If no ‘H’ option is included and the image is in a ‘supported’ format (see Note 5 on page R-186), then the image height will be calculated automatically using the image aspect ratio. Default: 25.4mm H dim Image height. If the ‘H’ option is set the ‘dpi’ option (see [ imgHeight ] below) is ignored. R-182 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description If no ‘W’ option is included and the image is in a ‘supported’ format (see Note 5 on page R-186), then the image width will be calculated automatically using the image aspect ratio. Default: 25.4mm maxWH N | Y If both the ‘W’ option and the ‘H’ option are set, then setting ‘maxWH’ to Y results in the values of ‘W’ and ‘H’ (above) being treated as maximum, not absolute, values. I.e. the image is scaled to the maximum possible size within the constraints of the ‘W’ and ‘H’ values while maintaining its original aspect ratio. See Note 10 on page R-187. dpi int Image size in dpi (dots per inch). Setting the ‘dpi’ option results in equal x and y inverse image scaling, i.e. the larger the dpi value the smaller the printed image. The ‘dpi’ option is ignored if used in combination with either or both the ‘W’ and ‘H’ options. The ‘dpi’ option is ineffective on EPS files. Graphics options pen 0 - 15 Pen pattern for border. Sixteen pen patterns are available [ penNum ] from 0 (black) through 15 (none). See Appendix 1, on page R- 531. fill int Fill pattern. Sixteen fill patterns are available from 0 (black) through 15 (none). See Appendix 1, on page R-531. pw pw Pen (border) width. Borders thicken equally about their [ penWidth ] centers. Default units are points. color name Border color. Orientation a 0 - 360 Angle of rotation (counterclockwise). [ imgAngle ] flip N | Y Flip image from left to right around its center point. [ flipLR ] Default:N Print mode o N | Y Y = Overprint. N = Knockout. [ overprint ] Default:N Universal 3D import options view name Specify name of U3D view to show. [ viewName ] Default: defaultView Miramo Reference Guide [ v 9.2 ] R-183 Inline markup codes CHAPTER 3 Option Value Description background default | Background color. Use three values for the RGB color model %/%/% | and four values for the CMYK color model. The three or fours %/%/%/% values are always treated as percentages. The percent sign itself is optional. Each percent value is rounded to an integer in the rannge 0 (0%) to 255 (100%). Default: default lighting 1 - 12 | Set background lighting. key Value Mnemonic key alias 1 fromFile 2 None 3 White 4 Daylight 5 Bright 6 Primary 7 Night 8 Red 9 Blue 10 Cube 11 Cad or CAD 12 Headlight The value of ‘lighting’ may be set to either an integer in the range 1 - 12 or to the corresponding key word listed above. Default: TBA renderMode 1 - 15 | Set rendering mode for imported U3D file. key Value Mnemonic key alias 1 BB or boundingBox 2 transparentBB 3 transparentBBOutline 4 Vertices 5 shadedVertices 6 wireFrame 7 shadedWireFrame 8 solid 9 transparent 10 solidWireFrame 11 transparentWireFrame 12 illustration 13 solidOutline 14 shadedIllustration 15 hiddenWireFrame The value of ‘renderMode’ may be set to either an integer in the range 1 - 15 or to the corresponding key word listed above. Default: TBA R-184 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Text runaround RA N | B | C Text runaround type. [ runAround ] Value Description N No runaround B Box runaround C Contour runaround Default:N RAgap dim Specify the gap between the Image and text flowing around [ runAroundGap ] it. The value of dim may be negative. Effective only if the ‘RA’ option (see above) is set to C or B. Default: 6pt Opacity and blend mode options The following options apply only if the ‘imode’ option is set to bypass (see page R-180). opacity percent Set image opacity. If ‘opacity’ is set to a value less than 100% and the /AllowTransparency PDF joboptions parameter is not set to true, the job will fail. See Note 8 on page R-154. Default: 100% blendMode key Set image blend mode. Ignored if opacity is 100%. The value of key may be any of the following: Normal, ColorDodge, ColorBurn, Darken, Difference, Exclusion, HardLight, Lighten, Multiply, Overlay, Screen, SoftLight. The blend mode setting determines how partly transparent layers are composited. See Note 7 on page R-153 for references to documents that provide information about the effect of blend mode settings. Default: Normal Metadata for graphic object (Image) GOid string string may contain up to 512 bytes of metadata associated with this instance of the Image code. This metadata is shown in FrameMaker MIF files in the Miramo Reference Guide [ v 9.2 ] R-185 Inline markup codes CHAPTER 3 Option Value Description /> Required Notes 1 The format of the imported file (i.e. whether PCX, MacPaint, xwd, Windows structured storage, etc) is recognized automatically. File extensions such as .xwd, .eps, .xls etc, are not required. Importing Windows structured storage files and OLE objects is supported on Windows NT only. In this context Windows NT all current versions of Windows NT 5, e.g. Windows 2000, Windows XP Professional and Windows 2003 Server. 2 In the case that the filename specified by the ‘file’ option (see page R-180) is a Windows structured storage file, if the requested output is in editable FrameMaker document format and the ‘oleEMF’ option (see page R-182) is set to N, and the ‘objName’ option (see page R-182) is not used, then the FrameMaker document will act as an OLE/ActiveX container. Double clicking on the ‘last view on save’ image will start up the embedded creator application to load and edit the contents of the Windows structured storage file, either in- place, if the ‘imode’ option (see page R-180) is set to R, or in a new window, if the ‘imode’ option is set to C. This assumes that an instance of the creator application is available to the editing host and that the structured storage file was either imported with the ‘imode’ option (see page R-180) set to C or the structured storage has the same absolute path name on the editing host as on the creator host. Typical creator applications are Microsoft Word, Microsoft Excel and Microsoft Visio. 3 The itell and ptell command-line utilities report basic image file statistics, e.g. image type, size, height, width, dpi and aspect ratio. To check usage type itell -h or ptell -h. 4 A Windows structured storage file cannot be imported if it contains a link to an external file. Such links must be broken before import. Processing will fail without warning if an attempt is made to import a Windows structured storage file containing an external link. 5 On Windows ‘supported’ image file formats comprise the following: BMP, CGM, EPS, GIF, JFIF, JPEG, PNTG, PCX, PDF, PNG, SVG, SWF, TIF, U3D, WMF, and XWD R-186 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes All the above image types are also supported on on Unix, with the following exceptions: BMP, SWF, and U3D 6 Several partially supported image file formats may also be imported provided the CITT G3, CITT G4, DXF, DRW, GEM, PICT and WPG. In the above PNTG indicates Mac Paint file format. SNRF indicates Sun Raster file format. A detailed discussion of supported image file formats is included in the Miramo User Guide, Chapter 3, ‘Anchored Frames and Images’, on pages U-37–39. 7 Fine control over image sizing and the sizing of enclosing anchored frames may be achieved by using the mmpp @image( ) function, described on pages R-521–522 or by using the mmxslt functions, described in sections mmxslt extension functions for image processing and mmxslt extension functions for PDF file import, on pages R-420–422 in Chapter 5, Miramo DTD and XML codes. 8 If the ‘imode’ option (see page R-180) may is set to C or bypass, the ‘pdfpage’ option is ignored. 9 On Windows NT 4 or 5 certain image file types may not import correctly unless the ‘imode’ option is set to C or bypass. An example of such an image file format is JPEG. If problems are encountered using the ‘file’ option on Windows, try setting the ‘imode’ option to C. 10 The use of the ‘maxWH’ option (see page R-183) is illustrated in Example 3.10 on page U-51 in the Miramo User Guide. 11 By default Windows Server 2008 and later versions of Windows Server do not support automation of Microsoft Office applications in headless mode. Support for automation of Microsoft Office applications in headless mode may be enabled using the following commands: Using cmd.exe: mkdir %systemroot%\SysWOW64\config\systemprofile\Desktop cd %systemroot%\SysWOW64\config\systemprofile\Desktop mmaccess or, using Windows Powershell: mkdir $env:systemroot\SysWOW64\config\systemprofile\Desktop cd $env:systemroot\SysWOW64\config\systemprofile\Desktop mmaccess In the the above mmaccess is a built-in Miramo command that grants read and write folder access permissions to the Miramo RunAs user account. As a minimum the Miramo RunAs user account needs the right to read the above Desktop folder. Miramo Reference Guide [ v 9.2 ] R-187 Inline markup codes CHAPTER 3 12 The ‘objName’ option (see page R-182) may refer to a named graphic object within either a Microsoft Powerpoint file or a Microsoft Excel file. In the case of Powerpoint, slides only may be imported. Slides are referenced by an integer number. The first slide in a Powerpoint presentation is 1. In the case of Excel, only charts and pictures may be imported using the ‘objName’ option. By default the first object found that has a name matching name is imported. To guarantee importing the correct object from an Excel file the ‘objName’ name value may be preceded by a worksheet name and a slash character, ‘/’. objName="worksheetname/objectname" Examples Example 3.57 illustrates importing an Encapsulated PostScript (EPS) file into an anchored frame. 1 EPS files are a special case since their Wa absolute width and height values can nor- T mally be determined from ‘%%Bounding- L 1-1 1-2 1-3 1-4 1-5 1-6 1-7 Box’ data contained within the file. For this reason the either a ‘W’ or ‘H’ option set. Because the 4-1 4-2 4-3 4-5 4-6 4-7 1 2 R-188 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes 11 fill="15" pen="0" color="Red"> 12 13 History of the world 14 25 26 Page 30 If the text in Example 3.58 is contained in the file ‘page_background’, then run- ning the Unix shell command shown in Example 3.59: 1 #!/bin/sh 2 MM_PS_WAIT=Y; export MM_PS_WAIT 3 miramo -m -Ppapersize 4.98in5.98in -Preg W -Pstartno 1 -Pendno 1 -Omif page_out.mif -Pfile page_out.ps page_background 4 fmps2eps page_out.ps page_out.eps Example 3.59 Command used to produce output in Figure 3.46 Miramo Reference Guide [ v 9.2 ] R-189 Inline markup codes CHAPTER 3 produces a single page document show- ing the first page as an EPS file with crop page_background.mif Page 1 Tuesday, September 17, 2013 1:47 AM marks, i.e. how the page will look when History of the world printed on an imagesetter. Notice that the Text and more text. Text and more text ... background image ‘bleeds’ into the crop margin area. This is because the 1 4 W="40mm" H="35.6mm" /> Currency 60 Q Rate 5 0 Example 3.60 Using the ‘objName’ option M Rate Credit Example 3.61 illustrates extracting the first slide from a Microsoft Powerpoint structured storage Yield Calm risk Frenzy risk file. Figure 3.47 Output from Example 3.60 1 Follow the road to success … Figure 3.48 Output from Example 3.61 R-190 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the code to import (formatted) text and included graphics from an external FrameMaker or other document. (Alternatively, use the Syntax Option Value Description Import file name and text flow file filename Required [ filename ] filename is the relative or absolute file name of an external file to be imported. The file to be imported can be another FrameMaker document, or a file created in another application (for example Microsoft Word) for which a Frame import filter is installed. A full description of the supported import filters and some of their limitations is contained within the FrameMaker ‘Help’ system in the online manual Using FrameMaker Filters. The external file may be imported by reference or by copying into the document depending on the ‘imode’ option value (below), apart from a FrameMaker document in MIF format which may only be imported by reference (by setting the ‘imode’ to N). By default, unless the ‘Tflow’ option (see below) is specified, the main document text flow, usually, but not always, flow ‘A’ in Frame documents, will be imported. Tflow name Name of text flow to import from specified document, if the [ textFlow ] document is in FrameMaker binary or MIF format. See Note 2 on page R-193. Default: is main document flow (usually A) Import mode imode R | C Import external file by copying (imode=C) or by reference [ importMode ] (imode=R). MIF files may only be imported by reference. Default:R Miramo Reference Guide [ v 9.2 ] R-191 Inline markup codes CHAPTER 3 Option Value Description Formatting control f I | C | P Formatting options for imported text. [ formatMode ] Value Description I Retain formatting from included document. C Apply formatting from current document on a matching tags basis, retain imported text format where tags don't match. P Reformat as plain text using the text format in force when the fo Y | N Retain format overrides when ‘f=C’ option is used. [ keepOverrides ] Using ‘f=I’ (use formats from included document), all format overrides in the imported document are retained. Using ‘f=P’ (plain text) all formatting information is removed from the imported text. Default:Y fp Y | N Retain manual page breaks when ‘f’ option is set to C. [ keepPageBreaks ] Using ‘f=I’ (use formats from included document), all manual page breaks in the imported document are retained. Using ‘f=P’ (plain text) no manual page breaks are retained. Default:Y Import filter filterid name Specify id of FrameMaker import filter to be used to import [ filterName ] this file. The filterid option value comprises a maximum of eight characters, made up of a four character vendor ID followed by up to four characters specifying a file format ID. The list of vendor+format id combinations is found in the [Filters] section of the maker.ini file (Windows) or the R-192 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description AW4W0331 Ami Professional 2-3.1 The filterid value is automatically truncated or space filled to exactly eight characters before further processing. /> Required Notes 1 The fastest, most reliable, file import performance occurs when importing FrameMaker documents. Importing other document types may be subject to unreliability and may occasionally cause performance degradation. A full description of the supported import filters and some of their limitations is contained within the FrameMaker ‘Help’ system in the online manual Using FrameMaker Filters. 2 If the file being imported is a FrameMaker document, then this file must contain a tagged, autoconnected main flow (nearly always the first autoconnected flow on the Right master page), or an autoconnected flow tagged ‘A’. An exception to this rule occurs when the ‘Tflow’ option is used, in which case the contents of the flow specified by ‘Tflow’ will be imported. In the vast majority of situations it will not be necessary to take notice of the above rules, since the default settings for FrameMaker documents meet their requirements, and these defaults are rarely changed. 3 Using the ‘f=C’ option (reformat imported text using current document's formats) the current (Miramo) document format definitions are applied to the imported text wherever format definition tags match. For matching tags, the ‘fo’ (retain format overrides) and ‘fp’ (retain manual page breaks) options may be used to control whether format and page break overrides on individual paragraphs or characters in the imported document are preserved or discarded. If the tags do not match (for example, the imported document contains paragraphs tagged as ‘Heading1’, but that tag is not defined in the current Miramo document) the format of the imported text is retained as it appears in the imported document. Miramo Reference Guide [ v 9.2 ] R-193 Inline markup codes CHAPTER 3 Examples To import a Microsoft Word document by reference, reformatting using the cur- rent document formats, preserving format overrides and removing manual page breaks: R-194 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use Syntax Option Value Description Include file name file filename filename is relative or absolute name of a file. [ filename ] Notes 1 The file included must contain Miramo markup which is valid at the point at which the code. To maintain the line breaks contained in the imported text, use the ‘nl’ option set to R or RX. Examples This is an example on Unix: Miramo Reference Guide [ v 9.2 ] R-195 Inline markup codes CHAPTER 3 Summary Use the Syntax Option Value Description Define index entry fmt name name is the index marker name. [ markerName ] Default: Index ix-page Single | Type of page reference in index. [ pageType ] Start | Value Type of index page reference End | Single Single page reference. NoPage Start First page in page range. End Last page in page range. NoPage Exclude page number. Default: Single ix-sort string string is index entry sort string. [ sortKey ] Only required if entry is to be sorted differently from the index text, or for sorting kanji index entries using yomi-gana. ix-show Y | N Include index entry in document text. If set to Y, The following building blocks may be used between deftext deftext is any or all of: text, binary newline characters and tabs. All newlines are mapped to space characters. Binary tabs are preserved unless the ‘-striptabs’ command line option is used. 1. A single index entry may have up to 4,068 distinct page number references. R-196 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhhhh;). Notes 1 To include spaces before the beginning of, or after the end of, index entry text (i.e. between Examples Example 3.62 contains several Miramo Reference Guide [ v 9.2 ] R-197 Inline markup codes CHAPTER 3 For further examples illustrating the usage of the usage of the R-198 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the Syntax Option Value Description ix-sort string string is sort string for index sub-entry. [ sortKey ] Only required if the sub-entry is to be sorted differently from the sub-entry text. /> Required Examples For examples illustrating the usage of the Miramo Reference Guide [ v 9.2 ] R-199 Inline markup codes CHAPTER 3 Summary Use the Syntax Option Value Description Insert marker text fmt name name is marker name. [ markerName ] show Y | N Include marker text as printable text in document. [ showIntext ] Default:Y > Building blocks The following building blocks may be used between deftext deftext consists of text, newline characters and binary tabs. All newlines are mapped to space characters. Binary tabs are preserved unless the ‘-striptabs’ command line option is used. Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhhhh;). However if the requested character is not available in the current font, it will be ignored with a warning message. R-200 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Miramo Reference Guide [ v 9.2 ] R-201 Inline markup codes CHAPTER 3 Summary Use the , code, to control mas- ter page usage in non-generated files. By default page layouts follow the body page layouts in a template file (if any). If the output document has more pages than are in the template file, or if there is no template file, then succeeding pages in single-sided documents all have the layout of the Right master page. In double-sided documents succeeding pages use alter- nating Right and Left masterpages. These default master page rules are explained in detail in Note 9 on page R-206. The Syntax Option Value Description Default master page usage options Specify new default rules for applying master pages to the destination page and to subsequent matching pages. See Note 2 on page R-205 for a definition of ‘destination page’. If either the current rectoPages name | Apply master page name to the first destination page, if it is a Default recto page, and to all subsequent pages in the document that are recto pages. See Note 8 on page R-206. versoPages name | Apply master page name to the first destination page, if it is a Default verso page, and to all subsequent pages in the document that are verso pages. Ignored if the document is not double-sided. See Note 8 on page R-206. oddPages name | Apply master page name to the first destination page, if it is Default an odd page, and to all subsequent pages in the document that are odd pages, counting the first page as 1. See Note 6 on page R-206. R-202 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description evenPages name | Apply master page name to the first destination page, if it is Default an even page, and to all subsequent pages in the document that are even pages, counting the first page as 1. See Note 6 on page R-206. allPages name | Apply master page name to the first destination page and all Default subsequent pages in the document. Exception master page usage options Specify a rule for applying a single exception master page to a destination page. See Note 2 on page R-205 for a definition of ‘destination page’. The rules for resolving conflicts when more than one option from the following Exception master page usage options is used are described in Note 3 on page R-205. Using the special page name Default results in a Left or Right master page being applied, depending on whether the destination page is a verso or a recto page (see Note 9 on page R-206). rectoPage name | Apply exception master page name to the destination page, if Default it is a recto page. See Note 8 on page R-206. versoPage name | Apply exception master page name to the destination page, if Default it is a verso page. Ignored if the document is not double- sided. See Note 8 on page R-206. oddPage name | Apply exception master page name to destination page, if it is Default an odd page, counting the first page as page 1. See Note 6 on page R-206. evenPage name | Apply exception master page name to destination page, if it is Default an even page, counting the first page as page 1. See Note 6 on page R-206. Page name | Apply exception master page name to destination page Default regardless of whether the page is odd, even, recto or verso. Last-page master page usage options Specify a rule for applying an exception master page to the last page in a document, or to the last page in a chapter in a book, that contains non-background text or graphics. Unlike other Miramo Reference Guide [ v 9.2 ] R-203 Inline markup codes CHAPTER 3 Option Value Description All the options in the following set of Last-page master page usage options are ignored if the document contains only one page. lastRectoPage name Apply background from master page name to the last non- empty recto page in the document. The master page applied must contain no auto connected text frames. See Note 8 on page R-206. lastVersoPage name Apply background from master page name to the last non- empty verso page in the document. The master page applied must contain no auto connected text frames. Ignored if the document is not double-sided. See Note 8 on page R-206. lastPage name Apply background from master page name to the last non- empty page in the document. The master page applied must contain no auto connected text frames. lastOddPage name Apply background from master page name to the last non- empty odd page in the document. The master page applied must contain no auto connected text frames. See Note 6 on page R-206. lastEvenPage name Apply background from master page name to the last non- empty even page in the document. The master page applied must contain no auto connected text frames. See Note 6 on page R-206. lastEmptyPage name Apply background from master page name to the last empty page in a document—for example the page added to make the page count even or odd. applyLastToFirst N | Y Apply the above last-page master page usage options even when the document contains only a single page. Default:N applyLastTagged N | Y Apply the above last-page master page usage options even if the last page is non-empty. In many cases, setting this option to Y will result in text overflowing into a new last page having and indeterminate format. Default:N Disconnected page disconnect Odd | Make page disconnected. Even | Default: None None /> Required R-204 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Notes 1 A code or by being the nearest code. 2 If the code ‘P’ option. 3 A destination page, or a set of destination pages, may satisfy several conditions simultaneously. For example, in a double-sided document an odd page may be either a recto or a verso page and the ‘oddPage’ page option may be set to have a different value to values specified for the ‘versoPage’ and ‘rectoPage’ options. Such conflicts are resolved as follows: – All recto and verso option values override all corresponding odd and even option values in each of the three categories: Default master page usage options, Exception master page usage options, and Last-page master page usage options. – In multi-page documents the values for last-page options listed under Last- page master page usage options override all other options. – The values for ‘Page’ and ‘allPages’ options have the lowest priority, in descending order. 4 To use a code, for example: Miramo Reference Guide [ v 9.2 ] R-205 Inline markup codes CHAPTER 3 6 Odd pages refer to odd numbered pages (i.e. 1,3,5,7...), where pages are numbered sequentially starting at 1 for the first page in the document. Even numbered pages refer to even numbered pages (i.e. 2,4,6,8...) where pages are numbered sequentially starting at 1 for the first page in the document. The starting page number setting is immaterial: if the first page number in a document is set to 2, or any other even number, by using the Numbering Properties dialog box in a FrameMaker template document, or by using the 1 ¡ R-206 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes 8 copycon=N > 9 14 The new master page rule specified in Example 15 ¡ The new master page rule specified in Example 3.63 is embedded in the output at the beginning of this sentence i.e. just after the ¡ character. If the next page immediately after the page where the ¡ character is shown is an odd page, then it will have the NewBackGround_Right master page format. If the next page immediately after the page where the ¡ character is shown is an even page, then it will have the NewBackGround_Left master page format. Succeeding odd and even pages will have NewBackGround_Right and NewBackGround_Left master page layouts applied to them. A will have its first page formatted as ‘First’, assuming that a master page called ‘First’ has been defined either in a template file or by using the will have its second page formatted as ‘First’, assuming there is no subsequent, overriding Miramo Reference Guide [ v 9.2 ] R-207 Inline markup codes CHAPTER 3 or will have its first page formatted as ‘First’, and all following pages will also be formatted as ‘First’ until the next the application of ‘First’ pages will begin from the second page of the document (unless overridden by a subsequent code ‘P’ option is not set to P, R or L, only the last code with a ‘P’ option setting of P, R or L, along with a Examples Examples illustrating basic usage of the Left R-208 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use Syntax Option Value Description Target frame selection options file filename Name of FrameMaker file in MIF format containing the frame [ filename ] to be extracted. frameNum int Extract the nth anchored frame in document. n is the sequence number representing the order in which anchored frames or equations were added to the target document. Default: 1 Rotation options Angle 0 | 90 | Angle to rotate imported MIF frame and its contents, 180 | measured counter-clockwise. 270 Default: 0 plusAngle 0 | 90 | Angle to rotate imported MIF frame and its contents, 180 | measured clockwise. 270 Default: 0 Frame dimensions W dim Width of frame. [ frameWidth ] Default: As set on imported MIF graphic frame H dim Height of frame. [ frameHeight ] Default: As set on imported MIF graphic frame Right Miramo Reference Guide [ v 9.2 ] R-209 Inline markup codes CHAPTER 3 Option Value Description Frame location options P b | T | B | I Position of anchored frame ( F N | Y Allow the frame to float. [ frameFloat ] Effective only if the ‘P’ option is set to b, T or B. Default: As set on imported MIF graphic frame A L | C | R | Horizontal alignment of frame. [ horizAlign ] nb | fb | Use the ‘A’ option to control horizontal positioning, either np | fp within or outside text columns and text frames. ‘P’ option values have different effects, depending on the value of the ‘P’ option (see above). The ‘P’ option is ignored if the ‘P’ option is set to I. Value Horizontal alignment L If ‘P’ set to b, T or B: at left, inside text column(s) Left R-210 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description If ‘P’ set to OF: at left, outside text frame If ‘P’ set to OC: at left, outside text column R If ‘P’ set to b, T or B: at right, inside text column(s) If ‘P’ set to OF: at right, outside text frame If ‘P’ set to OC: at right, outside text column C If ‘P’ set to b, T or B: centered, inside text column(s) nb If ‘P’ is set to any value other than I: align on side nearest page binding fb If ‘P’ is set to any value other than I: align on side farthest from page binding np If ‘P’ is set to OF or OC: align on side nearest page edge fp If ‘P’ is set to OF or OC: align on side farthest from page edge Default: As set on imported MIF graphic frame so dim Offset of frame from side of text column or text frame. [ sideOffset ] Effective only if the ‘P’ option is set to OC or OF. Value may be positive or negative. Default: As set on imported MIF graphic frame bo dim Offset of frame from text baseline. [ baselineOffset ] Effective only if the ‘P’ option is set to OC, OF or I. Value may be positive or negative. Default: As set on imported MIF graphic frame C N | Y Crop frame to fit in text column. [ frameCrop ] Effective only if the ‘P’ option is set to b, T or B. Default: As set on imported MIF graphic frame Text runaround RA N | B | C Text runaround type. [ runAround ] Value Description N No runaround B Box runaround C Contour runaround Default: As set on imported MIF graphic frame RAgap dim Specify the gap between the MifFrame and text flowing [ runAroundGap ] around it. The value of dim may be negative. Right Miramo Reference Guide [ v 9.2 ] R-211 Inline markup codes CHAPTER 3 Option Value Description Effective only if the ‘RA’ option (see above) is set to C or B. Default: As set on imported MIF graphic frame Frame border and fill styles pen 0 - 15 Pen pattern number. [ penNum ] Sixteen pen patterns for borders around anchored frame objects are available, from 0 (black) to 15 (none). (See Appendix 1, page R-531, for a description of fill patterns.) Default: As set on imported MIF graphic frame pw dim Pen width for border. [ penWidth ] Borders around all types of anchored frame thicken inwards towards the center of the anchored frame. (Note that this is different to the case of borders around a and fill 0 - 15 Fill pattern. As for ‘pen’ above. A ‘fill’ value of 15 makes the [ fillNum ] frame transparent. Default: As set on imported MIF graphic frame pstyle P | "dim Pen style. Solid or dashed. Setting ‘pstyle’ to P results in a [ penStyle ] dim ..." plain, solid border or line. Setting ‘pstyle’ to a series comprising an even number of dim values sets the border to have a dashed pattern. The first dim value specifies the length of a solid line segment, the next dim value specifies the length of a white segment, and so on. The pen pattern specification must be surrounded by double quotation marks. See Examples 2.14 and 2.15 on pages MD- 34 and MD-35 in the mmDraw Drawing Guide. Default: As set on imported MIF graphic frame Frame border and fill color color name Frame border and fill color. /> Required Left R-212 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Notes 1 The contents of the target anchored frame or equation are copied into the container document (i.e. the document that is created using the Right Miramo Reference Guide [ v 9.2 ] R-213 Inline markup codes CHAPTER 3 Summary The Syntax Option Value Description Display message in alert box. PDF: show Note. The alert message text is the text between the opening Left R-214 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description The alerttitle text Display alert box with given title and message given in [ alertTitle ] Right Miramo Reference Guide [ v 9.2 ] R-215 Inline markup codes CHAPTER 3 Summary Use the Syntax Option Value Description Hypertext and X-ref type & destination fmt H | X | B Type of destination link to create: [ destType ] Value Effect X Create cross-reference link H Create hypertext link B Create hypertext and cross-reference link Default:X id string string is a unique value indentifying a hypertext or cross- reference destination link, or both. The link type depends on the setting of the ‘fmt’ option (see above). For example: Horses usually have four legs, a head, Left R-216 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the Syntax Description ... Drawing codes See the Miramo mmDraw Reference Guide (PDF file drawguideNNN.pdf in installdir/docs). Required Every Notes 1 The drawing and graphic codes which may be used within a Examples Example 3.64 draws and ellipse and star. Right Miramo Reference Guide [ v 9.2 ] R-217 Inline markup codes CHAPTER 3 Example 3.64 Vector drawing using The output from Example 3.64 is shown in Figure 3.49. Example 3.65 shows how to produce a sim- ple line chart. The output from Example 3.65 is shown in Figure 3.50. When producing Temperature (Celsius) Figure 3.50 Output from Example 3.65 R-218 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary The Syntax Description Examples The following input assumes a default paragraph format in which hyphenation is switched on, either in the paragraph format in a FrameMaker template, or by set- ting the ‘H’ option in the code (see page R-226). The world has a circumference of 40,000 kilometers. The output from the above can be as shown The world has a circumfer- in Figure 3.51 at right: ence of 40,000 kilometers. Figure 3.51 Default hyphenation The next example shows the effect of suppressing hyphenation of the two longest words: The world has a Miramo Reference Guide [ v 9.2 ] R-219 Inline markup codes CHAPTER 3 [ Summary Use the code to begin a new paragraph or as a container for other objects, such as tables, anchored frames, and anchored text frames. A Miramo document will typically comprise from tens to hundreds of thousands of paragraphs. Paragraph tabstop and autonumbering properties may be set using the Syntax Option Value Description Reference pre-defined paragraph format fmt name name is paragraph tag name. If used, the ‘fmt’ option should [ pgfFormat ] be the first option on the code, to avoid overriding the values of preceding options, see Note 2 (on page R-228) and also Note 4 (on page R-228). If the ‘fmt’ option is omitted the settings of the preceding paragraph are inherited (and may optionally be overridden by the code options listed below, see Note 3 on page R- 228). Basic options A L | R | Justification. L = left only, R = right only, LR = left and [ justify ] LR | C right, C = center. fi dim First line indent. Distance of the first line of text from the left [ firstIndent ] side of a text column or from the left margin of a table cell. li dim Left indent (excluding the first line of the paragraph). Distance [ leftIndent ] of the second and succeeding lines of text from the left side of a text column or from the left margin of a table cell. R-220 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes [ Option Value Description ri dim Right indent. Distance of lines of text from the right side of a [ rightIndent ] text column or from the right margin of a table cell. sa dim Space above. Note that actual inter-paragraph spacing is [ spaceAbove ] determined by the larger of the space above the current paragraph and the space below the preceding paragraph, not the sum of the two. (This assumes that feathering between paragraphs is turned off.) sb dim Space below. See note above. [ spaceBelow ] un N | Y Use next paragraph. [ pgfUseNext ] Default:N np name Next paragraph tag. [ pgfNext ] Interline leading and line spacing mode l dim Leading. Default units are points. [ leading ] Leading is the space between lines within a paragraph. Line spacing (baseline to baseline) is leading plus point size of the text (see Figure 4.4 on page U-62 in the Miramo User Guide). ls F | P Line spacing. F = fixed (no adjustment for extra large [ lineSpacing ] characters, superscripts, inline anchored frames, etc.), P = proportional. Setting the ‘ls’ option to P prevents contact between text lines in cases where the text contains either larger than normal characters or inline anchored frames. Paragraph feathering FF int Feather factor. May be any positive integer. [ featherFactor ] Adds int hidden, zero depth, paragraphs ahead of the current paragraph except when the current paragraph is at the top of a text column. Setting the ‘FF’ option to a value greater than 0 has no effect unless feathering is switched on for the document, either via ‘Line Layout’ in a template file or by setting the Reference pre-defined font format F name Font tag. name may be either the name of a font definition [ fontFormat ] specified using the Miramo Reference Guide [ v 9.2 ] R-221 Inline markup codes CHAPTER 3 [ Option Value Description The following font options (below) override the settings of the ‘F’ option only if they are placed after the ‘F’ option in the sequence of options following the code. Font selection ff name Font family. See page R-137 in the Miramo Reference Guide. [ fontFamily ] fa name Font angle. See page R-137 in the Miramo Reference Guide. [ fontAngle ] fw name Font weight. See page R-138 in the Miramo Reference Guide. [ fontWeight ] fv name Font variation. See page R-138 in the Miramo Reference [ fontVariation ] Guide. Text size and color p dim | Text size. See Note 1 on page R-142. [ textSize ] rdim Default units are points (1/72 inches). See page R-138 in the Miramo Reference Guide. fcolor name Font color. See page R-138 in the Miramo Reference Guide. [ textColor ] Underline and overline uline N | S | D | Underline style. [ textUnderline ] M Value Description N No underline. S Single (normal) underline. D Double underline. M Numeric (low) underline. See page R-138 in the Miramo Reference Guide. Default:N o N | Y Overline. See page R-139 in the Miramo Reference Guide. [ textOverline ] Default:N Strike through and change bar t N | Y Strike through. See page R-139 in the Miramo Reference [ strikeThrough ] Guide. Default:N C N | Y Change bar. See page R-139 in the Miramo Reference Guide. [ changeBar ] Default:N R-222 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes [ Option Value Description Capitalization fc T | S | L | Capitalization. [ textCase ] U Value Description T As typed. S Small caps. L Lower case. U Uppercase. See page R-139 in the Miramo Reference Guide. Default:T Vertical and horizontal shift u N | Y Superscript. See page R-139 in the Miramo Reference Guide. [ superscript ] Default:N d N | Y Subscript. See page R-139 in the Miramo Reference Guide. [ subscript ] Default:N Ky percent Vertical displacement of text. See page R-140 in the Miramo [ vertShift ] Reference Guide. Default:0 Kx percent Horizontal text displacement. See page R-140 in the Miramo [ horizShift ] Reference Guide. Default:0 Kerning, character spread and stretch K Y | N Enable pair kerning and character spread. Also: enable [ textKern ] ligatures (Unix only). See page R-141 in the Miramo Reference Guide. Ks percent Inter-character spread, or tracking. See page R-141 in the [ textSpread ] Miramo Reference Guide. Default:0 fs percent Horizontally expand or compress characters. See page R-141 [ textStretch ] in the Miramo Reference Guide. Default: 100 textBGColor name Apply a background color to text. FrameMaker 10 and above only. See page R-141 in the Miramo Reference Guide. Default: no background text color Text language lang key Language. See page R-142 in the Miramo Reference Guide. [ textLanguage ] Miramo Reference Guide [ v 9.2 ] R-223 Inline markup codes CHAPTER 3 [ Option Value Description Letter and inter-word spacing (For examples showing the effect of the ‘gws’, ‘ows’, and ‘lws’ options below see the Miramo User Guide, Chapter 4 , pages U-58 –59.) cspace N | Y Allow additional letter spacing. [ letterSpacing ] Inter-word spacing in justified text may sometimes have to exceed the maximum specified by the ‘gws’ option (see below). In such cases, setting the ‘cspace’ option to Y will allow additional space to be added between letters within words to reduce excessive spacing between words. gws percent Maximum inter-word spacing. A value of 100 is equivalent to [ maxInterWord ] one quarter of an em space. ows percent Optimum inter-word spacing. A value of 100 is equivalent to [ optInterWord ] one quarter of an em space. lws percent Minimum inter-word spacing. A value of 100 is equivalent to [ minInterWord ] one quarter of an em space. Autonumbering an N | Y Enable autonumbering. [ autoNumber ] See the Pagination options (See also: Paragraph page or column placement P A | C | P | Paragraph placement. A = anywhere, C = top of column, P = [ pgfPosition ] L | R top of page, L = top of left page, R = top of right page. For single-sided documents (see the R-224 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes [ Option Value Description To apply a non-default master page, that is neither a ‘Left’ or ‘Right’ master page, nor the first body page in a template file, to the first page in a document then the ‘P’ option must be set to P and the first paragraph in the document must have a code with an associated TCN int | Start paragraph at the beginning of the nth auto-connected [ nextColNum ] int(warn) text column (see Note 5 on page R-229) on the current page. n may be any integer greater than 0. In the second form, int(warn), a warning message is produced if the paragraph cannot be placed as requested (see below). The string ‘(warn)’ must be typed exactly as shown. If the paragraph with ‘TCN’ set to n occurs in a text column whose sequence number on the page is less than n then that paragraph is moved to the top of text column n. If the paragraph with ‘TCN’ set to n occurs in a text column whose sequence number on the page is equal to or greater than n, or the value of n is greater than the total number of auto-connected text columns on the page, no action is taken except in the case the ‘TCN’ setting is followed by the warn keystring in parenthesis, as for example in, TCN="3(warn)" when, unless the paragraph is the first paragraph in text column n (i.e. 3 in the above example) a warning message will be written to standard error. The ‘TCN’ option cannot be used in a multi-columned text frame containing objects which straddle two or more columns (see Note 5 on page R-229). ‘P’ option settings of C and A are ignored when used in conjunction with the ‘TCN’ option. ‘P’ option settings of P, L and R, if present, take effect after the ‘TCN’ option takes effect. The ‘P’ option is described on page R-224. Run-in, in-column, side head or straddle Pf N | R | T | Paragraph placement format. N = normal, R = run-in, T = side [ alignFormat ] F | L | S | head top, F = side head first, L = side head last, S = straddle SN columns and side heads, SN = straddle columns only. rhp char The default punctuation for ending a run-in head. [ endRunInChar ] The default is ‘.’ (period). To have nothing, use the empty string, ie, ‘rhp=""’. Miramo Reference Guide [ v 9.2 ] R-225 Inline markup codes CHAPTER 3 [ Option Value Description Widow/orphan lines wo int Minimum number of widow/orphan lines. [ minLines ] Keep with next or previous paragraph wn N | Y Keep with next paragraph. [ withNext ] wp N | Y Keep with previous paragraph. [ withPrevious ] Reference frames above and below ts name Top separator. name is the name of a Reference page [ pgfFrameAbove ] graphics frame. The Reference page and named graphics frame may be created either by importing reference pages from a template file, or by using the code within a code ‘ts’ or ‘bs’ options respectively. Default: None bs name Bottom separator. name is the name of a Reference page [ pgfFrameBelow ] graphics frame. See ‘ts’ option above. Hyphenation options H Y | N Turn on hyphenation. [ hyphenate ] Hml int Maximum number of adjacent hyphenated lines. [ maxHyphens ] Hmp int Minimum number of characters before hyphen. [ minBeforeHyphen ] Hms int Minimum number of characters after hyphen. [ minAfterHyphen ] Hmw int Minimum word size to hyphenate. [ minWordSize ] R-226 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes [ Option Value Description Newline processing (output) nl N | R | RX Treat newline as hard return. N = newline is ignored, R = all [ newLines ] newlines are mapped to hard return character, RX = trailing newlines are stripped, remaining newlines are mapped to hard return character. The ‘nl’ option affects the current paragraph only and is not inherited by subsequent paragraphs. See Example 3.67 on R-229. Default:N Printing control options [ Unix only ] PSF 0 - 99 | 0 Printer special feature. The values 0 - 99, optionally [ printFeature ] - 99+n | followed by a plus sign and an integer, refer to user definable 0* - 99* commands for controlling the use of special features on PostScript printers. A single code may have up to 99 PSF option/value pairs. The values of the options must be in the range 0 to 99. The printer control commands take effect before the current page unless the command numbers are immediately (with no intermediate space) followed by ‘+n’, in which case the printer control command takes effect before the current +nth page. If the command numbers are immediately (with no intermediate space) followed by an asterisk, ‘*’, then the printer control command takes effect before the current page and also before all the following pages. The ‘PSF’ option is effective only when the printer name is prefixed with the string ‘mmpsf:’. A detailed description of how output device control works is given in Appendix 2 (see the Miramo Reference Guide pages R-533 –536). This Appendix should be read before using the ‘PSF’ option. Metadata options IDstring string string may contain up to 512 bytes of metadata associated with this instance of the P code. This metadata is shown in FrameMaker MIF files in the . Miramo Reference Guide [ v 9.2 ] R-227 Inline markup codes CHAPTER 3 [ Option Value Description code may be terminated by a code is terminated by any of the following: , code within a table cell may be terminated by any of the following: , , Notes 1 Typical usage of is as shown in Example 3.66 i.e. no override options are used. In general it is . . . better that instances of the code reference . . . pre-defined paragraph formats, either in the template file, or in the definitions section at the beginning of a . . . Miramo file (defined using makes maintenance of the document easier. . . . . . . 2 If override options are used in conjunction with the Example 3.66 Typical ‘fmt’ option, the ‘fmt’ option should be the first option usage of the code with no ‘fmt’ option (see page R-220) inherits the settings of the preceding paragraph, including any overrides that may be in effect for the preceding paragraph. Additional overrides may be added. The code inherits the font state as set by the preceding code. Font settings specified by instances of the code or the the point size specification ‘p=8’ will be ineffective,1 since it will be overridden by the point size specified for the ‘SwordFish’ font using the 1. This assumes that the point size setting for ‘SwordFish’ in the Character Designer is neither ‘As Is’, nor set to 8 points. Or, alternatively, that ‘SwordFish’ is defined using a R-228 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes [ Ordering options as above will ensure that ‘p=8’ is effective. The order of other options (apart from the ‘fmt’ option, see Note 2above) is not significant, except that if the same options are set more than once on the same code, then later values will override earlier values. For example, if using: will set the point size to 66 points. 5 The ‘TCN’ option affects the positioning of paragraphs at the top of text columns, not text frames. In cases where all text frames each contain just one text column this distinction is immaterial. However if a page contains two auto-connected text frames, the first with just one text column and the second with three text columns, then setting the ‘TCN’ option to 3 will move the paragraph to the top of the middle column of the second text frame. Examples Example 3.67 below shows how the ‘nl’ option (see page R-227) may be used to format software source code: initstrings(): initstrings(params, nparams) char *params[]; int nparams; { int i; for (i=0; i < nparams; i++) params[i]=(char *)NULL; } Example 3.67 Using the ‘nl’ option Miramo Reference Guide [ v 9.2 ] R-229 Inline markup codes CHAPTER 3 [ The output from Example 3.67 is shown in Figure 3.53. 12.3 initstrings(): initstrings(params, nparams) Example 3.68 illustrates using the char *params[]; Example 3.68 Using the will produce a seven page document. The first page will have the layout of the ‘First’ master page. All other pages will have the layout of the ‘Right’ master page, except for the fifth page, which will have the layout of the ‘Left’ master page. R-230 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the Syntax Option Value Description Page number style fmt curpage | Identifier for the page number format. [ pageNumType ] lastpage | Four corresponding page number format definitions are volnum | always defined in a FrameMaker template file, as follows: chapnum Value FrameMaker variable name curpage ‘Current Page #’ lastpage ‘Page Count’ volnum ‘Volume Number’ chapnum ‘Chapter Number’ Default: curpage /> Required Notes 1 If the Miramo Reference Guide [ v 9.2 ] R-231 Inline markup codes CHAPTER 3 Summary The code. The bookmark text, between the Syntax Option Value Description PDF bookmark structure options level int Bookmark level. [ bookmarkLevel ] See Note 2 on page R-233. Default:1 color %/%/% Color of bookmark text. [ bookmarkColor ] Default: 0/0/0 fa Regular | Font angle of bookmark text. [ fontAngle ] Italic Default: Regular fw Regular | Font weight of bookmark text. [ fontWeight ] Bold Default: Regular zoom percent Zoom level to show page containing bookmark destination. [ showAtZoom ] Default: current zoom level URI uri URI for bookmark. See Note 4 on page R-233. Default: none R-232 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description > Required Notes 1 If the input for a single output document or a book contains one or more Miramo Reference Guide [ v 9.2 ] R-233 Inline markup codes CHAPTER 3 Summary The Syntax Option Value Description page int int is the absolute page number the device request applies to. | +int +int applies the device request to the nth page after the | first current page. The value of n must be greater than 0. | next In this context the first page in the document is always page 1, regardless of page numbering settings. If the value of the ‘page’ option is first the device request applies to the first page in the document. first is an alias for 1. If the value of the ‘page’ option is next the device request applies to the page following the page containing the Notes 1 R-234 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes The duplex instruction in Example 3.69 will apply to the entire document, or until it is switched off. 2 If two or more 1 The 3 In the general case, if more than one Miramo Reference Guide [ v 9.2 ] R-235 Inline markup codes CHAPTER 3 Summary Use the Syntax Option Value Description name key key is the name of a page device parameter supported by the target output device. The value of key always begins with a ‘/ ’ character. See Note 2 on page R-237. value string string may be any PostScript value type that is appropriate for the setpagedevice key value specified by the ‘name’ option (see above). E.g. PostScript array, boolean, dict (dictionary), integer, number, null or string data types. Data type Format array The array data type comprises two or more numbers enclosed within matching square brackets, e.g. [ 392 628 ]. See Note 4 on page R-237. boolean The boolean data type may be either true or false. See Note 5 on page R-237. dict A value that begins with ‘/ ’ or a ‘/ ’ preceded by one or more spaces or tabs is treated as a dictionary value. The PostScript ‘<<’ and ‘>>’ dictionary operators must be omitted when the value data type is dictionary. See Note 6 on page R-238. integer Any appropriate integer, e.g. 7. See Note 7 on page R-238. number Any appropriate number, e.g. 42.5. See Note 8 on page R-238. null The string null. string The string data type comprises a string of text enclosed within matching round brackets, e.g. (BluePaperTray). See Note 9 on page R-239. R-236 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description /> Required Notes 1 The PostScript setpagedevice operator is described in the PostScript Language Reference Manual, Third Edition, Adobe Systems Incorporated, Addison- Wesley, Reading, Mass. 1999. ISBN 0-201-37922-8, Chapter 6, pages 391— 456. 2 The specific setpagedevice instructions supported an output device are listed in the vendor documentation and in the PPD file for the device. 3 The functioning of similarly, or identically, named setpagedevice instructions can vary on devices from different vendors. Tests should be conducted on the target output device to check the operation of specific output device control instructions. 4 Example 3.72 shows a setpagedevice instruction in raw PostScript PPD file format that contains a key value having data type of array. << /PageSize [612 729] >> setpagedevice Example 3.72 PostScript setpagedevice array data type The 5 Example 3.74 shows a setpagedevice instruction in raw PostScript PPD file format that contains key values having data type of boolean. << /Duplex true /Tumble true >> setpagedevice Example 3.74 PostScript setpagedevice boolean data type The Miramo Reference Guide [ v 9.2 ] R-237 Inline markup codes CHAPTER 3 If the In Example 3.76 the /PunchDetails key has a dictionary value in the form: <> The 1 Note that the ‘<<’ and ‘>>’ raw PostScript dictionary operator strings are not included within the ‘value’ option (see line 3 in Example 3.77). 7 Example 3.78 shows a setpagedevice instruction in raw PostScript PPD file format that contains key values having data type of integer. << /NumCopies 1 >> setpagedevice Example 3.78 PostScript setpagedevice integer data type The 8 Example 3.80 shows a setpagedevice instruction in raw PostScript PPD file format that contains key values having data type of number. R-238 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes << /MediaWeight 101.5 >> setpagedevice Example 3.80 PostScript setpagedevice number data type The 9 Example 3.82 shows a setpagedevice instruction in raw PostScript PPD file format that contains key values having data type of string. << /MediaType (BluePaper) >> setpagedevice Example 3.82 PostScript setpagedevice string data type The Miramo Reference Guide [ v 9.2 ] R-239 Inline markup codes CHAPTER 3 Summary Use Syntax Option Value Description Type and location options type H | B | F Type of row. [ rowType ] H = Header row. B = Body row. F = Footer row. A table must contain at least one body row. Default:B wn N | Y Keep this row with next row. [ withNext ] wp N | Y Keep this row with previous row. [ withPrevious ] Row text column/page placement P A | C | L | Row placement. A = anywhere, C = at top of column, L = at [ rowPlacement ] R | P top of page (left), R = at top of page (right), P = at top of page. This option has no effect if the table start position is set to float by setting the Row height options maxh dim Max permissible height of row. [ maxHeight ] minh dim Minimum permissible height of row. [ minHeight ] h dim Fixed height of row. [ rowHeight ] R-240 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Condition setting for row cond namelist namelist is a comma separated list of condition tag(s) to be [ conditions ] applied to the row. The tags may have been set up within the definitions section using the Cell options Cell fill and color (default for all cells in row) fill 0 - 15 Fill pattern. When used with the color name Background color. When used with the Cell border rulings (default for all cells in row) lr name Left ruling. The ruling designations (left, right, top and [ leftRule ] bottom) are unaffected if the cell is rotated, ie. cell rotation using the ‘a’ option changes the orientation of the cell contents, not its edge rulings. name is the name of a ruling format in a referenced FrameMaker template, or defined using the tr name Top ruling. See ‘lr’ above. [ topRule ] rr name Right ruling. See ‘lr’ above. [ rightRule ] br name Bottom ruling. See ‘lr’ above. [ bottomRule ] Cell margins (default for all cells in row) cm dim All cell margins, i.e. left, top, right and bottom, for all cells in [ allMargins ] table. Miramo Reference Guide [ v 9.2 ] R-241 Inline markup codes CHAPTER 3 Option Value Description Overrides the default margin specified in the table format, if any. If the ‘cm’ option is used in conjunction with any of the ‘clm’, ‘ctm’, ‘crm’ or ‘cbm’ cell margin options (see below), the latter will be ineffective unless it follows the ‘cm’ option. Default units are points. clm dim Cell left margin, for all cells in table. [ leftMargin ] Overrides the default left margin specified in the table format, if any. Default units are points. Text will not cross the left side of the cell when a negative dimension is given. ctm dim Cell top margin. [ topMargin ] Overrides the default top margin specified in the table format, if any. Default units are points. A negative top margin dimension may cause text to move above the top of the cell. crm dim Cell right margin. [ rightMargin ] Overrides the default margin specified in the table format, if any. Default units are points. Text will not cross the right side of the cell when a negative dimension is given. cbm dim Cell bottom margin. [ bottomMargin ] Overrides the default bottom margin specified in the table format, if any. Default units are points. A negative bottom margin dimension may cause text to move below the bottom of the cell. Cell text and margin rotation (default for all cells in row) a 0 | 270 | Orientation of text in cell. Rotation is clockwise. [ cellOrientation ] 90 | 180 Note that the placement orientation of cell rulings (as specified by the ‘lr’, ‘tr’, ‘rr’ and ‘br’ options) always remains fixed regardless of cell text orientation. Cell margins, as specified by both the R-242 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Vertical alignment of cell text (default for all cells in row) Ca T | M | B Cell vertical alignment of paragraph contents within cell: [ verticalTextAlign ] T = top of cell, M = middle of cell, B = bottom of cell. The orientation for ‘T’ (top) and ‘B’ (bottom) changes with cell rotation. For example, if Metadata options IDstring string string may contain up to 512 bytes of metadata associated with this instance of the Row code. This metadata is shown in FrameMaker MIF files in the Notes 1 All options may be used on the code options is shown on pages R-220–228. 2 Miramo Reference Guide [ v 9.2 ] R-243 Inline markup codes CHAPTER 3 Examples A 1 2 16 These goats did nothing but sleep all day and all night 17 and so that is the end of this story. 20 The Three The output from Example 3.84 is baa a a | Once upon a time, a shown in Figure 3.54. very long time ago, in a See Chapter 2, ‘Tables’, in the land over the hills and far across the seas, Miramo User Guide, pages U-13– there lived three goats 35, for further examples and dis- cussion. These goats did Goats nothing but sleep all The Three day and all night and so that is the end of this story. Figure 3.54 Output from Example 3.84 R-244 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the code to execute an operating system command from within Miramo. The standard output, if any or if it is not re-directed elsewhere, is treated as input to Miramo. The code may appear anywhere within the input file. Note that to include the code (processing instruction) in the out- put from mmxslt (or any other XSLT stylesheet processor) it is necessary to use the Syntax Description command ?> Required . Notes 1 The code can include any system commands. Pipes and I/O re- direction are supported. 2 The special file names /dev/null (Unix) and NUL (Windows) may be used to discard output from the code. On Unix, error messages written to standard error are automatically discarded. Under Windows, error messages may be discarded by redirecting the standard error (file descriptor 2) of a command to the special filename NUL. The example below illustrates discarding the error message produced when an attempt is made to remove a non-existent file using the Windows ‘del’ command: NUL ?> 3 A warning message is issued if the command returns an exit status other than 0. Miramo Reference Guide [ v 9.2 ] R-245 Inline markup codes CHAPTER 3 4 Example 3.85 shows an XSLT stylesheet fragment which illustrates how a processing instruction might be constructed using an XSLT stylesheet template. It is not possible to include any processing instruction in the mmxslt output by writing a processing instruction in the XSLT stylesheet. Processing instructions in the stylesheet are ignored completely. The code (processing instruction) in Example 3.86 > logfile ?> Example 3.86 Null code in XSLT is ignored. Examples Example 3.87 shows how the Unix operating system command ‘date’ could be used to create insert the current date within paragraph text: Today Example 3.87 Using the code The output from Example 3.87 is Today is: Tue Mar 3 15:35:33 PST 2009? shown in Figure 3.55. Note that the standard output from the system com- Figure 3.55 Output from Example 3.87 mand is included directly within the output. R-246 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use one or more Syntax Option Value Description pos dim Distance of the tabstop from the left edge of the text column [ tabPosition ] or the left margin of a table cell. Default:A A L | R | C | Alignment. [ tabAlign ] D Default:L leader string Leader string. [ tabLeader ] Default:A achar int Alignment character for ‘decimal’ tabstops, given as its ASCII [ tabAlignChar ] character code, for example 46 for the ‘.’ character, 44 for the ‘,’ character. Effective only if ‘achar’ is set to D (decimal alignment). Default:46 /> Required Notes 1 Tab stop setting overrides applied using the code will be inherited by subsequent codes. 2 See the Miramo Reference Guide [ v 9.2 ] R-247 Inline markup codes CHAPTER 3 Examples The following example illustrates using multiple The output from Example 3.88 is shown in Figure 3.56 at right. 22,34 13222,40 Changing the Example 3.88 R-248 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the , Syntax Option Value Description Notes 1 If the code paragraph alignment (‘A’ option) is set to R (right) or C (center) the tabstop settings are ignored. 2 See the Examples Example 3.89 illustrates using the 1 Miramo Reference Guide [ v 9.2 ] R-249 Inline markup codes CHAPTER 3 The ExPageHead paragraph format definition included in Example 3.89 is used in Example 3.90. 1 2 5 Left 7 Left 9 The output from Example 3.90 1 Left Center ...... Right is shown in Figure 3.58. 2 Left Center ...... Right and wrong 3 Left Center ...... Right way 4 Left Center ...... Right of way Figure 3.58 Output from Example 3.90 R-250 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the code, or after a code followed by text, anywhere outside an anchored frame, footnote or format definition. One or more Syntax Option Value Description Reference pre-defined table format fmt name name is the table format name. If included, the table format [ tblFormat ] name must appear before any other options. If no table format name is given, then the default Miramo table format is used. The default Miramo table format is described in the Miramo User Guide on pages U-17–18. Width of table with proportional column(s) tblWidth dim | Specify how to calculate the overall width of table when one auto or more column widths are set to be proportional using the Miramo Reference Guide [ v 9.2 ] R-251 Inline markup codes CHAPTER 3 Option Value Description auto Calculate the total table width based on the width of the table container less the applicable values specified for the table left and right indents. If the table is not within a table cell the calculation of the total table width is additionally determined by the value of the ‘tblWidthExtent’ option. If the table is within a table cell using the tblWidthExtent F | C | S | If the ‘tblWidth’ option is applicable and is not set to dim, A specify the extent of the overall width of table, provided the table is not within a table cell. Value Description F[rame] Adjust table width to width of text frame containing the first table row, less the table left and right indent values. C[olumn] As F above, except width is adjusted relative to text column width. S[idehead] As F above, except width is adjusted relative to sidehead width. If sideheads are not enabled for the text flow, the table width is adjusted relative to the text column width, as in C above. A[llColumns] As F above, except width is adjusted relative to the total of all current text-flow column widths plus all column gap widths, less the sidehead width. If sideheads are not enabled for the text flow, the table width is adjusted relative to the text frame width, as in F above. R-252 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description The ‘tblWidthExtent’ option is ignored if all table column widths are specified as fixed by setting all Increment or chop column count n int Number of columns in table, if different to the number of [ numColumns ] columns in a referenced table format, and greater than the number of column widths specified using Basic options li dim Left indent. The ‘li’ option is ignored if the ‘A’ option is set to [ tblLeftIndent ] R (see below), unless used with the ri dim Right indent. The ‘ri’ option is ignored if the ‘A’ option is set [ tblRightIndent ] to L (see below), unless used with the sa dim Space above. [ tblSpaceAbove ] sb dim Space below. [ tblSpaceBelow ] A L | C | R Horizontal alignment of table within text column. [ tblHorizAlign ] Value Horizontal alignment L Left C Center R Right Additional ‘A’ options, usable with the Miramo Reference Guide [ v 9.2 ] R-253 Inline markup codes CHAPTER 3 Option Value Description P A | F | C | Table placement. [ tblPosition ] P | L | R Value Placement A Anywhere F Float C Top of column P Top of page L Top of left page R Top of right page Note that these ‘P’ options are not usable with the wo int Minimum number of widow/orphan rows. [ minRows ] anc R | C Autonumbering direction for paragraphs and footnotes [ tblAutonumAxis ] within the table. R = numbering across rows, C = numbering down columns. Cell margins (default for all cells in table) cm dim All cell margins, i.e. left, top, right and bottom, for all cells in [ allMargins ] table. Overrides the default margin specified in the table format, if any. If the ‘cm’ option is used in conjunction with any of the ‘clm’, ‘ctm’, ‘crm’ or ‘cbm’ cell margin options (see below), the latter will be ineffective unless it follows the ‘cm’ option. Default units are points. clm dim Cell left margin, for all cells in table. [ leftMargin ] Overrides the default left margin specified in the table format, if any. Default units are points. Text will not cross the left side of the cell when a negative dimension is given. ctm dim Cell top margin. [ topMargin ] Overrides the default top margin specified in the table format, if any. Default units are points. A negative top margin dimension may cause text to move above the top of the cell. crm dim Cell right margin. [ rightMargin ] Overrides the default margin specified in the table format, if any. R-254 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description Default units are points. Text will not cross the right side of the cell when a negative dimension is given. cbm dim Cell bottom margin. [ bottomMargin ] Overrides the default bottom margin specified in the table format, if any. Default units are points. A negative bottom margin dimension may cause text to move below the bottom of the cell. Outside border rulings (In the following name must be the name of a Ruling defined in a template file or by using the lr name Left outside ruling. [ leftRule ] tr name Top outside ruling. [ topRule ] rr name Right outside ruling. [ rightRule ] br name Bottom outside ruling. [ bottomRule ] lbr N | Y Use ruling on last row. Y means draw bottom rule on last [ lastRuleOnly ] sheet only; N means draw rule on the bottom of every sheet. Header, footer (HF) & body row rulings (In the following name must be the name of a Ruling defined in a template file or by using the HFr name Ruling style used between rows in the heading and footing. [ HFRowRule ] Br name Default ruling used for body rows. [ bodyRowRule ] sr name Separator ruling. [ HFSeparatorRule ] name is the name of the separator ruling to use between the last heading row and the first body row and between the last body row and the first footing row. Exception (X) body row rulings xBr name Exception ruling for body rows. Used for every nth row [ bodyRowXRule ] (where n is specified using the ‘xBrp’ option). Default: None (i.e. the exception rule for body rows is to have no ruling between every nth body row). Miramo Reference Guide [ v 9.2 ] R-255 Inline markup codes CHAPTER 3 Option Value Description xBrp int Ruling period. Use the ruling specified with the ‘xBr’ option [ bodyRowXRulePeriod ] on every n rows. If ‘xBrp’ is set to 0 the exception ruling is never used. If ‘xBrp’ is set to 1 the exception ruling is used between every body row. If ‘xBrp’ is set to 2 the exception ruling is used between every second body row, and so on. Like all other table rulings, exception rulings are always overridden by any ruling options used with Column rulings (In the following name must be the name of a Ruling defined in a template file or by using the cr name Default column ruling for most columns. [ colRule ] Exception (X) column rulings xcn int Column number with right side which uses table column [ colXRuleNum ] ruling specified with ‘xcr’ option. xcr name Exception ruling for columns. Ruling style for column number [ colXRule ] specified using ‘xcn’ option. Header and footer (HF) fill and color HFfill 0 - 15 Header/Footer fill value HFcolor name Header/Footer color Table body fill and color shadeAxis R | C Table shading axis. R = shade by row. C = shade by column. [ tblShadeAxis ] Bfill 0 - 15 Body cells fill value. Default fill pattern for most body cells (see [ tblBodyFill ] ‘xBfill’ for exceptions to this). Bcolor name Body cells color. Default color for most body cells (see [ tblBodyColor ] ‘xBcolor’ for exceptions to this). Bp int Body shading period. The number of consecutive body [ bodyShadeNum ] columns/rows which use the shading values specified with the ‘Bfill’ and ‘Bcolor’ options above Exception (X) body fill and color xBfill 0 - 15 Exception fill pattern for body columns or body rows. [ tblXBodyFill ] xBcolor name Exception color for body columns or body rows. [ tblXBodyColor ] R-256 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description xBp int Exception body shading period. Number of consecutive [ xBperiod ] columns/rows which use the exception body shading values specified with the ‘xBfill’ and ‘xBcolor’ options. Exception column or row shading alternates with default body column or row shading to form a repeating pattern Table title options TP A | B | N Default table title placement. A = above table, B = below [ titlePosition ] table, N = no title. Only effective if the table instance contains a Tpf name Paragraph format for title of new table created with this [ titlePgfFormat ] format Only effective if the table instance contains a Tgap dim Table title gap [ titleGap ] Only effective if the table instance contains a fill 0 - 15 Background fill for all cells in the table. [ tblFill ] Note that the default for all cells in tables derived from the "Format A" and "Format B" table formats in standard Frame template files is 15, i.e. all cells have no fill and are transparent. This option overrides the ‘HFfill’ option (see above). Default: 7, opaque, no color color name Default background color for all cells in the table. The fill [ tblColor ] value of cells must be in the ranges 0-6 and 8-14 for the color setting to be effective, i.e. it is always necessary to set cell fill values within these ranges in order to get any cell background color or fill to become visible. This option overrides the ‘HFcolor’ option (see above). Cell text and margin rotation (default for all cells in table) a 0 | 270 | Orientation of text in cell. Rotation is clockwise. [ cellOrientation ] 90 | 180 Note that the placement orientation of cell rulings (as specified by the ‘lr’, ‘tr’, ‘rr’ and ‘br’ options) always remains fixed regardless of cell text orientation. Cell margins, as specified by both the Miramo Reference Guide [ v 9.2 ] R-257 Inline markup codes CHAPTER 3 Option Value Description Frame background color fcolor name Pen and fill color for the frame. [ tblFrameColor ] Default: Black Frame location options P b | T | B | I Position of anchored frame (or anchored reference frame, [ framePosition ] | R | OC | anchored table frame or anchored text frame) fF N | Y Allow the table to float. [ frameFloat ] Effective only if the ‘P’ option is set to b, T or B. Default:N A L | C | R | Horizontal alignment of table. [ horizAlign ] nb | fb | Use the ‘A’ option to control horizontal positioning, either np | fp within or outside text columns and text frames. R-258 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description ‘P’ option values have different effects, depending on the value of the ‘P’ option (see above). The ‘P’ option is ignored if the ‘P’ option is set to I. Value Horizontal alignment L If ‘P’ set to b, T or B: at left, inside text column(s) If ‘P’ set to OF: at left, outside text frame If ‘P’ set to OC: at left, outside text column R If ‘P’ set to b, T or B: at right, inside text column(s) If ‘P’ set to OF: at right, outside text frame If ‘P’ set to OC: at right, outside text column C If ‘P’ set to b, T or B: centered, inside text column(s) nb If ‘P’ is set to any value other than I: align on side nearest page binding fb If ‘P’ is set to any value other than I: align on side farthest from page binding np If ‘P’ is set to OF or OC: align on side nearest page edge fp If ‘P’ is set to OF or OC: align on side farthest from page edge Default: C, or L when ‘P’ is set to R, OF or OL. fso dim Offset of table from side of text column or text frame. [ sideOffset ] Effective only if the ‘P’ option is set to OC or OF. Value may be positive or negative. Default:0 fbo dim Offset of table from text baseline. [ baselineOffset ] Effective only if the ‘P’ option is set to OC, OF or I. Value may be positive or negative. Default:0 fC N | Y Crop table to fit in text column. [ frameCrop ] Effective only if the ‘P’ option is set to b, T or B. Default:N RAgap dim Specify the gap between the Miramo Reference Guide [ v 9.2 ] R-259 Inline markup codes CHAPTER 3 Option Value Description Frame border and fill styles fpen 0 - 15 Pen pattern number. [ penNum ] Sixteen pen patterns for borders around anchored frame objects are available, from 0 (black) to 15 (none). (See Appendix 1, page R-531, for a description of fill patterns.) Default:15 fpw dim Pen width for border. [ fpenWidth ] Borders around all types of anchored frame thicken inwards towards the center of the anchored frame. (Note that this is different to the case of borders around a and ffill 0 - 15 Fill pattern. As for ‘pen’ above. A ‘fill’ value of 15 makes the [ fillNum ] frame transparent. Default: 7 (opaque no fill) pstyle P | "dim Pen style. Solid or dashed. Setting ‘pstyle’ to P results in a [ penStyle ] dim ..." plain, solid border or line. Setting ‘pstyle’ to a series comprising an even number of dim values sets the border to have a dashed pattern. The first dim value specifies the length of a solid line segment, the next dim value specifies the length of a white segment, and so on. The pen pattern specification must be surrounded by double quotation marks. See Examples 2.14 and 2.15 on pages MD- 34 and MD-35 in the mmDraw Drawing Guide. Default:P Frame border and fill color color name Frame border and fill color. Metadata options IDstring string string may contain up to 512 bytes of metadata associated with this instance of the Tbl code. This metadata is shown in FrameMaker MIF files in the R-260 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Notes 1 Every table must include at least one body code, or within paragraph text. 2 An illustration of the Miramo Reference Guide [ v 9.2 ] R-261 Inline markup codes CHAPTER 3 The output from Example Item 1 1. This assumes that the ‘fso’ and ‘fbo’ option values are zero. Using negative values for these options may bring a ‘disappeared’ table into view. R-262 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Examples See Chapter 2, ‘Tables’, in the Miramo User Guide, pages U-13–35, for examples and further discussion. Miramo Reference Guide [ v 9.2 ] R-263 Inline markup codes CHAPTER 3 Summary Use one or more Syntax Option Value Description Applicable number of columns count int Apply options on this Cell options The Paragraph options The code options except for the pagination options ‘P’, ‘TCN’, ‘Pf’, ‘rhp’, ‘wo’, ‘wn’ and ‘wp’, and the flow and printing control options ‘FF’ and ‘PSF’ (see pages R-220–230). /> Required R-264 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Notes 1 A single empty code ‘fmt’ option is used it must appear before any other options. Examples Example 3.94 illustrates the usage of the 1 2 Miramo Reference Guide [ v 9.2 ] R-265 Inline markup codes CHAPTER 3 The output from Example 3.94 is shown in Figure 3.62. 12 345 Example 3.94 contains two heading 2 Africa Asia rows (see lines 11 and 12). 3 North South East West 4 A B C D 5 2 3 4 5 62 345 Figure 3.62 Output from Example 3.94 R-266 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use one or more Syntax Option Value Description pos dim Distance of the tabstop from the left edge of the text column [ tabPosition ] or the left margin of a table cell. Default:A A L | R | C | Alignment. [ tabAlign ] D Default:L leader string Leader string. [ tabLeader ] Default:A achar int Alignment character for ‘decimal’ tabstops, given as its ASCII [ tabAlignChar ] character code, for example 46 for the ‘.’ character, 44 for the ‘,’ character. Effective only if ‘achar’ is set to D (decimal alignment). Default:46 /> Required Notes 1 Tab stop setting overrides applied using the code will be inherited by subsequent codes. 2 See the Miramo Reference Guide [ v 9.2 ] R-267 Inline markup codes CHAPTER 3 Examples The following example illustrates using multiple The output from Example 3.88 is shown in Figure 3.56 at right. 22,34 13222,40 Changing the Example 3.88 R-268 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use one or more Syntax Option Value Description Specify fixed or proportional table column width(s) W dim | p* Required [ colWidth ] Column width, either fixed (W="dim", eg W="2cm") or proportional (W="p*", eg W="2.5*"). p may be any positive number. In the case of a proportional table column width, the actual width is calculated automatically from the overall width of the table, taking the other column widths into account, and using the number (p) before the ‘*’ character as a proportional weighting to apply to this column width. See Notes 2 through 6, starting on page R-270. count int Apply this column width to the following int columns, [ numColumns ] counting from one for this column. Default:1 minW dim For proportional column widths only (W=p*), set the [ minColWidth ] minimum allowed column width. See Note 5 on page R-271. Default: 5mm /> Required Notes 1 The number of columns in the table is set to the number of column widths specified using the Miramo Reference Guide [ v 9.2 ] R-269 Inline markup codes CHAPTER 3 2 Assuming the table is not in a table cell, the calculation of actual column widths from proportional column widths takes the following values into account: tblWidth: Overall width of table specified by the R-270 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes If only fixed table column widths are given, and there is no Examples The following examples illustrate fixed-width columns and how proportional col- umn widths are calculated. Tables with fixed-width columns The following: produces an empty single row, four column table with all column widths set to 0.25 inches, as shown in Figure 3.65. Figure 3.65 Output from Example 3.96 Example 3.97 below produces an empty four column ( 1 Miramo Reference Guide [ v 9.2 ] R-271 Inline markup codes CHAPTER 3 In Example 3.98 the sum of all ‘p’ values, propTotal, is 4 (1* × 2 + 2* × 1, from lines 2 and 3). The total width of the table, tblWidth, is set to Figure 3.67 Output from Example 3.98 50 mm (see line 1 in Example 3.98) and the first and fourth columns are set to have a fixed width of 5 mm each. Thus the total width available for proportional columns (propWidthAvailable) is (table width - sum of all fixed widths) = (50 - 10) = 50 mm. The actual width of each proportional column is derived as follows: column 1 = 5 mm wide (fixed) column 2 = ( 1 / 4 ) × 40 = 10 mm wide column 3 = ( 1 / 4 ) × 40 = 10 mm wide column 4 = 5 mm wide (fixed) column 5 = ( 2 / 4 ) × 40 = 20 mm wide The output from Example 3.98 is shown in Figure 3.67. Note that the row depth is greater than the row depth in Examples 3.65 and 3.97. This is because Example 3.98 references the FrameMaker ‘Format A’ table format, which uses the ‘Cell- Body’ paragraph format in body rows. The point size of ‘CellBody’ and the cell margin sizes in the ‘Format A’ table format are all bigger than their equivalent when a 1 In Example 3.99 the sum of all ‘p’ values, propTotal, is 4 WTextFrame (1* × 2 + 2* × 1, from lines ‘li’ w1 w2 w3 w4 ‘ri’ 3 and 4). WTbl-A The total width of the table, Figure 3.68 Output from Example 3.99 tblWidth, is derived from (Dashed lines show text frame border.) the width of the text frame containing the first row of the table less the sum of the table left and right indents. The output from Example 3.99 is shown in Figure 3.68. tblWidth in Figure 3.68 is indicated by the dimension WTbl-A and is calculated thus: R-272 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes WTbl-A = WTextFrame - (‘li’ + ‘ri’) where WTextFrame is the width of the enclosing text frame (or text column, if the WTextFrame = 65 mm WTbl-A = 65 mm - (6 mm + 7 mm) = 52 mm W2 = (WTbl-A - W1) * 1 / 4 = (52 mm - 8 mm) * 1 / 4 = 11 mm W3 = (WTbl-A - W1) * 1 / 4 = (52 mm - 8 mm) * 1 / 4 = 11 mm W4 = (WTbl-A - W1) * 2 / 4 = (52 mm - 8 mm) * 2 / 4 = 22 mm Auto-sizing tables to width of table cells When a table with proportional column widths is included within a table cell or within a set of horizontally spanned table cells the calculations for the included table left offset and the included table width are as follows: leftOffset = ‘clm’ + ‘li’ tblWidth = cellWidth - (‘clm’ + ‘li’ + ‘crm’ + ‘ri’) leftOffset is the distance between the centerline of the left border of the container cell and the centerline of the left outside border of the included table. tblWidth is the calculated total with of the included table. cellWidth is the width between the centerlines of the left and right borders of the container cell(s). The container cell left margin and the included table indent dimensions ‘clm’, ‘li’ and ‘ri’ are as shown in Figure 2.22 on page U-32 in the Miramo User Guide. In contrast with the case of an included table with all columns fixed width1, the size of the container cell right margin, ‘crm’, is taken into account in calculating the overall table width in the case of a table with proportional width columns included in a table cell. Including a table with proportional-width columns in a table cell is illustrated in Example 3.100, which is an extended version of Example 3.99. 1 1. The cell right margin dimension, ‘crm’, is not shown in Figure 2.22 on page U-32 (in the Miramo User Guide) because it has no effect on the calculation of the table width of a table within a table cell when the column widths of the included are all fixed width. Miramo Reference Guide [ v 9.2 ] R-273 Inline markup codes CHAPTER 3 9 A B C The output placement and extent of the included table in Example WTbl-A 3.100 is illustrated in Figure 3.69. w1 w2 w3 w4 The regions between the left, top, right and bottom of the included table overall extent (red dashed A B C box outline1) and the container cell borders comprise the container cell WTbl-B margins only, since the included table has zero left and right Figure 3.69 Output from Example 3.100 (The red dashed border designates the overall extent indents. The regions above and of the included table.) below the table within the included table extent are the values for space above and space below the included table. Example 3.101 illustrates how to automate the inclusion of a table with propor- tional-width columns within a table cell so that the outside borders of the included table are aligned with the borders of the container cell. 1 A B C 1. The term ‘table overall extent’ used here has the same meaning as the term ‘tableframe area’ used in sec- tion Tables within tables on pages U-31–33 in the Miramo User Guide R-274 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes 17 18 Example 3.101 Aligning borders of container cell and included table The output from Example 3.101 is illustrated in Figure 3.70. Example 3.101 is identical to Example 3.100 with the exception that a special set of overrides is included (shown in bold text). Setting the container cell ‘cm’ option to 0 (line 5 in Example 3.101) and the included table ‘li’, ‘ri’, ‘sa’ and ‘sb’ options to 0 and the ‘P’ option to R (line 8 in Example 3.101) ensures that the borders of the included table align with the borders of the container cell(s). In Example 3.101 the centerlines of the borders are aligned. In the case WTbl-A different border styles and thick- w1 w2 w3 w4 nesses are used for the container A B C cell and the included table then the WTbl-B dimensions of the container cell Figure 3.70 Output from Example 3.101 margins must be adjusted, to allow for half the thickness of each contiguous border. Miramo Reference Guide [ v 9.2 ] R-275 Inline markup codes CHAPTER 3 Summary Use the Syntax Description Examples The example given on page R-277 illustrates the use of both the R-276 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the Syntax Description Notes 1 If the input contains no Examples The example below illustrates the use of the Miramo Reference Guide [ v 9.2 ] R-277 Inline markup codes CHAPTER 3 On the first page, the title Table 1: List of Parts and header will be as shown in Figure 3.71, with the ... The second page will be as Table 1: List of Parts ( Continued ) shown in Figure 3.72. ...... Table page 2 of 3 Figure 3.72 Output from Example 3.102 (second page of table) R-278 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use Syntax Option Value Description fmt name name is optional paragraph format name (overrides the [ pgfFormat ] default table title paragraph format). All code options may be used with code options on pages R-220–228). Note that several code options, such as the pagination options and table cell options, have no effect when used with TP A | B Title position. A = above table. B = below table. [ titlePosition ] Tgap dim Gap between table title and table. [ titleGap ] > Required Notes 1 The presence or absence of a , Miramo Reference Guide [ v 9.2 ] R-279 Inline markup codes CHAPTER 3 Examples Example 3.103 creates a right aligned table (the ‘A’ option is set to R) with just two heading rows, one body row and 3 columns, and a table title. The output from Example 3.103 is Main title shown in Figure Col 1 Col 2 Col 3 3.73. If the table is con- Col 1 Col 2 Col 3 tinued on one or ABC DEF GH more pages, both the title and all the Figure 3.73 Output from Example 3.103 heading rows are repeated at the top of the table. Graphics, logos, etc, may be included in table titles or headings. A ‘table continued’ indicator may be included with the table title, using inline markup codes, as shown in Example 3.104. Secondary title R-280 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the code to import selected format catalogs and page layouts from a named MIF (Maker Interchange Format) template file. This file will nor- mally have been created on-screen using FrameMaker's WYSIWYG formatting capabilities. If no individual format option is specified, the default is to copy all formatting information from the specified template document. It is usually more convenient to specify the template file name and import options using the Miramo ‘-Tfile’ and ‘-Tformats’ or ‘-TXformats’ command line options (see pages R-19–20), or the -Cfile command line option (see page R-19). Syntax Option Value Description Template type file filename Required [ tplFile ] Absolute or relative name of template file. Files may be referenced using environment variables, as in ${FILENAME} (see the ‘-sendEnv’ command line option on page R-7). In this case environment variable names must be surrounded by curly braces. If the filename contains spaces it must be surrounded by double quotation marks. Note that the filename is required (see Example 3.105 on page R-283). The other options given to the command specify which formatting information is to be included from the specified template file. Extraction formats p Y | N Paragraph catalog. [ pgfCatalog ] f Y | N Font catalog. [ fontCatalog ] k Y | N Color catalog. [ colorCatalog ] See the Miramo Reference Guide [ v 9.2 ] R-281 Inline markup codes CHAPTER 3 Option Value Description l Y | N Page layout. All master pages (including running headers and [ pageCatalog ] footers) and body pages are copied from the specified template document. To include document formats and page size use the ‘L’ option, or the ‘l’ and ‘d’ options. d Y | N Document settings. See the L Y | N Page layout and document formats. See the R Y | N Reference pages. [ referencePages ] v Y | N Variable definitions. [ varDefs ] x Y | N Cross reference formats. [ xrefFormats ] t Y | N Table format catalog. This does not copy the ruling catalog [ tblCatalog ] information for table rules. See the ‘r’ option below. r Y | N Ruling catalog. [ rulingCatalog ] c Y | N Condition catalog. [ conditionCatalog ] /> Required . (Alternatively followed by with no text between the and the .) Notes 1 The MIF template file must contain no errors, and its layout must conform to that specified in the MIF reference manual. The best way of creating a template file is to save a FrameMaker document in MIF format. 2 As mentioned above, it is usually more convenient to specify the template file name and import options using the Miramo ‘-Tfile’ and ‘-Tformats’ or ‘-TXformats’ command line options (see pages R-19–20). 3 Format options may be specified in any order. 4 The Color Views catalog is always imported. To change the color view setting use the R-282 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes 5 To use a Miramo output file as a Miramo template, open the file in FrameMaker and save it out as MIF. This can be automated using DZbatcher (see www.miramo.com). Examples The following copies the page layout, document formats, and paragraph and font catalogs from the MIF template file ‘template.mif’ into the current document: p=Y L=Y /> Example 3.105 Simple usage Another, slightly more verbose, way of specifying the same thing is as follows, using the ‘l’ and ‘d’ options in place of the ‘L’ option above: p=Y l=Y d=Y /> Example 3.106 Alternative usage The following will include everything from the template file: Example 3.107 Most basic usage The following will include everything from the template file except for color defini- tions: /> Example 3.108 Copy all except for color definitions Miramo Reference Guide [ v 9.2 ] R-283 Inline markup codes CHAPTER 3 Summary Use the Syntax Option Value Description Notes 1 When running Miramo with the ‘-m’ or ‘-Mfile’ options it may also be necessary to use the <@suspend> and <@resume> mmpp functions (described on pages R-527 and R-525). Examples The following input: R-284 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes <@macro> CodeListing { <#def> fname {$1} <#def> listcmd {cat} " ; <#listcmd> <#fname> ; echo "" ?> } A file listing could then be included using: <|CodeListing> program.c Generally you should use a monospaced font for source code listings of any type. You should also pre-process the source code file to replace tabs with spaces. This is because Frame products treat tabs differently to most source code editors. The standard Unix pr command, available for Windows NT as part of the MKS Toolkit (http://www.mks.com), provides a simple way of replacing tabs with spaces, as well as pre-pending line numbers in source code listings. Miramo Reference Guide [ v 9.2 ] R-285 Inline markup codes CHAPTER 3 Summary Use the Syntax Option Value Description Include in foreground body page text flow or named master page background text frame target name Specify the destination, or target, for the contents within the [ targetName ] type F | B Specify whether the target text flow is foreground body page [ targetType ] text flow or a text flow within one or more named background text frames on a master page. Value Description F The destination is the first body page text flow. with a name matching the value set by the ‘target’ option. R-286 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Option Value Description B The destination is the text flow within a master page background text frame that has a name matching the value set by the ‘target’ option. If there is more than one instance of such a text flow, the contents within the append N | Y By default pre-existing contents of a text flow addressed by the createDefault Y | N If the ‘type’ option is set to F and no matching named body page text flow is found on the body pages of a FrameMaker template document, or is created using a Miramo Reference Guide [ v 9.2 ] R-287 Inline markup codes CHAPTER 3 Option Value Description auto N | Y Set autoconnect on or off. The ‘auto’ setting on later [ autoConnect ] sh N | Y Allow room for side-heads in this text flow. [ sideheads ] Sidehead and other text flow properties are specified either in a referenced FrameMaker template document or by using the code ‘Pf’ option (described on page R-225). Default: N Delete text flow delete N | Flow | Delete text flow, or text flow and container text frames, name [ deleteFlow ] Frame as specified by the ‘target’ option (see page R-286). If the main text flow, usually flow ‘A’, the results may be unexpected. Value Description Flow Delete contents of text flow name. Frame Delete contents of text flow name and delete associated container text frames. Default: N > Required Notes 1 There are two methods for naming a master page background text frame. – Set the R-288 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes document, view its Object Properties and set the value on-screen.1 2 If the input stream contains multiple code. To override the default properties, use a code with the desired options and values. If no corresponding text flow is found, the default paragraph format used is ‘Body’: the text is 12 point TimesNewRoman with a 2 point inter-line leading, and the space above and below is 0. All default paragraph settings may be overridden by using a code that includes format overrides. Examples The following three examples are equivalent: This is the beginning of a long document .... ... and this is the end 1. Note that mmTFName.dll must be available to the FrameMaker session that is used to create or edit the FrameMaker template document. On Windows NT this .dll is installed in the .\fminit\Plugins folder within the FrameMaker installation folder by double-clicking on the file mmTFNameSetupex.exe. On Unix this .dll may be installed by typing ./mmTFName.bin in a user window. Both files are included in the Standard Miramo distribution. Miramo Reference Guide [ v 9.2 ] R-289 Inline markup codes CHAPTER 3 This is the beginning of a long document .... ... and this is the end This is the beginning of a long document .... ... and this is the end Example 3.109 below shows using 1 2 3 21 22 Page R-290 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes 34 L="0.4in" T="4.5in" W="3.2in" H="0.3in" 35 fill="15" pen="0" color="Red" > 36 History of the world Apples 44 51 56 Texte et plus de texte. Texte et davantage de texte. 57 Texte et texte supplementaire ... 3.109 comprises a complete Miramo document. Apples If the text in Example 3.109 is con- Page 1 of 1 tained in a file called, say, Texte et Text and ‘mydoc.mm’, then running the com- plus de more text. mand: texte. Texte Text and et davantage more text ... miramo -Omif mydoc.mif de texte. 5.0 in mydoc.mm Texte et will produce a document with a run- texte sup- ning header and footer and two body plementaire ... text flows, as shown in Figure 3.74. Textflow "B" is in the left columnar text frame. Textflow "A" is in the right History of the world columnar text frame. 4.0 in Lines 2 through 37 in Example 3.109 comprise format definitions only, and Figure 3.74 Output from Example 3.109 (scaled to 45%) may be replaced by a reference to a FrameMaker template document with a similar layout. Miramo Reference Guide [ v 9.2 ] R-291 Inline markup codes CHAPTER 3 Summary Use the Syntax Description Notes 1 The Examples See the example of using R-292 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Summary Use the code to include a user variable instance (i.e. the variable's value.) Variable values are defined either in a template file or by using the Syntax Option Value Description Name of variable to include at this point fmt name name is the name of the variable. [ varName ] /> Required . (Alternatively followed by with no text between the and the .) Examples See Example 3.110 on page R-295 for an example of using the code to insert a named variable in paragraph text. Miramo Reference Guide [ v 9.2 ] R-293 Inline markup codes CHAPTER 3 Summary Use Syntax Option Value Description Define (assign value to) variable fmt name name is the name of the variable. [ varName ] > Building blocks The following building blocks may be used between deftext deftext is any or all of: text, binary newline characters and tabs. All newlines are mapped to space characters. Binary tabs are preserved unless the ‘-striptabs’ command line option is used. Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhhhh;). R-294 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes Examples Example 3.110 illustrates defining ( is a software application for automated document composition. command line options are shown on page ... Example 3.110 Defining and using named variables with Example 3.110 produces output similar to that shown in Figure 3.75. Miramo is a software application for automated document composition. Miramo command line options are shown on page ... Figure 3.75 Output from Example 3.110 Miramo Reference Guide [ v 9.2 ] R-295 Inline markup codes CHAPTER 3 Summary Use the Syntax Option Value Description Cross-reference format name, ID and file fmt name Required [ xrefFormat ] name is the name of a cross-reference format, either defined in a template file or by using the id string Required [ ID ] string is the destination identifier. The destination identifier, specified using the file filename filename is the file name of the document containing the destination identifier. If the ‘file’ option is omitted, the destinations is assumed to be in the current file. /> Required Examples The standard ‘Portrait’ template document shipped with Frame products includes a cross reference format named ‘See Heading & Page’, which is referred to using the R-296 Miramo Reference Guide [ v 9.2 ] CHAPTER 3 Inline markup codes options on pages R-89 and R-113 for information on importing format definitions from Frame template files. Alternatively, the ‘See Heading & Page’ cross reference format may be defined using the In Example 3.112 the cross-reference id is inserted at the beginning of a para- graph of text about horses, as follows: Horses are quadrupeds which have hooves, but unlike camels, they have no humps. Example 3.112 Creating a hidden cross reference destination id Figure 3.76 shows the paragraphs as they would be printed. The cross ref- Horses erence destination id text ‘X-horses’ Horses are quadrupeds which have hooves, but unlike camels, they is not shown as it is hidden marker have no humps. text: Figure 3.76 Output from Example 3.112 In the same document, a cross refer- ence may be made to the ‘X-horses’ destination id using the Camels have humps and four legs, but are unlike their fellow quadrupeds, horses. In the output shown in Figure 3.77, Camels have humps and four legs, the Miramo Reference Guide [ v 9.2 ] R-297 Inline markup codes CHAPTER 3 R-298 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Format definitions enable some or all aspects of the appearance a document to be defined without reference to a FrameMaker template file. The use of format definitions explicitly is entirely optional: some or all format definitions may be referenced from a template file using the code (see page R-281) and the ‘-Tfile’ or ‘-Cfile’ and ‘-Tformats’ command line options (see page R-19). Note that it is possible to import format definitions from a template file and define addi- tional formats of the same type using format definition codes. Formats defined using for- mat definition codes override those defined in and requested from, a template file.1 For example, if a template file contains a paragraph format called ‘Heading1’ and the input includes a Summary of format definition codes A summary of the format definition codes is shown below. Table 4.1 Summary of format definition codes Code name Page Text codes Master page codes Table format definition codes 1. To allow imported template format definitions to override the Miramo format definitions, see the ‘-Toverride’ command-line flag on page R-20. Miramo Reference Guide [ v 9.2 ] R-299 Format definitions CHAPTER 4 Table 4.1 Summary of format definition codes ( Continued ) Code name Page Variable definitions Post processing codes Miscellaneous codes There are 25 format definition codes in total. Structure of format definitions The general form of a format definition code is as follows: The list of whitespace (space, tab or newline) separated option=value pairs is optional, and is terminated with the ‘>’ option end symbol. In the case where there is no text and/or markup between the start code/option end sym- bol ( Example 4.3 illustrates several different forms for the content-free R-300 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Note that attempting to use the content-free end code as well as the format definition end code, as in the following example, will cause an error: Example 4.5 shows the Page Where format definitions may be used In general format definitions may occur anywhere in the Miramo input stream apart from within a footnote ( 1. Note however that the Miramo Reference Guide [ v 9.2 ] R-301 Format definitions CHAPTER 4 Property inheritance The order of format definition instances within certain groups is significant. For example, successive paragraph format definitions, using the Precedence It is possible to combine format definitions extracted from a template file with format def- initions explicitly defined within a Miramo file. In the event that the same format tag is defined in both places the Miramo format definition will by default1 take precedence over the format definition in the template file. A partial exception to this occurs when a 1. To allow imported template format definitions to override the Miramo format definitions, see the -Tover- ride command line flag on page R-20. 2. Control over how text columns and other objects are added to pre-existing master pages is achieved using the R-302 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Summary Use Syntax Option Value Description Define variable for background text frame fmt 1 - 12 Identifying number for the background ‘running text’ [ bgVarNum ] variable. Twelve corresponding variable format definitions are always defined in a FrameMaker template file, as follows: Value FrameMaker variable 1 ‘Running H/F 1’ 2 ‘Running H/F 2’ 3 ‘Running H/F 3’ n ‘Running H/F n’ (n <= 12) > Building blocks The following building blocks may be used between deftext deftext is any or all of: text, binary newline characters and tabs. All newlines are mapped to space characters. Binary tabs are preserved unless the ‘-striptabs’ command line option is used. Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhhhh;). Miramo Reference Guide [ v 9.2 ] R-303 Format definitions CHAPTER 4 Option Value Description R-304 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description If the ‘select’ option, shown in the second syntax definition above, is set to last, then the Notes 1 The default background variable definitions are shown in the section Default background variable definitions on page R-306 and correspond to the FrameMaker system variable names ‘Running H/F 1’, ‘Running H/F 2’, ‘Running H/F 3’ and ‘Running H/F 4’. 2 If there are two or more Examples The following illustrates setting up a dictionary style running header/footer which picks up the text of the first and last occurrence of a ‘EntryName’ paragraph on each page. Miramo Reference Guide [ v 9.2 ] R-305 Format definitions CHAPTER 4 Firstly, the type 1 and 2 This is equivalent to using FrameMaker to create a template where the ‘Running H/F 1’ system variable is defined as: <$paratext[EntryName]> and the ‘Running H/F 2’ system variable is defined as: <$paratext[+,EntryName]> Secondly, a reference to these two background text variables is inserted in a back- ground (untagged) text frame on the default ‘Right’ master page using the This is equivalent to using FrameMaker to insert the ‘Running H/F 1’ and ‘Run- ning H/F 2’ system variables in the ‘Right’ master page header text frame in a tem- plate file. An input file which includes the format definitions shown in Example 4.7 and which contains the following paragraphs: Albatross ... Cockatoo ... will produce a running header as shown in Figure 4.1. Albatross - Cockatoo 2 Figure 4.1 Dictionary style header See Example 3.19 on page R- 80 for another illustration of using R-306 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Miramo Reference Guide [ v 9.2 ] R-307 Format definitions CHAPTER 4 Summary Use Syntax Option Value Description Color format name fmt name Required [ colorName ] name is color format name. None of the FrameMaker reserved colors may be used as a CMYK values If one or more of the following CMYK options is set, the color model is assumed to be CMYK. c percent Percentage cyan. [ Cyan ] Default:0 m percent Percentage magenta. [ Magenta ] Default:0 y percent Percentage yellow. [ Yellow ] Default:0 k percent Percentage black. [ Black ] Default:0 RGB values If one or more of the following RGB options is set, and no CMYK options are set, the color model is assumed to be RGB. r percent Percentage red. [ Red ] Default:0 g percent Percentage green. [ Green ] Default:0 b percent Percentage blue. [ Blue ] Default:0 R-308 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description Color tint If the ‘tintBase’ and the ‘tintBase’ options all other options are ignored. tintBase name The name of the color from which the tint is derived. Default: Black tint percent 100% indicates solid color. Less than 100% indicates a [ tintPercent ] reduced percentage of the color. Ignored unless ‘tintBase’ is specified. Spot colors The following options are for defining a spot color. If the ‘libraryName’ and the ‘inkName’ options all other options are ignored. libraryName key Color library name. The ‘libraryName’ option is used with the ‘inkName’ option (see page R-310) to specify a spot color ink. Key Color library name crayon 'Crayon'. Key alias: Crayon. Example ink name: Apricot. dic 'DIC COLOR GUIDE SPOT'. Key alias: DICcolor. Example ink name: lp. focol 'FOCOLTONE'. Key alias: focoltone. Example ink name: 1070. greys 'Greys'. Key alias: Greys. Example ink name: 1% Grey.prcs. mun-hi 'MUNSELL® High Chroma Colors'. Key alias: munsellHighChroma. Example ink name: 2.5R 7:10. mun-bk 'MUNSELL® Book of Color'. Key alias: munsellBook. Example ink name: 2.5R 9:1. online 'Online'. Key alias: Online. Example ink name: 001-990033. panC 'PANTONE® Coated' Key alias: pantoneCoated. Example ink name: Yellow. panPS 'PANTONE® ProSim'. Key alias: pantoneProSim. Example ink name: Process Yellow. panU 'PANTONE® Uncoated'. Key alias: pantoneUncoated. Example ink name: Yellow. panPE 'PANTONE® Process Euro'. Key alias: pantoneProcessEuro. Example ink name: E1-1. Miramo Reference Guide [ v 9.2 ] R-309 Format definitions CHAPTER 4 Option Value Description panPSE 'PANTONE ProSim EURO®'. Key alias: pantoneProSimEuro. Example ink name: Process Yellow. panPCSG 'PANTONE® Process CSG'. Key alias: pantoneProcessCSG. Example ink name: 1-1. toyo 'TOYO COLOR FINDER'. Key alias: Toyo. Example ink name: 0001pc*. tru 'TRUMATCH 4-Color Selector'. Key alias: Trumatch. Example ink name: 1-a. custom 'mmCustom'. Key alias: mmCustom. Example ink name: myInk. inkName name Use the ‘inkName’ option to specify the name of an ink within the color library specified by the ‘libraryName’ option (see page R-309). The ‘inkName’ option requires the ‘libraryName’ option. Valid ink names for a color library may be found from the FrameMaker color definitions GUI. Ink density print option o N | Y Y = Overprint. N = Knockout. [ overprint ] Default:N /> Required Notes 1 The following is a list of FrameMaker reserved colors: Black, White, Red, Green, Blue, Cyan, Magenta, Yellow, Dark Grey, Pale Green, Forest Green, Royal Blue, Mauve, Light Salmon, Olive and Salmon. 2 The following is a default color definition: R-310 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions 3 Color definitions do not inherit properties from preceding color definitions. A short Examples The following defines a new color called ‘p165’: Miramo Reference Guide [ v 9.2 ] R-311 Format definitions CHAPTER 4 Summary Use Syntax Option Value Description Define the view and print status of a color vn 1 | 2 | 3 | Apply change in color status to color view n, where n is any [ viewNum ] 4 | 5 | 6 integer from 1 to 6. (See the color name Name of color, as defined in a FrameMaker document [ colorName ] template or by using the status cutout | Change the status of the color to cutout or invisible. [ viewStatus ] invisible /> Required Notes 1 The R-312 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Summary Use the Syntax Option Value Description Define condition properties fmt name Required [ conditionName ] name is condition format name. show N | Y Y=show or N=hide text tagged with this condition. [ conditionShow ] Note that all conditional text will be shown in the resulting document even if ‘show’is set to N, unless the cstyle A | D | U | Character style format override. [ conditionStyle ] S | O A = As Is, D = double underline, U = underline, S = strikeout, O = overline. The format override is not applied if the color name Color format override. [ conditionColor ] Specifies name of color used to display text tagged with this condition. The color format override is not applied if the Miramo Reference Guide [ v 9.2 ] R-313 Format definitions CHAPTER 4 Notes 1 By default, all conditional text in the generated document is shown with the format overrides specified by the individual condition tags. 2 Document wide condition settings are specified using the Examples In Example 4.8, a condition tag named "Model_58.NCp.33" is created, where text tagged with this condition will be displayed in the resulting document. Text will be highlighted in red with underlining. . . . Another illustration of using the R-314 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Summary Use Syntax Option Value Description Define a date format fmt ldate | Identifying label for the date format. [ dateFormat ] sdate | Six corresponding date format definitions are always defined lmdate | in a FrameMaker template file, as follows: smdate | lcdate | Value FrameMaker variable name scdate ldate ‘Current Date (Long)’ sdate ‘Current Date (Short)’ lmdate ‘Modification Date (Long)’ smdate ‘Modification Date (Short)’ lcdate ‘Creation Date (Long)’ scdate ‘Creation Date (Short)’ > Building blocks The following building blocks may be used between deftext deftext is any or all of: text, binary newline characters and tabs. All newlines are mapped to space characters. Binary tabs are preserved unless the ‘-striptabs’ command line option is used. Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhhhh;). Miramo Reference Guide [ v 9.2 ] R-315 Format definitions CHAPTER 4 Option Value Description R-316 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description Notes 1 The default date formats shown in the Default date formats section on page R- 318 may be suitable for use in most cases. 2 If there are two or more Examples Here is an example of redefining the default onlcdate (long creation date) format using 1 2 Miramo Reference Guide [ v 9.2 ] R-317 Format definitions CHAPTER 4 4 Inserting Note that spaces are treated as literals. Tabs characters are treated as tab spacing requests. A single space is added to the end of each line automatically. Default date formats The default R-318 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Summary Use the Syntax Option Value Description Page layout options pm dim Document page margins. The left, top, right and bottom [ allMargins ] margins are set to dim. Value is ignored unless number of columns (‘cn’) value is specified. Default: 1in plm dim Left margin. Value is ignored unless number of columns (‘cn’) [ leftMargin ] value is specified. Default: 1in ptm dim Top margin. Value is ignored unless number of columns (‘cn’) [ topMargin ] value is specified. Default: 1in prm dim Right margin. Value is ignored unless number of columns [ rightMargin ] (‘cn’) value is specified. Default: 1in pbm dim Bottom margin. Value is ignored unless number of columns [ bottomMargin ] (‘cn’) value is specified. Default: 1in W dim Page width. If the value of the ‘W’ option is less than the [ pageWidth ] value of the ‘H’ option (see below) the document is portrait; otherwise it is landscape. The minimum width allowed is 1 mm (ca. 0.04 inches). Miramo Reference Guide [ v 9.2 ] R-319 Format definitions CHAPTER 4 Option Value Description H dim Page height. If the value of the ‘H’ option is greater than the [ pageHeight ] value of the ‘W’ option (see above) the document is portrait; otherwise it is landscape. The minimum height allowed is 1 mm (ca. 0.04 inches). cn int Number of sub-columns within a text column. The size of the [ numColumns ] enclosing text column is specified using the page margin options above, and the width and gap between sub-columns is specified using the ‘cn’ and ‘cg’ options above. Note that this option is ignored unless one or more page margin option values are set, and can be overridden using the cg dim Gap between columns. Note that this option is ignored unless [ columnGap ] page margin options are set. See the ‘pm’, ‘plm’, ‘ptm’, ‘prm’ and ‘pbm’ options above. Page numbering pn int Starting page number. (Negative values are permitted.) [ pageNumStart ] pnf A | Page number format. A = Arabic, UA = UCAlpha, [ pageNumStyle ] UA | LA | LA = LCAlpha, UR = UCRoman, LR = LCRoman UR | LR Pagination options pd N | Y Y = double-sided. N = single-sided. [ doubleSided ] pf Right | First page. L = left, R = right. [ startSide ] Left (Applies only in the case of double-sided documents, i.e. when the ‘pd’ option is set to Y.) pr D | E | O | Page rounding prior to save/print. D = delete blank pages, [ lastPageRule ] F E = make page count even, O = make page count odd, F = fix page count Main text flow options f N | Y Y = turn feathering on. N = turn feathering off. [ feather ] Default:N sh N | Y Y = allow room for side-heads. N = no room for side-heads. [ sideheads ] Default:N maxl dim Maximum inter line spacing. Default units are points. [ maxLinePad ] R-320 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description maxp dim Maximum inter paragraph spacing. Default units are points. [ maxPgfPad ] Conditional text defaults csa Y | N Controls document-wide conditional text display. [ condTextShow ] Value Description Y Show all conditional text (overrides individual condition show/hide settings), N Show or hide text according to conditional text settings. Default:Y cfo N | Y Controls use of format overrides to highlight conditional text. [ condTextOverrides ] Y = display text using conditional text format overrides, N = display conditional text with no format overrides. Default:Y Volume numbering options The following options set up the VN Cont | How to compute volume number. [ volNum ] Same | Value Description File Cont Continue from previous book component. Aliases: cont, Continued and continued. Same Same as previous book component. File Read from file. If the ‘VN’ option is used, the ‘VNstyle’, ‘VNstring’ and ‘VNstart’ options are ignored. The default is determined by the ‘VNstyle’, ‘VNstring’ and ‘VNstart’ options. To restart numbering from 1, use the ‘VNstart’ option. VNstyle A | UA | Sets volume number style. [ volNumStyle ] LA | UR | Value Description LR | C A Arabic. UA Uppercase alpha. LA Lowercase alpha. UR Uppercase roman. LR Lowercase roman. C Custom. Miramo Reference Guide [ v 9.2 ] R-321 Format definitions CHAPTER 4 Option Value Description If ‘VNstyle’ is set to C the value of ‘VNstring’ is used for the VNstring string Set custom volume number string. [ volNumString ] ‘VNstring’ is ignored if the ‘VN’ option is used, Ignored unless ‘VNstyle’ is set to C. VNstart int Set volume number. [ volNumStart ] ‘VNstart’ is ignored if the ‘VN’ option is used, or if ‘VNstyle’ is set to C. Default:1 Chapter numbering options The following options set up the CN Cont | How to compute chapter number. [ chapNum ] Same | Value Description File Cont Continue from previous book component. Aliases: cont, Continued and continued. Same Same as previous book component. File Read from file. If the ‘CN’ option is used, the ‘CNstyle’, ‘CNstring’ and ‘CNstart’ options are ignored. The default chapter number is determined by the ‘CNstyle’, ‘CNstring’ and ‘CNstart’ options. To restart chapter numbering from 1, use the ‘CNstart’ option. CNstyle A | UA | Sets chapter number style. [ chapNumStyle ] LA | UR | Value Description LR | C A Arabic. UA Uppercase alpha. LA Lowercase alpha. UR Uppercase roman. LR Lowercase roman. C Custom. R-322 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description If ‘CNstyle’ is set to C the value of ‘CNstring’ is used for the CNstring string Set custom chapter number string. [ chapNumString ] ‘CNstring’ is ignored if the ‘CN’ option is used. Ignored unless ‘CNstyle’ is set to C. CNstart int Set chapter number. [ chapNumStart ] ‘CNstart’ is ignored if the ‘CN’ option is used, or if ‘CNstyle’ is set to C. Default:1 Paragraph numbering options PN Cont | Paragraph numbering. [ pgfNum ] Restart | Value Description File Cont Continue. Aliases: cont, Continued and continued. Restart Restart from 1. File Read from file. Default: Restart Document footnote properties fp name Paragraph tag for document footnotes. [ FNotePgf ] fn int Footnote start number. If either the ‘fs’ option or the ‘cs’ [ FNoteStart ] option is used, this number is ignored. fh dim Maximum height allowed for footnotes. [ FNoteMaxHeight ] fs perPage | Footnote numbering style. perPage = restart on each page, [ FNoteNum ] perFlow perFlow = start number sequentially from 1, or from the number specified with the ‘fn’ option if used. fc string Characters used in custom document footnote numbers if the [ FNoteSymbols ] ‘fnf’ option is set to C (custom footnote numbering format). Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhh;). However if the requested character is not available in the current font, it will be ignored with a warning message. Default: "* " (star, dagger and double dagger) Miramo Reference Guide [ v 9.2 ] R-323 Format definitions CHAPTER 4 Option Value Description faP U | B | D Anchor position: placement of document footnote number in [ FNoteAnchor ] text. U = superscript, B = baseline, D = subscript fnP U | B | D Number position: placement of number within footnote text. [ FNoteNumPos ] U = superscript, B = baseline, D = subscript fnf A | C | UA Footnote number format. A = Arabic, C = Custom, [ FNoteStyle ] | LA | LR UA = UCAlpha, LA = LCAlpha, UR = UCRoman, LR = LCRoman See ‘fc’ option for custom numbering specification. fap string Anchor prefix: prefix to appear before document footnote [ FNoteAnchorPrefix ] number in text. fas string Anchor suffix: suffix to appear after document footnote [ FNoteAnchorSuffi number in text x ] fnp string Number prefix: prefix to appear before number in document [ FNotePrefix ] footnote. fns string Number suffix: suffix to appear after number in document [ FNoteSuffix ] footnote. Table footnote properties tfp name Paragraph format for table footnotes. [ tblFNotePgf ] tfc string Characters used in custom table footnote numbers if the ‘fnf’ [ tblFNoteSymbols ] option is set to C (custom page numbering format). Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhh;). However if the requested character is not available in the current font, it will be ignored with a warning message. Default: "* " (star, dagger and double dagger) tfaP U | B | D Anchor position: placement of table footnote number in table [ tblFNoteAnchorPos ] cell. U = superscript, B = baseline, D = subscript tfaP U | B | D Number position: placement of number within table footnote [ tblFNoteNumPos ] text. U = superscript, B = baseline, D = subscript tfnf A | C | UA Table footnote number format. A = Arabic, C = Custom, [ tblFNoteStyle ] | LA | LR UA = UCAlpha, LA = LCAlpha, UR = UCRoman, LR = LCRoman. See ‘tfc’ option for custom numbering specification. tfap string Table footnote anchor prefix: prefix to appear before table [ tblFNoteAnchorPrefix ] footnote number in table cell. R-324 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description tfas string Table footnote anchor suffix: suffix to appear after table [ tblFNoteAnchorSuffix ] footnote number in table cell. tfnp string Table footnote number prefix. Prefix to appear before table [ tblFNotePrefix ] footnote number in table cell. tfns string Table footnote number suffix. Suffix to appear after number [ tblFNoteSuffix ] in table footnote. Paragraph line-break characters lb chars OK to break lines at these characters. [ lineBreakChars ] Default: "/ - " (slash, minus, endash, emdash) Run in head punctuation characters pc chars Set of punctuation characters not to be stripped from run-in [ punChars ] heads. Default document language lang key Language used for hyphenation and spell-checking of text [ textLanguage ] lines. key may be: None, NoLanguage, USEnglish, UKEnglish, German, SwissGerman, French, CanadianFrench, Spanish, Catalan, Italian, Portuguese, Brazilian, Danish, Dutch, NewDutch, NewGerman, NewSwissGerman, Norwegian, Nynorsk, Swedish, Japanese, SChinese, SimplifiedChinese, TChinese, TraditionalChinese, Korean. Change bar properties cbg dim Change bar gap. Distance of change bar from edge of [ changebarGap ] column. cbw dim Thickness of change bar. [ changebarWidth ] cbp L | R | N | Change bar position. L = left of column, R = right, [ changebarPos ] F N = nearest page edge, F = furthest page edge cbc name Change bar color. [ changebarColor ] cbauto N | Y Automatic change bars. [ changebarAuto ] Miramo Reference Guide [ v 9.2 ] R-325 Format definitions CHAPTER 4 Option Value Description View-only (locked) document options v N | Y View only document. [ viewonly ] vx G | O | N Change behavior of active cross references in view only [ xrefMode ] document. G = goto behavior, O = open behavior, N = not active. vs N | Y | U User selection allowed?. N = No, Y = Yes, U = user only [ selectMode ] (enable user selection with no highlighting). vb N | Y Display borders in view only document. [ viewBorders ] vm N | Y Display menu bars in view only document. [ showMenu ] vp N | Y Display popup menus in view only document. [ showPopups ] vpl N | Y Makes window behave as command palette window in view [ cmdPalette ] only document. Quotation marks, superscript, subscript and small caps settings sq Y | N Smart quotes. [ smartQuotes ] ss Y | N Smart spaces. [ smartSpaces ] us percent Superscript size as percentage of current text size. [ superscriptSize ] ds percent Subscript size as percentage of current text size. [ subscriptSize ] cs percent Small caps size as percentage of current text size. [ smallcapsSize ] ud percent Superscript displacement (up) as percentage of text size. [ superscriptPos ] dd percent Subscript displacement (down) as percentage of text size. [ subscriptPos ] Color printing options pb N | Y Print blank pages. [ printBlankPages ] ps N | Y Print separations. [ printSeparations ] R-326 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description npcolor namelist Comma separated list of colors not to print. [ noPrintColors ] pcolor namelist Comma separated list of process colors to be printed. [ printColors ] Document view options vn 1 | 2 | 3 | Set color view number (see Note 1, on page R-328). [ viewNum ] 4 | 5 | 6 g N | Y Display grid on. [ showGrid ] gp dim Display grid interval. [ gridSpace ] gs dim Snap grid interval [ snapSpace ] gr real Snap rotation interval (degrees). [ snapAngle ] r N | Y Display rulers on opening document. [ showRuler1 ] rf N | Y Display formatting ruler (icons above top ruler) on opening [ showRuler2 ] document G Y | N Display graphics. If set to N, images and drawn objects are not [ showGraphics ] displayed or printed. b Y | N Display borders. [ showBorders ] s Y | N Display text symbols. [ showSymbols ] Window (on-screen display( options wL int Position of left edge of Frame document window in pixels. [ windowLeft ] Default:0 wT int Position of top edge of Frame document window in pixels. [ windowTop ] Default:0 wW int Width of Frame document window in pixels. [ windowWidth ] Default: from document page size wH int Height of Frame document window in pixels. [ windowHeight ] Default: from document page size Miramo Reference Guide [ v 9.2 ] R-327 Format definitions CHAPTER 4 Option Value Description Dz int Zoom setting. [ windowZoom ] /> Required Notes 1 A FrameMaker template contains six different color view settings. The default view is View 1 in which, by default, all colors are visible except for White, which is set to Cutout. In Views one through six any defined color may be switched to being Normal (visible), Cutout or Invisible. The Examples The following code sample shows an instance of a The following is the R-328 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions H = 215.9mm cg = 0 plm = 20mm ptm = 20mm prm = 20mm pbm = 20mm wL = 50 wT = 60 wW = 690 wH = 800 Dz = 140 pn = 1 pnf = A ppnf = A pd = Y pf = R F = N pr = D maxl = 2pt maxp = 6pt fp = Footnote fn = 1 fh = 12cm fs = F fc ="* " faP = U fnP = U Miramo Reference Guide [ v 9.2 ] R-329 Format definitions CHAPTER 4 fap = "" fas = "" fnp = "" fns = "" lb = " - " pc = "" cbg = 6.35mm cbw = 1mm cbp = N cbcolor=Black cbauto = N v = N vx = G vs = Y vb = Y vm = Y vpl = N lang="USEnglish" g = N gp = 10mm gs = 2mm gr = .25 r = Y rf = Y G = Y vn = 1 b = Y s = N sq = Y ss = Y us = 80 ds = 80 cs = 80 ud = 50 dd = 25 R-330 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions pb = N ps = N npcolor="Blue" pcolor="Black" /> If two or more pn = 22 pcolor = Cyan /> Miramo Reference Guide [ v 9.2 ] R-331 Format definitions CHAPTER 4 Summary Use Syntax Option Value Description File name format type fmt long | Identifying label for the file name format. [ filenameFormat ] short Two corresponding file name format definitions are always defined in a FrameMaker template file, as follows: Value FrameMaker variable name long ‘Filename (Long)’ short ‘Filename (Short)’ Default: long > Building blocks The following building blocks may be used between deftext deftext is any or all of: text, binary newline characters and tabs. All newlines are mapped to space characters. Binary tabs are preserved unless the ‘-striptabs’ command line option is used. Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhhhh;). R-332 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description Notes 1 It is not normally necessary to use the Examples Using the default filename format definitions, the input markup in Example 4.10 1 The short filename is: The long filename is: produces the output shown The short filename is: fdefs in Figure 4.3. The long filename is: /u/miramo/man/man900/book/fdefs Figure 4.3 Output from Example 4.10 Default file name formats The default Miramo Reference Guide [ v 9.2 ] R-333 Format definitions CHAPTER 4 1 R-334 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Summary Use , Syntax Option Value Description Name of font format fmt name Required [ fontFormat ] name is font format name. Font selection ff name Font family. [ fontFamily ] E.g. the following The next word is Helvetica and ... produces: The next word is Helvetica and ... fa name Font angle. [ fontAngle ] E.g. the following Some italic text ... produces: Some italic text ... fw name Font weight. [ fontWeight ] Some bold text ... produces: Some bold text ... fv name Font variation. [ fontVariation ] E.g. the following Some text in the Helvetica-Narrow variation produces: Some text in the Helvetica-Narrow variation Alternatively, the following Some text in the Helvetica-Narrow variation also produces: Some text in the Helvetica-Narrow variation Miramo Reference Guide [ v 9.2 ] R-335 Format definitions CHAPTER 4 Option Value Description Text size and color p dim | Text size. See Note 1 on page R-142. [ textSize ] rdim Default units are points (1/72 inches). An rdim value may have any of the following forms: +20%, 120%, 85%, -4%, +dim and -dim (e.g. +2pt, -1mm). A relative text point size, rdim, value may only be used when the ‘-tENC’ command line option (R-9), or the corresponding option on the fcolor name Font color. [ textColor ] E.g. the following Today is a Red letter day ... produces: Today is a Red letter day ... Underline and overline uline N | S | D | Underline style. [ textUnderline ] M Value Description N No underline. S Single (normal) underline. D Double underline. M Numeric (low) underline. E.g. the following single underline double underline o N | Y Overline. E.g. overline [ textOverline ] Default:N R-336 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description Strike through and change bar t N | Y Strike through. E.g. strike through [ strikeThrough ] Default:N C N | Y Change bar. E.g. change bar [ changeBar ] Default:N Capitalization fc T | S | L | Capitalization. [ textCase ] U Value Description T As typed. S Small caps. L Lower case. U Uppercase. E.g. this input Small caps Small caps Small caps Small caps produces: Small caps SMALL CAPS small caps SMALL CAPS Default:T Vertical and horizontal shift u N | Y Superscript. E.g. superscript [ superscript ] Default:N d N | Y Subscript. E.g. subscript [ subscript ] Default:N Ky percent Vertical displacement of text. [ vertShift ] percent is the required text downshift expressed as a percentage of an em in the current font size. If percent is preceded by a minus sign the text is upshifted. The upshift or downshift is always relative to the default paragraph baseline. If the paragraph line spacing is set to ‘Fixed’ using the Paragraph Designer in a template file or by setting the code ‘ls’ option to F (see pages R- 360 and R-221), then the shifted text may interfere with text above or below and may also extend above or below the border of a text frame or a table cell. This input Some text down1 down2up1 more text... Miramo Reference Guide [ v 9.2 ] R-337 Format definitions CHAPTER 4 Option Value Description up1 produces: Some text more text... down1 down2 Note that the up and down shifting is always relative to the default paragraph baseline. Default:0 Kx percent Horizontal text displacement. [ horizShift ] percent is the required text leftshift expressed as a percentage of an em in the current font size. If percent is preceded by a minus sign, then the text is rightshifted. For example This text is shifted||rightwards| (not) Kerning, character spread and stretch K Y | N Enable pair kerning and character spread. Also: enable [ textKern ] ligatures (Unix only). This input AWAY and AWAY produces: AWAY and AWAY fi R-338 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description produces: fi This input fi (Unix only) produces: fi (Unix only) Ks percent Inter-character spread, or tracking. [ textSpread ] percent is relative increase/ decrease in character spread. Negative values reduce character spread. Spread is expressed as a percentage of the font's em space size. The character spread option in fs percent Horizontally expand or compress characters. [ textStretch ] E.g. the following This is expanded text and this is compressed text. produces: This is expanded text and this is compressed text. Default: 100 textBGColor name Apply a background color to text. FrameMaker 10 and above only. Default: no background text color Text language lang key Language. [ textLanguage ] key may be any one of the following: None, NoLanguage, USEnglish, UKEnglish, German, SwissGerman, French, CanadianFrench, Spanish, Catalan, Italian, Portuguese, Brazilian, Danish, Dutch, Norwegian, Nynorsk, Finnish, Swedish, Japanese, SChinese, SimplifiedChinese, TChinese, TraditionalChinese, Korean. The following additional language key values are supported when running with FrameMaker 8 or above: Bulgarian, Croatian, Czech, Estonian, Finnish, Greek, Hungarian, Latvian, Lithuanian, NewGerman, NewSwissGerman, Polish, Romanian, Russian, Slovak, Slovenian, Turkish. Miramo Reference Guide [ v 9.2 ] R-339 Format definitions CHAPTER 4 Option Value Description Hyphenation and spell checking is suppressed if the ‘lang’ option is set to None or NoLanguage. /> Required Notes 1 In the case of a Examples Many FrameMaker documents contain a default paragraph format called ‘Body’. The equivalent Miramo fcolor=Black p = 12.0 K = N Kx = 0.0 Ky = 0.0 Ks = 0.0 uline = N o = N t = N d = N u = N fc = T R-340 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions C = N /> Note that though the ‘Body’ paragraph format will generally exist in the paragraph catalog of a FrameMaker template file, a ‘Body’ character format will not exist in the font catalog of a FrameMaker template file unless it is deliberately created by the user. Miramo Reference Guide [ v 9.2 ] R-341 Format definitions CHAPTER 4 Summary The Syntax Option Value Description Character and entity mapping id string Required string may comprise one or more ASCII characters in the range 33 through 126 (decimal), excluding ", ', &, ;, < and >. The text between the R-342 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description Building blocks The following building blocks may be used between text Individual characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhhhh;). Note that the entity name string or numeric character reference may refer to a character defined using a ... The building block may be used specify an output replacement character, using a series hexadecimal digit to specify the character's Unicode address. For example, the markup to specify the Unicode character U+260E, BLACK TELEPHONE, as the replacement character is: 260E. Required Every Notes 1 Included Miramo Reference Guide [ v 9.2 ] R-343 Format definitions CHAPTER 4 1 The output from Example 4.12 is shown in Figure 4.4. The 6 1 Replace §, U+00A7, with ¶, U+00B6. 3 A file containing dozens or thousands of Examples Example 4.14 shows how to use the R-344 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions 1 2 14 (3) AdobePiStd telephone (☎) sign. (bad) 15 16 17 Example 4.14 produces the output shown in Figure 4.6. (1) Wingdings telephone ( ) sign. An input character, in either hexadeci- (2) Wingdings telephone ( ) sign. mal or decimal numeric character (3) AdobePiStd telephone ( ) sign. (bad) entity form or in binary, will always be ☎ transformed on output if the character (4) AdobePiStd telephone ( ) sign. (good) ☎ is specified in the value of the ‘id’ (5) ZapfDingbatsStd telephone ( ) sign. ☎ option on a Miramo Reference Guide [ v 9.2 ] R-345 Format definitions CHAPTER 4 The content between r&mychar1;&mychar1;O&mychar1;so Example 4.15 Using Example 4.15 produces the output rOs| Os| OOs| so shown in Figure 4.7 at left. Figure 4.7 Output from Example 4.15 R-346 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Summary Use one or more Syntax Option Value Description Text frame dimensions and location W dim Width of text frame. [ frameWidth ] Default: inherited from preceding H dim Height of text frame. [ frameHeight ] Default: inherited from preceding L dim Distance of left side of text frame from left side of enclosing [ frameLeft ] frame or page. Default: inherited from preceding T dim Distance of top of text frame from top of enclosing frame or [ frameTop ] page. Default: inherited from preceding Text frame graphics properties pen 0 - 15 Sixteen pen patterns for text frame border are available, from [ penNum ] 0 (black) to 15 (none). See Appendix 2. pw dim Pen width. Note that borders thicken equally about their [ penWidth ] centers. Default units are points pstyle P | "dim Pen style. Solid or dashed. Setting ‘pstyle’ to P results in a [ penStyle ] dim ..." plain, solid border or line. Setting ‘pstyle’ to a series comprising an even number of dim values sets the border to have a dashed pattern. The first dim value specifies the length of a solid line segment, the next dim value specifies the length of a white segment, and so on. Miramo Reference Guide [ v 9.2 ] R-347 Format definitions CHAPTER 4 Option Value Description The pen pattern specification must be surrounded by double quotation marks. See Examples 2.14 and 2.15 on pages MD- 34 and MD-35 in the mmDraw Drawing Guide. Default:P fill 0 - 15 Fill pattern. See ‘pen’ above. A fill value of 15 represents a fill [ fillNum ] of ‘None’, i.e. transparent. color name Pen and fill color a 0 - 360 Angle of rotation (counterclockwise) about the center of the [ angle ] text frame. In this case, the dimension options LTWH relate to the unrotated text frame. Multi-column layout options cn int Number of equally sized sub-columns within this text frame. If [ numColumns ] this option has a value of 2 or greater the gap between sub- columns is determined by the ‘cg’ option (see below). Default:1 (1 subcolumn) cg dim Gap between sub-columns within this text frame. This value is [ columnGap ] only effective if the value of the ‘cn’ option (see above) is set to 2 or greater. Default: 18pt Feathering & side-head settings sw dim Side-head column width. Effective only when room for side- [ sideheadWidth ] heads is switched on (see the sg dim Gap between side-head column and main text column(s) [ sideheadGap ] within text frame. Effective only when room for side-heads is switched on (see the sp L | R | I | O Specify side-head placement within text frame. L=left side, [ sideheadPosition ] R = Right side, I = Inside and O = Outside of text frame. Outside refers to the side nearest the page edge in the case of double-sided documents. Effective only when room for side- heads is switched on (see the Column balancing cb N | Y Balance columns. Adjust the sub-columns in a final text frame [ balanceColumns ] which is not full so that the text is evenly distributed across the sub-columns. R-348 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description Metadata for graphic object (NextTextFrameDef) GOid string string may contain up to 512 bytes of metadata associated with this instance of the NextTextFrameDef code. This metadata is shown in FrameMaker MIF files in the Notes 1 Body text and other Miramo input markup will flow from a Examples Example 4.16 below shows using 1 2 Miramo Reference Guide [ v 9.2 ] R-349 Format definitions CHAPTER 4 5 6 12 13 Page 30 History of the world 31 34 4.16 comprises a complete Miramo document. If the text in Example 4.16 is contained in a file called, say, ‘mydoc.mm’, then running the command: miramo -Omif mydoc.mif mydoc.mm R-350 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions will produce a document with a running header Page 1 of 1 and footer and a main text flow comprising Text and more text. Text and more text ... three columnar text frames. 6.0 in History of the world 5.5 in Figure 4.8 Output from Example 4.16 (scaled to 25%) Miramo Reference Guide [ v 9.2 ] R-351 Format definitions CHAPTER 4 Summary Use the Syntax Option Value Description Create new master or reference page fmt name Required [ pageName ] name is the name of master page to be defined. If name includes the colon (‘:’), space or tab characters, the page name must be enclosed in matching double quotes. copy name Name of master page to copy onto this page, optionally [ copyPage ] connecting tagged text frames on the named master page with matching tagged text frames defined using this copytop N | Y Copy master page named using the ‘copy’ option on top of [ copyTop ] (Y) or beneath (N) the objects created by this copycon B | E | N Connect (B,E) or don't connect (N) tagged text frames on [ copyConnect ] master page given using the ‘copy’ option to the beginning (B) or end (E) of text frames on this page where flow tags on the target (this) master page match flow tags on the copied page. N: don't connect text frames with matching tags. In this case, where text frames have matching tags the top-most text frame takes precedence (see ‘copytop’ option above). Default:B R-352 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description a 0 | 90 | Page angle. Specifies rotation angle for page in degrees [ pageAngle ] 180 | 270 anticlockwise from the page orientation indicated by the type M | R Page type. [ pageType ] M = Master page, R = Reference page. Default:M Zero or more of the following codes may be enclosed within the Notes 1 The Miramo Reference Guide [ v 9.2 ] R-353 Format definitions CHAPTER 4 The Examples Example 4.18 illustrates using the 1 R-354 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions 19 20 21 34 Miramo Reference Guide [ v 9.2 ] R-355 Format definitions CHAPTER 4 Summary Use Syntax Option Value Description Define page number formats fmt curpage | Identifying label for the page number format. [ pageNumType ] lastpage | Four corresponding page number format definitions are volnum | always defined in a FrameMaker template file, as follows: chapnum Value FrameMaker variable name curpage ‘Current Page #’ lastpage ‘Page Count’ volnum ‘Volume Number’ chapnum ‘Chapter Number’ > Building blocks The following building blocks may be used between deftext deftext is any or all of: text, binary newline characters and tabs. All newlines are mapped to space characters. Binary tabs are preserved unless the ‘-striptabs’ command line option is used. Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhhhh;). R-356 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description Miramo Reference Guide [ v 9.2 ] R-357 Format definitions CHAPTER 4 Notes 1 It is not normally necessary to use the 1. See the ‘-Tfile’ and ‘-Cfile’ command line options on page R-19, and the R-358 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Summary Use , Syntax Option Value Description Paragraph format name fmt name Required [ pgfFormat ] name is paragraph format name. Basic options A L | R | Justification. L = left only, R = right only, LR = left and [ justify ] LR | C right, C = center. fi dim First line indent. Distance of the first line of text from the left [ firstIndent ] side of a text column or from the left margin of a table cell. li dim Left indent (excluding the first line of the paragraph). Distance [ leftIndent ] of the second and succeeding lines of text from the left side of a text column or from the left margin of a table cell. ri dim Right indent. Distance of lines of text from the right side of a [ rightIndent ] text column or from the right margin of a table cell. sa dim Space above. Note that actual inter-paragraph spacing is [ spaceAbove ] determined by the larger of the space above the current paragraph and the space below the preceding paragraph, not the sum of the two. (This assumes that feathering between paragraphs is turned off.) sb dim Space below. See note above. [ spaceBelow ] un N | Y Use next paragraph. [ pgfUseNext ] Default:N np name Next paragraph tag. [ pgfNext ] Miramo Reference Guide [ v 9.2 ] R-359 Format definitions CHAPTER 4 Option Value Description Interline leading and line spacing mode l dim Leading. Default units are points. [ leading ] Leading is the space between lines within a paragraph. Line spacing (baseline to baseline) is leading plus point size of the text (see Figure 4.4 on page U-62 in the Miramo User Guide). ls F | P Line spacing. F = fixed (no adjustment for extra large [ lineSpacing ] characters, superscripts, inline anchored frames, etc.), P = proportional. Setting the ‘ls’ option to P prevents contact between text lines in cases where the text contains either larger than normal characters or inline anchored frames. Font options (In addition to the ‘F’ font option listed below, the F name Font format name. name may be either the name of a font [ fontFormat ] definition specified using the Letter and inter-word spacing (For examples showing the effect of the ‘gws’, ‘ows’, and ‘lws’ options below see the Miramo User Guide, Chapter 4 , pages U-58 –59.) cspace N | Y Allow additional letter spacing. [ letterSpacing ] Inter-word spacing in justified text may sometimes have to exceed the maximum specified by the ‘gws’ option (see below). In such cases, setting the ‘cspace’ option to Y will allow additional space to be added between letters within words to reduce excessive spacing between words. gws percent Maximum inter-word spacing. A value of 100 is equivalent to [ maxInterWord ] one quarter of an em space. ows percent Optimum inter-word spacing. A value of 100 is equivalent to [ optInterWord ] one quarter of an em space. lws percent Minimum inter-word spacing. A value of 100 is equivalent to [ minInterWord ] one quarter of an em space. R-360 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description Autonumbering an N | Y Enable autonumbering. [ autoNumber ] See the Paragraph page or column placement P A | C | P | Paragraph placement. A = anywhere, C = top of column, P = [ pgfPosition ] L | R top of page, L = top of left page, R = top of right page. For single-sided documents (see the code with an associated Run-in, in-column, side head or straddle Pf N | R | T | Paragraph placement format. N = normal, R = run-in, T = side [ alignFormat ] F | L | S | head top, F = side head first, L = side head last, S = straddle SN columns and side heads, SN = straddle columns only. rhp char The default punctuation for ending a run-in head. [ endRunInChar ] The default is ‘.’ (period). To have nothing, use the empty string, ie, ‘rhp=""’. Widow/orphan lines wo int Minimum number of widow/orphan lines. [ minLines ] Keep with next or previous paragraph wn N | Y Keep with next paragraph. [ withNext ] Miramo Reference Guide [ v 9.2 ] R-361 Format definitions CHAPTER 4 Option Value Description wp N | Y Keep with previous paragraph. [ withPrevious ] Reference frames above and below ts name Top separator. name is the name of a Reference page [ pgfFrameAbove ] graphics frame. The Reference page and named graphics frame may be created either by importing reference pages from a template file, or by using the code within a code ‘ts’ or ‘bs’ options respectively. Default: None bs name Bottom separator. name is the name of a Reference page [ pgfFrameBelow ] graphics frame. See ‘ts’ option above. Hyphenation options H Y | N Turn on hyphenation. [ hyphenate ] Hml int Maximum number of adjacent hyphenated lines. [ maxHyphens ] Hmp int Minimum number of characters before hyphen. [ minBeforeHyphen ] Hms int Minimum number of characters after hyphen. [ minAfterHyphen ] Hmw int Minimum word size to hyphenate. [ minWordSize ] Table cell options clm dim Cell left margin applied to a table cell when this format is [ cellMarginLeft ] specified for the first paragraph in a table cell. The cell margin overrides the default cell margin specified for the table containing this paragraph. Default units are points. Text will not cross the left side of the cell when a negative dimension is given. When the first cell margin option (clm, ctm, crm or cbm) is encountered on a R-362 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description ctm dim Cell top margin applied to a table cell when this format is [ cellMarginTop ] specified for the first paragraph in a table cell. See ‘clm’ above. Default units are points. A negative top margin dimension may cause text to move above the top of the cell. Default: 6pt crm dim Cell right margin applied to a table cell when this format is [ cellMarginRight ] specified for the first paragraph in a table cell. See ‘clm’ above. Default units are points. Text will not cross the right side of the cell when a negative dimension is given. Default: 6pt crm dim Cell bottom margin applied to a table cell when this format is [ cellMarginBottom specified for the first paragraph in a table cell. See ‘clm’ ] above. Default units are points. A negative bottom margin dimension may cause text to move below the bottom of the cell. Default: 6pt cm dim Set left, top, right and bottom cell margins when this [ cellMarginAll ] paragraph format is applied to the first paragraph in a table cell. The cell margins override the default cell margins specified for the table containing this paragraph. Default units are points. Text will not cross the left or right sides of the cell when a negative dimension is given, but it may cross the top or bottom edges of the cell. Ca T | M | B Cell vertical alignment of paragraph contents within cell: [ cellVerticalAlign ] T = top of cell, M = middle of cell, B = bottom of cell. The orientation for ‘T’ (top) and ‘B’ (bottom) changes with cell rotation. For example, if Acrobat options PDFbmLevel int PDF bookmark level applied to this paragraph tag during conversion to PDF. If the bookmark level is zero, the paragraph is not included as an PDF bookmark in the resulting PDF file. PDF bookmark levels may also be applied by importing paragraph definitions from a template file (see page R-281), or by referencing a configuration file using the ‘-config’ command line option or the equivalent Miramo Reference Guide [ v 9.2 ] R-363 Format definitions CHAPTER 4 Option Value Description Bookmark levels have no effect unless the ‘-Afile’ command line option is used, or the ‘-Opdf’ or ‘-Opdfx’ command line options are used. The ‘-PDFpnames’ command line option may be used to control whether paragraph tags are to be included in Acrobat bookmarks. See page R-15 for a description of these command line options. Note that the ‘PDFbmLevel’ option is ignored, and the foregoing rules are invalid, if the Zero or one Notes 1 In addition to the options listed above, any or all of the options applicable to the R-364 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions 2 Options which are not specified within a sa = 0 sb = 0 np = "" un = N l = 2 ls = P F = "Body" ff=TimesNewRoman fv=Regular fw=Regular fa=Regular 1. This is as defined in the ‘Portrait’ template document shipped with Frame products. If this template doc- ument has been re-configured, then the following listing may not be accurate. Miramo Reference Guide [ v 9.2 ] R-365 Format definitions CHAPTER 4 fcolor=Black p=12pt K=N Ks=0 uline=N o=N d=N u=N fc=T C=N cspace = N gws= 110 ows= 100 lws= 90 an = N P = A Pf = N rhp=". " wo = 1 wn = N wp = N ts = "" bs = "" H = N Hml= 2 Hmp= 3 Hms= 3 Hmw= 5 lang = "USEnglish" Ca = T > R-366 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Property inheritance Miramo Reference Guide [ v 9.2 ] R-367 Format definitions CHAPTER 4 Summary Use the Syntax Option Value Description Include metadata in output PDF document information dictionary key string string is the name of a ‘document info’ field (see note 1 [ keyName ] below). Max length of string is 255 ASCII characters. This length includes multiple characters that may be used to represent one or more Unicode characters outside the ASCII range. > Required Notes 1 key may have the following special values: Author, Title, Subject and Keywords. In addition key my be assigned any arbitrary value. key cannot be used to define values for the Creator, Creation Date and Modification Date fields. R-368 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Examples The following shows an example of using 1 Miramo Reference Guide [ v 9.2 ] R-369 Format definitions CHAPTER 4 Summary The Syntax Option Value Description Password options permPwd string Required. Encrypt PDF file. string is permissions password (see [ permissionsPassw Note 3 on page R-372). Maximum length is 32 8-bit ord ] characters. The ‘permPwd’ option is required and must be set to a non- null value. Setting the permissions password to a null value results in a fatal error. The permissions password may alternatively be referred to as the owner or master password (see Note 4 on page R-372). Default: permpassword openPwd string string is opening password (see Note 5 on page R-373). [ openPassword ] Maximum length is 32 8-bit characters. If the ‘openPwd’ or is included and set to a non-null value Acrobat document viewer applications will request the user to enter a password before opening the PDF document. If the ‘openPwd’ or option is omitted or set to a null value, then no password is needed to open the output PDF document. If set to a non-null value, the opening password must be different to the permissions password set using the ‘permPwd’ or option. Setting the ‘permPwd’ and ‘openPwd’ options to the same value results in a fatal error. The opening password may alternatively be referred to as the user password (see Note 6 on page R-373). Default: no password keyLength 40 | 128 Length of encryption key. Default:40 R-370 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description Permission settings The following permission (security) settings may be changed only by a recipient who knows the permissions password, assuming the PDF document is displayed using an Adobe Acrobat viewer application. See Note 3 on page R-372. Print Y | N | Set printing permissions. [ allowPrint ] L[ow] Value Printing permission Y Printing allowed. N No printing allowed. L[ow] Only low resolution printing allowed. Default:Y Modify Y | N Allow modifications. [ allowModify ] If the ‘Modify’ option is set to N, the user will not be able to add form fields or make any other changes via Adobe Acrobat. Default:Y Accessibility Y | N Allow text access for screen reader devices intended for the [ enableAccess ] visually impaired. Default:Y Copy Y | N Allow copying and extracting text and graphics. [ allowCopy ] Default:Y Annotate Y | N Allow adding and editing annotations and form fields. [ allowAnnotate ] Default:Y encMeta N | Y Encrypt metadata. [ encryptMetadata ] Default:N Operational options processor pdftk | Third-party PDF processor application to use. plop See Note 1 on page R-372. Default: pdftk useRAM Y | N Perform PDF transformations in RAM. Silently ignored if the ‘processor’ option is set to pdftk. Default: Y (if ‘processor’ option is set to plop) /> Required Miramo Reference Guide [ v 9.2 ] R-371 Format definitions CHAPTER 4 Notes 1 The R-372 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions value is referred to as the master password. In Acrobat 6 this value is referred to as the permissions password. 5 If the opening password is not set, or set to a null value, anyone can open and view the PDF document. If certain operations on the PDF document have been restricted, e.g. printing is disallowed, then a user who does not have the permissions password will be constrained by those restrictions (see Note 3). For maximum practical security and convenience the opening password should be a minimum of eight characters comprising a random mix of upper and lower case characters, digits and common punctuation characters. Ideally opening passwords will not be chosen by users.1 Instead, opening passwords should be generated by the Miramo user and sent separately to the user. 6 The Adobe PDF version 1.4 specification, and later versions, refer to the value of the ‘openPwd’ option as the document ‘user’ password. In Acrobat 6 this value is referred to as the ‘Document open’ password. 1. This is because it is nigh-impossible to ensure that users will select passwords that have a high degree of security, i.e. not subject to standard dictionary, name or date attacks. Miramo Reference Guide [ v 9.2 ] R-373 Format definitions CHAPTER 4 Summary Use the Syntax Description Notes 1 The input stream may contain multiple code for a single output document: a ‘in- document’ PostProcess code. (See Note 4 on page R-379.) • At the same level as a code within a R-374 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Examples Usage of the Miramo Reference Guide [ v 9.2 ] R-375 Format definitions CHAPTER 4 Summary Use the Syntax Option Value Description type FDK | Specify the post-processor application type. FDK designates a eScript | FDK (FrameMaker API) application. eScript designates an fScript ExtendScript application (FrameMaker 10 or above only). fScript designates a FrameScript application. When the ‘type’ option is set to FDK the ‘name’ option must be used (see Note 2 on page R-378). When the ‘type’ option is set to eScript or fScript the ‘file’ option must be used (see Note 3 on page R-378). Default: FDK FDK API options (applicable only if the post processing application is a FDK API) name name Specify registered name of FDK API client (i.e. the first field in the [APIclients] entry for this client in the maker.ini file located in the FrameMaker installation folder). Required if the ‘type’ option is set to FDK. The ‘name’ option is ignored if the ‘type’ option is not set to FDK. param string Optional FDK API application parameter value. The ‘param’ option is ignored if the ‘type’ option is not set to FDK. Scripting option (applicable only if the post processing application is ExtendScript or FrameScript) file filename Specify the name of the script to be applied. Relative pathnames are interpreted relative to postprocessors folder in the Miramo installation folder, otherwise a full pathname must be specified. See Note on page R-. The ‘file’ option is ignored if the ‘type’ option is set to FDK. R-376 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description Post processing application timing option applyWhen key Specify when to execute the Book option Applicable for book-wide post post processing applications, when the applyTo key Key Description Book Process book object. GenChapters Process all generated chapters. Chapters Process all non-generated chapters. AllChapters Process all chapters. If the ‘applyTo’ option is set to GenChapters, Chapters or AllChapters, the post processing application is applied on the specified set of chapters in the order in which they occur in the book. If the ‘applyTo’ option is set to Book, post processing the book object occurs after the final Miramo Reference Guide [ v 9.2 ] R-377 Format definitions CHAPTER 4 Notes 1 Post processing applications must be used with extreme caution. A post processing application which contains a bug, or triggers an alert, will disable the mmServer processing channel at least until the job times out. For this reason setting the ‘-maxProcTime’ job parameter to a low value can improve efficiency when testing post processing applications (see page R-6). The installation of faulty or inappropriate post processing applications may also prevent mmServer startup. mmServer must be stopped and restarted before attempting to use any new post- processing applications, or after installing FrameScript.1 If an evaluation version of FrameScript is used and the evaluation period expires, mmServer will be unable to start owing to a hidden dialog box. In the case that mmServer fails to start the special mmVisor escape key combination Ctrl-Alt-f may be used to start FrameMaker in the mmServer RunAs user account. This can help in diagnosing mmServer start-up problems. 2 When the ‘type’ option is set to FDK the FDK API client must be registered by adding and entry like the following to the maker.ini file located in the FrameMaker installation folder (%FMHOME%\maker.ini): The location of the script files shown in Example 4.19 is as follows: 1. FrameScript installation registers the ‘fsl’ FrameScript API client wrapper for use with FrameMaker. 2. In addition to this calling method, the R-378 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions (A) C:\myApplication\myExtendScript.jsx (B) %MM_HOME%\postprocessors\myFrameScript.fsl The pathnames of these scripts are then passed as a parameter to the ‘ScriptingSupport’ API client (ExtendScript) or the ‘fsl’ API client (FrameScript). In the case a script file specified by the 1 ... content ... ... more content ... ... content ... ... more content ... Example 4.20 shows using the and code. Example 4.20 contains four Miramo Reference Guide [ v 9.2 ] R-379 Format definitions CHAPTER 4 The fourth 1 TestTOC - fixed title TestTOC - fixed content chapter 1 Chapter 1 content R-380 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions 30 chapter 2 Chapter 2 content Example 4.21 shows input for a three-chapter book (lines 13 to 20, 22 to 28, 30 to 36) that contains invocations for both book-wide and in-document post processing applications. The book-wide Seq Ref Line Script file name Chapter name Notes 1 C 7 exGen_save.jsx testTOC.fm Invoked at line 20. On chapter completion, on save, before book update. 2 B 5 exChap_open.jsx chapter1 Invoked at line 28. On chapter completion, on open, before book update. 3 B 5 exChap_open.jsx chapter2 Invoked at line 36. On chapter completion, on open, before book update. 4 G 32 exInChapter.jsx chapter2 Invoked at line 36. On chapter completion, on open, before book update (after (3) B above). Book updated here 5 D 9 exAll_update.jsx testTOC.fm Invoked at line 37, post book update. 6 E 17 exInChapter.jsx testTOC.fm Invoked at line 37, post book update. Miramo Reference Guide [ v 9.2 ] R-381 Format definitions CHAPTER 4 Table 4.2 Post processing application invocation sequence ( Continued ) Seq Ref Line Script file name Chapter name Notes 7 D 9 exAll_update.jsx chapter1.fm Invoked at line 37, post book update. 8 F 25 exInChapter.jsx chapter1.fm Invoked at line 37, post book update. 9 D 9 exAll_update.jsx chapter2.fm Invoked at line 37, post book update. 10 A 3 exBk_update.jsx book Invoked at line 37, post book update. Applied to book file ‘test.book’. 6 Sample scripts and the 'myApi.dll' FDK client are available in the %MM_HOME%\postprocessors folder in the Miramo installation folder. Test input files may be found in the %MM_HOME%\postprocessors\testfiles folder. Examples Example 4.22 illustrates how an FDK client application is called using the 1 /*------2 * myAPI: Miramo R-382 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions 29 IntT 30 res=FE_Success; 31 F_ObjHandleT 32 pgfId=NULLID, 33 textFlowId=NULLID; 34 F_TextLocT 35 textLoc; 36 37 /*------38 * Get ID of current document and its main text flow 39 * ------*/ 40 if ( docId == NULLID ) 41 docId=F_ApiGetId(FV_SessionId, FV_SessionId, FP_FirstOpenDoc); 42 43 textFlowId=F_ApiGetId(FV_SessionId, docId, FP_MainFlowInDoc); 44 45 /*------46 * Create new paragraph at the beginning of the text flow and 47 * insert text at the beginning of the paragraph 48 * ------*/ 49 pgfId=F_ApiNewSeriesObject(docId, FO_Pgf, textFlowId); 50 textLoc.objId = pgfId; 51 textLoc.offset = 0; 52 F_ApiAddText(docId, &textLoc, param); 53 F_ApiAddText(docId, &textLoc, "This text added by myAPI: " ); 54 55 return(res); 56 } 57 58 /*------59 * F_ApiInitialize()Receive FA_Note_ClientCall notifications 60 * ------*/ 61 VoidT F_ApiInitialize(IntT init) 62 { 63 F_ApiNotification(FA_Note_ClientCall, True); 64 } 65 66 /* ------67 * F_ApiNotify()Respond to FA_Note_ClientCall notification 68 * ------*/ 69 VoidT F_ApiNotify(IntT notification, F_ObjHandleT docId, 70 StringT sparm, IntT iparm) 71 { 72 IntT res=FE_Success; 73 74 switch (notification) { 75 case FA_Note_ClientCall: 76 res=myApi(docId, sparm); 77 F_ApiReturnValue(res); 78 break; 79 80 default: 81 break; Miramo Reference Guide [ v 9.2 ] R-383 Format definitions CHAPTER 4 82 } 83 } Example 4.22 myAPI.c R-384 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Summary Use Syntax Option Value Description Table ruling names and properties fmt name Required [ ruleName ] name is ruling format name. pen 0 - 15 Pen pattern for ruling, 0 (black) through to 15 (none). [ penNum ] Default:0 pw dim Pen width. Default units are points. [ penWidth ] Default: 0.5pt rl 0 | 1 | 2 Number of lines in ruling. [ numLines ] Default:1 rg dim Distance between ruling line centers. Applies only if ‘rl=2’ (see [ lineGap ] above). Default units are points. Default: 2pt color name Ruling colour. Default: Black /> Required Notes 1 Rulings are centered about table cell borders. See illustration in Figure 2.14 on page U-25 in the Miramo User Guide. 2 Options not specified within a Miramo Reference Guide [ v 9.2 ] R-385 Format definitions CHAPTER 4 3 If there are two or more Examples The default R-386 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Summary Use one or more Syntax Option Value Description Number of instances of column specification count int Apply options on this Notes 1 In table instances the default column width values specified by the codes within a Miramo Reference Guide [ v 9.2 ] R-387 Format definitions CHAPTER 4 Examples Example 4.23 shows a table format definition, newTable, that incorporates several different variations of the 1 In table instances that reference the ‘newTable’ table definition shown in Example 4.23, using the R-388 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Summary Use a set of one or more Syntax Option Value Description Paragraph options The options except for the pagination options ‘P’, ‘TCN’, ‘Pf’, ‘rhp’, ‘wo’, ‘wn’ and ‘wp’, and the flow and printing control options ‘FF’ and ‘PSF’. See the code description on pages R-220 –230 of the ‘Inline markup codes’ chapter.) /> Required Notes 1 If the code ‘fmt’ option is used it must appear before any other options. Examples See the example given for Miramo Reference Guide [ v 9.2 ] R-389 Format definitions CHAPTER 4 Summary Use Syntax Value Description Building blocks The following building blocks may be used between deftext deftext is any or all of: text, binary newline characters and tabs. All newlines are mapped to space characters. Binary tabs are preserved unless the ‘-striptabs’ command line option is used. Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhhhh;). Examples See example 3.104 on page R-280 for an example of using the R-390 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Summary Use Syntax Option Value Description Table format name fmt name Required [ tblFormat ] name is table format name. Basic options li dim Left indent. The ‘li’ option is ignored if the ‘A’ option is set to [ tblLeftIndent ] R (see below), unless used with the ri dim Right indent. The ‘ri’ option is ignored if the ‘A’ option is set [ tblRightIndent ] to L (see below), unless used with the sa dim Space above. [ tblSpaceAbove ] sb dim Space below. [ tblSpaceBelow ] A L | C | R Horizontal alignment of table within text column. [ tblHorizAlign ] Value Horizontal alignment L Left C Center R Right P A | F | C | Table placement. [ tblPosition ] P | L | R Value Placement A Anywhere F Float C Top of column P Top of page L Top of left page R Top of right page Miramo Reference Guide [ v 9.2 ] R-391 Format definitions CHAPTER 4 Option Value Description If ‘P’ is set to F text will backfill space ahead of the table wo int Minimum number of widow/orphan rows. [ minRows ] anc R | C Autonumbering direction for paragraphs and footnotes [ tblAutonumAxis ] within the table. R = numbering across rows, C = numbering down columns. cm dim All cell margins, i.e. left, top, right and bottom, for all cells in [ allMargins ] table. Overrides the default margin specified in the table format, if any. If the ‘cm’ option is used in conjunction with any of the ‘clm’, ‘ctm’, ‘crm’ or ‘cbm’ cell margin options (see below), the latter will be ineffective unless it follows the ‘cm’ option. Default units are points. clm dim Cell left margin, for all cells in table. [ leftMargin ] Overrides the default left margin specified in the table format, if any. Default units are points. Text will not cross the left side of the cell when a negative dimension is given. ctm dim Cell top margin. [ topMargin ] Overrides the default top margin specified in the table format, if any. Default units are points. A negative top margin dimension may cause text to move above the top of the cell. crm dim Cell right margin. [ rightMargin ] Overrides the default margin specified in the table format, if any. Default units are points. Text will not cross the right side of the cell when a negative dimension is given. cbm dim Cell bottom margin. [ bottomMargin ] Overrides the default bottom margin specified in the table format, if any. Default units are points. A negative bottom margin dimension may cause text to move below the bottom of the cell. Outside border rulings (In the following name must be the name of a Ruling defined in a template file or by using the lr name Left outside ruling. [ leftRule ] R-392 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description tr name Top outside ruling. [ topRule ] rr name Right outside ruling. [ rightRule ] br name Bottom outside ruling. [ bottomRule ] lbr N | Y Use ruling on last row. Y means draw bottom rule on last [ lastRuleOnly ] sheet only; N means draw rule on the bottom of every sheet. Header, footer (HF) & body row rulings (In the following name must be the name of a Ruling defined in a template file or by using the HFr name Ruling style used between rows in the heading and footing. [ HFRowRule ] Br name Default ruling used for body rows. [ bodyRowRule ] sr name Separator ruling. [ HFSeparatorRule ] name is the name of the separator ruling to use between the last heading row and the first body row and between the last body row and the first footing row. Exception (X) body row rulings xBr name Exception ruling for body rows. Used for every nth row [ bodyRowXRule ] (where n is specified using the ‘xBrp’ option). Default: None (i.e. the exception rule for body rows is to have no ruling between every nth body row). xBrp int Ruling period. Use the ruling specified with the ‘xBr’ option [ bodyRowXRulePeriod ] on every n rows. If ‘xBrp’ is set to 0 the exception ruling is never used. If ‘xBrp’ is set to 1 the exception ruling is used between every body row. If ‘xBrp’ is set to 2 the exception ruling is used between every second body row, and so on. Like all other table rulings, exception rulings are always overridden by any ruling options used with Column rulings (In the following name must be the name of a Ruling defined in a template file or by using the cr name Default column ruling for most columns. [ colRule ] Miramo Reference Guide [ v 9.2 ] R-393 Format definitions CHAPTER 4 Option Value Description Exception (X) column rulings xcn int Column number with right side which uses table column [ colXRuleNum ] ruling specified with ‘xcr’ option. xcr name Exception ruling for columns. Ruling style for column number [ colXRule ] specified using ‘xcn’ option. Header and footer (HF) fill and color HFfill 0 - 15 Header/Footer fill value HFcolor name Header/Footer color Table body fill and color shadeAxis R | C Table shading axis. R = shade by row. C = shade by column. [ tblShadeAxis ] Bfill 0 - 15 Body cells fill value. Default fill pattern for most body cells (see [ tblBodyFill ] ‘xBfill’ for exceptions to this). Bcolor name Body cells color. Default color for most body cells (see [ tblBodyColor ] ‘xBcolor’ for exceptions to this). Bp int Body shading period. The number of consecutive body [ bodyShadeNum ] columns/rows which use the shading values specified with the ‘Bfill’ and ‘Bcolor’ options above Exception (X) body fill and color xBfill 0 - 15 Exception fill pattern for body columns or body rows. [ tblXBodyFill ] xBcolor name Exception color for body columns or body rows. [ tblXBodyColor ] xBp int Exception body shading period. Number of consecutive [ xBperiod ] columns/rows which use the exception body shading values specified with the ‘xBfill’ and ‘xBcolor’ options. Exception column or row shading alternates with default body column or row shading to form a repeating pattern Table title options TP A | B | N Default table title placement. A = above table, B = below [ titlePosition ] table, N = no title. Only effective if the table instance contains a R-394 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description Tpf name Paragraph format for title of new table created with this [ titlePgfFormat ] format Only effective if the table instance contains a Tgap dim Table title gap [ titleGap ] Only effective if the table instance contains a Notes 1 The name values of ruling or color format used with the above options must match a ruling or color format defined in the Ruling or Color catalog of the template file and imported using the ‘-Tfile’ or ‘-Cfile’ command line options, or rulings or colors defined using li=0in ri=0in sa=12pt sb=12pt wo=1 A=L P=A 1. This is as defined in the ‘Portrait’ template document shipped with Frame products. If this template doc- ument has been re-configured, then the following listing may not be accurate in your case. Miramo Reference Guide [ v 9.2 ] R-395 Format definitions CHAPTER 4 anc=N clm=6pt ctm=6pt crm=6pt cbm=4pt lr=Thin tr=Thin rr=Thin br=Thin lbr=N HFr=Thin Br=Thin xBr=Thin xBrp=4 sr=Double cr=Thin xcn=1 xcr=Thin HFfill=15 HFcolor=Black Bfill=15 Bcolor=Black Bp=2 sc=N xBfill=15 xBcolor=Black xBp=2 Tpf=TableTitle TP=A Tgap=6pt > R-396 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Miramo Reference Guide [ v 9.2 ] R-397 Format definitions CHAPTER 4 Summary The Syntax Value Description Building blocks The following building blocks may be used between deftext deftext is any or all of: text, binary newline characters and tabs. All newlines are mapped to space characters. Binary tabs are preserved unless the ‘-striptabs’ command line option is used. Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhhhh;). R-398 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Summary Use the Syntax Option Value Description Type, flow and auto-connect settings type F | B Text frame type: F = foreground, B = background. [ textFrameType ] Ignored unless the 1. See the Miramo Reference Guide [ v 9.2 ] R-399 Format definitions CHAPTER 4 Option Value Description If ‘type’ is set to B, or the text frame is within an flow name Flow name for this series of text frames. [ flowName ] Normally this option should either be omitted or should be set to A. ‘A’ is the default flow tag used within all standard FrameMaker templates and documents. Ignored unless text frame ‘type’ option (see above) is set to F or, if the IX Index AIX Author index SIX Subject index LOM List of markers IOM Index of markers AML Alphabetic marker list IOR Index of references LOR List of references Default:A name name Name to use for this series of text frames. [ textFrameName ] Ignored unless the ‘type’ option is set to B. auto Y | N Autoconnect. Note that this option should almost always [ autoConnect ] either be omitted or should be set to Y to allow new pages to be added to the document as required by the text flow contents. Default:Y R-400 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description p N | Y PostScript code: if p=Y, the text enclosed between the [ PScode ] Text frame dimensions W dim Width of text frame. [ frameWidth ] Default: 40 mm, or inherited from preceding H dim Height of text frame. [ frameHeight ] Default: 60 mm, or inherited from preceding Text frame location L dim Distance of left side of text frame from left side of enclosing [ frameLeft ] frame or page. Default: 0, or inherited from preceding T dim Distance of top of text frame from top of enclosing frame or [ frameTop ] page. Default: 0, or inherited from preceding Text frame graphics properties pen 0 - 15 Sixteen pen patterns for text frame border are available, from [ borderPen ] 0 (black) to 15 (none). See Appendix 1, on page R-531. pw dim Pen width. Note that borders thicken equally about their [ penWidth ] centers. Default units are points pstyle P | "dim Pen style. Solid or dashed. Setting ‘pstyle’ to P results in a [ penStyle ] dim ..." plain, solid border or line. Setting ‘pstyle’ to a series comprising an even number of dim values sets the border to have a dashed pattern. The first dim value specifies the length of a solid line segment, the next dim value specifies the length of a white segment, and so on. The pen pattern specification must be surrounded by double quotation marks. See Examples 2.14 and 2.15 on pages MD- 34 and MD-35 in the mmDraw Drawing Guide. Default:P Miramo Reference Guide [ v 9.2 ] R-401 Format definitions CHAPTER 4 Option Value Description fill 0 - 15 Fill pattern. See ‘pen’ above. A fill value of 15 represents a fill [ frameFill ] of ‘None’, i.e. transparent. color name Pen and fill color a 0 - 360 Angle of rotation (counterclockwise) about the center of the [ angle ] text frame. In this case, the dimension options LTWH relate to the unrotated text frame. Multi-column layout options cn int Number of equally sized sub-columns within this text frame. If [ numColumns ] this option has a value of 2 or greater the gap between sub- columns is determined by the ‘cg’ option (see below). The depth of text in each sub-column may be balanced (equalized) at the end of the text flow by setting the ‘cb’ option to Y (see below). Default:1 (1 subcolumn) cg dim Gap between sub-columns within this text frame. This value is [ columnGap ] only effective if the value of the ‘cn’ option (see above) is set to 2 or greater. Default: 18pt Feathering & side-head settings sh N | Y Allow room for side-heads in this text flow. The side-head [ sideheads ] width, gap and location are specified using the ‘sg’, ‘sw’ and ‘sp’ options above. For details of how to specify paragraphs as side-head or run- in heads, see the code ‘Pf’ option (described on page R-225). Effective only when sw dim Side-head column width. Effective only when room for side- [ sideheadWidth ] heads is switched on (see ‘sh’ option below and Note 1 on page R-404). sg dim Gap between side-head column and main text column(s) [ sideheadGap ] within text frame. Effective only when room for side-heads is switched on (see ‘sh’ option below and Note 1 on page R- 404). R-402 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description sp L | R | I | O Specify side-head placement within text frame. L=left side, [ sideheadPosition ] R = Right side, I = Inside and O = Outside of text frame. Outside refers to the side nearest the page edge in the case of double-sided documents. Effective only when room for side- heads is switched on (see ‘sh’ option below and Note 1 on page R-404). Feathering options f N | Y Feather text within this text flow. [ feather ] Effective only when maxp dim Maximum inter-paragraph padding when feathering is [ maxPgfPad ] switched on. Default: 6pt maxl dim Maximum inter-line padding when feathering is switched on. [ maxLinePad ] Default: 2pt Baseline synchronization b N | Y Baseline synchronization of lines across multiple sub-columns. [ alignBaselines ] If b = Y, the baselines of text in adjacent columns are synchronized. The ‘b’ option is effective only if the ‘cn’ option has a value of 2 or greater. bl dim Line spacing for synchronized baselines. [ baselineSpace ] bh dim Maximum character height for synchronization of the first line [ maxCharHeight ] in the text column; if characters exceed this height, the first line is not synchronized Column balancing cb N | Y Balance columns. Adjust the sub-columns in a final text frame [ balanceColumns ] which is not full so that the text is evenly distributed across the sub-columns. Text runaround RA N | B | C Text runaround type. [ runAround ] Value Description N No runaround B Box runaround Miramo Reference Guide [ v 9.2 ] R-403 Format definitions CHAPTER 4 Option Value Description C Contour runaround Default:N RAgap dim Specify the gap between the TextFrameDef and text flowing [ runAroundGap ] around it. The value of dim may be negative. Effective only if the ‘RA’ option (see above) is set to C or B. Default: 6pt Metadata for graphic object (TextFrameDef) GOid string string may contain up to 512 bytes of metadata associated with this instance of the TextFrameDef code. This metadata is shown in FrameMaker MIF files in the Notes 1 If a R-404 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions 2 If Examples See the examples for Miramo Reference Guide [ v 9.2 ] R-405 Format definitions CHAPTER 4 Summary Use Syntax Option Value Description Set default units for document fmt in | cm | in = inches, cm = centimeters, mm = millimeters, pc = picas, [ unitName ] mm | cc | pt = points, dd = didots, cc = ciceros. pt | dd | A point is defined as 1/72 inch (.35278 mm) and a pica is 12 pc points. A didot is defined as .37668 mm and a cicero is 12 didots. /> Required Examples The following placed at the beginning of a miramo input file is a valid R-406 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Summary The Syntax Description ... XMP data Required Every Notes 1 There are two methods of specifying metadata in PDF files. The simplest method is to use the Miramo Reference Guide [ v 9.2 ] R-407 Format definitions CHAPTER 4 by the contents of the XMP dc:creator element; the contents of the Examples Example 4.24 shows a simple illustration of using the 1 R-408 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions 24 25 Example 4.24 Simple The Packet header begin attribute (line 2 in Example 4.24) should always be set either to the empty string or contain the three binary bytes: 0xEF, 0xBB and 0xBF. The Packet header id attribute (also on line 2 in Example 4.24) must always have the value: "W5M0MpCehiHzreSzNTczkc9d". Though the media management xapMM:DocumentID element may contain any arbitary UTF-8 string, as shown on line 14 in Example 4.24, it is frequently a 128- or 144-bit integer encoded as 22 or 24 base 64 characters in guid or uuid format. The entire text in Example 4.24, i.e. lines 1 through 25, may be referenced from an external file, say mymetadata.mmo, as illustrated in Example 4.25 External .xmp metadata files may be referenced using the 1 Alternatively several 1 Miramo Reference Guide [ v 9.2 ] R-409 Format definitions CHAPTER 4 Summary Use the Syntax Option Value Description Define cross-reference format fmt name Required [ xrefFormat ] name is the name of the cross-reference format. > Building blocks The following building blocks may be used between deftext deftext is any or all of: text, binary newline characters and tabs. All newlines are mapped to space characters. Binary tabs are preserved unless the ‘-striptabs’ command line option is used. Special characters may be encoded using the character entity name string (&name;), or the numeric character reference (&#nn; or &#xhhhh;). R-410 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Option Value Description Miramo Reference Guide [ v 9.2 ] R-411 Format definitions CHAPTER 4 Option Value Description In the case that one of the paragraph formats listed is the same as that containing the R-412 Miramo Reference Guide [ v 9.2 ] CHAPTER 4 Format definitions Examples The output shown in Figure 4.9 contains several hidden cross-reference destina- Jazz trumpeters tions, created using the In 1929 Tenessee man, Willie the 2 Jazz trumpeters Wailer, ... 3 4 Some of the most famous: Figure 4.9 Output from Example 4.28 5 6 7 Louis Armstrong 9 Jazz legend Louis Armstrong 10 raised the trumpet to new heights. 11 12 Willie the Wailer 14 In 1929 Tenessee man, Willie the Wailer, ... Example 4.28 Input for the output shown in Figure 4.9 above If a cross reference format, ‘see_also.2’, is defined as shown in Example 4.29, 1 then the cross reference instance shown in Example 4.30 Aldo Moriali, a trumpeter much influenced by Louis Armstrong's produces the out- put shown in Fig- Aldo Moriali, a trumpeter much influenced by Louis Armstrong's (see also Louis Armstrong on page 413, in the ure 4.30 listing for Jazz trumpeters, which starts on page 413) most innovative techniques ... Figure 4.10 Output from Example 4.30 Miramo Reference Guide [ v 9.2 ] R-413 Format definitions CHAPTER 4 R-414 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes This chapter describes special XML-related markup codes and includes the Miramo Doc- ument Type Definition (DTD). It also gives some background information on using the mmxslt stylesheet processor to map from a well-formed XML file to a well-formed, valid Miramo (XML) input stream, including information on extending the range of characters (glyphs) accessible using gen- eral entity declarations in conjunction with the The declaration An input stream may incorporate an XML declaration, but it is ignored by Miramo. Note that the ‘encoding’ attribute has no effect — by default Miramo assumes UTF-8 encoding. If the XML declaration is present, it must appear before any other Miramo markup in the document, for example: A one paragraph input file The A two paragraph input file A two paragraph input file The processing instruction The code is documented on page R-111 and may be used to divert inline data to an external system command. The processing instruction The code is documented on page R-245 and may be used to execute an external system command, whose output is treated as input to Miramo. code The Miramo input stream may include a reference to the Miramo DTD listed on pages R- 422–447, which allows external applications to validate the Miramo input stream against Miramo Reference Guide [ v 9.2 ] R-415 Miramo DTD and XML codes CHAPTER 5 the Miramo DTD; however Miramo ignores the statement, so changes made to the ‘miramo.dtd’ will not affect Miramo's operation. Here is an example of a well-formed, valid Miramo XML data file: A one paragraph document with some bold text. Figure 5.1 Output from Example 5.1 Using XSLT stylesheets XSLT provides a convenient, well documented methodology for transforming an XML encoded data stream to Miramo markup, i.e. to an XML encoded data stream which con- forms to the Miramo DTD listed on pages R-422–447. The Miramo distribution includes the mmxslt XSLT stylesheet processor. See page R-27 for a description of mmxslt and its command line options. The output encoding should generally be set to ‘utf-8’ in the XSLT stylesheet. Example 5.2 shows a very simple XSLT stylesheet which will convert a document containing a sequence of codes: Assuming the file ‘simple.xml’ contains the following: R-416 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes mmxslt -xsl simple.xsl simple.xml Example 5.4 Running mmxslt using the ‘simple.xsl’ stylesheet will produce the output shown in Example 5.5, which is suitable for processing using Miramo. Aacute characters: (ÁÁ) Second paragraph Note that when using mmxslt to create Miramo XML files, the Miramo XML must be well formed: in particular, all option (attribute) values must be enclosed in double or single quotes, and every markup code (element) requires a matching end code. Miramo itself does not enforce either of these rules, as illustrated in many of the examples given in the Miramo Reference Guide, but mmxslt will fail unless the Miramo XML is well formed. Example 5.6 shows an invalid XSLT stylesheet which breaks these rules: The correct version of this stylesheet is shown in Example 5.2 on page R-416. Entity references and mmxslt This section explains how to use mmxslt to use general entity declarations to extend the range of characters accessible via Miramo markup codes. A general entity is an entity that can be mapped to another set of characters when an entity reference of the form &name; is encountered in the XML input stream. An XML file may reference an internal DTD (included in the XML file) or external DTD (in an external file referenced using the SYSTEM identifier). The DTD may include general entity declarations in the following form: If mmxslt encounters a general entity of the form &name; in the input XML file, it will expect to find a corresponding entity declaration in the document DTD - otherwise mmx- slt will exit with an error message. If mmxslt finds an entity declaration corresponding to the entity reference, it will replace the entity reference with its definition. By including a set of entity declarations which map character names onto their XML numeric character references, together with an equiva- Miramo Reference Guide [ v 9.2 ] R-417 Miramo DTD and XML codes CHAPTER 5 lent set of Miramo 1 2 3 5 6 7 8 ]> 9 The input encoding for the XML file ‘entitytest.xml’ (Example 5.7) is set to ‘ISO-8859-1’, and the first Aacute: Á Oacute: Ó IOcy: Note that the binary ‘Aacute’ character, and the Ó and Ё characters have been mapped to their equivalent Unicode numeric character entity references. The markup shown in Figure 5.2 includes the Ё numeric character reference, which is not included in US-ASCII. To map the Ё to a character in the Baskerville- CyrillicLTStd font, the ‘simple.xsl’ stylesheet must be extended to include the 1 2 R-418 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes 5 6 7 Processing the XML file in Example 5.9 using the ‘modified simple.xsl’ XSLT stylesheet listed in Example 5.9 and then running the command: mmxslt -Xctrans decimal -xsl modified_simple.xsl -indent 0 entitytest.xml Example 5.10 Running mmxslt using the ‘simple.xsl’ stylesheet 1 2 Aacute: Á Oacute: Ó IOcy: Ё The Miramo XML output shown in Example 5.11 now includes the The output from Example 5.12 is shown in Figure 5.3. Aacute: Á Oacute: Ó Accessing mmxslt extension functions IOcy: To use the Miramo-specific extension functions, the Figure 5.3 Output from running the command shown in Example 5.12 XML file must include a declaration for the Miramo extension function namespace (http://ExternalFunction.miramo.com), and the Miramo Reference Guide [ v 9.2 ] R-419 Miramo DTD and XML codes CHAPTER 5 namespace declarations should be excluded from the transformation output. Example 5.13 illustrates a stylesheet element which does both: 1 2 R-420 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes • imageType() Returns image type. The returned value may be any of the following strings: BMP, CGM, EPS, GIF, JFIF, JPEG, PNTG, PCX, PDF, PNG, SNRF, SVG, SWF, TIF, U3D, WMF, and XWD. • imageSize() Returns overall size of image file in bytes. • imageErr() Gets detailed numeric status code from the getImageStats(fileName) function. Return code may be any of the following: 0 No error. 1 fileName does not exist. 2 fileName exists but is not readable. 3 fileName is a folder (or directory). 4 fileName contains an unsupported image format. 5 fileName is a supported image format but appears to be corrupt. 6 fileName is a CGM file and setImageGGMopt(key) is set to a value higher than the number of pictures in the file. A further discussion and illustration of using mmxslt image processing extension func- tions is contained in the Miramo User Guide on pages U-53–56. mmxslt extension functions for PDF file import The following describes the mmxslt built-in PDF file extension functions. • getPdfStats(fileName) getPdfStats(fileName) extracts data from a PDF file. The extracted data may be accessed using the following PDF related extension functions. The getPdfStats(fileName) function must be called before using any of the following PDF related extension functions. getPdfStats(fileName) returns 0 (false) or 1 (true) depending on whether the getPdfStats(fileName) function was able to extract the data from the file fileName. • pdfPages() Returns the total number of pages in the PDF file referenced by the preceding getPdfStats(fileName) function. • pdfArtBoxL(pageNum), pdfArtBoxT(pageNum), pdfArtBoxW(pageNum) and pdfArtBoxH(pageNum) The pdfArtBoxL(pageNum), pdfArtBoxT(pageNum), pdfArtBoxW(pageNum) and pdfArtBoxH(pageNum) functions return, respectively, the left and top offsets and the width and height of the PDF art box on page pageNum in a PDF file referenced by the preceding getPdfStats(fileName) function. All returned values are in points. The left and top offsets are relative to the PDF media box. The first page is numbered 1. Miramo Reference Guide [ v 9.2 ] R-421 Miramo DTD and XML codes CHAPTER 5 A warning is issued if there is no preceding getPdfStats(fileName) function. A warning is issued if the value of pageNum is out of range. In this case all the returned values are set to 0. • pdfCropBoxL(pageNum), pdfCropBoxT(pageNum), pdfCropBoxW(pageNum) and pdfCropBoxH(pageNum) Equivalent to pdfArtBoxL(pageNum), et al, (see above), except the extracted data relates to the PDF crop box. • pdfMediaBoxL(pageNum), pdfMediaBoxT(pageNum), pdfMediaBoxW(pageNum) and pdfMediaBoxH(pageNum) Equivalent to pdfArtBoxL(pageNum), et al, (see above), except the extracted data relates to the PDF media box. • pdfErr() Gets detailed numeric status after the getPdfStats(fileName) function has been called. Return code may be any of the following: 0 No error. 1 fileName does not exist. 2 fileName exists but is not readable. 3 fileName is a folder (or directory). 4 fileName is not a PDF file. 5 fileName is a PDF file but appears to be corrupt. Miscellaneous mmxslt extension functions Additional mmxslt extension functions are described below. • fileBaseName(fileName) Returns basename of a file. • fileDirName(fileName) Returns directory name (full path name) of a file. • fileSize(fileName) Returns size of file fileName in bytes/octets. Miramo DTD The Miramo DTD is shown below, copied from the file ./docs/xml/miramo.dtd in the Miramo installation directory. Table 5.1 miramo.dtd 1 2 3 R-422 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Table 5.1 miramo.dtd ( Continued ) 4 11 12 13 14 15 %miramoent; 16 17 18 19 20 21 22 46 47 48 56 57 64 65 70 71 Miramo Reference Guide [ v 9.2 ] R-423 Miramo DTD and XML codes CHAPTER 5 Table 5.1 miramo.dtd ( Continued ) 74 |ATextFrame 75 |BGVar 76 |BGMarker 77 |CmdData 78 |Comment 79 |Conditional 80 |Date 81 |DPage 82 |FNote 83 |FileName 84 |HyperCmd 85 |Include 86 |Import 87 |IX 88 |Marker 89 |MapChar 90 |MkAlert 91 |MkDest 92 |PDFbookmark 93 |PageNum 94 |PSr 95 |Tbl 96 |TblCont 97 |TblFrame 98 |TblSheet 99 |Unconditional 100 |Var 101 |XRef 102 |EOF 103 %inTextMarkup; 104 "> 105 106 113 114 115 116 117 118 119 120 121 122 123 124 125 129 130 133 134 137 R-424 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Table 5.1 miramo.dtd ( Continued ) 138 143 144 151 152 156 157 158 162 163 173 174 180 181 185 186 191 192 196 197 202 203 Miramo Reference Guide [ v 9.2 ] R-425 Miramo DTD and XML codes CHAPTER 5 Table 5.1 miramo.dtd ( Continued ) 208 209 216 217 218 219 240 241 242 243 255 256 257 258 262 263 264 265 272 273 274 275 R-426 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Table 5.1 miramo.dtd ( Continued ) 278 279 280 281 285 286 287 288 295 296 297 298 304 305 306 307 310 311 312 313 329 330 331 332 336 337 338 339 Miramo Reference Guide [ v 9.2 ] R-427 Miramo DTD and XML codes CHAPTER 5 Table 5.1 miramo.dtd ( Continued ) 348 349 350 351 358 359 360 361 367 368 369 370 388 389 390 391 401 402 403 404 R-428 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Table 5.1 miramo.dtd ( Continued ) 418 "> 419 420 421 422 428 434 443 448 451 458 459 463 464 472 473 474 487 Miramo Reference Guide [ v 9.2 ] R-429 Miramo DTD and XML codes CHAPTER 5 Table 5.1 miramo.dtd ( Continued ) 488 500 501 509 510 514 515 520 521 522 523 524 525 537 538 539 540 541 550 551 552 R-430 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Table 5.1 miramo.dtd ( Continued ) 558 runAroundGapNMTOKEN #IMPLIED 559 > 560 561 562 563 576 577 578 581 582 583 588 589 590 593 594 595 598 599 603 604 609 610 611 619 620 623 624 Miramo Reference Guide [ v 9.2 ] R-431 Miramo DTD and XML codes CHAPTER 5 Table 5.1 miramo.dtd ( Continued ) 628 pdfWidth NMTOKEN #IMPLIED 629 pdfHeight NMTOKEN #IMPLIED 630 pdfScale NMTOKEN #IMPLIED 631 pdfStartPageNumNMTOKEN #IMPLIED 632 pdfEndPageNumNMTOKEN #IMPLIED 633 pdfDoubleSided%bool; #IMPLIED 634 > 635 636 637 638 639 642 643 644 645 648 649 650 658 659 660 661 667 668 669 670 671 674 675 676 687 688 689 693 694 695 R-432 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Table 5.1 miramo.dtd ( Continued ) 698 699 700 705 706 707 711 712 713 733 734 735 746 747 748 751 752 753 Miramo Reference Guide [ v 9.2 ] R-433 Miramo DTD and XML codes CHAPTER 5 Table 5.1 miramo.dtd ( Continued ) 766 > 767 768 769 795 796 797 806 807 808 811 812 817 823 824 825 828 829 830 R-434 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Table 5.1 miramo.dtd ( Continued ) 834 835 836 855 856 857 868 869 870 873 874 875 879 880 881 882 883 896 897 898 899 900 Miramo Reference Guide [ v 9.2 ] R-435 Miramo DTD and XML codes CHAPTER 5 Table 5.1 miramo.dtd ( Continued ) 902 %arrow.object.attrib; 903 > 904 905 906 924 925 926 936 937 938 947 948 949 957 958 959 966 967 968 R-436 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Table 5.1 miramo.dtd ( Continued ) 972 973 974 978 979 980 985 986 987 992 993 994 995 1004 1005 1010 1013 1029 1030 1031 1034 1035 1036 1039 1040 1041 Miramo Reference Guide [ v 9.2 ] R-437 Miramo DTD and XML codes CHAPTER 5 Table 5.1 miramo.dtd ( Continued ) 1042 name CDATA #IMPLIED 1043 value CDATA #IMPLIED 1044 > 1045 1046 1047 1055 1056 1057 1068 1069 1070 1076 1077 1078 1079 1080 1095 1096 1097 R-438 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Table 5.1 miramo.dtd ( Continued ) 1111 tblFrameColor CDATA #IMPLIED 1112 %frame.location.attrib; 1113 runAroundGapNMTOKEN #IMPLIED 1114 %pen.attrib; 1115 IDstring CDATA #IMPLIED 1116 > 1117 1118 1119 1123 1124 1125 1130 1131 1132 1142 1143 1144 1145 1146 1147 1148 1159 1160 1161 1172 1173 1174 1175 1176 1179 1180 Miramo Reference Guide [ v 9.2 ] R-439 Miramo DTD and XML codes CHAPTER 5 Table 5.1 miramo.dtd ( Continued ) 1181 1186 1187 1188 1189 1190 1191 1192 1193 1201 1202 1203 1204 1205 1206 1207 1208 1211 1212 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 R-440 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Table 5.1 miramo.dtd ( Continued ) 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1273 1274 1275 1276 1279 1280 1283 1284 1287 1288 1289 1290 1291 1292 1293 1294 1295 1300 1303 1304 1305 1314 1315 1316 Miramo Reference Guide [ v 9.2 ] R-441 Miramo DTD and XML codes CHAPTER 5 Table 5.1 miramo.dtd ( Continued ) 1321 1322 1323 1329 1330 1341 1344 1345 1350 1353 1354 1355 1359 1360 1366 1369 1370 1371 1385 1386 1387 R-442 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Table 5.1 miramo.dtd ( Continued ) 1391 file CDATA #IMPLIED 1392 applyWhen (onOpen|OnSave|postBookUpdate) "onOpen" 1393 applyTo (Book|GenChapters|Chapters|AllChapters) "AllChapters" 1394 > 1395 1396 1397 1398 1399 1400 1408 1409 1413 1414 1419 1420 1421 1424 1425 1426 1429 1430 1431 1442 1443 1446 1449 1450 1457 1460 Miramo Reference Guide [ v 9.2 ] R-443 Miramo DTD and XML codes CHAPTER 5 Table 5.1 miramo.dtd ( Continued ) 1461 1462 1473 1474 1478 1479 1484 1485 1491 1492 1496 1497 1502 1503 1517 1518 1529 1530 R-444 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Table 5.1 miramo.dtd ( Continued ) 1531 lb CDATA #IMPLIED 1532 > 1533 1534 1537 1538 1541 1542 1549 1550 1559 1560 1569 1570 1576 1577 1589 1590 1597 1598 1599 1600 Miramo Reference Guide [ v 9.2 ] R-445 Miramo DTD and XML codes CHAPTER 5 Table 5.1 miramo.dtd ( Continued ) 1601 fmt CDATA #REQUIRED 1602 copytop %bool; "N" 1603 copy CDATA #IMPLIED 1604 copycon (B|E|N) "B" 1605 a NMTOKEN "0" 1606 type (M|R) "M" 1607 > 1608 1609 1610 1625 1626 1627 1637 1638 1639 1642 1643 1644 1659 1660 1661 1664 1665 1666 1667 1674 1679 Miramo Reference Guide [ v 9.2 ] R-447 Miramo DTD and XML codes CHAPTER 5 R-448 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Summary The Syntax Option Value Description Single document output All, or any subset of, the following may be used concurrently. Ofm filename Name of FrameMaker binary document to create. [ fmFile ] Omif filename Name of FrameMaker MIF (Maker Interchange Format) [ MIFFile ] document to create. Oviewfm filename Name of locked (view-only) FrameMaker binary document to [ fmViewFile ] create. Oviewmif filename Name of locked (view-only) FrameMaker MIF (Maker [ mifViewFile ] Interchange Format) document to create. Ortf filename Name of RTF file to create. [ rtfFile ] Ortfj filename Name of RTF file to create, using Japanese filter version. [ rtfFileJ ] Miramo Reference Guide [ v 9.2 ] R-449 Miramo DTD and XML codes CHAPTER 5 Option Value Description Ohtml filename Name of HTML file to create. [ htmlFile ] Oxml filename Name of XML file to create. [ xmlFile ] Printing and print file output options P N | Y Print to default printer. [ Print ] Default: from ‘-P’ command line option, if set, or N Pdefault name Set the default printer to printer named name for this job. [ defaultPrinter ] Applicable when producing PostScript or PDF output. name must be surrounded by double quotation marks if the printer name contains spaces. Setting the default printer on a per-job basis should be avoided when high throughput is important. Default: from ‘-Pdefault’ command line option, if set Pname name Print to printer name. [ printerName ] Default: from ‘-Pname’ command line option, if set Pfile filename [, pname ] [ printFile ] Print to named PostScript file. On NT only, filename may optionally be followed by a comma and then the name, pname, of the printer driver to be used. See Note 7 on page R-460. PAfile filename [, pname ] [ printAFile ] Print to named PostScript file, with Acrobat support. Pcopies int Number of copies to be printed. Default: from ‘-Pcopies’ command line option, if set, or 1 On NT only, filename may optionally be followed by a comma and then the name, pname, of the printer driver to be used. See Note 7 on page R-460. Pscale percent Scale document to given percentage before printing. Default: from -Pscale command line option, if set, or 100 Preg D | N | W | Print registration and crop marks. [ printCropMarks ] T Value Description D Default, i.e. as set in template document, if any. N No registration marks. This is the default if there is no template document. W Western registration marks T Tombo registration marks Default: from ‘-Preg’ command line option, if set, or D or N R-450 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Option Value Description Pstartpage int Print file starting from given page number. The page number refers to the page number variable which may appear on the printed page, not the sheet number within the output document. Default: first page in the document Pendpage int Print file starting ending at given page number. The page number refers to the page number variable which may appear on the printed page, not the sheet number within the output document. Default: last page in the document Pstartno int Print file starting from given pagecount. The pagecount refers to the sequential sheet number within the file, with the first page numbered as 1, not to the page numbers which may be printed in the document. Default:1 Pendno int Print file ending at given pagecount. The pagecount refers to the sequential sheet number within the file, with the first page numbered as 1, not to the page numbers which may be printed in the document. Default: last page in the document Ppapersize default | Select printer paper size either using a paper size code such as pagesize | a4, or by specifying a custom papersize width and height a3 | a4 | using the form WuHu, for example ‘9cm20cm’ or a5 | b5 | ‘210mm10in’. Note that a custom papersize code may not tabloid | include any spaces. legal | See the description for the ‘-Ppapersize’ command line letter | option, on page R-17, for more details. WuHu Default: default PpageOrder F | L Print first page first Default: F if ‘-PpageOrder’ command line option is not used, or as per ‘-PpageOrder’ command line option (see page R-18). Pseps N | Y Print document in 4 CMYK color separated versions. [ separations ] Default: N unless ‘-Pseps’ command line option is used (see page R-18). Pskipblanks N | Y Suppress printing of blank pages within document. [ printNoBlanks ] Default: N unless ‘-Pskipblanks’ command line option is used (see page R-18). Pfonts none | Fonts to embed in PostScript output. (Unix only) [ printFonts ] x13 | x35 Value Description | all | none No included fonts (default). Asian x13 All except ‘Standard 13’ and Asian fonts. Miramo Reference Guide [ v 9.2 ] R-451 Miramo DTD and XML codes CHAPTER 5 Option Value Description x35 All except ‘Standard 35’ and Asian fonts. all All fonts except Asian fonts. Asian Only Asian fonts. Default: none, unless ‘-Pfonts’ command line option is used (see page R-16). Template options Cfile filename Copy all body pages and format specifications from filename [ tplCopyFile ] to the beginning of the current document. filename must be a FrameMaker document saved in MIF format. The ‘Cfile’ and ‘Tfile’ options are mutually exclusive: if both are used, the later option takes precedence over the earlier option. The ‘Cfile’ option differs from the ‘Tfile’ option in that the contents of the body pages are copied from the specified file, and all formatting specifications are always copied from the specified file. (The ‘Tflow’, ‘Tformats’ and ‘TXformats’ options are ignored). The ‘Cfile’ option takes precedence over the ‘-Cfile’ command line option (described in Chapter 2, ‘Running Miramo’, R-19). Default: from ‘-Cfile’ command line option Tfile filename Use filename as the source for formatting specifications. [ tplFile ] filename must be a FrameMaker document saved in MIF format. The ‘Cfile’ and ‘Tfile’ options are mutually exclusive: if both are used, the later option takes precedence over the earlier option. If neither the ‘Tformats’ nor the ‘TXformats’ option is used, then all formats in the template are imported. The ‘Tfile’ option takes precedence over the ‘-Tfile’ command line option (described in Chapter 2, ‘Running Miramo’, R-19). Default: from ‘-Tfile’ command line option Toverride N | Y Allow template format definitions to override Miramo format [ tplOverride ] definition code markup. Default: from ‘-Toverride’ command line option, or N if none given Tformats key Specify formats to be extracted from the template file given [ tplImportFormats ] with the ‘Tfile’ option. The formats to be included are specified by a key string comprising one or more characters from the following set: dcpflLRruvtkxTF R-452 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Option Value Description The formats denoted by the key characters are described in Chapter 2 , ‘Running Miramo’ (see the description of the ‘-Tformats’ and ‘-TXformats’ command line options on page R-20). Note that the ‘F’ format flag copies text flow formats from text flow ‘A’ of the template file. To copy text flow formats from a different text flow, use the ‘Tflow’ option described below. Default: from ‘-Tformats’ command line option TXformats key Specify formats to be excluded from the template file given [ tplExFormats ] with the ‘Tfile’ option. The formats to be excluded are specified by a key string comprising one or more characters from the following set: dcpflLRruvtkxTF The formats denoted by the key characters are described in Chapter 2, ‘Running Miramo’ (see the description of the ‘-Tformats’ and ‘-TXformats’ command line options on page R-20). Default: from ‘-TXformats’ command line option Tflow name Set the name of the main textflow to name. Specific textflow [ textFlow ] attributes, for feathering, side-head settings and baseline synchronization, are as defined in a template file or by using the Template image processing mode tplImode normal | If the ‘-tplImode’ command-line option is set to bypass, any bypass images in EPS, JPEG, PNG or TIFF format that are imported by reference in a template document or that are imported using the PDF output options Opdf filename [ , pname ] Name of PDF file to create. On NT only, filename may optionally be followed by a comma and then the name, pname, of the printer driver to be used. See Note 7 on page R-460. Miramo Reference Guide [ v 9.2 ] R-453 Miramo DTD and XML codes CHAPTER 5 Option Value Description Opdfx filename [ , pname ] Name of PDF file to create. filename will contain no hypertext links. (Output files will be smaller than those created using the ‘Opdf’ option, and production will be faster.) On NT only, filename may optionally be followed by a comma and then the name, pname, of the printer driver to be used. See Note 7 on page R-460. Pmulti key | Output a PDF file or a PostScript file, or both, for each key+key printable chapter in a book. (See the ‘print’ option on the PDFmode normal | Method to use for creating PDF file. saveAs Setting the ‘PDFmode’ option to normal distills the temporary PostScript file in a single pass. R-454 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Option Value Description Setting the ‘PDFmode’ option to saveAs uses the FrameMaker ‘Save As’ method. The ‘PDFmode’ option must be set to saveAs to include .U3D or .SWF files. If ‘PDFmode’ is set to saveAs, the ‘PDFjobopts’ option must use the ‘+’ style of PDF joboptions file referencing. If the ‘PDFcmyk’ option is set to Y the value of ‘PDFmode’ is forced to saveAs. The ‘PDFmode’ option is not effective when running with versions of FrameMaker prior to version 9. See the ‘-PDFmode’ command line option on page R-14. Default: normal, unless forced to saveAs by setting the ‘PDFcmyk’ option to Y. PDFcmyk N | Y Specify CMYK color model in PDF output. Setting the ‘PDFcmyk’ option to N creates RGB PDF output. Setting the ‘PDFcmyk’ option to Y creates CMYK PDF output. If the ‘PDFcmyk’ option is set to Y the value of ‘PDFmode’ is forced to saveAs. The ‘PDFcmyk’ option is not effective when running with versions of FrameMaker prior to version 9. See the ‘-PDFcmyk’ command line option on page R-14. Default: N PDFjobopts file | Change the .joboptions file used for PDF output for a job. file file,file is name of file containing job options settings. If file contains one or more spaces, file must be surrounded by double quotes, "file name". On Windows a PDF joboptions file must always have a ‘.joboptions’ suffix. If file does not have a ‘.joboptions’ suffix, the suffix is silently assumed. For example, if the file value of the ‘PDFjobopts’ option is set to ‘foo’ this is taken as a shorthand for ‘foo.joboptions’. In the second form, file,file, the file following the comma separator is the name of file containing job options settings to use when creating separate PDF output for each chapter in a book, if different settings are required to the settings used when outputting the book as a single PDF file. This form is effective only if a ‘-Pmulti’ option is used (see pages R-13 and R-454). See also the ‘-PDFjobopts’ option on page R-14. For further notes and guidance relating to .joboptions files see section PDF .joboptions files (Windows only) on page R-32. PDFbookmarks Default | Set bookmark display in output PDF document. All | None See the ‘-PDFbookmarks’ command line option on page R-15 | int for a description of the option values. Default: From template, if specified, otherwise Default Miramo Reference Guide [ v 9.2 ] R-455 Miramo DTD and XML codes CHAPTER 5 Option Value Description PDFview Page | Set PDF document view on opening. Default | See the ‘-PDFview’ command line option on page R-15 for a Width description of the option values. Default: Page PDFthread N | F | C Set PDF article threads. See the ‘-PDFthread’ command line option on page R-15 for a description of the option values. Default:N PDFopenpage int Set page to display on opening the PDF document. Default:1 PDFpdests N | Y Create a named destination for every paragraph (slow). Default:N PDFtagged N | Y Create ‘Tagged’ PDF (slow). Default:N PDFpnames N | Y Include paragraph tags in bookmark text during Acrobat PostScript file generation. Ignored unless the ‘PAfile’, ‘Opdf’ or ‘Opdfx’ options are used. Book options Bfile filename Specify name of book file to be created. By convention a book [ bookName ] file name has the suffix ‘.book’, but any valid filename may be used. The ‘Bfile’ option cannot be used with any of the following Bappend N | Y N = create a new book file, Y = add to existing book file created by Miramo. Default:N Bupdate Y | N | OQ Set book update mode. | OS Value Description Y Update book chapters and book file, starting with closed book chapters. N No book update. R-456 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Option Value Description OQ Same as Y above, except that all chapters in the book are opened before updating, and all changes to the chapters and book file after the update are unsaved. OS Same as OQ above, except that all changes to the chapters in the book and the book file that result from the update are saved. See the -Bupdate command-line option on page R-10 for more details. Default:Y Bremove N | Y Remove (delete) a book file and its component documents [ deleteBook ] when finished processing. ‘Brm’ is an alias for ‘Bremove’. See the ‘-Bremove’ command line option, on page R-11. Default: N (see page R-11). Specify PDF bookmark hierarchy config filename file is name of a configuration file specifying Acrobat [ configFile ] bookmark levels. See the section entitled Controlling bookmark levels using a ‘config’ file in ‘Running Miramo’, on page R-34, for a description of how to set up a bookmark configuration file. Default: from the command line, if the ‘-config’ command line option is used (see page R-15). Operating mode options stripInput N | tab | Enable special processing of text containing binary tab, nl | all newline and carriage return characters. Value Description N No action (default). tab Strip occurrences of the character U+0009, HORIZONTAL TABULATION, from input text content. (By default binary tab characters are treated as printable tab characters.) Binary tab control characters may be included using the Miramo Reference Guide [ v 9.2 ] R-457 Miramo DTD and XML codes CHAPTER 5 Option Value Description imageCache N | Y Enable image caching when the tENC utf-8 | Specify the default document text processing mode. The [ textEncoding ] wcp-1252 option values may be in either uppercase or lowercase. See | us-ascii | the description of the ‘-tENC’ command line option on page iso-8859-1 R-9 for details. Default: utf-8 userapi string Name of user API client to run prior to print/save. See the ‘-userapi’ command line option on page R-21. Default: from -userapi command line option R-458 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes Option Value Description Job processing options (The following job processing options are not applicable on Solaris jobID string Specify a user or application-generated string to identify jobs and/or job types that are waiting, processing or completed. The value of ‘jobID’ is stored in the jobRecord ‘jobID’ attribute. See the fourth column in Figure 5.2, mmVisor Status, Settings, Environment and jobRecord screen, on page MS-32 and in Figure 5.6, Log file jobRecord data display, on page MS-34 in the mmServer Guide. string must be enclosed within a pair of quotation mark, ", or apostrophe characters, ', U+0027 APOSTROPHE or U+0022 QUOTATION MARK. string may comprise a set of any characters with the following exceptions: control characters (including newline characters) and the enclosing characters. maxProcTime seconds Override the default mmServer ‘maxProcTime’ processing channel group value for a job instance. The value of ‘maxProcTime’ is stored in the jobRecord ‘maxProcTime’ attribute. pcg int | name Use the ‘processGroup’ option to submit a job to a processing [ processGroup ] channel group other than the default. The ‘processGroup’ option may have an integer or a name value. If an integer, it refers to the processing channel group number. If a name, it refers to the processing channel group name. If a processing channel group is referenced by name its int value is looked up from the mmserver.xml mmServer configuration file in the %MM_HOME%\config folder. Default: 1 > Required Notes 1 Only one Miramo Reference Guide [ v 9.2 ] R-459 Miramo DTD and XML codes CHAPTER 5 3 Option values on one Examples The following is an example of a very simple Miramo input file, using the MiramoXML code demonstration R-460 Miramo Reference Guide [ v 9.2 ] CHAPTER 5 Miramo DTD and XML codes then a FrameMaker document called ‘demo.fm’ will be created and printed on the default system printer. Miramo Reference Guide [ v 9.2 ] R-461 Miramo DTD and XML codes CHAPTER 5 R-462 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp Introduction mmpp is a Miramo macro pre-processor. The basic operation of mmpp is to act as a filter between its input and its output. mmpp may be combined with Miramo in a single-pass process by using the Miramo ‘-m’ or ‘-Mfile’ command line options. The overall purpose of mmpp is to simplify the presentation of data for subsequent processing by Miramo. As well as macro definitions and expansions, mmpp supports macro arguments, file inclu- sion, reading and processing external files line-by-line, system commands, expression evaluation, conditional output, ‘for’ loops, variable definitions, ‘regular expression’ matching and substitution, as well as a number of powerful string and arithmetic func- tions. A summary of the mmpp built-in macros and functions, including several which are not documented elsewhere, is given on pages R-516–529. mmpp is text and line-oriented, and in this respect its capabilities are intentionally more restricted than some general purpose macro processors, such as m4. However as a pre- processor for Miramo input mmpp provides many special capabilities not available in other macro processors. The main advantages of using mmpp are: • Avoidance of repetition of large sections of Miramo markup, especially for formatting complex tables or for including multiple graphic images. • Conditional evaluation of macro arguments and arithmetic functions enables formatting issues to be handled in a sophisticated manner independent of the database extraction routines. For example color coding of printed output can be varied depending on data values. Similarly tab stop settings or point sizes for text can be varied according to the length of the text item being processed. • mmpp's support for defined variables and delayed evaluation of variables enables easy parameterization of document settings. It also provides for special, or boundary, conditions, for example excessive data, or exceptional page break conditions. • Two-pass processing. Though mmpp is normally used in single-pass mode, using the Miramo ‘-M’ or ‘-Mfile’ command line options, it is a stand-alone program and may be used in a shell script in two-pass mode, enabling otherwise impossible effects, for example including a table of contents section within a single target document. • Because mmpp is designed to integrate with Miramo, it is possible to avoid the need for frequent single or multiple backslash (‘\’, ‘\\’, ‘\\\’, etc) or other escape sequences when defining macros. Miramo Reference Guide [ v 9.2 ] R-463 mmpp — Miramo macro preprocessor CHAPTER 6 • Using the mmpp ‘<@map>’ code makes it easy to map or re-map characters to produce support for extended character sets and to change the representation of characters. • The ability to read and process unformatted or specially formatted (eg. ‘CSV’ or tab separated values) external files. The set of built-in macros and functions supported by mmpp has a different syntax to the inline markup supported by Miramo. While both programs support ‘system’ and ‘include’ functions with similar capabilities, they are invoked with different keywords. mmpp will pass through Miramo's and Running mmpp In general, mmpp is a filter which reads standard input and writes to standard output. Its usage is summarized here: mmpp [ -v ] [ -Mfile includefile ] [ inputfile ] where the ‘-v’ requests mmpp version to be printed to standard error. A file may be prepended to the input stream using the ‘-Mfile’ includefile option. Note that if mmpp is invoked using the Miramo ‘-M’ command line option, then the ‘-Mfile’ includefile option must be used to include a file to be processed by mmpp. The following simple shell script (Unix only) runs mmpp and Miramo as a two pass pro- cess: #!/bin/sh # mmpp2mif mmpp $1 > mmpp.out.$1 miramo -Omif $1.mif -Tfile myspec.tpl < mmpp.out.$1 rm mmpp.out.$1 Example 6.1 Using mmpp with Miramo in two passes (Unix) The equivalent .CMD script for use under Windows NT would be as follows: REM mmpp2mif.cmd mmpp %1 > mmpp_out_%1 miramo -Omif %1.mif -Tfile myspec.tpl < mmpp.out.%1 del mmpp_out_%1 Example 6.2 Using mmpp with Miramo in two passes (Windows NT) If Miramo is run with the ‘-M’ or ‘-Mfile’ option then by default Miramo executes mmpp and reads its standard output directly. If Miramo is run with ‘-m’ and ‘-diag’, then Miramo runs mmpp with the ‘-d’ command line flag. Note that the Miramo ‘-M’ and ‘-Mfile’ command line options runs mmpp by default only. If the $MMPP environment variable is set to the name of another filter program then this program will be invoked by Miramo in the place of mmpp. If Miramo is run with both mmpp (‘-M’ or ‘-Mfile’) and mmxslt (‘-X’ or ‘-Xfile’) command line options, mmpp reads the output from mmxslt and passes its output to the miramo program.1 R-464 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor mmpp exit codes The mmpp exit codes are listed in Table Value Description 6.1. 0 Success. No errors or warnings Using comments 1 Fatal error. E.g. syntax error 2 Non-fatal error. Warnings were issued In mmpp the character string ‘@-’ denotes the beginning of a comment. Table 6.1 mmpp exit codes The comment text is terminated by a newline. The comment character string may be disabled by preceding it with a backslash escape character ‘\’, as in ‘\ If @- is placed at the beginning of a line, or is pre- @------ceded by whitespace only, the whole line is dis- @--- sales_by_region.mmp carded by mmpp. The input shown in Example 6.3 @------@- Date: May 24, 2018 will produce no output. @------If a comment string, ‘@-’, is included part-way along Example 6.3 Input with no output an input line, then text after the comment string, the comment string itself and any whitespace immediately preceding the comment string is discarded. Thus the output from: ABC @--- Three letters from the Roman alphabet is the string ‘ABC’ (without trailing whitespace) followed by a newline. Example 6.4 shows a simple @------macro definition containing com- @- MACRO: LargeNumber ments. @------@- (Fit long string of digits in table column) All ‘ mmpp when the macro is called, $1 @--- Reduce text size and such comments may be used } @else { @--- Normal size number within macro definition bodies to $1 improve the readability of the out- } put of the Miramo input file, as } @--- END of LargeNumber macro @------well as for help with debugging. Example 6.4 Simple macro definition Defining variables A variable definition comprises a variable code (<#define>, which may be abbreviated to <#def>), a variable name and a variable value. Every variable definition must start with the code ‘<#define>’ or ‘<#def>’. This code must be at the beginning of a line (or be preceded by whitespace only). The variable name must be on the same line as the variable code, fol- lowed by the variable definition. 1. The optimal way to combine mmpp and mmxslt processing is to use mmpp X macros, described on pages R-500–515. Miramo Reference Guide [ v 9.2 ] R-465 mmpp — Miramo macro preprocessor CHAPTER 6 Variable names can be created on a dynamic, data-driven basis: when a variable is defined within a macro definition, its name may also be the value of a macro argument or another variable. The variable name ‘two- <#define> two-humped Bactrian humped’ is given five defini- <#define> two-humped {Bactrian} tions in Example 6.5 <#define> two-humped @toupper( Bactrian ) <#define> two-humped {BROWN @toupper( Bactrian )} Each succeeding definition <#define> two-humped {brown @tolower( { Bactrian}) (with a single space replaces its predecessor, which before and after it) } is forgotten. Example 6.5 Repeated variable definitions To define variables whose val- ues include either whitespace (which is not part of a function argument) or newlines, enclose the variable values with curly brace delimiters, ‘{’ and ‘}’. A variable may be defined as an empty string by using curly brace delimiters, ‘{’ and ‘}’, with nothing between them. A variable instance comprises the variable name preceded by an opening delimiter, ‘<#’, and followed by a ‘>’, as in ‘<#name>’, for example: A <#two-humped> camel is easy to ride A variable value may include text, built-in functions such as @len( ), @eval( ), @toupper( ), @tolower( ), @mifstr( ) and @gsub( ), and already defined variable instances (‘<#name>’). Functions and variable instances are evaluated immediately except for when they occur in macro body definitions (see page R-474). Example 6.6 illustrates dynamic naming of variables: 1 <@macro> vardef { 2 <#def> $1 $2 name1 3 $1 4 value1 5 <#name1> value2 6 <#def> <#name1> value2 Figure 6.1 Output from Example 6.6 7 <#value1> 8 } 9 <|vardef> name1|value1 Example 6.6 Dynamic variable naming will produce the output shown in Figure 6.1. Variable names A variable name may be any string comprising the upper Head-24 and lower case ASCII letters A through Z and the under- _Alpha score character, ‘_’. The following additional characters DrawRule.0.5pt _ - _ - - may be included within a variable name, provided they MyFavoritePhotographs are not at the beginning: the digits 0 through 9, ‘-’ and ‘.’. Example 6.7 Valid variable names Example 6.7 shows some valid variable names. A variable name may be up to a 1000 bytes long. Variables and macros (see later) have different name spaces, i.e. it is possible to define a variable and a macro of the same name. R-466 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor Built-in variables mmpp has a single built-in variable definition, ‘OS’. The value of ‘OS’ is a string denoting the type of the host operating system on which mmpp is running. This string can have two values: unix or nt. The ‘OS’ variable makes it easier to write platform independent macros. The macro shown in Example 6.8 will work on any host. <@macro> copyfile { @if (<#OS> = nt) {<@system> {copy $1 $2} @--- Use NT copy command @else {<@system> {cp $1 $2}} @--- Use Unix copy command } <@copyfile> a b <|copyfile> horse.txt | donkey.txt Example 6.8 Using the built-in <#OS> variable (In Example 6.8 ‘<@copyfile>’ and ‘<|copyfile>’ are two different methods of calling the ‘copyfile’ macro. How to define and call macros is described in the following sections.) Defining standard macros A standard macro definition1 comprises a macro code, a macro name and a macro body. Every macro definition must start with the macro code, ‘<@macro>’. This code must be at the beginning of a line (or be preceded by whitespace only). The macro name must be on the same line as the macro code. The macro body is always enclosed by ‘{’ and ‘}’ delimit- ers. The opening delimiter, ‘{’, must be on the same line as the macro code and the macro name. In the case of basic macro definitions, the closing delimiter must be at the end of a line, i.e. it must be followed by a newline character, or whitespace (tab or space) charac- ters followed by a newline character. The set and order of characters that may be used in a macro name is the same as for a vari- able name (see the section Variable names on page R-466). Examples of standard macro definitions. Example 6.9 contains several simple stan- <@macro> birds { dard macro definitions. All the macro creatures with feathers definitions in Example 6.9 produce iden- } tical output whenever the macro ‘name’ is <@macro> birds {creatures with feathers called using <@name> or <|name>. } In Example 6.9, the macro ‘name’ is <@macro> birds { creatures with feathers} recorded as the string "creatures with feathers\n", i.e. "creatures with feathers" <@macro> birds {creatures with feathers} followed by a newline character. If the Example 6.9 Standard macro definitions mmpp input shown in Example 6.10 is processed by mmpp, the output will be as shown in Figure 6.2. 1. An alternative macro format, X macros, is described on pages R-500–515. Miramo Reference Guide [ v 9.2 ] R-467 mmpp — Miramo macro preprocessor CHAPTER 6 <@macro> birds {creatures with feathers} text before macro text before macro <@birds> creatures with feathers text after macro text after macro Example 6.10 Simple macro definition (2) Figure 6.2 Output from Example 6.10 Macros may be defined anywhere within an mmpp input stream. Macros must be defined before they are called, unless they are called within the body of another macro. In this case they must be defined before the calling macro is called. If a macro name is re-used, then all previous definitions of the macro with the same name are lost. Re-defining macros can be useful, and no warning messages are issued in this case. Built-in macros, for example ‘<@include>’ cannot be re-defined. Newlines and whitespace within macro definitions The treatment of newlines and whitespace within a macro definition body is as follows: • A newline encountered either immediately after the opening curly brace of the macro definition body, or separated from the opening curly brace by white space only, is ignored. In the latter case the whitespace is also ignored. • If there is no newline immediately before the closing curly brace of the macro definition body, and the closing curly brace is preceded by non-whitespace text of any kind, then a newline is added. • If on the input line containing the closing curly brace ‘}’ of the macro definition body, the closing curly brace is preceded by whitespace only, this whitespace is discarded. • All whitespace and newlines surrounding control flow statements (@if, @else and @for), macro calls, mappings variable definitions, and special functions such as <@write>, are discarded. • Newlines elsewhere within the macro body are output unchanged. Since newlines after the beginning of a macro definition body and before its end are sig- nificant the macro definitions shown in Example 6.11 will produce identical output, as shown in Figure 6.3. ======AA ======start <@macro> newlines { ======AA ======start @--- Next line has 4 x space ------} ------======BB ======start <|newlines> ------======BB ======start <@macro> newlines { ======CC ======start @--- Next line has tab ------} ------======DD ======start <|newlines> ------======CC ======start ======<@macro> newlines { } Figure 6.3 Output from macro calls ------in Example 6.11 <|newlines> ======DD ======start <@macro> newlines {} R-468 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor ------<|newlines> ======Example 6.11 Newline processing (1) A further illustration of newline processing is shown in Example 6.12 and Figure 6.4. 1 ======AA ======2 <@macro> name { 3 ======AA ======4 macro ------5 6 body text macro 7 } 8 ------body text 9 <|name> ======BB ======10 ======BB ======------11 <@macro> name { 12 macro 13 macro 14 body text 15 body text} Figure 6.4 Output from macro calls 16 ------in Example 6.12 17 <|name> Example 6.12 Newline processing (2) (Each word, ‘macro’, ‘body’ and ‘text’, is output on a line by itself, and an extra newline is placed before and after the word ‘macro’.) The foregoing rules relating to the treat- <@macro> nothing { ment of newlines and whitespace <#def> zero 0 within a macro definition body can @for(i = 1 to 50) { <#def> zero @eval(<#zero> + $$i) have surprising results. The first of the } macros in Example 6.13, ‘nothing’, pro- } duces no output when called. <|nothing> <@macro> 5newlines {@for(i = 1 to 5){}} The other macros in Example 6.13, ‘_5- <|_5-newlines> newlines’ and ‘_1-newline’, will output <@macro> 1newline {} five and one newlines respectively. This <|_1-newline> is because they contain strings, albeit Example 6.13 Newline processing (3) empty strings, without <#define>s or control-flow statements to ‘nullify’ these strings. The treatment of newlines and whitespace after and before the opening and closing curly braces, ‘{’ and ‘}’, following control-flow statements is identical to that following the open- ing and closing curly braces surrounding a macro definition body. Note that a completely empty macro definition, {}, outputs nothing. Argument place holders: $1, $2, ... $n A standard macro definition body may contain an unlimited number of argument place holders. These place holders are denoted by ‘$n’, where n may be any integer from 1 upwards, without leading zeros. When the macro is called any occurrence of ‘$n’ in its body is replaced by whatever text string is provided by its nth argument. Any instance of a $, immediately followed by a non-zero digit, itself optionally followed by any number of Miramo Reference Guide [ v 9.2 ] R-469 mmpp — Miramo macro preprocessor CHAPTER 6 contiguous digits is interpreted as an argument place holder. $0 is a place holder for the macro name. Thus a macro definition body containing ‘$1 and $2’ will output ‘Jack and Jill’ in the case that its first argument is ‘Jack’ and its second argument is ‘Jill’, so that: <@macro> whoandwho {$1 and $2} <@whoandwho> Jack Jill outputs: Jack and Jill If a standard macro definition contains one or more argument place holders having numeric values greater than the number of arguments supplied when the macro is called, then these argument place holders are substituted by a zero length string. For example, if a macro definition body contains the string ‘$4449’ and there are less than 4,449 argu- ments when the macro is called, then ‘$4449’ will be replaced by a zero length string on output. Argument place holders are also substituted by a zero length string when the argument value itself is zero length. Numeric strings which begin ‘$0’, immediately followed by one or more digits, always result in the name of the macro being output followed by the digits after the zero. Thus ‘$01234’, for example, will be replaced by ‘macroname1234’. $ style argument references may be included in (or at the beginning of) numeric strings by enclosing the reference within curly braces, ‘{’ and ‘}’. Matched pairs of curly braces are always discarded when a macro is evaluated. Example 6.14 illustrates the operation of ‘$0’ and ‘$n’ when encountered in numeric strings: Passing the text in Example 6.14 through mmpp produces the output shown in Figure 6.5. <@macro> argtest { 1. $ output = 1$1 1. $ output = 1FirstArg 2. $ output = 1$1234 2. $ output = 1 3. $ output = {$1}0234 3. $ output = FirstArg0234 4. $ output = 1{$01}234 4. $ output = 1argtest1234 5. $ output = 1{$2222}234 5. $ output = 1234 6. $ output = 1{222}4 6. $ output = 12224 8. $ output = 1$1AB234 8. $ output = 1FirstArgAB234 9. $ output = 1$A3B234 9. $ output = 1$A3B234 } Figure 6.5 Output from macro calls in Example 6.14 <|argtest> FirstArg Example 6.14 Newline processing (1) Argument substitution is more complicated when a <@macro> Farewell { macro definition body includes a call to another $1 $2 macro. In Example 6.15 when the macro ‘Farewell’ } <@macro> Aurevoir { is called from within the macro ‘Aurevoir’, the sec- $1 ond and third arguments to ‘Aurevoir’ will be substi- <@Farewell> $2 $3 Bon chance! tuted for the first and second argument place holders } in the macro body of ‘Farewell’. Example 6.15 Argument substitution (including a call to another macro) R-470 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor Additional argument place holders: $#, $*, $(n) and $(m - n) The $#, $*, $(n) and $(m - n) argument place holders enable flexible argument addressing and manipulation. Their meanings are described below: $# Argument count. A ‘$#’ within the body of a macro definition will be sub- stituted by the number of arguments given to the macro when it is called. $* All arguments. A ‘$*’ within the body of a macro definition will be sub- stituted by the text of all of the arguments given to the macro when it is called. Each argument is separated by a vertical bar sign, ‘|’. For example calling the macro ‘printargs’: <@macro> printargs { $* } <|printargs> lions|tigers produces: lions|tigers The set of arguments passed to a macro can be passed to another macro which is called from within the first macro. For example: <@macro> controlmacro { @if($1 = 1) {<|macro.one> $* } @if($1 = 2) {<|macro.two> $* } } $(n) Argument number. A $(n) within the body of a macro definition will be substituted by argument $n. n may be a literal integer, a variable having an integer value, an expres- sion which evaluates to an integer or a macro argument in the form ‘$n’ having an integer value. Additionally n may be $#. $($#) is always the value of last argument to a macro. If n is a literal integer, then $n and $(n) are equivalent. For example, $(1) is equivalent to $1. If the third argument to a macro has the value 948, then $($3) is the value of the 948th argument. $(m - n) Argument range. A $(m - n) within the body of a macro definition will be substituted by all arguments in the range $m to $n. m must be greater than zero and less than n. Each argument is separated by a vertical bar sign, ‘|’. m and n may be literal integers, variables having integer values, expres- sions which evaluate to integers or macro arguments in the form ‘$n’ having integer values. Additionally n may be $#. Several possible usages are shown in Example 6.16. A subset of the arguments passed to a macro can be passed to another macro is which called from within the first macro. For example: <@macro> controlmacro { @if($1 = 1) {<|macro.one> $(2 - $#)} @if($1 = 2) {<|macro.two> $(2 - $#)} } Example 6.16 illustrates several of the usages of $#, $* and $(m - n). Miramo Reference Guide [ v 9.2 ] R-471 mmpp — Miramo macro preprocessor CHAPTER 6 1 <@macro> rangevars { 2 <#def> argc $# 3 4 5 6 \$(1 - \@eval(\$# - 2)): $(1 - @eval($# - 2)) @--- Equivalent to $* 7 \$(4 - \<#argc>): $(4 - <#argc>) @--- Arguments 4 to end 8 \$(1 - 43): $(1 - 43) @--- Arguments 1 to 43 9 @--- (missing arguments are 10 @--- silently ignored) 11 \$(1 - 3): $(1 - 3) @--- Arguments 1 to 3 12 \$(\$1 - \$2): $($1 - $2) @--- Arguments 3 to 8 13 14 } 15 <|rangevars> 3|4|a3|a4|a5|a6|{a9 16 a9a9}|a10 Example 6.16 Using $#, $* and $(m - n) The output from Example 6.16 is shown in Figure 6.6. $(1 - @eval($# - 2)): 3|4|a3|a4|a5|a6 Calling standard macros $(4 - <#argc>): a4|a5|a6|a9 a9a9|a10 There are two styles for calling standard $(1 - 43): 3|4|a3|a4|a5|a6|a9 a9a9|a10 macros. In the simplest case, when $(1 - 3): 3|4|a3 there are no macro arguments, a macro $($1 - $2): a3|a4 may be called by enclosing the macro name with a beginning delimiter, which Figure 6.6 Output from macro calls in Example 6.16 may be ‘<@’ or ‘<|’, and an end delimiter, which is always ‘>’, thus: ‘<@name>’ or ‘<|name>’. A call to a macro must always be at the beginning of an input line (or be pre- ceded by whitespace only).1 A macro definition, along with the two methods of calling the macro are shown below. <@macro> Uppercase { ABCDEFGHIJKLMNOPQRSTUVWXYZ } The above may be called by: <@Uppercase> or <|Uppercase>. In both cases the output will be: ABCDEFGHIJKLMNOPQRSTUVWXYZ The difference between the two styles of calling macros, distinguished by using ‘@’ or ‘|’ as the second character of the opening delimiter, is in the presentation of macro arguments. If a macro is called using ‘<@name>’, then arguments are processed as a series of strings separated by one or more tabs or spaces. Arguments which include whitespace or new- lines may be enclosed by curly brace delimiters, ‘{’ and ‘}’. Given this macro definition: 1. An exception to this rule occurs in the special case that a macro is called within the macro definition body of another macro: <@macro> bb { <|aa> } or <@macro> bb { <|aa> } This is because any text following the ‘{’ opening delimiter is deemed to be on a new line. R-472 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor <@macro> Letters { $1 $2 $3 $4 $#} The calls shown in Example 6.17 will produce iden- <@Letters> AAAA BBBB CCCC tical output. viz. AAAA BBBB CCCC 3 <@Letters> {AAAA} BBBB {CCCC} AAAA BBBB CCCC 3 <@Letters> AAAA {BBBB} CCCC AAAA BBBB CCCC 3 <@Letters> {AAAA} BBBB CCCC AAAA BBBB CCCC 3 <@Letters> AAAA BBBB {CCCC} AAAA BBBB CCCC 3 Example 6.17 Calling macros (1) (‘3’ is the number of arguments, requested by ‘$#’.) All whitespace and newlines following an argument opening delimiter, ‘{’, and preceding the argument closing delimiter, ‘}’, are regarded as being part of the argument itself. (Note that this differs from the handling of newlines after and before opening and closing delim- iters in macro definition bodies.) If the macro shown above, i.e. <@macro> Letters { $1 $2 $3 $4 $#} is called by: <@Letters> AAAA { BB BB } CCCC The output will be: AAAA BB BB CCCC 3 In the above output the single space indent preceding the third argument string, ‘CCCC’, results from the space character placed between the ‘$2’ and ‘$3’ argument place holders in the ‘Letters’ macro definition body. The two spaces preceding the ‘3’ result from ‘$4’ being a zero length string (since only three arguments are supplied). Arguments to macros called with the opening delimiter ‘<|’, as in ‘<|name>’, are separated by the ‘|’ character. Arguments which span more than one line (i.e. which contain at least one newline character) must be enclosed by the curly brace delimiters, ‘{’ and ‘}’. For example, an alternative method of calling the ‘Letters’ macro above is: <|Letters> AAAA|{ BB BB }| C{CC}C Again, the output will be: AAAA BB BB CCCC 3 Matching curly braces, ‘{’ and ‘}’, are stripped from the result of macro expansion. Conse- quently substitution of the third argument " C{CC}C" above is expanded as: " CCCC". Whitespace between arguments in a macro call is ignored. The following macro calls are equivalent: <@Letters> AAAA BBBB CCCC <@Letters> AAAA BBBB CCCC <|Letters> AAAA|BBBB|CCCC <|Letters> AAAA|BBBB|CCCC To include initial white space in the first argument to a macro called using <|macroname>, Miramo Reference Guide [ v 9.2 ] R-473 mmpp — Miramo macro preprocessor CHAPTER 6 surround the argument with matched curly braces: <|Letters> { AAAA}|BBBB|CCCC Each argument passed to a macro is initially treated as a string, i.e. it is implicitly sur- rounded by curly braces. Macro expansion and evaluation Macro evaluation is always delayed until the macro is called. When a macro is called it is first expanded by substituting arguments as appropriate, and it is then evaluated. Evalua- tion covers conditionals, functions, variable definitions, etc. This process is repeated each time a macro is called. Using variables in macros Variable definitions are evaluated immediately unless they occur within a macro defini- tion body, in which case the variable is evaluated when the macro is called. A useful effect of this is that variables within macros may be incremented, thus providing a means of maintaining running totals or counts. Example 6.18 illustrates how delayed evaluation of variable instances within a macro def- inition body allows a variable to be defined using its own previous value. @------<#define> n 2 <#define> ALB Albertine @------<@macro> plustwo { <#n> <#define> n @eval( <#n> + 2 ) } @------<@macro> albert { <#ALB> <#define> ALB {Albertine + <#ALB> } 2 } 4 @------6 <@plustwo> Albertine <@plustwo> Albertine + Albertine <@plustwo> Albertine + Albertine + Albertine <@albert> <@albert> Figure 6.7 Output from Example 6.18 <@albert> Example 6.18 Incrementing variables The output from Example 6.18 is shown in Figure 6.7. Note that the last three lines of output are indented. This is because a tab character precedes the <#ALB> variable in the macro definition body of the macro ‘albert’. Defining and using arrays in macros mmpp supports one or two dimensional arrays, which can be defined and used within a macro for storing text and numbers for use later in the mmpp input stream. Arrays are similar to mmpp variables except that while array elements may be defined any- where, they may only be referenced within macros. Arrays are useful for storing or accu- R-474 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor mulating a number of related pieces of information for use later. Each piece of information is stored as an array ‘element’ which may be referenced using one or two inte- ger subscripts to locate its position within the array, often within an @for( ) loop. It is not necessary to ‘declare’ an array, or to specify how many elements an array has, or to specify whether the array is one or two dimensional (i.e. whether one or two integer subscripts are required to reference an array element). An array springs into existence the first time it is defined or used. An array element definition comprises an array definition code (<#define>), an array ele- ment name, and a value. The array element name comprises a string, followed immedi- ately by an open square bracket ‘[’, followed by either one or two comma separated positive integer subscript values, followed by a closing square bracket ‘]’. An array element name may be any string comprising the upper and lower case alphabetic letters A through Z, the digit 0 through 9 and the underscore character, ‘_’. The following additional characters may be included within array names providing they are not at the beginning: ‘-’ and ‘.’. The following are examples of array element names: Names[1] total[$$i, $$j] Column-Opts[<#x>,<#y>] Array element subscript values may be expressed as loop or macro parameters (eg $$i, $i, $3), variable instances (eg <#n>) or positive integers (eg ‘4’) or the result of arithmetic expressions returned by @eval( ). Array element subscripts must evaluate to positive inte- ger values, i.e. in the last example above, the variables <#x> and <#y> must be defined as integers, not as text or non-integer numbers. In addition, all array element references for a given array must use the same number of integer subscript values, so that the following: <#def> Names[1] Doe ... <#def> Names[1,2] John will cause an error. Some examples of array element definitions are shown in Figure 6.8. <#define> names[1] {Daniel O'Connell} <#define> attributes[<#row>, <#col>] {lr=None} <#define> total[<#col>] @eval($total[<#col>] + 22) Figure 6.8 Defining array values The last example above incorporates an array element reference $total[<#col>] which is evaluated when the containing macro is called. (See ‘Using variables in macros’, on page R-474, for a discussion of delayed evaluation of variable and array instances within macro bodies). An array element reference must begin with the ‘$’ character, and is immediately followed by an array element name. The following are examples of array element references: Miramo Reference Guide [ v 9.2 ] R-475 mmpp — Miramo macro preprocessor CHAPTER 6 $Names[1] $total[$$i, $$j] $Column-Opts[3,2] Example 6.19 illustrates the use of arrays in conjunction with @for loops within a macro. <#def> rc 0 <#def> cols 0 <#def> coltot {} <@macro> addto { <#def> rc @eval(<#rc> + 1) @if($# > <#cols>) {<#def> cols $#} @for (i=1 to $#) { <#ifndef> total[$$i] 0 <#def> total[$$i] {@eval($total[$$i] + $i)} } } <@macro> showtotals { @--- @--- Down the page @for (i=1 to <#cols>){Total for column $$i is $total[$$i]} @--- @--- Across the page (must use a variable to keep output on same line) @for (i=1 to <#cols>){<#def> coltot {<#coltot>Col$$i = $total[$$i]; }} <#coltot> <#def> rc0 Total for column 1 is -3 <#def> cols0 Total for column 2 is 13 <#def> coltot{} Total for column 3 is 0 } Total for column 4 is 13 <|addto> 1 Col1 = -3; Col2 = 13; Col3 = 0; Col4 = 13; <|addto> -1|0|-3|4 <|addto> 5|9|-3|9 Figure 6.9 Output from Example 6.19 <|addto> -8|4|6 <|showtotals> Example 6.19 Incrementing variables The output from Example 6.19 is shown in Figure 6.9. Environment variables in macro and variable definitions The values of environment variables defined in the environment running mmpp can be accessed within the body of a macro, variable or array element definition using the form ‘${varname}’. If mmpp is run as a Miramo preprocessor, using the ‘-M’ or ‘-Mfile’ command line option, then the ‘-sendEnv’ command line option must be set to Y for user environ- ment variables to take effect (see the ‘-sendEnv’ command line option on page R-7). If the environment variable is undefined, the string ‘${varname}’ is silently replaced with a zero length string. No warning message is printed. Note that the name of the environment variable must be enclosed in curly braces, ‘{’ and ‘}’, as shown. If these braces are omitted, as in the string ‘$varname’, then the string is treated as ordinary text. There is no method of directly accessing the following built-in Unix Bourne shell environ- ment variables: $#, $*, $@, $-, $?, $$ and $!. To access the values of these variables they must first be assigned to a variable having a simple name. For example, if the value of ‘$$’, the process id of the current process, is assigned to a shell variable called ‘PID’ thus: #!/bin/sh PID=$$ ; export PID Then the value of the current process id may be accessed within mmpp as follows: R-476 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor <#def> PID {${PID}} (The outer curly braces, ‘{’, and ‘}’, in the above protect against mmpp reporting a fatal error in the case the environment variable is not defined.) Using <@map> The ‘<@map>’ code enables the translation of an input string to an output string and works in a similar way to ‘<#define>’. Mappings are defined using the following syntax: <@map> inputstring outputstring or <@map> inputstring {outputstring} Curly braces are required around the outputstring if it contains spaces. In general the inputstring cannot contain whitespace characters or any of the ‘$’, ‘<’, ‘>’, ‘&’ or ‘;’ charac- ters: all other printable 7-bit ASCII characters are allowed. The exception to this rule is that inputstring may comprise a single <#name>, where name is the name of a variable itself defined as a string which contains only the characters permitted for the inputstring of <@map>. Thus this is allowed: <#def> numb33 33 <@map> <#numb33> {thirty three} In the above case when input text contains the string ‘&33;’ the ‘&33;’ will be replaced by ‘thirty three’. This behavior is useful creating mappings automatically. A string may be mapped to the empty string by using curly brace delimiters, ‘{’ and ‘}’, with nothing between them, as the outputstring. The major difference between <#define> and <@map> is that instances of strings to be mapped in the input are delimited by an opening ‘&’ character and a closing ‘;’ character. If the input contains an ‘&’ and ‘;’ delimited string which is not previously mapped using the ‘<@map>’ code, then this string, including the delimiters, is passed through untouched. If the input contains an ‘&’ and ‘;’ delimited string which has been mapped using the ‘<@map>’ code, the mapping may be prevented by escaping the string with a preceding backslash, ‘\ ’, character. 1 @------2 <@macro> MapTest { 3 <@map> bull bullmap bullmap 4 <@map> ABCvalue &zzzz; ABCvalue 5 <#def> ABC ABCvalue &ABC; 6 <#def> DEF $1 \&ABC; 7 <#def> D {… • \•} &ABCvalue; 8 <@map> hello $1 \&ABCvalue; 9 <@map> hello2 &$1; \&<#ABC>; 10 @------XYZ 11 • … bullmap \• 12 <#ABC> XYZ 13 &ABC; &XYZ; 14 \&ABC; &\&hello;; 15 &<#ABC>; &XYZ; 16 \&<#ABC>; &zzzz; 17 \&\<#ABC>; &XYZ; 18 <#DEF> Figure 6.10 Output from Example 6.20 19 <#D> 20 &hello; Miramo Reference Guide [ v 9.2 ] R-477 mmpp — Miramo macro preprocessor CHAPTER 6 21 &&hello;; 22 &\&hello;; 23 &hello2; 24 &ABCvalue; 25 &$1; 26 @------27 } 28 <@MapTest> XYZ Example 6.20 String replacement using <@map> If the input shown in Example 6.20 is run through mmpp, then the output will be as shown in Figure 6.10. Note that ‘&’ and ‘;’ delimited strings which represent character encodings ‘built-in’ to, and recognized by, Miramo, for example, ‘\…’, ‘\•’, etc, have no special meaning within mmpp, unless they are mapped using ‘<@map>’ code. Hence the ‘<@map>’ code may be used to override a Miramo built-in character encoding. et seq.). Simple string processing functions mmpp supports five simple built-in string processing functions: @len( ), \@substr( ), @toupper( ), @tolower( ) and @mifstr( ). The operation of these functions is described in the Summary of built-in macros and functions at the end of this chapter (see page R-522). All string processing functions take a single string as their argument. Example 6.21 illus- trates using the @len( ) function. 1 <#define> d {ddd ddd} 2 <#define> g {ggg gg} 3 <#define> alen @len(aaaa) 4 <#define> ylen @len( ) 5 <#define> blen @len( {bb b}) 6 <@macro> length { 7 <#define> clen @len($1) 8 <#define> dlen @len ( <#d> ) 9 <#define> elen @len ( { <#d> <#g> } ) 10 <#alen>, <#ylen>, <#blen>, <#clen> : <#dlen>, <#elen> 11 } 12 <|length> cc c Example 6.21 Using @len( ) The output from Example 6.21 is: 4, 4, 5, 4 : 8, 18 In the definition of ‘clen’ in the seventh line of Example 6.21 above, the ‘$1’ place holder for argument substitution is not surrounded by curly braces. This is because individual arguments to macros are always treated as single strings. However it is perfectly accept- able to place curly braces around all argument place holders, as well as around variable values in definitions. The following is not allowed: <#define> alen @len(aa aa) This is because the @len( ) function (as well as the @toupper( ), @tolower( ) and @mifstr( ) functions) may have only a single string as its argument. The correct form of the above is: <#define> alen @len( {aa aa} ) R-478 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor This assigns the value 5 to ‘alen’. The @substr( ) function returns a substring from a string and must contain at least two comma separated arguments and may contain three. In the case of @substr(string, position) the suffix of string starting at position is returned. In the case of @substr(string, position, length) the substring of string starting at position containing length characters is returned. The position of the first character in a string is 1. The position of the second character in a string is 2. In the (unusual) case string is a literal string, then it must be surrounded by curly braces, ‘{’ and ‘}’. The second and optional third arguments to @substr( ) must never be surrounded by curly braces. Example 6.22 illustrates the usage of @substr( ). <@macro> capfirst { <#def> firstchar @substr(@toupper($1), 1, 1) <#def> remainder @substr($1, 2) <#def> cherries @substr({ is a bowl of cherries}, 1, 10) <#firstchar><#remainder><#cherries> } <|capfirst> the meaning of Life Example 6.22 Using @substr( ) The output from Example 6.22 is: The meaning of Life is a bowl @substr( ) is more useful when used in conjunction with the @matchlen( ) and the @match( ) functions, discussed later. Splitting strings with the @slice( ) function The @slice( ) function splits its string argument into a series of substrings and passes the substrings to a user defined macro. The syntax for @slice is shown below. @slice({string}, key [, postopts]) macroname [fieldwidths] key may be either: fw (field widths) or tsv (tab separated values). string can be any of: a literal string, a variable, an array element or a macro argument (‘$n’). postopts can be any of: trim, ltrim or rtrim. trim removes whitespace from both the begin- ning and end of the sub-string. ltrim removes whitespace from the beginning of the sub- string. rtrim removes whitespace from the end of the sub-string. ‘Whitespace’ comprises a sequence of one or more tab or space characters. fieldwidths may only be used if key is set to fw. fieldwidths specifies a series of sub-string sizes by their lengths (number of 8-bit characters), each preceded by the vertical bar sign (‘|’). If an input string is shorter than the total length of the fieldwidths then the extra field- widths are silently ignored. Similarly, if the length of the input string is greater than the total of the fieldwidth values the extra characters are ignored. A fieldwidths specification ending with ‘|-’ will assign all the remaining characters in the input string to the last argu- ment to macroname. macroname is a user-defined macro which is passed each sub-string as a separate argu- ment, starting from 1 (‘$1’) through to n. There is no limit to the size of n (nor to the Miramo Reference Guide [ v 9.2 ] R-479 mmpp — Miramo macro preprocessor CHAPTER 6 length of an input string). Example 6.23 illustrates the usage of the @------<@macro> date { @slice( ) function. The output from Exam- <#def> year $1 2001 ple 6.23 is shown in Figure 6.11. <#def> month_no $2 10 <#def> day_no $3 30 The string splitting requirement illustrated <#year> Figure 6.11 Output <#month_no> from Example 6.23 in the above example is so simple that the <#day_no> same effect could just as well be achieved } using the @substr( ) function. A more prac- @------<@macro> datestring { tical use of the @slice( ) function is shown @slice($1, fw, rtrim) date|4|2|2 in Processing ‘fixed field width’ files using } @------<@readfile>( ), on page R-497. <|datestring> 20011030 @------Regular expressions, text matching and Example 6.23 Using @slice( ) text replacement mmpp supports five built-in pattern matching and text substitution functions: @match( ), @matchlen( ), @matchcount( ), @sub( ), and @gsub( ). All these functions use ‘regular expressions’ as a notation for specifying and matching text.1 A regular expression may be supplied as an argument to one of the five mmpp pattern matching and substitution functions as any one of the following: – a variable instance, e.g. <#varname> – an array reference, e.g. $arrayname[2] – a mapping instance, e.g. &name; – a loop parameter instance, e.g. $i or $$i – a macro argument instance, e.g. $1 or $# – a string processing function i.e. @toupper( ), @tolower( ), @mifstr( ) – a text substitution function, i.e. @sub( ), @gsub( ) – text, whitespace and any of the above enclosed within curly braces, ‘{’ and ‘}’, using the same syntax as for a macro definition body Each of the above will be expanded into a sequence of characters representing a regular expression. For example, within a ‘numberof’ macro called as follows: <|numberof> [0-9]+|^[A-Z] ‘$1’ expands into the regular expression ‘[0-9]+’. and ‘$2’ expands into the regular expres- sion ‘^[A-Z]’. A ‘|’ within a regular expression in a macro argument must be escaped using a backslash, ‘\’. 1. Detailed descriptions of how regular expressions work, along with many examples, are contained in The AWK Programming Language by Aho, Kernighan and Weinberger, Addison-Wesley, 1988, ISBN 0-201- 07981-X, pp 28-43; sed & awk by Dale Dougherty, O'Reilly & Associates, 1992, ISBN 0-937175-59-5, pp 27-55; and, most comprehensive, Mastering Regular Expressions by Jeffrey E. F. Friedl, O'Reilly & Associ- ates, 1997, ISBN 1-56592-257-3. The Miramo program code used to evaluate regular expressions is based on publicly available source code written by Henry Spencer. This source code is copyright by the University of Toronto (and carries a notice saying that it may be used freely subject to the restriction that the author is not responsible for any conse- quences whatsoever). R-480 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor A regular expression differs only from a text string in the interpretation of the special (‘meta’) characters it contains. Regular expression metacharacters are: ^ $ . [ ] | ( ) * + ? Their meaning is summarized in Table 6.2. Table 6.2 Metacharacters in regular expressions Metacharacter(s) Meaning . Matches any single character ^ Matches the beginning of a string $ Matches the end of a string [chars] A character class. Matches any single character from chars, so [XYZ] matches any one of the characters X,Y or Z. chars can incorporate ranges of characters, so [A-Za-z0-9] matches any alphanumeric character. If the first character in chars is ‘^’ (carat), all characters except the remaining characters in chars are matched, so [^0-9] is a complemented character class which matches any character which is not a number. Note that this differs from the interpretation of the carat character ‘^’ outside square brackets, where it is used to match the beginning of a string. char Matches the meta character char literally (regexp) Round brackets are used for grouping regular expressions * Matches zero or more occurrences of the preceding regexp + Matches one or more occurrences of the preceding regexp ? Matches zero or one occurrences of the preceding regexp regexp1|regexp2 Matches regexp1 or regexp2 Note the meaning of the metacharacters ^ and $ in mmpp is different to their meaning in most regular expression matching environments. Usually the metacharacters ^ and $ match the beginning and end of input lines. In mmpp ^ and $ match the beginning or end of the input argument string. Newlines contained within this input string are not matched by either the ^ or $ metacharacters. Matching new lines is achieved by entering a literal newline, or newline and carriage return under Windows NT, within the regular expres- sion pattern. In this case the whole regular expression must be enclosed within curly braces, ‘{’ and ‘}’. (Examples of regular expressions containing new lines are shown below in the section Matching and replacing new lines on page R-483). Examples of regular expressions which incorporate single character regular expressions (^ $ . and [..]) are shown in Table 6.3. Table 6.3 Simple regular expressions RE Meaning abc Matches the substring ‘abc’ anywhere in a string ^abc Matches abc at the beginning of a string (but not at the beginning of new lines in the string) \^abc Matches the substring ‘^abc’ anywhere in a string abc$ Matches abc at the end of a string Miramo Reference Guide [ v 9.2 ] R-481 mmpp — Miramo macro preprocessor CHAPTER 6 Table 6.3 Simple regular expressions ( Continued ) RE Meaning ab. Matches ab followed by any other character [1-9] Matches a single digit in the range 1-9 (not zero) [^a-zA-Z] Matches a single non-alphabetic character. Note the use of the carat character, ‘^’, to specify a complemented character class. Regular expressions such as these may be combined into more complex expressions using the meta characters ‘(’ and ‘)’ (grouping), ‘*’ ‘+’ and ‘?’ (repetition), and ‘|’ (alternation). Examples of more complex regular expressions are shown in Table 6.4. Table 6.4 Complex regular expressions RE Summary Description .* Matches any text zero or more occurrences (*) of any character (.) [a-z]+|[0-9]+ Matches a lower case word, any sequence of one or more lower case e.g. ‘the’, or integer, e.g. characters ([a-z]+) or (|) one or more digits ‘123’ ([0-9]+) [-]?[0-9]+[.]?[0-9]* Matches a decimal number, an optional ‘-’ character ([-]?), followed by e.g. -12.33, 1. or 0.485 one or more digits ([0-9]+), optionally followed by a decimal point ([.]?) and zero or more digits ([0-9]*). [0-9]+$ Matches an integer at the one or more digits ([0-9]+) at the end of end of text the text ($) mmpp string matching functions mmpp supports three string matching functions, @match( ), @matchlen( ) and @matchcount( ). • The function @match(argument, regexp) returns zero (no match), or the position of the leftmost substring matching regexp in argument. • The function @matchlen(argument, regexp) returns zero (no match), or the length of the substring matching regexp in argument. • The function @matchcount(argument, regexp) returns zero (no match), or the number of matches in argument. • The first character in all string arguments is always position 1. The values returned by @match( ) and @matchlen( ) are suitable for use with the @sub- str( ) function, which extracts a portion of its argument according to start position and length. Example 6.34, on page R-491, contains some illustrations of the usage of @match( ) func- tions. R-482 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor String substitution functions: @sub( ) and @gsub( ) The @sub( ) and @gsub( ) functions perform pattern matching and substitution on their argument, returning the new (substituted) string. The function @sub(argument, r, s) finds the leftmost longest substring matched by the regular expression r in argument; and then replaces the substring with s. For example, <#def> v {cocoa is good for you} @sub({<#v>}, {g[a-z]+}, {bad}) within a macro definition returns the value: cocoa is bad for you when the macro is called. The function @gsub(argument, r, s) is similar, except that it substitutes s for all substrings which match the regular expression r in argument. (The ‘g’ is for ‘global’, meaning throughout the argument.) For example, using the same definition of ‘v’ above, <#def> v {cocoa is good for you} @gsub(<#v>, {o}, {O}) returns the value: cOcOa is gOOd fOr yOu The following example uses @sub( ) and @gsub( ) in a macro definition to convert a number from a common European format to a US and UK format: <@macro> delimswap { @--- Replace ','s with 'x's, then replace '.'s with ','s @--- and finally replace 'x's with '.'s <#def> num @sub({@gsub({@sub({$1}, {\,}, {x})}, {\.}, {,})}, {x}, {.}) <#num> } <|delimswap> 3.333.615,00 The output from the above is: 3,333,615.00 Matching and replacing new lines In most implementations of regular expressions matching new lines is achieved using ‘\n’ or ‘\r’ (carriage return) within the match pattern. In mmpp however match patterns con- taining just ‘\n’, or ‘\r’, for example, will match all occurrences of the characters ‘n’, or ‘r’, within the input. (The two-character strings ‘\n’ and ‘\r’ are matched using ‘\\n’ and ‘\\r’.) To match new lines in mmpp they must be entered into the match pattern as literals, e.g. by pressing the Enter key. Similarly, if new lines are required in the replacement string, these too must be entered as literals. In both cases the whole match pattern and replace- ment string must be enclosed within curly braces, ‘{’ and ‘}’. Below are some examples of regular expressions which match and substitute new lines. The macro in Example 6.24 outputs the number of new lines contained in its argument: <@macro> newlines { <#def> nlcount @matchcount({$1}, { }) @--- Line above ends with '{', followed by NL (or CR & NL on Win NT) <#nlcount> } Example 6.24 Count the number of newlines Miramo Reference Guide [ v 9.2 ] R-483 mmpp — Miramo macro preprocessor CHAPTER 6 The value of <#nlcount> will vary depending on how the macro is <@newlines> {1 called. 2 3 In the first call in Example 6.25 ‘newlines’ will output 3. In the sec- } ond and third calls above, ‘newlines’ will output 4 and 2 respec- <@newlines> { 1 tively. 2 3 Example 6.26 addresses the common requirement wherein single } new lines need to be replaced by hard returns, and two or more <@newlines> {1 2 consecutive new lines need to be replaced by new paragraphs. 3} 1 <@macro> MkFmt-1 { Example 6.25 Calls to 2 <#def> text {$1} macro ‘newlines’ 3 @--- Replace multiple contiguous line ends with ' ' 4 <#def> text @gsub({<#text>}, {[@--- First newline 5 ][ @--- Second newline 6 ]+}, {@--- ]+ (at least one, or more instances of second newline) 7 })@--- Replace with newline followed by 8 @--- Replace every line end with ' by 14 <#def> text @gsub({<#text>}, { }, { 16 17 }) 18 <#text> 19 } Example 6.26 ‘MkFmt-1’ macro Calling ‘MkFmt-1’ with a multi-line text argument, as shown in Example 6.27, <@MkFmt-1> {1st line 1st line 1st line of 2nd paragraph, Another paragraph, comprising two End of input End of input} Figure 6.12 Output from Example 6.27 Example 6.27 Argument for MkFmt-1 produces the output shown in Figure 6.12. Regular expression match patterns and substitution strings can be assigned to mmpp vari- ables. Using this technique, the example above can be made more easily comprehensible and, incidentally, slightly more sophisticated: 1 <@macro> MkFmt-2 { 2 <#def> text {$1} 3 @--- 'nl' is a new line 4 <#def> nl { 5 } 6 @--- 'w' is zero or more spaces or tabs 7 <#def> w {[ | ]*} R-484 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor 8 @--- 'wlw' is (optional) whitespace, newline, (optional) whitespace 9 <#def> wlw {<#w><#nl><#w>} 10 @------11 @--- Replace (optional) whitespace, newline, (optional) whitespace 12 @--- with '\r' newline 13 @- 14 <#def> text @gsub({<#text>}, {<#wlw>}, {\r<#nl>}) 15 @------16 @--- Replace all instances of '\r' newline 17 @--- immediately followed by one or more instances 18 @--- of '\r' newline by ' ' newline 19 @- 20 <#def> text @gsub({<#text>}, {\\r<#nl>[\\r[<#nl>]+}, {<#nl> <#nl>}) 21 <#text> 22 } Example 6.28 ‘MkFmt-2’ macro The output from ‘MkFmt-1’ and ‘MkFmt-2’ is identical. Matching and replacing backslashes Matching and replacing backslash <@macro> bs { characters is counter-intuitive. Exam- <#def> bs1 \ ple 6.29 illustrates attempts to use <#def> abc @gsub($1, \, {xxx}) <#def> abc @gsub($1, {\}, {xxx}) @gsub( ) to replace backslashes, all <#def> abc @gsub($1, {\\}, {xxx}) of which will result in a fatal error. <#def> abc @gsub($1, {<#bs1>}, {xxx}) <#abc> The failures are caused by either a lit- } <|bs> a-\\-a-\-a eral or implied backslash character preceding the match pattern's termi- Example 6.29 Bad backslash matching nating comma, ‘,’, or ‘}’. Conversely, all the substitutions in Example 6.30 will work correctly (see the output shown in Figure 6.13). 1 <@macro> bs { 2 Input: $1 Input: a-\\-a-\-a 3 ------4 <#def> bs1 \ Replace \\ with \ : a-\-a-\-a 5 <#def> bs2 \\ Replace \ with \\ : a-\\\\-a-\\-a 6 <#def> bs3 \\\ Replace \ with \\\ : a-\\\\\\-a-\\\-a 7 <#def> bs4 \\\\ Replace \ with | : a-||-a-|-a 8 <#def> bs5 \\\\\ Figure 6.13 Output from Example 6.30 9 @--- Replace \\ with \ 10 <#def> abc @gsub($1, {<#bs4>}, {<#bs1>}) 11 Replace \\ with \ : <#abc> 12 @--- Replace \ with \\ 13 <#def> abc @gsub($1, {<#bs2>}, {<#bs2>}) 14 Replace \ with \\ : <#abc> 15 @--- Replace \ with \\\ 16 <#def> abc @gsub($1, {<#bs2>}, {<#bs3>}) 17 Replace \ with \\\ : <#abc> 18 @--- Replace \ with | 19 <#def> abc @gsub($1, {<#bs2>}, {|}) 20 Replace \ with | : <#abc> 21 } 22 <|bs> a-\\-a-\-a Example 6.30 Matching and replacing backslashes Miramo Reference Guide [ v 9.2 ] R-485 mmpp — Miramo macro preprocessor CHAPTER 6 The ‘&’ character in the substitution string If the substitution string contains one or more occurrences of the ‘&’ character, every occurrence of the ‘&’ character is replaced by the substring matched by the regular expression before the substitution occurs. For example, <@macro> tmp { <#def> v {cocoa is good for you on Monday} @gsub(<#v>, {[A-Za-z]o}, {&O}) } <|tmp> returns the string: coOcoOa is goOod foOr yoOu on MoOnday To prevent the ‘&’ character from being interpreted in this way, use ‘\&’, so that <@macro> tmp { <#def> v {cocoa is good for you on Tuesday} @gsub(<#v>, {[a-z]o}, {\&O}) } <|tmp> returns the string: &O&Oa is &Ood &Or &Ou on Tuesday The replacement of ‘&’ by the substring matched by the regular expression happens immediately before the substring is substituted into the argument, so that: <@macro> tmp { <#def> v {cocoa is good for you on Friday} @gsub(<#v>, {[a-z]o}, {@toupper(&)}) } <|tmp> returns the string: cocoa is good for you on Friday This is because the evaluation of @toupper(&) happens before the substitution of the ‘&’ character, and yields ‘&’ as its result. Boolean and arithmetic expressions Arithmetic and boolean expressions are used within the @eval( ), @if( ), @ifnot( ), @elif( ), @elifnot( ) and <@include_if>( ) functions. Examples are: <#def> a @eval( ($3+20.2) / 5) @if( $1 = $2 ) { ... } The @if( ) function evaluates the expression within round brackets, ‘(’ and ‘)’. If the expression is numeric and evaluates to a non-zero value, then the expression is treated as true. A zero result is false. A value is numeric if it has the following form: [whitespace][sign][digits][dpoint[digits]][e | E[sign][digits][whitespace] ‘dpoint’ in the above signifies a decimal point. Its value depends on the locale setting of the host computer system.1 Expressions are built up using the logical AND and OR operators, the addition, subtraction, multiplication, division and modulus operators (+,-,*,/,%), together with the comparison operators equals, not equals, greater than or equal to, less than or equal to, greater than, or less than (=, <>, >=, <=, >, <). All operators apart from equals (=) and not equals (<>) require numeric operand values R-486 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor and will generate a syntax error if applied to non-numeric values. If both operands to the equals (=) and not equals (<>) operators are numeric, numeric comparison will be used, otherwise case sensitive string comparison will be used. Note that leading and trailing spaces are significant in string comparison, but are ignored dur- ing numeric comparison, so that: @if({ abc} = {abc}) yields false, since string comparison is used, but @if({ 111} = {111}) yields true, since numeric comparison is used. Table 6.5 contains several examples of expressions. Table 6.5 Evaluating boolean expressions Example Evaluates to: @eval( ((1+35) - 22) % 6 ) 2 @eval( $1 > $2 ) 1 or 0. Will cause syntax warning and evaluate to 0 if $1 and/or $2 are not recognized as numeric values. @if( $1 = $2 ) 1 or 0. If both $1 and $2 are recognized as numeric values, numeric comparison will be used, string comparison will be used in all other cases. @eval( {A$1} = {A$2} ) 1 or 0. Forces string comparison rather than numeric comparison. The curly braces around the two values are necessary to allow text and numbers to be mixed, but they will be stripped off prior to performing the comparison. @if( 3 * -1 ) Expression is true (non-zero). @if(3 + 2 AND 4/2 - 2) Expression is false. ( 4/2 - 2 = 0 ) Table 6.6 contains a list of boolean and arithmetic operators which are allowed within 1. On Unix systems, the locale is determined by either the LC_ALL or LANG environment variables, which are automatically set up when the system is configured. The LC_NUMERIC category of the locale controls which character is recognized as the decimal point and is determined by the settings of the LC_ALL, LC_NUMERIC, or LANG environment variables, in decreasing order of precedence. Thus, if LC_ALL is set to ‘C’ (the US and UK English locale) and LC_NUMERIC is set to "de" (Germany), LC_ALL overrides LC_NUMERIC, and the ‘.’ character will be used as the decimal symbol. Similarly, the LANG envi- ronment variable is used to determine the decimal symbol if neither LC_NUMERIC or LC_ALL are set. Under Windows NT 4.0, the Regional Settings control panel controls the default language used on the sys- tem, and the Number tab allows the ‘Decimal symbol’ to be specified, normally as ‘.’ or ‘,’. This can lead to confusing regionally determined effects. The expression: ({ 1,5} = {1,5}) will evaluate to true on a German or French (or any other) system where the decimal symbol is configured as ‘,’ (comma). In this case mmpp will make a numeric comparison. On a US system, or any other system where the decimal symbol is configured as ‘.’ (period), the expression will evaluate to false, because {1,5} is not recognized as a number. Using string comparison, the leading spaces in the first value are significant, so the two operands are not the same. Miramo Reference Guide [ v 9.2 ] R-487 mmpp — Miramo macro preprocessor CHAPTER 6 expressions, grouped in increasing order of precedence. Table 6.6 Boolean and arithmetic operators Operator Description AND logical and OR logical or = equal <> not equal >= greater than or equal <= less than or equal > greater than < less than + addition - subtraction * multiplication / division % remainder Expressions may be enclosed in round braces ‘(’ and ‘)’ to achieve different precedence rules, so that: <@macro> arithmetic { @eval( 10 + 2 / 2 ) @eval( (10 + 2) / 2 ) } <|arithmetic> produces two output lines, as follows: <@macro> arithmetic { @eval( 10 + 2 / 2 ) @eval( (10 + 2) / 2 ) } <|arithmetic>The precedence of ‘/ ’ (the division operator) is nor- mally greater than that of ‘+’ (the addition operator). Arithmetic functions mmpp supports several arithmetic and trigonometric functions. These are detailed in Table 6.6. Table 6.7 Arithmetic functions Function Description @sin(arg) Sine of arg (degrees) @asin(arg) Arc sine of arg @cos(arg) Cosine of arg (degrees) @acos(arg) Arc cosine of arg @tan(arg) Tangent of arg (degrees) @atan(arg) Arc tangent of arg R-488 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor Table 6.7 Arithmetic functions ( Continued ) Function Description @sqrt(arg) Square root of arg @ceil(arg) The least integral value greater than or equal to arg @floor(arg) The greatest integral value less than or equal to arg @round(arg) Round a floating point number, arg, to the nearest integer. @round(arg1, arg2) Round a floating point number, arg1, to arg2 decimal places. Example 6.31 illustrates how these arithmetic functions work. <@macro> arith { <#ifndef> A 0 <#def> A @eval(<#A> + 1) <#def> n @gsub({$1}, {,}, {}) Input value (<#A>): $1 ------Floor: @floor(<#n>) Ceiling: @ceil(<#n>) Sq. Root: @sqrt(<#n>) Asine: @asin(<#n>) Acos: @acos(<#n>) Atan: @atan(<#n>) } <|arith> -1 <|arith> 3.4999 <|arith> 3.5 <|arith> -3.6 <|arith> 999,962,147,483.649 Example 6.31 Arithmetic function usage The output from Example 6.31 is shown in Figure 6.14. Input value (1): -1 ------Floor: -1 Ceiling: -1 Sq. Root: NaN Asine: -90.000000765 Acos: 180.00000153 Atan: -45.000000382 Input value (2): 3.4999 ------Floor: 3 Ceiling: 4 Sq. Root: 1.870801967 Asine: 0 Acos: 0 Atan: 74.054172296 Input value (3): 3.5 ------Floor: 3 Ceiling: 4 Sq. Root: 1.870828693 Asine: 0 Acos: 0 Atan: 74.054604728 Input value (4): -3.6 ------Floor: -4 Ceiling: -3 Sq. Root: NaN Asine: 0 Acos: 0 Atan: -74.475889636 Input value (5): 999,962,147,483.649 ------Floor: 999962147483 Ceiling: 999962147484 Sq. Root: 999981.07356272 Asine: 0 Acos: 0 Atan: 90.000000765 Figure 6.14 Output from Example 6.31 The trigonometric functions in Example 6.31 produce accurate results up to the first seven digits. The arithmetic functions in Example 6.31 produce accurate results up to fif- Miramo Reference Guide [ v 9.2 ] R-489 mmpp — Miramo macro preprocessor CHAPTER 6 teen digits. In the event any arithmetic function, apart from @round( ), evaluates to a number having more than six decimal places mmpp prints the result rounded to six deci- mal places.1 mmpp does not fail or issue a warning when invalid numeric arguments are supplied to arithmetic functions other than @round( ). In such cases the returned values may be ‘0’, ‘- 1.#IND’ (Windows NT 4, as illustrated in the case of ‘Input value (1)’ in Figure 6.14) or ‘NaN’. It is up to the user to check for these error values. Example 6.32 illustrates the usage of the @round( ) function. <@macro> rounding { <#ifndef> A 0 <#def> A @eval(<#A> + 1) @if(<#A> = 1) {Input: Output: } @if(<#A> = 1) {------} @if($# = 1) {\@round($1) @round($1)} @else {\@round($1, $2) @round($1, $2)} } <|rounding> 3.4999 <|rounding> 3.5 <|rounding> 9113.6|-3 <|rounding> -3.6 <|rounding> 999962147483.649|-2 <|rounding> 7483.649190|18 <|rounding> 7483.649190|14 <|rounding> 111117483.6696649190|6 <|rounding> 111117483.6696|6 Example 6.32 Using @round( ) The output from 6.32 is shown in Figure 6.15. Input: Output: ------@round(3.4999) 3 @round(3.5) 4 @round(9113.6, -3) 9000 @round(-3.6) -4 @round(999962147483.649, -2) 999962147500 @round(7483.649190, 18) 7483.649190000000000000 @round(7483.649190, 14) 7483.64919000000000 @round(111117483.6696649190, 6) 111117483.669665 @round(111117483.6696, 6) 111117483.669600 Figure 6.15 Output from Example 6.32 Flow control using @if( ), @elif( ) and @else @if( ) flow control statements have the following form: @if ( expr ) { . . . } | @ifnot ( expr ) { . . . } [@elif( expr ) { . . . }]* [@elifnot( expr ) { . . . }]* [@else { . . . }] An @if( ) or an @ifnot( ) may optionally be followed by any number of @elif( ) and/or @elifnot( ) statements, optionally followed by a single @else statement. An @if( ) or an @ifnot( ) statement may optionally be by a single @else statement. 1. The number of decimal places output may be increased to a value in the range 7 to 15 by setting the environment variable MM_DECPLACES to a number in this range. R-490 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor Boolean expressions may be evaluated within the arguments to the @if( ), @elif( ) and @elifnot( ) statements. Alternatively a numeric expression may be used. A numeric expression which evaluates to zero (or, simply a zero) is ‘false’. All numeric expressions which evaluate to non-zero values, or non-zero constants, are ‘true’. Multiple expressions may be combined within a single expression. This is illustrated by the input in Example 6.33 and the output shown in Figure 6.16. <@macro> B { @if ($# < 3) { Not enough Arguments} @elif ( $1 > $2 AND $2 = $3 AND $2 = 2 ) { This is true: $1>$2 and $2=$3 and $2=2 } This is true: 3>2 and 2=2 and 2=2 @else { This is not true: (2 > 3 and 3=3 ) This is not true: ($1 > $2 and $2=$3 ) This is not true: (1 > 1 and 1=1 ) } } Figure 6.16 Output from Example 6.33 <|B> 3|2|2 <|B> 2|3|3 <|B> 1|1|1 Example 6.33 Simple @if( ) and @else expressions @if( ) statements may be nested: @if( $1 = 1 ) { . . . } @elif( $1 = 2 ) { @if($2 = 2) {Both args = 2 } @else { . . . } } @elif( $1 = 3 ) { . . . } @else { not 1, 2 or 3 } String values may be compared directly, as shown in Example 6.34. 1 <@macro> testif { 2 <#def> string {$1} 3 @if(<#string> = aaabb) { Exact match } 4 @if(@match(<#string>, {bb})) { String contains 'bb'} 5 @if(@matchcount(<#string>, {a}) > 2) { More than 2 'a's} 6 @if(@match({${PATH}}, {tiff})) { PATH variable contains 'tiff' } 7 } 8 <|testif> aaabb Example 6.34 Complex @if( ) and @else expressions The output from Example 6.34 is Exact match shown in Figure 6.17 String contains 'bb' More than 2 'a's (The final output line above will be PATH variable contains 'tiff' present only if mmpp is running in an Figure 6.17 Output from macro calls in Example 6.34 environment wherein the PATH vari- able does contain the string ‘tiff’.) The curly braces around the referenced environment variable argument in the last @if( ) function in Example 6.34 are vital: if the curly braces around PATH in the following are omitted @if(@match({${PATH}}, {tiff})) { PATH var contains 'tiff' } The result will be a syntax error. Miramo Reference Guide [ v 9.2 ] R-491 mmpp — Miramo macro preprocessor CHAPTER 6 Loops using @for( ) ‘For’ loops may be included within a macro definition body. The syntax of ‘for’ loops is as follows: @for( cvar = m TO n ) { . . . } where ‘cvar’ is a counter variable. ‘m’ and ‘n’ must be integers, variables having integer val- ues or expressions which evaluate to integers. The set and order of characters that may be used for a cvar is the same as for a variable name (see the section Variable names on page ). On each iteration of the loop the value of ‘m’ is incremented by 1. When the value of ‘m’ is greater than the value of ‘n’ the loop terminates. If the initial values of ‘m’ and ‘n’ are the same, the loop is executed once. If the initial value of ‘n’ is less than the initial value of ‘m’ the loop is skipped. ‘$$cvar’ returns the current value of <@macro> Factorial { ‘n’. ‘$cvar’ returns the value of the <#def> val 1 nth argument to the macro contain- @for(f = 1 TO $1 ) { <#def> val @eval(<#val> * $$f) ing the for loop. The ‘TO’ keyword } may be in upper or lower case. <#val> } ‘For’ loops may be nested, one <|Factorial> 5 within another. Example 6.35 Calculating factorials Example 6.35 illustrates a simple ‘for’ loop. The output from Example 6.35 is the number ‘120’ on a line by itself. Example 6.36 shows the beginnings of a utility macro, which may be called by other mac- ros to make a simple interface for formatting tables. <@macro> Tbldef{ <#def> units {pt} @- Units <#def> tblname {$1} @- Table name <#def> nc @eval($# - 1) @- No of cols <#def> tw 0 @- Table width <#def> colwidths {} Running external programs, using <@system> The <@system> command is similar to the Miramo inline markup code (see Chapter 3, pages R-245–246), in that its argument comprises a string of one or more system commands. There are however two major differences: • The argument to <@system> may be delimited by curly braces: a ‘{’ before the R-492 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor beginning and a ‘}’ after the end of the argument. • If the argument to <@system> continues over several input lines the argument must be surrounded by curly braces, ‘{’ and ‘}’. When <@system> is used within a macro definition mmpp variables, mappings and array elements (e.g. <#name>, &name;), as well as @for loop parameters (e.g. $i, $$i) are all expanded prior to being passed to the shell for processing. Expansion may be suppressed by inserting a backslash, ‘\ ’, escape character in front of these items. Several illustrations of <@system> usage are shown in Example 6.37. Case 1: <@system> { date } Case 1: Tue Sep 17 01:50:42 IST 2013 Case 2: <@system> { echo ${DISPLAY} } Case 2: tiger:1.0 Case 3: <@system> { date ; echo ${DISPLAY} } Case 3: Tue Sep 17 01:50:42 IST 2013 Case 4: tiger:1.0 <@system> { date echo ${DISPLAY} Case 4: } Tue Sep 17 01:50:42 IST 2013 tiger:1.0 Case 5: <@system> { Case 5: date Tue Sep 17 01:50:42 IST 2013 echo ${DISPLAY} tiger:1.0 } Figure 6.19 Outputs from <@system> Example 6.37 Using the <@system> { } command in Example 6.37 The output from Example 6.37 is shown in Figure 6.19. The output of the last three examples above is identical. Since all the commands in the above examples write to standard output, their output will be read and processed by mmpp as part of the input stream. (The above ‘date’ and ‘echo’ examples apply on Unix only. These commands work differently under Windows NT and should be avoided. A platform independent equivalent of ‘echo’ can be simulated using the mmpp ‘@write’ function, described on page R-494.) Example 6.38 shows more <#define> A {$3} complicated methods of pre- <@system> {awk -F: '\{printf("%s\n", <#A>)\}' /etc/ paring a <@system> com- group} mand line. <@system> {awk -F: '\{printf("%s\n", $3)\}' /etc/group} Each of the three invoca- <@macro> hello { tions of <@system> in <#def> awkcmd {awk -F: '\{printf("%s\n", $$1)\}' / etc/group} Example 6.38 produces } exactly the same output. <|hello> 3 <@system> { <#awkcmd> } Note that ‘A’ is defined as $3 in the first line, and is Example 6.38 Using <@system> treated as a literal ‘$3’. This is because a define outside the scope of macro definition text does not treat ‘$’ followed by a number as special. Special treatment of ‘$number’ occurs only within macro definition body text. The curly braces within the awk command (in Example 6.38) are escaped using backslashes. This is to prevent them being stripped by Miramo Reference Guide [ v 9.2 ] R-493 mmpp — Miramo macro preprocessor CHAPTER 6 mmpp. If <@system> is used within a macro definition any output from the <@system> com- mand not redirected elsewhere will become part of the output from mmpp. However if this output contains mmpp macros, they will be passed through as literals and not inter- preted. There are two ways to have the output from <@system> processed by mmpp. The simplest way is to have mmpp process the input data twice, using mmpp as an in-line filter: ... | mmpp | miramo -M -Omif outfile otheropts ... | mmpp -M includefile | miramo -Omif outfile -Mfile includefile otheropts Alternatively mmpp can process the output of the system command by including mmpp as a post-processing filter within the system command itself. Writing to files, using <@write> To output information to a file it is more efficient to use <@write> in place of <@system> wherever possible. <@write> takes two arguments: <@write> filename { outputtext and variable values } filename can be any file name, with the exception that names ‘error’, ‘Error’ and ‘ERROR’ have the special effect of causing output text to be written to standard error. Files names may be specified using environment variables provided their values are addressed using curly braces, e.g. ${HOME}. Any mmpp functions contained within outputtext are inter- preted before data is appended to the output file. The behavior of <@write> is slightly different depending on whether it is included within a macro. This is illustrated in Example 6.39. <@macro> sses { <@write> Error { 1 s-> <#define> ss {} 2 ss-> @for(i = 1 to 5){ 3 sss-> <#def> ss {<#ss>s} 4 ssss-> $$i <#ss>$1 5 sssss-> } } 1 s$1 } 2 ss$1 <|sses> -> 3 sss$1 <@write> Error { 4 ssss$1 5 sssss$1 <#define> ss {} Figure 6.20 Output from Example 6.39 @for(i = 1 to 5) { <#def> ss {<#ss>s} $$i <#ss>$1 } } Example 6.39 Using <@write> inside and outside macro definitions When mmpp processes the input shown in Example 6.39 the text shown in Figure 6.20 is output to ‘standard error’. The first use of <@write> above is within a macro definition, and for this reason ‘$1’ is treated as a positional parameter and substituted for. (If the macro is called without an argument, then ‘$1’ will disappear silently.) In the second use of <@write> above, outside R-494 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor a macro definition, the ‘$1’ is treated as literal text. The <@readfile>( ) function mmpp input files will ideally be produced in ‘keycode’ structured form by a DBMS data extraction utility. However it is often necessary to process minimally structured input streams, such as collections of records whose fields have width offsets, are separated by tabs or are enclosed in double quotes and separated by commas (‘CSV’ files). The <@readfile>( ) function addresses this need. <@readfile>( ) also enables processing of ‘marked up’ files: for example IBM BookMaster, troff, HTML or XML files. The <@readfile>( ) function reads a file line by line. Each line is passed to a user-defined macro for processing. The simplest usages of <@readfile>( ) are as follows: <@readfile>(filename, csv) macroname or <@readfile>(filename, tsv) macroname or <@readfile>(filename, fw) macroname Assuming the last of the above examples is included within a mmpp macro definition, when that macro is called <@readfile>( ) reads each line in filename and, after each line, calls macroname with the line as its argument (‘$1’). The ‘fw’ after filename is a key specify- ing how the file should be interpreted. ‘fw’ denotes ‘field widths’ and in the absence of any field width specifications, the whole line will be passed to macroname as a single argu- ment. The complete syntax for <@readfile>( ) is shown below: <@readfile>(filename, key [, postopts]) macroname [, endmacro] [fieldwidths] key may be any of the following: fw (field widths), csv (comma separated values) or tsv (tab separated values). fieldwidths may only be specified if key has the value fw, in which field sizes are specified by their lengths (number of 8-bit characters), each preceded by the vertical bar sign (‘|’). If an input line is shorter than the total length of the fieldwidths then the extra fieldwidths are silently ignored. Similarly, if the length of any input line is greater than the total of the fieldwidth values the extra characters are ignored. A fieldwidths specification ending with ‘|-’ will assign all the remaining characters in the input line to the last argument to macroname. When key is set to fw and no fieldwidths specification is included, then the whole line is passed to macroname as a single argument, $1. macroname is called once for every input line in filename and is passed each field as a sep- arate argument, starting from 1 (‘$1’) through to n. There is no limit to the size of n (nor to the length of an input line). postopts can be any of: trim, ltrim or rtrim. trim removes whitespace from both the begin- ning and end of the field. ltrim removes whitespace from the beginning of the field. rtrim removes whitespace from the end of the field. ‘Whitespace’ comprises a sequence of one or more tab or space characters. In general postopts are useful only when key is set to fw. The optional endmacro is the name of a user-defined macro to call after <@readfile>( ) has completed reading file. The endmacro macro cannot be passed any arguments. Miramo Reference Guide [ v 9.2 ] R-495 mmpp — Miramo macro preprocessor CHAPTER 6 Processing ‘CSV’ files using <@readfile>( ) CSV, or Comma Separated Values, files are a common spreadsheet and database dump format. Fields, which may be any length, are enclosed in double quotation marks and separated by commas. Assume the CSV data in Example 6.40 is con- "LNAME","FNAME","DIDWHAT" tained in the file, ‘data.csv’. The first line in "Melville","Herman","Hunted whales" the above comprises mnemonic column head- "Ozymandias","","Built a palace" "Washington","George","Rode a horse" ings (which are usually discarded in Miramo output). The remaining lines contain three Example 6.40 Contents of file ‘data.csv’ records each with three fields. A minimum of two macros, and one explicit macro call, are required to read and process data from ‘data.csv’. This is illustrated in Example 6.41. @------@--- getdata.mmp @------1 LNAME FNAME DIDWHAT <@macro> process_input_lines { 2 Melville Herman Hunted whales $1 $2 $3 3 Ozymandias Built a palace } 4 Washington George Rode a horse @------Figure 6.21 Output from Example 6.41 <@macro> getdata { <@readfile>(data.csv, csv) process_input_lines } @------<|getdata> @------Example 6.41 Simple <@readfile> example The output form Example 6.41 is shown in Figure 6.21. Example 6.42 shows how to process the same CSV file into a Miramo table. This example uses the <@readfile>( ) endmacro option, triggered when <@readfile>( ) encounters the end of the ‘data.csv’ file, to append the Miramo mandatory end of table inline markup code, via the ‘end_of_input’ macro. @------@--- getdata.mmp @------<@macro> end_of_input { R-496 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor Running the command: mmpp getdata.mmp on the input shown in Example 6.42 produces the output shown in Figure 6.22. Alternatively, running the command miramo -M -P getdata.mmp will print a table on a single page on the default system printer. Processing ‘fixed field width’ files using <@readfile>( ) Many applications, especially those 12345678901234567890123456789012345678901234 running on IBM AS/400 systems, spec- Melville Herman Hunted whales ify fields by their starting position and Ozymandias Built a palace Washington George Rode a horse length. For example, the first field may have a length of 20 characters starting Example 6.43 Fixed length fields at the first character in the line. This is the case in the data file shown in Example 6.43, ‘data.fw’, where the second field starts at position 21 and is 10 characters long and the third field starts at position 31 and is 20 characters long. Putting the following mmpp macro code into a file called ‘getdata.mmp’ 1 @------2 @--- getdata.mmp 3 @------4 <@macro> process_input_lines { 5 6 Field 1: $1|<-- Field end 7 8 Field 2: $2|<-- Field end 9 } 10 @------11 <@macro> getdata { 12 <@readfile>(data.fw, fw) process_input_lines|20|10|30 13 } 14 @------15 <|getdata> 16 @------Example 6.44 Processing fixed width fields and running the following command: mmpp getdata.mmp Miramo Reference Guide [ v 9.2 ] R-497 mmpp — Miramo macro preprocessor CHAPTER 6 produces: 1 2 Field 1: 12345678901234567890|<-- Field end 3 4 Field 2: 1234567890|<-- Field end 5 6 Field 1: Melville |<-- Field end 7 8 Field 2: Herman |<-- Field end 9 10 Field 1: Ozymandias |<-- Field end 11 12 Field 2: |<-- Field end 13 14 Field 1: Washington |<-- Field end 15 16 Field 2: George |<-- Field end Figure 6.23 Output from Example 6.44 If the ‘rtrim’ flag is used with the <@readfile>( ) function in the ‘getdata’ macro, thus <@readfile>(data.fw, fw, rtrim) process_input_lines|20|10|30 the trailing spaces are removed from each field: The output from the above is shown below: 1 2 Field 1: 12345678901234567890|<-- Field end 3 4 Field 2: 1234567890|<-- Field end 5 6 Field 1: Melville|<-- Field end 7 8 Field 2: Herman|<-- Field end 9 10 Field 1: Ozymandias|<-- Field end 11 12 Field 2: |<-- Field end 13 14 Field 1: Washington|<-- Field end 15 16 Field 2: George|<-- Field end Figure 6.24 Output from Example 6.44 (with the ‘rtrim’ flag set) Files containing fixed length fields some- 123456789012345678901234567890123456789012 times contain multiple record types. Each 01Fruits Tropical different record type may be identified by 02Mangoes 337Smooth 02Pineapples 0Prickly, with spike a key at the beginning of the record. This 02Coconuts 12Hairy structure is illustrated in Example 6.45. 01Vegtables Non-Tropical 02Potatoes 2915812Smooth The record type is indicated here in the Example 6.45 Fixed width field file format with first, two character, field. Record type ‘01’ multiple record types contains two data fields: the first starting at position 3, the second starting at position 18 and extending to position 30. Record type ‘02’ contains three data fields: the first starting at position 2, the second starting at posi- tion 14 and the third starting at position 23 and extending to position 50. To process files containing multiple fixed fieldwidth record structures the @slice( ) func- tion may be used in combination with the <@readfile>( ) function, as shown in Example R-498 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor 6.46. 1 @------2 @--- getdata.mmp 3 @------Fruits|Tropical 4 <@macro> RType_One { Mangoes|337|Smooth 5 $* Pineapples|0|Prickly, with spike 6 } Coconuts|12|Hairy 7 @------Vegtables|Non-Tropical 8 <@macro> RType_Two { Potatoes|2915812|Smooth 9 $* Figure 6.25 Output from Example 6.46 10 } 11 @------12 <@macro> process_input_lines { 13 @if($1 = 01) {@slice({$2}, fw, trim) RType_One|15|-} 14 @if($1 = 02) {@slice({$2}, fw, trim) RType_Two|12|8|-} 15 } 16 @------17 <@macro> getdata { 18 <@readfile>(data.fw, fw) process_input_lines|2|- 19 } 20 <|getdata> 21 @------Example 6.46 Processing multiple fixed field width records The output from Example 6.46 is shown in Figure 6.25. Miscellaneous transformation functions mmpp supports several transformation functions. These functions are listed in Table 6.8. Table 6.8 Miscellaneous transformation functions Function Description @dec2bin(arg) Convert a decimal number to a binary byte. See the Summary entry for @dec2bin( ) on page R-517. @dec2hex(arg) Convert from a decimal number to a hexadecimal number. See the Summary entry for @dec2hex( ) on page R-517. @hex2bin(arg) Convert from a hexadecimal string to a binary string. See the Summary entry for @hex2bin( ) on page R-520. @hex2dec(arg) Convert from a hexadecimal number to a decimal number. See the Summary entry for @hex2dec( ) on page R-520. @ucs2_to_utf8(arg) Convert from UCS-2 to UTF-8 (hexadecimal). See the Summary entry for @ucs2_to_utf8( ) on page R-528. @utf8_to_ucs2(arg) Convert from UTF-8 (binary) to UCS-2 (hexadecimal). See the Summary entry for @utf8_to_ucs2( ) on page R-528. The usage of the transformation functions shown in Table 6.8 is illustrated in Example 6.47. 1 <@macro> transtests { 2 3 \@hex2dec(20): @hex2dec(20) 4 \@hex2dec(400): @hex2dec(400, 6) 5 \@hex2dec(400): @hex2dec(400, 2) 6 7 \@dec2bin(65): @dec2bin(65) Miramo Reference Guide [ v 9.2 ] R-499 mmpp — Miramo macro preprocessor CHAPTER 6 8 9 \@dec2hex(33): @dec2hex(33)@- 10 \@dec2hex(1024, 4): @dec2hex(1024, 4) @hex2dec(20): 32 11 \@dec2hex(316251, 4): @dec2hex(316251, 4) @hex2dec(400): 001024 12 @hex2dec(400): 1024 13 \@hex2bin(4142eb): @hex2bin(4142eb) 14 \@hex2bin(41 42 eb): @hex2bin(41 42 eb) @dec2bin(65): A 15 \@hex2bin(4 142e b9): @hex2bin(4 142e b9) 16 @dec2hex(33): 21 17 \@hex2dec(21): @hex2dec(21) @dec2hex(1024, 4): 0400 18 \@hex2dec(21, 5): @hex2dec(21, 5) @dec2hex(316251, 4): 4d35b 19 20 \@ucs2_to_utf8(0042): @ucs2_to_utf8(0042) @hex2bin(4142eb): AB 21 \@ucs2_to_utf8(0200): @ucs2_to_utf8(0200) @hex2bin(41 42 eb): AB 22 \@ucs2_to_utf8(0800): @ucs2_to_utf8(0800) @hex2bin(4 142e b9): AB 23 \@ucs2_to_utf8(0250): @ucs2_to_utf8(0250) 24 } @hex2dec(21): 33 25 <|transtests> @hex2dec(21, 5): 00033 Example 6.47 Transformation functions @ucs2_to_utf8(0042): 42 @ucs2_to_utf8(0200): c880 @ucs2_to_utf8(0800): e0a080 The output from Example 6.47 is shown in Figure @ucs2_to_utf8(0250): c990 6.26. Figure 6.26 Output from Example 6.47 X macros X macros may be used to extend the Miramo markup language and to facilitate processing of XML input data. X macros specifically enable the following capabilities and features: 1 User-programmable extensions to the Miramo markup language. X macros have a near-identical syntax to the syntax of Miramo markup codes. 2 An an efficient, high-speed interface for processing simple XML input. 3 Following from the above, the ability to create libraries of Miramo extension modules. 4 In many cases, a more flexible and easy to maintain macro programming environment than that provided by standard macro processors. X macros support the capabilities of standard macros (see page R-467 et seq.), except for those relating to argument place holders. The calling syntax for X macros mimics the structure of XML elements. Arguments are passed to X macros as option-value pairs, sim- ilar in style to XML attributes and values. Option values are accessed within X macros as the values of automatically created variables having the same name as the option name, with an optional prefix. Defining X macros The rules for defining X macros are the same as for defining standard macros (see the sec- tion Defining standard macros on page R-467) with the following exceptions. 1 An X macro definition starts with the ‘<@xmacro>’ X macro code, i.e. in place of the ‘<@macro>’ code used to introduce a standard macro definition. 2 An X macro body may have one or two parts. The first part, referred to as the macro body start section, corresponds to the whole of a standard macro definition body. The optional second part, referred to as the macro body termination section, R-500 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor is enclosed by ‘{’ and ‘}’ delimiters. The opening delimiter, ‘{’, must follow on the same line as the closing delimiter of the macro body start section, separated by zero or more space or tab characters. This structure is illustrated below: <@xmacro> xmacroname { start section } <@xmacro> xmacroname { start section } <@xmacro> xmacroname { start section }{ termination section } <@xmacro> xmacroname { start section }{ termination section } 3 A minus sign, ‘-’, surrounded by one or more spaces or tabs, following the ‘<@xmacro>’ code causes all input between the initial macro call and the terminating call to be assigned to a special variable, $xmacroname. The value of $xmacroname is available in the termination section of the macro body: <@xmacro> - xmacroname { }{ $xmacroname } 4 The special function @xgetvals( ), or @xgetvals(arg), may be included within the macro body start section to read the option names and values supplied when the macro is called, and to create mmpp variables using the parameter names and variables supplied. Example 6.48 shows a standard macro definition. <@macro> stdMacroArcLen { <#def> rrad @eval($1 * $1) <#def> ang $2 Length = @eval(3.14159*<#rrad>*<#ang>/360 ) } <|stdMacroArcLen> 3.5in|45 Example 6.48 Standard macro definition Length = 4.810559687in An equivalent X macro definition using the @xgetvals( ) function is shown in Example 6.49. <@xmacro> xMacroArcLen { @xgetvals() Length = @eval(3.14159 * <#radius> * <#radius> * <#angle> / 360 ) } If a special string is included within the braces in @xgetvals( ), e.g. @xgetvals(xyz), then that string is prepended to all mmpp variables created by @xgetvals( ), so that Example 6.49 could be re-written as shown in Example 6.50. <@xmacro> xMacroArcLen { @xgetvals(AL) Length = @eval(3.14159 * <#ALradius>*<#ALradius> * <#ALangle>/360) Miramo Reference Guide [ v 9.2 ] R-501 mmpp — Miramo macro preprocessor CHAPTER 6 } The macro calls in Examples 6.48, 6.49 and 6.50 produce identical results, viz. Length = 4.810559687in 5 The special function @xputvals( ), or @xputvals(arglist), may be included within an X macro definition to write out the option names and values supplied when the macro is called. arglist is an optional list of comma separated option names to be excluded. The operation of @xputvals( ) is illustrated in Example 6.51. (The vertical bars are included only as illustrative delimiters.) <@xmacro> putVals { xputvals(): |@xputvals()|@-- All options, default xputvals(opt2): |@xputvals(opt2)|@-- All options, except opt2 <#def> optionsA {|@xputvals()|} <#def> optionsB {|@xputvals(opt1)|} <#def> optionsC {|@xputvals(opt1, opt2)|} optionsA: <#optionsA> optionsB: <#optionsB> optionsC: <#optionsC> } The output from Example 6.51, is shown below. xputvals(): |opt1="ABC" opt2="XYZ"| xputvals(opt2): |opt1="ABC"| optionsA: |opt1="ABC" opt2="XYZ"| optionsB: |opt2="XYZ"| optionsC: || 6 With the exception of $0 and $xmacroname, ‘$’ style argument place holders as used within standard macro definitions (see the sections Argument place holders: $1, $2, ... $nand Additional argument place holders: $#, $*, $(n) and $(m - n)on pages R- 469–470 and R-471–472) have no special meaning within X macro definitions. For example, if an X macro definition contains the string ‘$1’ the ‘$1’ is treated as plain text. In an X macro start section or termination section $0 references the macro name. When used in an X macro termination section $xmacroname references any content included between a call to the macro start section and a call to the macro termination section (see exception item 3 on page R-501), if the X macro is defined with a minus sign preceding its name. 7 An X macro may contain calls to standard macros or to other X macros. If an X macro contains a call to another X macro, the called macro must be defined before the macro which calls it is defined. Calling X macros A call to an X macro has the following syntax: R-502 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor option=value option="value" option='value' ... An option and value pair must be on the same line. Option values may be surrounded by single or double quotation marks, ‘ ' ’ or ‘"’. Values containing whitespace or equals signs must be surrounded by single or double quotation marks. An option name must be pre- ceded by one or more spaces, tabs or newlines. Multiple option and value pairs may extend over several lines. A series of options and values must be terminated by a ‘>’ char- acter or by the ‘/>’ string. Options with the same name may be repeated. In this case the option value is that of the last instance. There are three types of X macro calls: calls Section Called by that execute an X macro start section, calls that execute an X macro termination section and Start section Miramo Reference Guide [ v 9.2 ] R-503 mmpp — Miramo macro preprocessor CHAPTER 6 X macro examples (content free) Example 6.53 shows a macro which outputs a 1 <@xmacro> Rand { sequence of pseudo-random numbers, using the 2 <#def> rnum @rand() @rand( ) function in its start section definition. 3 @print(<#rnum>, n) 4 }{} The output from Example 6.53 is: 5 First= ' The output from Example 6.55 is: Factorial of 5 = '120' There are several ways in which the ‘Factor’ macro shown in Example 6.55 may be improved. First the ‘val’ variable on line 2 is subject to been overridden. If the ‘val’ vari- able were to be set to a value other than ‘1’, then the macro would return an incorrect result. There are two ways to prevent this happening, both illustrated in Example 6.56. R-504 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor The first way is to move the definition of the ‘val’ variable to after the @xgetvals( ) func- tion, i.e. switching the order of lines 2 and 3 in Example 6.55. The second way is to call @xgetvals( ) with a an argument to be used as the prefix for all called variable definitions. This is illustrated in Example 6.55 on line 5. The effect of the @xgetvals( ) function ‘f.’ argument, i.e. the call @xgetvals(f.) is that every option is preceded by the string ‘f.’ and it is therefore impossible to overwrite the value of any variable that does not begin with ‘f.’. Example 6.56 illustrates a solution to 1 <@xmacro> Factor { another problem with X macros, i.e., 2 <#def> f.fval {} there is no way of ensuring that all 3 <#def> f.err {} 4 <#def> f.err {<#f.err>Factor: bad} the necessary options will be present 5 @xgetvals(f.) when a macro is called. If an option 6 <#def> val 1 7 @ifnot(@len(<#f.fval>)) { is missing, the macro call will either 8 <@write> eLog {Factor: bad 'fval'} inherit the value of the option, if 9 @print({<#f.err> 'fval' }, n) included, when the macro was previ- 10 } 11 @else{ ously called (ultimately, all mmpp 12 @for(f = 1 TO <#f.fval> ) { variables are global), or fail with a 13 <#def> val @eval(<#val> * $$f) 14 } fatal error. The solution illustrated in 15 @print(<#val>, n) Example 6.56 deals with the case that 16 } 17 } the option must be included with 18 Factorial of 6 = ' X macro examples (with content) Example 6.57 illustrates an alternative 1 <@xmacro> - Fact2 { macro design, also for calculating the 2 @--- Start section factorial of a number. An alternative 3 <#def> val 1 4 }{ structure is shown, wherein the data is 5 @--- Termination section the text between Miramo Reference Guide [ v 9.2 ] R-505 mmpp — Miramo macro preprocessor CHAPTER 6 X macros to create decorated headings Document designs may incorporate decorative headings, for example to reverse text out of a strapline or enclose text within a border rule. As there is no single inline markup code to do such formatting, the next three sections, X macros to create decorated headings— ‘mkBox’ macro, X macros to create decorated headings—‘BoxHead’ macro and X macros to cre- ate decorated headings—‘BoxHeadRow’ macro, show how to create a series of X macros to extend the markup language to include this capability. Two decorated heading contexts are catered for: 1 Free standing. These decorated headings may occur anywhere within the input where a code is permitted. Free standing decorated headings are created using the macro ‘BoxHead’, shown in Example 6.61 (see page R-510). Examples of free standing decorated headings are shown in Figures 6.28 to 6.31 on pages R-510–511. 2 Decorated headings within table heading rows or table body rows. These decorated headings are created using the macro ‘BoxHeadRow’, shown in Example 6.67 (see page R-513), which acts as a wrapper for the X macros to create decorated headings—‘mkBox’ macro The ‘mkBox’ X macro shown in Example 6.58 is a utility macro for the production of text frames surrounded by square or rounded rectangles with an optional background color or image. The ‘mkBox’ X macro supports nearly twenty options. The default values for all these options are defined at the beginning of the ‘mkBox’ macro start section (lines 2 to 16 in Example 6.58). Any or all of the default values may be overridden when the ‘mkBox’ macro is called, using option names the same as those defined in the start section, without the ‘mkb_’ prefix added by the @xgetvals(mkb_) call on line 66. The remainder of the ‘mkBox’ macro start section in Example 6.58 is concerned with cal- culating location and size values (lines 18 to 38) and drawing a rectangle with a back- ground fill or including an image (lines 42 to 49). If a background image is included and the heading has round corners, then the image corners are masked using the R-506 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor 1 <@xmacro> mkBox { 2 @-- (continues to line 63) 3 <#def> mkb_W 40mm @-- Width of frame to fit within 4 <#def> mkb_H 20mm @-- Height of frame to fit within 5 <#def> mkb_Radius 4mm @-- Corner radius 6 <#def> mkb_bgImage {} @-- Default = no background image 7 <#def> mkb_penW 2pt @-- Default box line width 8 <#def> mkb_penColor Blue @-- Defalul box line color 9 <#def> mkb_Project 0pt @-- Distance to o'hang on each side 10 <#def> mkb_bgColor Red @-- Default box fill color 11 <#def> mkb_maskColor {Black @-- Default color to mask image corners 12 pen=7} @-- Default pen for default color only 13 <#def> mkb_TFrameLM {} @-- Textframe Left margin 14 <#def> mkb_TFrameTM {} @-- Textframe Top margin 15 <#def> mkb_TFramePos I @-- Position of TextFrame, I = Inside 16 @-- border rule, N = Contiguous with AFrame 17 @xgetvals(mkb_) 18 @if(<#mkb_Project>) {<#def> mkb_W @eval(<#mkb_W> + <#mkb_Project> * 2 )} 19 <#def> mkb_LT @eval(<#mkb_penW> / 2 ) 20 <#def> mkb_LTmask @eval(<#mkb_Radius> / -2 ) 21 <#def> mkb_LTmaskW @eval(<#mkb_Radius> + <#mkb_penW>) 22 @------23 @if(@len(<#mkb_TFrameLM>) = 0 OR @len(<#mkb_TFrameTM>) = 0 ) { 24 <#def> mkb_TFrameLM 0 25 <#def> mkb_TFrameTM 0 26 @if(<#mkb_TFramePos> = I) { 27 <#def> mkb_TFrameLM <#mkb_penW> 28 <#def> mkb_TFrameTM <#mkb_penW> 29 <#def> mkb_TFH @eval(<#mkb_H> - <#mkb_penW> * 2) 30 <#def> mkb_TFW @eval(<#mkb_W> - <#mkb_penW> * 2) 31 } 32 } 33 @------34 <#def> mkb_TFH @eval(<#mkb_H> - <#mkb_TFrameTM> * 2) 35 <#def> mkb_TFW @eval(<#mkb_W> - <#mkb_TFrameLM> * 2) 36 @------37 <#def> RectSize { L=<#mkb_LT> T=<#mkb_LT> radius=<#mkb_Radius> 38 W=@eval(<#mkb_W> - <#mkb_penW>) H=@eval(<#mkb_H> - <#mkb_penW>)} 39 40 41 Miramo Reference Guide [ v 9.2 ] R-507 mmpp — Miramo macro preprocessor CHAPTER 6 56 radius=@eval(<#mkb_Radius> + <#mkb_LTmaskW> / 2) /> 57 } 58 59 @if(<#mkb_penW> > 0) { 60 If the ‘mkBox’ macro shown in Example 6.58 were to be called with no arguments, as shown in Example 6.59 the output would be as shown in Figure 6.27. X macros to create decorated headings—‘BoxHead’ macro Example 6.61 contains an X macro, ‘BoxHead’, for the production of free standing deco- rated headings. The ‘BoxHead’ macro calls the ‘mkBox’ macro (lines 22 to 26 in Example 6.61), and produces headings surrounded by square or rounded rectangles with an optional background color or image. Example 6.60 shows how the ‘BoxHead’ macro is called. R-508 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor The content enclosed between the 1 <@xmacro> - BoxHead { 2 @--- Start section (continues to line 17) 3 <#def> bh.W 130pt @-- Default overall width of box heading 4 <#def> bh.H 40pt @-- Default overall height of box heading 5 <#def> bh.sa 10pt @-- Default space above box heading 6 <#def> bh.sb 07pt @-- Default space below box heading 7 <#def> bh.Location A @-- Default location (see code 'P' option) 8 <#def> bh.paraOpts {} @-- Default paragraph options for heading text 9 <#def> bh.ParaFmt BoxHead @-- Default paragraph format 10 <#def> bh.TFrameLM 6pt 1. Using the $BoxHead variable is not necessary to reference the heading text. The same output effect could be achieved by deleting line 36 in Example 6.61 and moving lines 19 to 35 from the beginning of the termination section to the end of the start section (i.e. after line 17 in Example 6.61). In addition the minus sign in line 1 would need to be deleted, since otherwise all the content between Miramo Reference Guide [ v 9.2 ] R-509 mmpp — Miramo macro preprocessor CHAPTER 6 11 <#def> bh.TFrameTM 1pt 12 <#def> bh.p 9pt 13 <#def> bh.textAlign L 14 @xgetvals(bh.) 15 <#def> bh.hp1 9pt @-- Hidden para1 16 <#def> bh.AFdown @eval(<#bh.H> - (<#bh.hp1> * 2 / 3)) 17 @--- Start section end 18 }{ 19 @--- Termination section start 20 ls=F an=N P=<#bh.Location> > 21 28 l=0 sa=<#bh.sa2> sb=<#bh.sb> wp=Y > 42 @--- Termination section end 43 } Example 6.61 ‘BoxHead’ macro Example 6.62 shows the default operation of the ‘BoxHead’ macro. 1 In Example 6.62 the heading text, enclosed within Figure 6.28 Output from Example 6.62 the R-510 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor 1 5 p="12pt" 6 paraOpts="fcolor='White'" 7 >The next five years Still many hydrogen molecules ... Example 6.63 Using ‘maskColor’ Figure 6.29 Output from Example 6.63 In Example 6.63 the border is suppressed by setting the ‘penW’ option to zero. The head- ing text is set to white using the ‘paraOpts’ bucket option, which can contain any number of paragraph options. Note that the option values within the ‘paraOpts’ value string can- not themselves be surrounded by double quotation marks. Example 6.64 shows that when an image is included the ‘maskColor’ option can be used to fill the block rectangle. This is because the rounded mask rectangle is cropped by the enclosing anchored frame. 1 The cooling has begun ... Example 6.64 Using ‘maskColor’ The included image is always sized to fit within the innermost edge of the border. Example 6.65 shows a natural mask, i.e. the mask color defaults to white. 1 1. Any value of Radius greater than half the width and height value results in a rounded rectangle becom- ing a circle. Miramo Reference Guide [ v 9.2 ] R-511 mmpp — Miramo macro preprocessor CHAPTER 6 1 Algebra and Algebra and some other 10 some other branches of mothematics ... branches of mothematics ... Example 6.66 Producing a circular heading (2) Figure 6.32 Output from X macros to create decorated headings— Example 6.66 ‘BoxHeadRow’ macro Example 6.67 defines a macro, ‘BoxHeadRow’, to facilitate the inclusion of decorated headings within tables. Like the ‘BoxHead’ macro described in the previous section (see Example 6.61 on page R- 510) the ‘BoxHeadRow’ macro provides a wrapper for the ‘mkBox’ macro (see Example 6.58 on page R-508). The ‘BoxHeadRow’ macro includes a special table within a text frame (created by a call to the ‘mkBox’ macro, line 16 in Example 6.67) within a standard table row. The special in-row table needs to inherit some, but not all, the attributes of the parent table. For example, the column widths of the in-row table must be identical to those of the parent table. To achieve this effect the column widths need to be stored every time a non-in-row 1 <@xmacro> BoxHeadRow { 2 @------3 <#def> tbh_inBoxHeadRow 1 @-- Flag used in 'Tbl' macro 4 @------5 <#def> rbh_H 40pt @-- Overall height of enclosing AFrame 6 <#def> rbh_Type B @-- BoxHead row type (H, B, or F) 7 <#def> rbh_tblOpts {} @-- Local (head) tbl options 8 @------9 @xgetvals(rbh_) 10 @------11 <#def> rbh_AFrameW @eval(<#tcw.cwTot> + (2 * <#rbh_Project>)) 12 @------13 18 @- BUG R-512 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor 23 <#def> tbh_inBoxHeadRow 0 24 } Example 6.67 BoxHead in table macro Example 6.68 contains the macro ‘Tbl’, which always starts by writing out a string corre- sponding to itself. This is achieved using <$0 in place of 1 <@xmacro> Tbl { 2 <#ifndef> tbh_inBoxHeadRow 0 3 @------4 @- Output table code 'as is' 5 @------6 <$0 @xputvals() > 7 @------8 @ifnot(<#tbh_inBoxHeadRow>) { 9 @------10 @- If not a BoxHeadRow special table, store Tbl args 11 @- & zero vals used in 'TblColWidth' & 'subHeading' 12 @------13 <#def> tbl_args {@xputvals()} 14 @------15 <#def> tcw.cwTot 0 @-- Width of table 16 <#def> tcw.cwCount 0 @-- Number of Example 6.69 contains the macro ‘TblColWidth’, which counts the number of columns and stores their widths whenever one or more 1 <@xmacro> TblColWidth { 2 <#def> tcw.count 1 3 <#def> tcw.cwCount @eval(<#tcw.cwCount> + 1) 4 @------5 @- Store Miramo Reference Guide [ v 9.2 ] R-513 mmpp — Miramo macro preprocessor CHAPTER 6 15 @------16 <#def> tcw.ColCount @eval(<#tcw.ColCount> + (1 * <#tcw.count>)) 17 <#def> tcw.cwTot @eval(<#tcw.cwTot> + (<#tcw.W> * <#tcw.count>)) 18 } Example 6.69 Macro ‘TblColWidth’ to modify operation of Example 6.70 contains the macro ‘subHeading’, which conditionally outputs a 1 <@xmacro> - subHeading {}{ 2 @ifnot(<#sbh.first>) { Example 6.71 shows sample input to produce a table containing a series of decorated table heading rows, both in the table header and within table body rows. 1 2 R-514 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor 31 32 The output from Example 6.71 is shown in Figure 6.33. The decorated heading macros shown in this section and the preceding two sections are are included in the file ‘boxHeadings.mmp’ in the xmacros directory within the samples directory. Miramo Reference Guide [ v 9.2 ] R-515 mmpp — Miramo macro preprocessor CHAPTER 6 Summarymmpp syntax summary of built-in macros and functions The following is a summary of the built-in macros and functions, as well as text quoting and commenting conventions, supported by mmpp. Note that, with the exception of ‘@-’, all functions which begin with an ‘@’ (for example, ‘@len( )’, ‘@for( )’, etc.) are recognized only within the following macro definitions, vari- able definitions, array element definitions, the arguments to <@system> and <@write>. In the following description, ‘whitespace’ refers to a sequence of one or more space or tab characters; ‘newline’ refers to the Unix newline character ‘\n’ (octal ‘\012’) or, interchange- ably, to the Windows newline and carriage-return control code pair. The special characters ‘{’ and ‘}’ may always be included as printable text within macro and variable definition body text using ‘\{’ or ‘\}’. Summary of built-in macros and functions @- comment Anywhere within the input stream, begin comment text to be stripped by mmpp. Comment text is terminated by a newline. [See page R-465] { ... macro definition body text ... } All built-in macros and functions, but not macro definitions, may be included within macro definition body text. Macro body definition text occurring after an ini- tial opening delimiter, ‘{’, is considered to begin on a new line. [See pages R-467– 477] @acos( argument ) In a macro definition body or a variable definition, return the arc cosine of the argument. [See pages R-488–490] @asin( argument ) In a macro definition body or a variable definition, return the arc sine of the argu- ment. [See pages R-488–490] @atan( argument ) In a macro definition body or a variable definition, return the arc tangent of the argument. [See pages R-488–490] @basename( argument ) @basename( argument1, d ) In a macro definition body or a variable definition, if argument is a string contain- ing folder or directory separators (‘ \’ on Windows NT, ‘/ ’ on Unix) return the part of the string after the last separator character. R-516 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor Summary of built-in macros and functions ( Continued ) If argument contains no folder or directory separator characters, the whole string is returned. In the second case above, when argument is followed by a comma, ‘ , ’ , a space and the key letter ‘d’, if argument is an actual folder or directory name the returned string value is terminated by a separator character. @char2dec( argument ) In a macro definition body or a variable definition, convert a single 8-bit charac- ter, argument, to its decimal representation in the range 32 to 127. For example, @char2dec(A) returns the decimal value 65. @cos( argument ) In a macro definition body or a variable definition, return the cosine of the argu- ment (degrees). [See pages R-488–490] @ceil( argument ) In a macro definition body or a variable definition, return the least integral value greater than or equal to the argument. [See pages R-488–490] @dec2bin( argument ) In a macro definition body or a variable definition, convert a decimal number argument to a single byte binary character. argument must be in the range 1 to 255. [See pages R-499–500] @dec2hex( argument ) @dec2hex( argument1, argument2 ) In a macro definition body or a variable definition, convert a number in base-10 (decimal) representation, argument, to base-10 (decimal) representation. If @dec2hex( ) has two arguments, the result is zero-padded to argument2 digits. @dec2hex(14) outputs: e @dec2hex(14, 4) outputs: 000e @dec2hex(8364) outputs: 20ac Use @hex2dec( ), described on page R-520, for conversion from hexadecimal to decimal. [See pages R-499–500] Miramo Reference Guide [ v 9.2 ] R-517 mmpp — Miramo macro preprocessor CHAPTER 6 Summary of built-in macros and functions ( Continued ) <#define> name definition Define variable name. The definition may begin anywhere within the input stream provided it is on a new line preceded by whitespace only. Enclosing delimiters in the form of opening and closing curly braces, ‘{’ and ‘}’, must surround definition if it includes whitespace or newlines. Variables are evaluated immediately when defined outside a macro definition body. Variables defined within a macro defini- tion body are evaluated when the macro is called. Their scope is global. <#def> may be used in place of <#define>. When mmpp encounters the string ‘<#name>’ anywhere in its input the value of definition is substituted in its place. [See pages R-465–466] Also: see <#ifndefine> below. <#define> arrayname[ int ] definition <#define> arrayname[ int, int ] definition Define the value of an element in array arrayname. The definition may begin any- where within the input stream provided it is on a new line preceded by whitespace only. Enclosing delimiters in the form of opening and closing curly braces, ‘{’ and ‘}’, must surround definition if it includes whitespace or newlines. When mmpp encounters the string ‘$arrayname[int]’ or the string ‘$arrayname[int, int]’ anywhere within macro, variable or array element definition body text the value of the array element is substituted in its place. [See pages R- 474–476] @elif( boolean expression ) { ... more macro definition body text ... } @elifnot( boolean expression ) { ... more macro definition body text ... } In a macro definition body, process text and/or operators if the expression associ- ated with a matching @if( ) is false (or true in the case of a matching @ifnot( )) and there has been no intermediate instance of an @elif( ) expression which has evaluated to true (or alternatively there has been no intermediate @elifnot( ) which has evaluated to false). @elif( ) must immediately follow the terminating ‘}’ of the matching @if( ) or @elif( ), or be separated from it only by a single newline and any number of other whitespace characters. [See page R-490] @else { ... more macro definition body text ... } In a macro definition body, process text and/or operators if the expression associ- ated with a matching @if( ) is false (or true in the case of a matching @ifnot( )) and there has been no intermediate instance of an @elif( ) expression which has evaluated to true. @else must immediately follow the terminating ‘}’ of the matching @if( ), @elif( ) or @elifnot( ), or be separated from it only by a single newline and any number of other whitespace characters. [See page R-490] R-518 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor Summary of built-in macros and functions ( Continued ) <@eof> <@eof> may be used on a line by itself to terminate all input processing. All input after the <@eof> will be discarded. @eval( arithmetic expression ) In a macro definition body or a variable definition, return the value of the expres- sion. Addition, subtraction, multiplication, division and modulus are supported (+, -, *, /, %). [See page R-486] @exp( argument ) In a macro definition body or a variable definition, return the exponent of the argument. <#fdefine> name filename Assign the contents of filename to variable name. The definition may begin any- where within the input stream provided it is on a new line preceded by whitespace only. <#fdef> may be used in place of <#fdefine>. filename may be any system filename, optionally designated using shell environment variables, as in ${FILENAME}. Environment variable names must be surrounded by curly braces. @filetype( filename, key ) In a macro definition body or a variable definition, returns true, i.e. 1, if file filename has the attribute specified by the value of key. The permitted values of key and their corresponding attributes are: Key File attribute fm FrameMaker binary file (at least readable) mif FrameMaker MIF file (at least readable) pdf PDF, Portable Document Format or ‘Acrobat’, file (at least readable) r The file exists and is readable w The file exists and is writable rw The file exists and is readable and writable @floor( argument ) In a macro definition body or a variable definition, return the greatest integral value less than or equal to the argument. [See pages R-488–490] @for( loop expression ) { ... more macro definition body text ... } In a macro definition body, process text and/or operators while loop expression evaluates to true. A loop expression has the form: Miramo Reference Guide [ v 9.2 ] R-519 mmpp — Miramo macro preprocessor CHAPTER 6 Summary of built-in macros and functions ( Continued ) cvar = m TO n where cvar is a counter variable and m and n are integers, variables which have integer values or expressions which evaluate to integers. After the loop is pro- cessed the value of m is incremented by 1. The loop is processed repeatedly until the value of m is greater than the value of n. The counter variable cvar may comprise upper and lower case alphabetic charac- ters in the range a - z. The current value of cvar may be accessed using ‘$$cvar’. The value of the corre- sponding argument to the macro containing the ‘for’ loop may be accessed using ‘$cvar’. @for loops may be nested, one within another. [See pages R-492–492] @gsub( { argument }, { regexp }, { substitutionstring } ) Return the string argument after substituting substitutionstring for all occurrences of the string matched by regexp if present, otherwise return the string argument unchanged. If substitutionstring contains the ampersand character, ‘&’, then this is replaced by the matched string prior to each substitution. [See pages R-480–486] @hex2bin( argument ) In a macro definition body or a variable definition, convert hexadecimal represen- tation of one or more binary bytes into binary data. The hexadecimal encoded data is processed two digits at time, from the beginning. Spaces between hexadec- imal digits are ignored. If argument contains an odd number of hexadecimal digits, the last digit is ignored. Example: @hex2bin(4 1 42e b 4344) outputs ABCD. In this example the output letters A, B, , C and D are the Latin-1 encodings for the following bit values, 01000001, 01000010, 11101011, 01000011 and 01000100. [See pages R-499–500] @hex2dec( argument ) @hex2dec( argument1, argument2 ) In a macro definition body or a variable definition, convert a number in base-16 (hexadecimal) representation, argument, to base-10 (decimal) representation. If @hex2dec( ) has two arguments, the result is zero-padded to argument2 digits. Use @dec2hex( ), described on page R-517, for conversion from decimal to hexa- decimal. [See pages R-499–500] @if( boolean expression ) { ... more macro definition body text ... } @ifnot( boolean expression ) { ... more macro definition body text ... } In a macro definition body, process text and/or operators if boolean expression is true (or, in the case of @ifnot( ), is false). An expression is ‘true’ if it evaluates to any number other than 0. An expression is ‘false’ if it evaluates to 0. R-520 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor Summary of built-in macros and functions ( Continued ) Comparison operators greater than, greater than or equals, less than, less than or equals, not equals and equals are supported ( >, >=, <, <=, <>, = ). Boolean expres- sions may be combined using AND and OR. The precedence of AND and OR is lower than that of the comparison operators. Expressions may be grouped using ‘(’ and ‘)’. [See page R-490] <#ifndefine> name definition Same as ‘<#define>’ above, except that definition is ignored if name is already defined. <#ifndefine> may be abbreviated to <#ifndef>. @image ( filename ) Use the @image( ) function within an expression to determine properties of an image file. If filename is in a supported import image format, then @image( ) eval- uates to 1 (success). In all other cases it evaluates to 0. Additionally, and more usefully, @image( ) sets the following mmpp variables: <#img.w>, <#img.h>, <#img.ar>, <#img.dpi>, <#img.type> and <#img.err>. If @image( ) evaluates to 1, these variables are set as described below. <#img.w> and <#img.h> variables are set to the width and height of the (first) image in filename. The width and height values are always expressed as an integer number of pixels except in the case of EPS files when the returned values are in points. The <#img.ar> variable is set to the aspect ratio of the image. <#img.ar> equals <#img.w> divided by <#img.h>. <#img.dpi> is the image resolution in pixels per inch. Several image file formats never include, or sometimes do not include, dpi data. In such cases, e.g. EPS files and many JPEG files, the value of <#img.dpi> is set to 0 (zero). The <#img.type> variable is set to a string value denoting the image file format. These string values represent the supported image file types and can be any of the following: BMP, CGM, EPS, GIF, JFIF, JPEG, PNTG, PCX, PNG, SNRF, TIF, WMF, XWD, SVG, and EMF u3d,. The string PNTG indicates the image is in Mac Paint file format. SNRF indicates the image is in Sun Raster file format. The <#img.err> error status variable is set to 0 (no error). If @image( ) evaluates to 0, i.e. an error is encountered, the <#img.err> variable is set to an integer value in the range 1 to 5. The possible values of <#img.err> and their corresponding meanings are as follows: Error Description 0 No error. filename data has been successfully determined 1 filename does not exist 2 filename exists but is not readable Miramo Reference Guide [ v 9.2 ] R-521 mmpp — Miramo macro preprocessor CHAPTER 6 Summary of built-in macros and functions ( Continued ) 3 filename is a folder (or directory) 4 filename contains an unsupported image format (or may not be in any image format) 5 filename is in a supported image format but may be corrupt If @image( ) evaluates to 0, then <#img.w>, <#img.h>, <#img.ar> and <#img.type> are all set to 0. [Examples illustrating the usage of the @image( ) code are included in the Miramo User Guide, pages U-48–52] <@include> filename <@include_if> ( boolean expression ) filename Temporarily switch input processing to file. filename may be any system file, optionally designated using shell environment variables, as in ${FILENAME}. See the description of using environment variables on R-476). <@include_if>( ) may be used to include a file conditionally. If the expression within the braces following an <@include_if> statement evaluates to 0 or false the named file is not included. In all other cases the file is included. If <@include> or <@include_if>( ) is used within a macro definition body, the data within the included file is simply passed through to the standard output of mmpp without processing. @isInt( argument ) In a macro definition body or a variable definition, return 1 (true) if argument is an integer. @isNum( argument ) In a macro definition body or a variable definition, return 1 (true) if argument is a number. @len( argument ) In a macro definition body or a variable definition, return the number of charac- ters in argument. [See pages R-478–479] @log( argument ) In a macro definition body or a variable definition, return the logarithm of the argument. @log10( argument ) In a macro definition body or a variable definition, return the base 10 logarithm of the argument. R-522 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor Summary of built-in macros and functions ( Continued ) <@macro> name { ... macro definition body text ... } Define macro name. The name must be separated from the ‘<@macro>’ code by whitespace only (not including newlines). The macro definition body text may contain argument placeholders ($1, $2 ... $n, $#, $* and $(m – n) ), calls to other macros, variable definitions, conditionals, expressions, etc. A macro definition body begins with a ‘{’ on the same line as the macro name. A macro definition body is terminated by a ‘}’, followed by a newline (which may optionally be preceded by whitespace). Matching curly braces within the macro definition body text are removed from the result of a macro expansion. A macro cannot be defined within a macro. [See pages R-467–477] <@name> arg1 arg2 ... argn Call macro name with whitespace separated arguments. Enclosing ‘{’ and ‘}’ delim- iters must surround arguments containing whitespace or newlines. <|name> arg1 | arg2 | ... argn Call macro name with ‘|’ separated arguments. Enclosing ‘{’ and ‘}’ delimiters must surround arguments containing newlines (or surround newlines within argu- ments). <@map> inputstring outputstring Replace inputstring with outputstring. When mmpp encounters &inputstring; any- where in its input stream outputstring is substituted in its place. Enclosing delimit- ers in the form of opening and closing curly braces, ‘{’ and ‘}’, must surround outputstring if it includes whitespace or newlines. Mappings are evaluated immediately when they are defined outside a macro defi- nition body. Mappings defined within a macro definition body are evaluated when the macro is called. Their scope is global. [See pages R-477–478] @match( { argument }, { regexp } ) If regexp is present in the string argument, return its starting position, otherwise return 0. The first character in the argument string is at position 1. [See pages R- 480–486] @matchcount( { argument }, { regexp } ) If regexp is present in the string argument, return the number of occurrences, oth- erwise return 0. [See pages R-480–486] @matchlen( { argument }, { regexp } ) If regexp is present in the string argument, return its length, otherwise return 0. [See pages R-480–486] Miramo Reference Guide [ v 9.2 ] R-523 mmpp — Miramo macro preprocessor CHAPTER 6 Summary of built-in macros and functions ( Continued ) @print( argument ) @print( argument, n ) In a macro definition body or a variable definition, print a string argument to stan- dard output. If argument is followed by the letter ‘n’, as shown above, the string is printed without a new line at its end. @mifstr( argument ) Convert a string for use within @pdfpages ( filename ) Use the @pdfpages( ) function within an expression to determine page count and other properties of a PDF file. If filename is in a parsable PDF format, then @pdfpages( ) evaluates to 1 (success). In all other cases it evaluates to 0. @pdfpages( ) also sets the following mmpp variables: <#pdf.pages> and <#pdf.err> and creates thirteen mmpp arrays containing location and size parameters of the PDF media box, art box and crop box for each page in the PDF file. The arrays are indexed by page number (the first page in the document is always 1). If @pdfpages( ) evaluates to 1, these variables and arrays are set as described below. In the following the values for Left and Top are relative to the media box. The <#pdf.pages> variable is set to the total number of pages in the PDF file. $pdf.mL[n], $pdf.mT[n], $pdf.mW[n], and $pdf.mH[n] contain the Left, Top, Width and Height values (in points) for the PDF media box on page n. $pdf.aL[n], $pdf.aT[n], $pdf.aW[n], and $pdf.aH[n] contain the Left, Top, Width and Height values (in points) for the PDF art box on page n. $pdf.cL[n], $pdf.cT[n], $pdf.cW[n], and $pdf.cH[n] contain the Left, Top, Width and Height values (in points) for the PDF crop box on page n. $pdf.rotate[n], contains the angle of rotation (0, 90, 180 or 270) of page n. The <#pdf.err> error status variable is set to 0 (no error). If @pdfpages( ) evaluates to 0, i.e. an error is encountered, the <#pdf.err> variable is set to an integer value. The possible values of <#pdf.err> and their correspond- ing meanings are as follows: Error Description 0 No error. filename data has been successfully determined 1 filename does not exist 2 filename exists but is not readable 4 filename is not a PDF file (or may not be in any image format) 5 filename is a PDF file but may be corrupt R-524 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor Summary of built-in macros and functions ( Continued ) @rand( ) In a macro definition body or a variable definition, return a pseudo random num- ber. <@readfile>( filename, key [, postopts] ) macroname [, endmacro] [fieldwidths] (Parameters within square brackets,‘[’ and ‘]’ above, are optional.) filename may be any text file. key may be any of the following: Key File attribute fw Field widths csv Comma separated values tsv Tab separated values bsv Vertical bar separated values postopts can be any of: trim, ltrim or rtrim. trim removes whitespace from both the beginning and end of the field. ltrim removes whitespace from the beginning of the field. rtrim removes whitespace from the end of the field. macroname is any user defined macro. macroname is called once for every input line in filename and is passed each field as a separate argument, starting from 1 (‘$1’) through to n (‘$n’). There is no limit to the size of n (nor to the length of an input line). endmacro is the name of a user-defined macro to call after <@readfile>( ) has com- pleted reading filename. The user-defined endmacro macro cannot be passed any arguments. fieldwidths may only be specified if key has the value fw, in which case fields are specified by their lengths (number of 8-bit characters), each preceded by the verti- cal bar sign (‘|’). If an input line is shorter than the total length of the fieldwidths then the extra field- widths are silently ignored. Similarly, if the length of any input line is greater than the total the fieldwidth values the extra characters are ignored. A fieldwidths specification ending with ‘|-’ will assign all the remaining characters in the input line to the last argument to macroname. E.g. ‘30|-’ (without the sur- rounding single quotation marks) assigns the first 30 characters to $1 and all remaining text on the same line to $2. If key is set to fw and there is no fieldwidths specification, the entire line is passed to macroname as the value of $1. [See pages R-495–499] <@resume> <@resume> may be used on a line by itself anywhere within the input stream to resume mmpp processing if previously suspended within the current input file using <@suspend> (see below). If the input contains no prior <@suspend> request, <@resume> is silently discarded from the output. Miramo Reference Guide [ v 9.2 ] R-525 mmpp — Miramo macro preprocessor CHAPTER 6 Summary of built-in macros and functions ( Continued ) @round( argument ) @round( argument1, argument2 ) In a macro definition body or a variable definition, round a floating point number, argument, to the nearest integer value. If @round( ) has two arguments argument1 is rounded to argument2 decimal places. [See pages R-488–490] @sin( argument ) In a macro definition body or a variable definition, return the sine of the argument (degrees). [See pages R-488–490] @slice( string, key [, postopts]) macroname [fieldwidths] (Parameters within square brackets,‘[’ and ‘]’ above, are optional.) Split a string into sub-strings. string may be literal string, a variable, an array element or a macro argument ($n). key may be fw, csv, tsv or bsv. These key values have the same meaning as the key values for <@readfile>( ), see page R-525. postopts are the same as for <@readfile>( ), see page R-525. macroname is any user defined macro. macroname is passed each field as a separate argument, starting from 1 (‘$1’) through to n (‘$n’). There is no limit to the size of n (nor to the length of an input string). fieldwidths may only be specified if key has the value fw, in which case sub-strings are specified by their lengths (number of 8-bit characters), each preceded by the vertical bar sign (‘|’). If an input string is shorter than the total length of the field- widths then the extra fieldwidths are silently ignored. Similarly, if the length of any input string is greater than the total the fieldwidth values the extra characters are ignored. A fieldwidths specification ending with ‘|-’ will assign all the remaining characters in the input string to the last argument to macroname. [See pages R-479- R-480] @sqrt( argument ) In a macro definition body or a variable definition, return the square root of the argument. [See pages R-488–490] @sub( { argument }, { regexp }, { substitutionstring } ) Return the argument after substituting substitutionstring for the first occurrence of the string regexp if present, otherwise return the string argument unchanged. If substitutionstring contains the ampersand character, ‘&’, then this is replaced by the matched string. [See pages R-480–486] R-526 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor Summary of built-in macros and functions ( Continued ) @substr( { argument }, position ) Return the suffix of string argument starting at position. The first character of argu- ment string is at position 1. If the value of position is greater than the length of the argument string, then nothing is returned. [See pages R-480–486] @substr( { argument }, position, length ) Return a substring of argument starting at position, containing at most length char- acters. The first character of argument string is at position 1. If either length, or length plus position, is greater than the length of the argument string, then the entire suffix (only) is returned. If the value of position is greater than the length of the argument string, then nothing is returned. [See pages R-480–486] <@suspend> <@suspend> may be used on a line by itself anywhere within the input stream to suspend processing by mmpp. Processing is resumed either when an <@resume> (see above) is encountered or the end of the current file is reached. The primary use of <@suspend> is for documenting Miramo applications. <@system> { command(s) } Run a system command. If the command is longer than a single line, then it must be enclosed within left and right curly braces, ‘{’ and ‘}’. It may be any set of com- mand lines or programs runnable by the Unix shell sh, or by the Windows NT command processor cmd.exe. The standard output of the command is read by mmpp if <@system> is used outside a macro definition body. Otherwise the stan- dard output is discarded. [See pages R-492–495] @tabx( argument [, n ]) The @tabx( ) function, when used in a macro definition body or a variable defini- tion, converts tab characters in argument to spaces according to a tab specification. By default tab positions are assumed to occur every eight characters. The tab posi- tion settings by including the n parameter, where n is an integer specifying the character offset from one tab position to the next. @tan( argument ) In a macro definition body or a variable definition, return the tangent of the argu- ment (degrees). @tolower( argument ) In a macro definition body or a variable definition, translate the characters in argu- ment to lower case. @toupper( argument ) In a macro definition body or a variable definition, translate the characters in argu- ment to upper case. Miramo Reference Guide [ v 9.2 ] R-527 mmpp — Miramo macro preprocessor CHAPTER 6 Summary of built-in macros and functions ( Continued ) @trim( argument ) @ltrim( argument ) @rtrim( argument ) @trim( ) removes whitespace from the beginning and end of argument. @ltrim( ) removes whitespace from the beginning of argument. @rtrim( ) removes whitespace from the end of argument. Whitespace is one or more space or tab characters. @ucs2_to_utf8( argument ) In a macro definition body or a variable definition, convert a four-digit hexadeci- mal number argument to hexadecimal-encoded UTF-8. E.g. @ucs2_to_utf8(20AC) outputs: e282ac [See pages R-499–500] @utf8_to_ucs2( argument ) In a macro definition body or a variable definition, convert a hexadecimal- encoded string argument from UTF-8 to UCS-2 (hexadecimal). E.g. @utf8_to_ucs2(e282ac) outputs: 20ac [See pages R-499–500] @while( boolean expression ) { ... more macro definition body text ... } In a macro definition body, repeatedly process text and/or operators while boolean expression is true. An expression is ‘true’ if it evaluates to any number other than 0. An expression is ‘false’ if it evaluates to 0. Comparison operators greater than, greater than or equals, less than, less than or equals, not equals and equals are supported ( >, >=, <, <=, <>, = ). Boolean expres- sions may be combined using AND and OR. The precedence of AND and OR is lower than that of the comparison operators. Expressions may be grouped using ‘(’ and ‘)’. <@write> filename { ... message text ... } <@write> -n filename { ... message text ... } In the first form above, append message text to file filename. If the file filename does not exist, <@write> creates it. In the special case filename is either the string ‘error’ or the string ‘ERROR’ the message text is written to stan- dard error. message text is generally equivalent to macro definition body text and may comprise anything from simple text through to the full range of functions supported within macro definitions. In the second form above, using the ‘-n’ flag, write message text to filename. [See pages R-492–495] R-528 Miramo Reference Guide [ v 9.2 ] CHAPTER 6 mmpp — Miramo macro preprocessor Summary of built-in macros and functions ( Continued ) @xgetvals( argument ) Use @xgetvals( ) in an X macro definition start section to assign option values to variables having the same name as the option name. If argument is non-null, the variable name is is prepended with the value of argument. [See paragraph 4 on page R-501] <@xmacro> name { ... start section ... } <@xmacro> name { ... start section ... } { ... termination section ... } <@xmacro> - name { ... start section ... } { ... termination section ... } Define X macro name. name must be separated from the ‘<@xmacro>’ code by tabs and/or spaces only (not including newlines), or by a minus sign, ‘-’ surrounded by tabs and/or spaces only. An X macro start section is called by <$macroname>, or <$macroname options >. An X macro termination section is called by . X macro calls may also have the form: <$macroname/>, or <$macroname options />. Such calls first execute the start section then execute the termination section. In the foregoing, options have the same syntax as standard options and values, i.e. option name = option value. If a minus sign, ‘-’, followed by whitespace, is placed before a X macro name the entire content encountered between <$macroname> and is assigned to the variable $macroname instead of being output. The value of the variable $macroname is accessible in the termination section of the X Macro defini- tion. Matching curly braces within the macro definition body text are removed from the result of a macro expansion. A macro cannot be defined within a macro. [See pages R-500–503] @xputvals( ) @xputvals( argument ) Use @xputvals( ) in an X macro definition start section or termination section to write out the option names and values in the same form as passed to the macro when called. The optional argument may be a comma separated list of option names to exclude from writing out. [See paragraph 5 on page R-502] Miramo Reference Guide [ v 9.2 ] R-529 mmpp — Miramo macro preprocessor CHAPTER 6 R-530 Miramo Reference Guide [ v 9.2 ] APPENDIX 1: Pen and fill patterns and colors Pen and fill patterns The following table illustrates the set of pen and fill patterns available to Miramo users via the ‘pen’ and ‘fill’ code options. 0 setgray .1 setgray .3 setgray .5 setgray .7 setgray .9 setgray .97 setgray 1 setgray 0F1E3C78F0E1C378 0F87C3E1F0783C1E CCCCCCCCCCCCCCCC FFFF0000FFFF0000 8142241818244281 03060C183060C081 8040201008040201 0000000000000000 Definition (PostScript setgray & image strings) Pattern Pen no. 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 Miramo Reference Guide [ v 9.2 ] R-531 Pen and fill patterns and colors APPENDIX 1: Colors and separations White Yellow Black Red Green Blue Cyan Magenta Color name Color Pantone colors The following shows how to create a Pantone color, using the R-532 Miramo Reference Guide [ v 9.2 ] APPENDIX 2: Output device control [Unix only] Introduction Miramo provides direct access to the special features of PostScript output devices. If the output device supports special features such as multiple input and output bins, duplex operation, ‘underlays’ or other procedures, forms, etc, stored on a hard disk, then all of these features can be accessed using Miramo inline markup codes. The Miramo code ‘PSF’ (PostScript Special Feature) option may be assigned an integer value in the range 0 - 99, optionally followed by ‘+n’, where n is an integer. The device control operation performed by the ‘PSF’ option value selects the PostScript device control commands stored in the corresponding shell environment variable ‘$mmPSF_n’, where n is an integer in the range 0 - 99. Miramo has a set of default commands for PSF values 0 - 8 (see page 534 below). This Appendix provides a detailed description of how to use Miramo to directly control the operation of the PostScript output device. Using the code ‘PSF’ option to control output devices The code ‘PSF’ option (see the Miramo Reference Guide page 227) enables direct control of the special features of a PostScript output device. Each ‘PSF’ option may be assigned a value in the range 0 to 99; several ‘PSF’ option-value pairs may follow a single code. Merely setting the value of ‘PSF’ to say 66 will have no effect on the output. The option setting ‘PSF=66’ can only have effect if the shell environment variable ‘$mmPSF_66’ is set to a string comprising a device-specific control command valid for the intended Post- Script output device. For example ‘$mmPSF_66’ could be defined as follows: mmPSF_66="statusdict begin 0 setpapertray end" ; export mmPSF_66 The above assumes a Bourne shell (sh) environment. The equivalent for the C shell is: setenv mmPSF_66 "statusdict begin 0 setpapertray end" In the above the string statusdict begin 0 setpapertray end is a commonly used printer-spe- cific PostScript command to select the upper paper feed tray. If the Miramo input con- tains markup like this: Example 2.1 Using the code ‘PSF’ option then the output device will be set to commence feeding paper from the upper input bin, beginning with the page on which above paragraph appears. This assumes that the device control code assigned to ‘$mmPSF_66’, i.e. statusdict begin 0 setpapertray end, is correct for the printer.1 (See also the section headed Restrictions on page 536 below.) Miramo Reference Guide [ v 9.2 ] R-533 Output device control [Unix only] APPENDIX 2: Using the PSF ‘+n’ and ‘*’ flags The integer value assigned to the ‘PSF’ option may optionally be followed by either a ‘+n’ string (plus sign, followed by an integer value) or a string comprising a single ‘*’ character. These suffix strings act as flags which affect placing, priority and persistence of the ‘PSF’ device control commands. By default the output device control command applies to the page containing the code ‘PSF=n’ option. But if the integer value n is immediately followed by a ‘+n’ string flag (with no intervening spaces), the device control command applies to the current+nth page of the document, i.e. the page immediately after the page containing the code ‘PSF=n’ option if n is equal to 1, or the page two pages later if n is equal to two. Most printer hardware control commands, such as commands which select input and output bins and set duplex operation, act as print job-persistent switches. This means that if duplexing is set to begin with the current page, and duplexing has not previously been set using the ‘*’ flag (for example ‘PSF=n*’) all the following pages will be duplexed until another ‘PSF’ option is set to request a change back to simplex operation. If the integer value assigned to a ‘PSF’ option is immediately followed by a ‘*’ character, then the output device control command is applied to the current page and all the follow- ing pages. This means that if paper is requested to be fed from the upper input bin of a printer, using the ‘*’ flag, then paper will continue to be fed from the upper input bin. If this request is later overridden by a request to feed paper from another input bin using a ‘PSF’ option without a ‘*’ flag, then the following pages will revert to being fed from the upper input bin.1 Default device control commands In the section Using the PSF ‘+n’ and ‘*’ flags above, if the environment variable ‘$mmPSF_66’ is not set either when the document is created or at the time of printing, then the code ‘PSF’ output device control option will have no effect on the output. The exception to this rule is when ‘PSF’ is assigned a value in the range 0 to 8. Miramo has built-in defaults for each of these values. These default device commands and their functions are detailed in the table below. PSF Default device-specific command code Function value 0 statusdict begin 0 setpapertray end Feed from input bin 0 1 statusdict begin 1 setpapertray end Feed from input bin 1 1. Detailed descriptions of device-specific commands and operators are usually contained in a document entitled PostScript Language Supplement which should be (but often is not) supplied with the hardware. Alternatively the device control operators can be extracted from the PPD (PostScript printer description) file for the output device. PPD files are often supplied on floppy disk along with the output hardware. Addi- tionally most manufacturers make PPD files available from Web pages and bulletin boards. 1. Generally the ‘*’ flag should not be used with the ‘PSF’ option for a command that sets a printer into duplex operation, since this is likely to prevent the printer ever producing duplexed output. R-534 Miramo Reference Guide [ v 9.2 ] APPENDIX 2: Output device control [Unix only] PSF Default device-specific command code Function value 2 statusdict begin 2 setpapertray end Feed from input bin 2 3 statusdict begin 3 setpapertray end Feed from input bin 3 4 statusdict begin 4 setpapertray end Feed from input bin 4 5 statusdict begin /manualfeed true def end Feed from manual feed tray 6 statusdict begin /setduplexmode where Force simplex printing { begin false setduplexmode end } if end 7 statusdict begin /setduplexmode where Force duplex printing { begin true setduplexmode end } if (in standard ‘portrait’ mode) /settumble where { begin false settumble end } if end 8 statusdict begin /setduplexmode where Force duplex printing { begin true setduplexmode end } if (in ‘landscape’ mode) /settumble where { begin true settumble end } if end 9 - 99 May be specified by user, by defining environment variables ‘$mmPSF_9’ through ‘$mmPSF_99’ The default device control operators will be effective on a large number (probably the majority) of the PostScript printers currently in use. However there are also a large num- ber of PostScript printers for which the above defaults will be inappropriate and will result in errors if used. These errors can be avoided by assigning the correct device con- trol code to the environment variables ‘$mmPSF_0’ through ‘$mmPSF_8’. Changing the appearance of pages The ‘PSF’ option may also be used to embed PostScript operators. This requires familiarity with PostScript programming. For example, the ‘$mmPSF_98’ and ‘$mmPSF_99’ envi- ronment variables could be defined thus: mmPSF_98=".75 .75 scale 5.0 rotate" ; export mmPSF_98 mmPSF_99="\ gsave\ .95 setgray\ /Helvetica-Bold findfont 180 scalefont setfont\ 180 140 translate 0 0 moveto\ 50 rotate\ (COPY) show\ grestore\ " ; export mmPSF_99 Example 2.2 Using PostScript code to change page printing Now if these ‘PSF’ options are added to the first paragraph in the document: Miramo Reference Guide [ v 9.2 ] R-535 Output device control [Unix only] APPENDIX 2: all pages of the document will be reduced to 75% of normal size, rotated 5 degrees anti- clockwise by the printer. In addition the word ‘COPY’ will be printed in light gray under- neath the other text and graphics in the document.1 Some output devices are equipped with local hard disks which can store special proce- dures, cached forms and logos, as well as other performance enhancing features. Some environments provide additional support for print management facilities. These usually use the PostScript Document Structuring Conventions (DSC) to manage the inclusion of spe- cial features, such as fonts, underlays, forms, etc, within a print job. All these features should be accessible using the ‘PSF’ code.2 Restrictions While it is easy to get Miramo to access all the features of an output device, the following should be noted: • Documents must be printed in ascending page order. • All output device control commands will be ignored unless the name of the output printer is prefaced with the string ‘mmpsf:’ when printing a document. • With the exception of output device control operators intending to use the default ‘PSF’ values 0 to 8, all ‘PSF’ device control operators above the value 8 will be ignored unless they are in the user's process environment at the time of printing. • Using incorrect device control commands for the output device will result in full or partial failure of the output. Simple example The following example assumes the PostScript output device supports multiple input bins, duplexing and also recognizes the Miramo default device control commands. It also assumes that the document has a ‘landscape’ aspect ratio. If these assumptions are correct, then the first page should be fed from the upper input bin and the second page printed duplex on the reverse side of the first page: all following pages to be printed simplex from the lower input bin: In the above example the paragraph ‘FirstPara’ may be any paragraph on the first page of the document. 1. The order in which ‘PSF’ options follow the code is significant, and can drastically affect the out- put produced. For example, if the codes shown in Example 2.2 are supplied in the order shown, the page text and the ‘COPY’ text will both be reduced and rotated (additionally rotated in the case of the ‘COPY’ text). If the codes are supplied in reverse order the ‘COPY’ text will be printed in its normal size and rota- tion prior to the page being reduced and rotated. 2. If printer built-in ‘underlays’ are being used or special PostScript code to image text or other items behind the document text, then special care may be needed to set all the tables and graphic objects in the document to be transparent (fill = 15). R-536 Miramo Reference Guide [ v 9.2 ] APPENDIX 3: Running API clients This appendix describes how a Miramo document may be customized by invoking a Frame API client using the ‘-userapi apiname’ command line option (see page R-21.) The custom API client may use Frame Developer Kit (FDK) functions to modify the Miramo document immediately before saving and/or printing when any Miramo -P (printing) or -O (output) command line options are used. How Miramo invokes the custom API client Miramo uses the FDK F_ApiCallClient() function to invoke the API client named via the ‘-userapi’ command line flag. This in turn calls the F_ApiNotify() function of the target client: VoidT F_ApiNotify(notification, docId, sparm, iparm); with the notification argument set to FA_Note_ClientCall, docId set to 0 (zero), sparm set to the name of the active document and iparm set to 0 (zero). In order for the target client to receive the notification sent to it by Miramo, it must be registered for use with FrameMaker or FrameMaker+SGML, and must have requested the FA_Note_ClientCall notification by incorporating the following code: F_ApiNotification(FA_Note_ClientCall, True); The process of registering an API client is outlined below, and is described in detail in the FDK Platform Guide distributed with the FDK. Additional information may be passed to the API client via environment variables, accessed using the standard C library function ‘getenv()’. An example of this is given in the sample code below. If the ‘myapi’ program uses F_ApiReturnValue() to return anything other than FE_Success (0), Miramo reports the error code to stderr (Unix) or the Frame console win- dow (Windows NT). Writing a custom API client The process of setting up and using a customized Frame API client with Miramo is as fol- lows: 1 Create a new API client based on the sample code given on page R-539. This code must incorporate the Frame Developer Kit (FDK) functions F_ApiNotification(), F_ApiNotify() and F_ApiReturnValue(). 2 Compile the API client as described in the FDK platform guide. 3 Register the custom API client for use with FrameMaker. Miramo Reference Guide [ v 9.2 ] R-537 Running API clients APPENDIX 3: This is done by editing the ‘apiclients’ file (Unix) or the ‘maker.ini’ or ‘fmsgml.ini’ file (Windows NT). IMPORTANT: the entry for the custom API client must be located before that for the standard Miramo API client, ‘mmapi’, otherwise Miramo will not be able to invoke the custom API client, and will issue a warning message. 4 Set any environment variables used by your API client The sample API client myapi uses the MMUSERAPI_PARAM environment variable if it is set. 5 Run Miramo with the ‘-userapi’ command line flag Sample API client - myapi The source code for a sample Frame API client called ‘myapi’ is included on page R-539. It may be invoked using the Miramo ‘-userapi myapi’ command line option. myapi adds a new paragraph to the beginning of the Miramo document. The contents of the paragraph are either: This paragraph created by myapi or are taken from the value of the MMUSERAPI_PARAM environment variable if it is available. Registering myapi [Unix] This is an extract from an apiclients file which has been modified as described in the sec- tion Maintaining the ‘apiclients’ file [Solaris] on page R-7 in the Miramo Reference Guide, and also registers the myapi API client once it has been successfully compiled: In the above the environment variable ${MM_HOME} is set to the Miramo installation directory. Registering myapi [Windows NT] Below is an extract from the [APIclients] section of the ‘maker.ini’ or ‘fmsgml.ini’ (FrameMaker+SGML) file, showing possible modifications made to register both myapi and the standard Miramo api client ‘mmapi’: R-538 Miramo Reference Guide [ v 9.2 ] APPENDIX 3: Running API clients myapi=Standard,Custom api client,C:\installdir\bin\myapi.dll mmapi=Standard,Miramo api,C:\installdir\bin\mmapi.dll In the above lines, installdir will be replaced by the name of the installation folder selected or created during the setup process. This assumes that myapi.dll has been compiled and copied to the Miramo bin folder. Running Miramo with the -userapi flag The following command line will ensure that Miramo invokes the custom API client ‘myapi’ immediately before printing the document described by ‘inputfile’: miramo -P -userapi myapi inputfile myapi - source listing Below is the source code for the ‘myapi’ custom API client. This source code is also included on the Miramo distribution CD. (Its location is shown in Figure 2.1, on page R- 3 of the Miramo Reference Guide.) /*------* myapi: Miramo user API sample * * This is a sample Frame API client called `myapi' which may * be invoked using the Miramo `-userapi myapi' command line option. * ------*/ #include Miramo Reference Guide [ v 9.2 ] R-539 Running API clients APPENDIX 3: } /* ------No need to change any of the code below */ /*------* F_ApiInitialize() * ------*/ VoidT F_ApiInitialize(IntT init) { /*------* Set notification for FA_Note_ClientCall * ------*/ F_ApiNotification(FA_Note_ClientCall, True); } /* ------* F_ApiNotify()respond to FA_Note_ClientCall notification * When called by Miramo, sparm is set to document file name. * ------*/ VoidT F_ApiNotify(IntT notification, F_ObjHandleT docId, StringT sparm, IntT iparm) { IntT res=FE_Success; switch (notification) { case FA_Note_ClientCall: res=mmUserApi(docId, sparm); F_ApiReturnValue(res); break; default: break; } } R-540 Miramo Reference Guide [ v 9.2 ] APPENDIX 4 List of inline markup codes and options Miramo User and Reference Guide [ v 9.2 ] R-541 List of inline markup codes and options APPENDIX 4 Miramo User and Reference Guide [ v 9.2 ] R-542 APPENDIX 4 List of inline markup codes and options Miramo User and Reference Guide [ v 9.2 ] R-543 List of inline markup codes and options APPENDIX 4 Miramo User and Reference Guide [ v 9.2 ] R-544 APPENDIX 4 List of inline markup codes and options Miramo User and Reference Guide [ v 9.2 ] R-545 List of inline markup codes and options APPENDIX 4 Miramo User and Reference Guide [ v 9.2 ] R-546 APPENDIX 4 List of inline markup codes and options code options ] space spaceAfter Y | N R-132 Reference pre-defined font format fmt fontFormat name R-137 Font selection ff fontFamily name R-137 fa fontAngle name R-137 fw fontWeight name R-138 fv fontVariation name R-138 Text size and color p textSize dim | rdim R-138 fcolor textColor name R-138 Underline and overline uline textUnderline N | S | D | M R-138 o textOverline N | Y R-139 Strike through and change bar t strikeThrough N | Y R-139 C changeBar N | Y R-139 Capitalization fc textCase T | S | L | U R-139 Vertical and horizontal shift u superscript N | Y R-139 d subscript N | Y R-139 Ky vertShift percent R-140 Kx horizShift percent R-140 Kerning, character spread and stretch K textKern Y | N R-141 Ks textSpread percent R-141 fs textStretch percent R-141 textBGColor textBGColor name R-141 Text language lang textLanguage key R-142 Miramo User and Reference Guide [ v 9.2 ] R-547 List of inline markup codes and options APPENDIX 4 (Continued) Frame dimensions W frameWidth dim R-145 H frameHeight dim R-145 Frame offset (relative to enclosing graphic object) T frameTop dim R-145 L frameLeft dim R-145 Frame border and fill styles pen penNum 0 - 15 R-145 pw penWidth dim R-146 fill fillNum 0 - 15 R-146 pstyle penStyle P | "dim dim ..." R-146 Frame border and fill color color color name R-146 Metadata for graphic object (Frame) GOid GOid string R-146 Miramo User and Reference Guide [ v 9.2 ] R-548 APPENDIX 4 List of inline markup codes and options Miramo User and Reference Guide [ v 9.2 ] R-549 List of inline markup codes and options APPENDIX 4 Miramo User and Reference Guide [ v 9.2 ] R-550 APPENDIX 4 List of inline markup codes and options Miramo User and Reference Guide [ v 9.2 ] R-551 List of inline markup codes and options APPENDIX 4 Miramo User and Reference Guide [ v 9.2 ] R-552 APPENDIX 4 List of inline markup codes and options Miramo User and Reference Guide [ v 9.2 ] R-553 List of inline markup codes and options APPENDIX 4 Reference pre-defined paragraph format fmt pgfFormat name R-220 Basic options A justify L | R | LR | C R-220 fi firstIndent dim R-220 Miramo User and Reference Guide [ v 9.2 ] R-554 APPENDIX 4 List of inline markup codes and options (Continued) li leftIndent dim R-220 ri rightIndent dim R-221 sa spaceAbove dim R-221 sb spaceBelow dim R-221 un pgfUseNext N | Y R-221 np pgfNext name R-221 Interline leading and line spacing mode l leading dim R-221 ls lineSpacing F | P R-221 Paragraph feathering FF featherFactor int R-221 Reference pre-defined font format F fontFormat name R-221 Font selection ff fontFamily name R-222 fa fontAngle name R-222 fw fontWeight name R-222 fv fontVariation name R-222 Text size and color p textSize dim | rdim R-222 fcolor textColor name R-222 Underline and overline uline textUnderline N | S | D | M R-222 o textOverline N | Y R-222 Strike through and change bar t strikeThrough N | Y R-222 C changeBar N | Y R-222 Capitalization fc textCase T | S | L | U R-223 Vertical and horizontal shift u superscript N | Y R-223 d subscript N | Y R-223 Ky vertShift percent R-223 Kx horizShift percent R-223 Kerning, character spread and stretch K textKern Y | N R-223 Ks textSpread percent R-223 fs textStretch percent R-223 textBGColor textBGColor name R-223 Text language lang textLanguage key R-223 Letter and inter-word spacing cspace letterSpacing N | Y R-224 gws maxInterWord percent R-224 ows optInterWord percent R-224 lws minInterWord percent R-224 Autonumbering an autoNumber N | Y R-224 Paragraph page or column placement P pgfPosition A | C | P | L | R R-224 TCN nextColNum int | int(warn) R-225 Miramo User and Reference Guide [ v 9.2 ] R-555 List of inline markup codes and options APPENDIX 4 (Continued) Run-in, in-column, side head or straddle Pf alignFormat N | R | T | F | L | S | SN R-225 rhp endRunInChar char R-225 Widow/orphan lines wo minLines int R-226 Keep with next or previous paragraph wn withNext N | Y R-226 wp withPrevious N | Y R-226 Reference frames above and below ts pgfFrameAbove name R-226 bs pgfFrameBelow name R-226 Hyphenation H hyphenate Y | N R-226 Hml maxHyphens int R-226 Hmp minBeforeHyphen int R-226 Hms minAfterHyphen int R-226 Hmw minWordSize int R-226 Newline processing (output) nl newLines N | R | RX R-227 Printing PSF printFeature 0 - 99 | 0 - 99+ | 0 - 99 R-227 Metadata IDstring IDstring string R-227 Miramo User and Reference Guide [ v 9.2 ] R-556 APPENDIX 4 List of inline markup codes and options Miramo User and Reference Guide [ v 9.2 ] R-557 List of inline markup codes and options APPENDIX 4 Miramo User and Reference Guide [ v 9.2 ] R-558 APPENDIX 4 List of inline markup codes and options code options ] code options ] Table title location options TP titlePosition A | B R-279 Tgap titleGap dim R-279 Template type file tplFile filename R-281 Extraction formats p pgfCatalog Y | N R-281 f fontCatalog Y | N R-281 Miramo User and Reference Guide [ v 9.2 ] R-559 List of inline markup codes and options APPENDIX 4 (Continued) k colorCatalog Y | N R-281 l pageCatalog Y | N R-282 d docSettings1 Y | N R-282 L docSettings2 Y | N R-282 R referencePages Y | N R-282 v varDefs Y | N R-282 x xrefFormats Y | N R-282 t tblCatalog Y | N R-282 r rulingCatalog Y | N R-282 c conditionCatalog Y | N R-282 Miramo User and Reference Guide [ v 9.2 ] R-560 APPENDIX 5 List of format definition markup codes and options Miramo User and Reference Guide [ v 9.2 ] R-561 List of format definition markup codes and options APPENDIX 5 Miramo User and Reference Guide [ v 9.2 ] R-562 APPENDIX 5 List of format definition markup codes and options Miramo User and Reference Guide [ v 9.2 ] R-563 List of format definition markup codes and options APPENDIX 5 Miramo User and Reference Guide [ v 9.2 ] R-564 APPENDIX 5 List of format definition markup codes and options Miramo User and Reference Guide [ v 9.2 ] R-565 List of format definition markup codes and options APPENDIX 5 Miramo User and Reference Guide [ v 9.2 ] R-566 APPENDIX 5 List of format definition markup codes and options Miramo User and Reference Guide [ v 9.2 ] R-567 List of format definition markup codes and options APPENDIX 5 Miramo User and Reference Guide [ v 9.2 ] R-568 APPENDIX 5 List of format definition markup codes and options Miramo User and Reference Guide [ v 9.2 ] R-569 List of format definition markup codes and options APPENDIX 5 Miramo User and Reference Guide [ v 9.2 ] R-570 General Index Specials in in Miramo Guides [ v 9.2 ] U-R-CH-571 General Index in in in in in R-220–R-230 in Miramo Guides [ v 9.2 ] U-R-CH-572 General Index Miramo Guides [ v 9.2 ] U-R-CH-573 General Index R-218, R-291, R-510, R-512, MD-13, MD-16, @atan, in mmpp R-488 MD-20, MD-21, MD-25, MD-28, MD-33, in example MD-13 Miramo Guides [ v 9.2 ] U-R-CH-574 General Index CG-115, CG-118, CG-123, CG-131, CG-146 <$chapnum> U-71 cell <$pagenum> U-71 (no) feathering in U-62 <$volnum> U-71 anchored frames in U-13 Miramo Guides [ v 9.2 ] U-R-CH-575 General Index CG-119 -Blastpage R-10 separation, examples R-532 -Pskipblanks R-18 , view, setting R-327 R-328 -Pstartno R-17 color gradient R-151 -Pstartpage R-17 Miramo Guides [ v 9.2 ] U-R-CH-576 General Index -Xparam R-6 in example U-92, R-128 -xvfb R-7 using U-91–U-92 -Xxsl R-6 DTD Miramo Guides [ v 9.2 ] U-R-CH-577 General Index discarding command errors font metrics U-60 R-245 font tag R-221, R-360 Excel, Microsoft and OLE R-186 FontBBox U-60 exit codes miramo R-23 in example R-340, R-345, R-346, R-419 mmpp R-465 Miramo Guides [ v 9.2 ] U-R-CH-578 General Index PICT U-45 importing documents PNG U-38 ASCII text R-195 raster (Sun) U-38, U-40–U-42 FrameMaker documents R-191–R-194 TIFF U-39, U-44 ISO Latin1 text R-195 xwd U-39, U-40–U-44 MIF files R-191–R-194 graphics MS Word files R-191–R-194 above/below every paragraph R-226, R-362 importing graphics borders around R-183 BMP U-37 importing R-159–R-160, R-180–R-190 BoundingBox (in EPS) U-46–U-48 importing from Frame documents R-56–R-61 by copying into document R-159, R-180 rotation of R-183 by reference to external file R-159, R-180 Group 3 fax, image file format U-44 CGM U-37, R-420 , – , – , – Group 4 fax, image file format U-39, U-44 EPS U-37 U-44 U-48 R-159 R-160 R-180 R-190 H from Frame documents R-56–R-61, R-226, -h, command line option R-5 R-362 GIF U-38 hair space Group 3 fax U-44 including in text R-43 Group 4 fax U-39, U-44 hard return JFIF U-38 default setting at input line ends R-227 JPEG U-38 including within text R-42 MacPaint files U-38, U-40–U-44, R-159–R-160, @hex2bin, in mmpp R-499 R-180–R-190 @hex2dec, in mmpp R-499 PCX U-38, U-40–U-44 PCX files R-159–R-160, R-180–R-190 hexadecimal from decimal, in mmpp R-499 – PICT U-45 HiResBoundingBox U-46 U-48 PNG U-38 HTML R-495 raster (Sun) U-38, U-40–U-42 Doc code option R-114 TIFF U-39, U-44 MiramoXML code option R-450 TIFF files R-159–R-160, R-180–R-190 -Ohtml command line option R-11 xwd U-39, U-40–U-44 on master page R-353 joboptions Image cacheing R-9 PDF R-32 , , , , image caching R-9 R-99 R-122 R-168 R-458 JPEG, image file format U-38, R-187, CG-66, @image( ) mmpp function CG-110, CG-115, CG-118, CG-123, CG-131, examples U-48–U-52 CG-146 , imageCache, Miramo Guides [ v 9.2 ] U-R-CH-579 General Index text R-142, R-176, R-223, R-339, MD-8, MD-47 IDstring R-73 LC_ALL, environment variable R-487 -Mfile, command line option U-29, R-6, R-284, LC_NUMERIC, environment variable R-487 R-463, R-464 leading, space between lines R-221, R-360 -Mhelp, command line option R-5 letter spacing U-59–U-60, R-224, R-360 Microsoft Excel and OLE R-186 line spacing R-221, R-360 Microsoft Visio and OLE R-186 line spacing in paragraph text Microsoft Word and OLE R-186 fixed, ls=F R-221, R-360 MIF , floating, ls=P R-221 R-360 importing R-191–R-194 , leading, ls=l R-221 R-360 printing MIF files R-30 listing, source code R-284 LZW compression, in TIFF files U-44 minimum page width R-319 – M MinionPro CH-52 CH-69 -M, command line option U-29, R-5, R-463, R-464 miramo -m, command line option R-284 exit codes R-23 calling macros within macros R-470 MM_ICU_DATA_DIR, environment variable R-29 comments in R-465 MM_MAKERNAME, environment variable R-23 defining R-467–R-472 MM_PDF_PREFS, environment variable R-22 – defining variables in R-465 R-466 mmConnect MS-19–MS-30 expansion and evaluation R-474 Miramo Guides [ v 9.2 ] U-R-CH-580 General Index in regular expressions R-481 in TIFF files U-44 stripping from input R-8, R-98, R-122, R-168, -PAfile, command line option R-19 R-457 page size R-347–R-351 -Omif, command line option R-11 body pages U-81 double-sided U-81, U-83, U-84 -Opdf, command line option R-12 empty pages U-82 -Opdfx, command line option R-13 filler U-87, U-91 operating system forcing page breaks U-86 checking in mmpp R-467 Paintbrush, PC paint program U-38, U-40 OR boolean operator, in mmpp R-488 Pantone colors , orphans R-226 R-361 example R-532 -Ortf, command line option R-11 R-37, R-220–R-230 graphics above or below R-226, R-362 in example U-3, U-4, U-6, U-8, U-9, U-10, hyphenation in R-226, R-362 U-12, U-16, U-18, U-20, U-24, U-27, U-30, indentation R-220, R-359 U-35, U-48, U-49, U-51, U-52, U-54, U-55, justification in R-220, R-359 U-57, U-58, U-66, U-72, U-74, U-78, U-80, keeping with next R-226, R-361 U-84, U-85, U-86, U-89, U-90, U-91, U-92, keeping with previous R-226, R-362 R-31, R-32, R-37, R-38, R-51, R-52, R-67, leading (l) R-221, R-360 R-68, R-69, R-76, R-77, R-80, R-86, R-87, left indent (li) R-220, R-359 R-102, R-103, R-109, R-130, R-133, R-134, line spacing (fixed, ls=F) R-221, R-360 R-135, R-144, R-156, R-157, R-178, R-189, line spacing (l) R-221, R-360 R-194, R-205, R-206, R-207, R-208, R-228, line spacing (leading, l) R-221, R-360 R-229, R-230, R-244, R-250, R-274, R-277, line spacing in U-63–U-64 R-284, R-285, R-289, R-290, R-291, R-295, newlines R-227 R-297, R-306, R-317, R-346, R-350, R-355, next paragraph (np, un) R-221, R-359 R-380, R-381, R-413, R-416, R-417, R-418, numbering R-224, R-361 R-419, R-509, R-510, R-511, R-512, R-514, orphan lines in R-226, R-361 R-533, R-535, R-536, MD-44 placement (P) R-224, R-361 examples U-57–U-60 right indent (ri) R-221, R-359 -P, command line option R-4, R-16 rules above or below R-226, R-362 PackBits compression U-38 run-in (Pf=R) R-225, R-361 Miramo Guides [ v 9.2 ] U-R-CH-581 General Index side heads (Pf=T,F,L) R-225, R-361 -PDFtagged, command line option R-15 space above (sa) R-221, R-359 -PDFthread, command line option R-15 , space below (sb) R-221 R-359 -PDFview, command line option R-15 space between U-62–U-63 pen straddle (Pf=S) R-225, R-361 shadings and patterns R-531 top of column (TCN=int) R-225 widow lines in R-226, R-361 -Pendno, command line option R-17 word spacing U-58–U-59, R-224, R-360 -Pendpage, command line option R-17 in in example R-135 PICT, image file format U-45 Doc code option R-114 -PDFhelp, command line option R-5 separations R-31 to PostScript files R-16 -PDFmode, command line option R-14 command line option R-7 -PDFopenpage, command line option R-15 Miramo Guides [ v 9.2 ] U-R-CH-582 General Index proportional table column widths R-251, R-252 RunAs user -Pscale, command line option R-16, R-19 enable/disable logon MS-17 -Pseps, command line option R-18 running headers/footers -Pskipblanks, command line option R-18 dictionary style R-305 placement R-240 standard error, in mmpp R-464, R-494, R-528, row straddle R-464 in table cells U-24, U-28, R-85 standard input, in mmpp R-464 RTF standard output, in mmpp R-464, R-493, R-522, Doc code option R-113, R-114 MiramoXML code option R-449 R-527 -Ortf command line option R-11 straddle, column -Ortfj command line option R-11 in table cells U-24, U-28, R-84 Miramo Guides [ v 9.2 ] U-R-CH-583 General Index MD-47 in footnotes R-136 superscript (text) R-139, R-176, R-223, R-337, tabs MD-7, MD-46 including in output R-43 – , – , – SWF setting R-247 R-248 R-249 R-250 R-267 , , R-268 in PDF files R-14 R-115 R-455 , , , , – stripping from input U-8 R-8 R-98 R-121 Symbol CH-78 CH-80 , – R-168 R-457 SymbolStd CH-81 CH-84 I/O redirection R-245 usage summary R-527 anchored frame in (example) R-50 in example U-18, U-19, U-21, U-24, U-27, anchored frames in U-13 U-28, U-32, U-34, U-35, U-55, R-50, R-154, at top of column U-30–U-31 R-244, R-261, R-265, R-515 – basic markup rules for U-13 U-17 row height (min) R-240 Miramo Guides [ v 9.2 ] U-R-CH-584 General Index MD-47 in example R-109 spread, tracking U-59–U-60 underline text alignment double R-138, R-175, R-222, R-336, MD-6, in table cells U-18–U-20 MD-46 paragraph R-220, R-359 low R-138, R-175, R-222, R-336, MD-6, MD-46 Text encoding R-99, R-122, R-169, R-458 numeric R-138, R-175, R-222, R-336, MD-6, text encoding R-9 MD-46 , , , , , text frames single R-138 R-175 R-222 R-336 MD-6 , – , – MD-46 autoconnecting R-288 R-289 R-291 R-347 , Unicode R-29 R-351 R-400 R-406 background R-399 in example U-52, U-55, U-92, R-80, R-156, in example U-52 R-517 R-188, R-189, R-290, R-301, R-306, R-350, @ceil( ) R-354, R-355 in example R-489 R-517 on master page R-353 R-505, R-507, R-509, R-510, R-512, Tombo, registration marks R-17, R-117, R-450 R-513, R-514, MD-26, MD-27, MD-28, -Toverride, command line option R-20 MD-35, MD-36, MD-37, CG-13, CG-14, , -tplImode, command line option R-21 CG-15 CG-16 – , , <#define> R-518 tracking, in text U-59 U-60 R-224 R-360 , , , , , – in example U-27 U-85 R-104 R-465 transparency U-38 R-148 R-158 R-466, R-474, R-475, R-478, R-493, , , image alpha channel U-39 R-33 R-181 R-494 troff R-495 @elif( ) R-518 two-sided document U-57 in example U-52, R-490, R-491 -TXformats, command line option R-20 @elifnot( ) R-518 Type 1 fonts U-60 in example R-490 @else R-518 U in example U-23, U-49, U-51, U-52, , , , , , U3D R-465 R-467 R-490 R-491 R-496 R-505, R-507, MD-27, MD-37 in PDF files R-14, R-115, R-455 R-519 <@eof> UCS-2 conversion, in mmpp R-499 @eval( ) R-519 @ucs2_to_utf8, in mmpp R-499 in example U-26, U-51, R-125, R-469, Miramo Guides [ v 9.2 ] U-R-CH-585 General Index R-488, R-489, R-490, R-492, R-501, in example R-504, R-505, R-510 R-504, R-505, R-507, R-508, R-510, @rand( ) R-525 R-512, R-513, R-514, MD-26, MD-27, in example R-504 MD-28, MD-36, CG-14, CG-15, CG-16 <@readfile> R-525 @exp( ) R-519 in example R-495, R-496, R-497, R-498, <#fdefine> R-519 R-499, MD-27, MD-37 @filetype( ) R-519 <@resume> R-525 @floor( ) R-519 @round( ) R-526 in example R-489, CG-15 in example R-490 @for( ) R-519 @rtrim( ) R-528 in example U-23, U-28, R-469, R-476, @sin( ) R-526 R-492, R-494, R-504, R-505, R-512, in example MD-27 MD-27, MD-28, MD-36, CG-15, CG-16 @slice( ) R-526 @gsub( ) R-520 in example U-28, R-480, R-499 in example R-483, R-484, R-485, R-486, @sqrt( ) R-526 R-489 in example R-489 R-520 @hex2bin( ) @sub( ) R-526 in example R-500 R-520 in example R-483 @hex2dec( ) @substr( ) R-527 , in example R-499 R-500 in example R-479 @if( ) R-520 R-527 , , , , <@suspend> in example U-23 U-49 U-51 U-52 <@system> R-527 R-465, R-467, R-471, R-476, R-486, , , , , , , in example R-467 R-493 R-487 R-490 R-491 R-496 R-499 @tabx( ) R-527 R-507, R-508, MD-27, MD-28, MD-36, R-527 , , @tan( ) MD-37 CG-14 CG-15 @tolower( ) R-527 <#ifndef> , , , , in example R-466 in example R-125 R-476 R-489 R-490 R-527 , , @toupper( ) R-496 R-513 MD-26 , , <#ifndefine> R-521 in example R-466 R-479 R-486 @trim( ) R-528 @ifnot( ) R-520 , , , in example U-49 in example R-490 R-505 R-513 R-514 R-528 @image( ) R-521 @ucs2_to_utf8( ) , in example R-500 in example U-49 U-51 R-528 <@include> R-522 @utf8_to_ucs2( ) , , @while( ) R-528 in example U-23 U-85 MD-36 R-528 <@include_if> R-522 <@write> R-522 in example U-49, U-85, R-494, R-505, @isInt( ) , @isNum( ) R-522 MD-27 MD-37 R-529 @len( ) R-522 @xgetvals( ) , , , , , in example R-465, R-478, R-505, R-507, in example U-10 U-27 U-28 U-48 U-49 , , , U-50, U-51, R-501, R-504, R-505, R-507, MD-27 MD-36 MD-37 CG-15 , , , , , @log( ) R-522 R-510 R-512 R-513 MD-27 MD-28 , , , @log10( ) R-522 MD-35 MD-37 CG-14 CG-15 R-529 @ltrim( ) R-528 <@xmacro> , , , , , <@macro> R-523 in example U-10 U-27 U-28 U-48 U-49 , , , , , , in example U-23, U-26, U-28, U-52, U-85, U-50 U-51 R-125 R-501 R-502 R-504 , , , , , U-90, R-104, R-285, R-465, R-466, R-467, R-505 R-507 R-509 R-512 R-513 , , , , , R-468, R-469, R-470, R-471, R-472, R-514 MD-27 MD-28 MD-35 MD-36 , R-473, R-474, R-476, R-477, R-479, CG-13 CG-15 R-529 R-480, R-483, R-484, R-485, R-486, @xputvals( ) , , , , R-488, R-489, R-490, R-491, R-492, in example R-125 R-502 R-510 R-512 R-493, R-494, R-496, R-497, R-499, R-513 R-501, MD-26, MD-36 -userapi, command line option R-21 <@map> R-523 UTF-8 conversion, in mmpp R-499 in example R-477 @utf8_to_ucs2, in mmpp R-499 @match( ) R-523 in example R-491, R-507 V @matchcount( ) R-523 , -v, command line option R-5 in example R-483 R-491 @matchlen( ) R-523 -v, mmpp command line option R-464 @mifstr( ) R-524 R-293 @pdfpages( ) R-524 in example R-295 @print( ) R-524 Miramo Guides [ v 9.2 ] U-R-CH-586 General Index in example U-66, U-68, U-70, U-73, U-75, -Xparam, command line option R-6 R-101, R-104, R-295 in example R-76, R-358 fileBaseName(fileName) R-422 fileName(fileName) R-422 W fileSize(fileName) R-422 Webdings CH-103–CH-105 getImageStats(fileName) R-420 getPdfStats(fileName) R-421 whitespace imageAR() R-420 in macro definitions R-468 imageDPI() R-420 in mmpp variables R-466 imageErr() R-421 widows R-226, R-361 imageHeight() R-420 window imageSize() R-421 document R-327 imageType() R-421 Wingdings CH-89–CH-91 imageWidth() R-420 , , , pdfArtBoxH(pageNum) R-421 WMF, image file format CG-66 CG-110 CG-115 , , , pdfArtBoxL(pageNum) R-421 CG-118 CG-123 CG-131 CG-146 pdfArtBoxT(pageNum) R-421 Word files pdfArtBoxW(pageNum) R-421 importing R-191–R-194 pdfCropBoxH(pageNum) R-422 word spacing U-58–U-59, R-224, R-360 pdfCropBoxL(pageNum) R-422 Word, Microsoft and OLE R-186 pdfCropBoxT(pageNum) R-422 <@write> mmpp function pdfCropBoxW(pageNum) R-422 pdfErr() R-422 examples of R-494–R-495 pdfMediaBoxH(pageNum) R-422 usage summary R-528 pdfMediaBoxL(pageNum) R-422 X pdfMediaBoxT(pageNum) R-422 pdfMediaBoxW(pageNum) R-422 X macros pdfPages() R-421 – , – , examples R-501 R-515 MD-26 MD-29 setImageGGMopt(key) R-420 – MD-35 MD-38 processing instructions R-111, R-112, R-245, -X, command line option R-6 R-246 -Xctrans, command line option R-6 stylesheets R-416–R-417 -Xhelp, command line option R-5 using entity references R-417 XML U-11, U-53–U-56, R-1, R-6, R-12, R-27–R-29, -xvfb, command line option R-7 , – R-111–R-112, R-245–R-246, ??–R-346, R-415– xwd, image file format U-39 U-40 U-44 R-447, R-495 -Xxsl, command line option R-6 code R-415 processing instruction R-111– Z – R-112, R-415 ZapfDingbatsStd CH-85 CH-88 processing instruction R-245– R-246, R-415 declaration R-415 Doc code option R-114 DTD, for Miramo R-422–R-447 Miramo Guides [ v 9.2 ] U-R-CH-587 Notes Notes Miramo [ v 9.2 ] Notes Notes Miramo [ v 9.2 ] Notes Miramo [ v 9.2 ]
numeric underline switch off underline produces: single underline double underline numeric underline switch off underline Default:N
This text is shifted||rightwards | produces: This text is shifted||rightwards| (not) This text is shifted| |rightwards| If more text were to be added immediately after the input shown above, it would be placed immediately after the second red vertical bar, ‘|’, super-imposed on the last few letters of the second ‘rightwards’. For example |T|| the letters
|T| |the letters
(hard return). 2 In FrameMaker output documents each specific area marked active by the
(hard [ showIntext ] return) or its equivalents cannot be included. Default:Y > Building blocks
Inserts hard return in definition text.
Inserts hard return in definition text.
Goats
Inserts hard return in definition text.
Inserts hard return in definition text.
Inserts hard return in definition text.
Inserts hard return in definition text.
numeric underline switch off underline produces: single underline double underline numeric underline switch off underline Default:N
This text is shifted||rightwards | produces: This text is shifted||rightwards| (not) This text is shifted| |rightwards| If more text were to be added immediately after the input shown above, it would be placed immediately after the second red vertical bar, ‘|’, super-imposed on the last few letters of the second ‘rightwards’. For example |T|| the letters ‘|T|’ are shifted leftwards. They have a falsely small left indent. (not)
|T| |the letters ‘|T|’ are shifted leftwards. They have a falsely small left indent. produces: |T|| the letters ‘|T|’ are shifted leftwards. They have a falsely small left indent. (not) |T| |the letters ‘|T|’ are shifted leftwards. They have a falsely small left indent. Default:0
Replace AA with gold (gold). 3
Replace ¶, U+00A7, with ¶, U+00B6. 5 Replace §, U+00A7, with ¶, U+00B6.
Figure 4.4 Output from Example 4.12 6
2
Inserts hard return in definition text.
Inserts hard return in definition text.
Inserts hard return in definition text.
Inserts hard return in definition text.
' 9 <#def> text @gsub({<#text>}, { 10 }, {
11 }) 12 @--- Replace all instances of '
' newline which are 13 @--- immediately followed by
15
1st line of 2nd paragraph, preceded by 3 blank lines.
preceded by 3 blank lines. These are the third and
These are the third and fourth lines of 2nd paragraph. fourth lines of 2nd paragraph.
Another paragraph, comprising two lines only. lines only.
Figure 6.33 Output from Example 6.71 20
Size
($m)
21
Fund
Stars 22
in
C in example U-6, U-24, U-27, U-52, U-55, , , , , , , @ceil, arithmetic function, in mmpp R-489 R-139 R-140 R-244 R-336 R-338 R-344 R-83–R-88 , , , , , ,
R-75 R-79 R-197 R-201 R-294 R-303 vertical alignment of text in U-20, R-84, R-243, R-315, R-333, R-356, R-390, R-398, R-410 , , , , R-363