Running OmniMark<font size=3><sup>®</sup></font>

Using OmniMark V3

2. Running OmniMark

Previous chapter is Chapter 1, "About This Manual".

Next chapter is Chapter 3, "OmniMark Error Messages".

This chapter focuses on the command-line for running OmniMark, specifying input and output files, and selecting processing options.

2.1 Command-Line Basics

The command-line for running OmniMark has the form:

omnimark arg1 arg2 ...

Each argi is an argument. Except when more than one input document is specified, the order of arguments is immaterial. There are three forms of arguments:

A system-specific filename identifying the input file to be translated. Any number of these may be given. If none are given, the standard input is translated. If more than one file is given, they are each processed in the order they are specified on the command-line. In a down-translation, the concatenation of all these files is treated as a single SGML document.
A minus sign followed by a keyword. This type of argument is called a control argument. For example,
```
-warnings
```
A control argument followed by at least one space and then one or more user-specified values. For example,
```
-source to-tex.xom

-os toc document.toc
```

The possible arguments are itemized in Section 2.3, "OmniMark Command-Line Options".

2.2 Running an OmniMark Program

The command-line most frequently used for running OmniMark programs has the form:

omnimark input -source program -of output

where the arguments are:

input is the name of the file containing the input document.
program is the system-dependent name of the file containing the OmniMark program in source code form. It usually has the form name.xom.
output is the name of the file where the output is to be written to.

2.3 OmniMark Command-Line Options

This section lists the options for OmniMark. Arguments can appear in any order on the command-line. Options can be entered in any case, but file names may be entered in any case only if your particular file system is case-insensitive.

The only argument that is not preceded by a control argument is the name of each input file. If no input file is specified, the input is read from the standard input.

If the -source and -save control arguments are both specified, there is no input file to process. Note: For MS-Windows systems, the concepts of standard input and standard output are not supported unless OmniMark is run from an MS-DOS window. Wherever OmniMark expects some input, due to the other options in the command-line, an input file must be explicitly specified. The standard output must be bound to a file by specifying either the -of or -os output options. Also, if the -log option is not given in this situation, error messages are written to the file xgml.out. The location of this file will vary with your particular Windows configuration.

The other possible control arguments are listed below in alphabetical order:

-activate switch-name: activates the OmniMark switch named switch-name prior to running an OmniMark program. Any INITIAL specification for the specified switch is ignored.
-a switch-name: is an abbreviation of the -activate argument. It is useful when there is more than one activation required on the command-line.
-alog log-path: specifies that any error messages produced by OmniMark be written to the file given by log-path. The difference between this option and the -log option is that messages are written to the end of the file log-path if it already exists. If neither this argument nor the -log argument is specified, error messages are written to the program's standard output stream. On many computer systems, they appear on the user's screen.
-aof output: specifies output, the system-specific name of a file into which standard OmniMark output is written. The difference between this option and the -of option is that output is written to the end of the named file if it already exists.
-aos stream file: opens and associates the stream stream with the file file in the same manner as the -os argument, except that output is written to the end of the file if it already exists. This argument cannot be specified when the -source and -save options have both been specified.
-argsfile command-file-path: specifies that some of the contents of the command-line are in the arguments file given by command-file-path. When an -argsfile command-file-path option is encountered, the contents of command-file-path is immediately processed as if it appeared on the command-line. Multiple arguments files may be specified on a command-line, and arguments files can refer to other arguments files.
The percent sign (%) can be used to enter in a string characters such as the single quote ('), double quote ("), and the percent sign itself by placing a percent sign before them. This is often more easily done inside an arguments file than on the command-line because of the command processor's interpretation of characters such as quotation marks.
White space inside arguments files is used only to separate options and file names, so an arguments file can contain several lines of options. For example, the following two examples of arguments files, taken from a possible MS-Windows sample, are equivalent:
```
c:\proj1\omnimark\rtf\rtf2tex.xom -save
c:\proj1\omnimark\rtf\rtf2tex.csc
-brief -log c:\proj1\omnimark\rtf\rtf2tex.log
```
and
```
c:\proj1\omnimark\rtf\rtf2tex.xom
-save
c:\proj1\omnimark\rtf\rtf2tex.csc
-brief
-log
c:\proj1\omnimark\rtf\rtf2tex.log
```
This option is primarily of interest to users of systems with limited command-line lengths, such as MS-DOS and MS-Windows, but can be used on any platform. Commonly specified options can be placed in a single arguments file and accessed every time.
-brief: disables printing of the identification information that normally appears when OmniMark begins processing.
-counter counter-name value: sets the OmniMark counter named counter-name to value prior to running an OmniMark program. Any INITIAL specification for the specified counter is ignored.
-c counter-name value: is an abbreviation of the -counter argument.
-deactivate switch-name: deactivates the OmniMark switch named switch-name prior to running an OmniMark program. Any INITIAL specification for the specified switch is ignored.
-dea switch-name: is an abbreviation of the -deactivate argument.
-define stream-name content: specifies the stream stream-name which is to be opened as a buffer and have the contents specified by content placed in it, after which it will be closed. The effect of this argument is to have a buffer with a defined content when OmniMark starts processing. Each stream may be defined at most once.
This argument cannot be specified when the -source and -save options have both been specified.
-d stream-name content: is an abbreviation of the -define argument.
-expand: lists the OmniMark source program on the standard output or the -log file with comments deleted and macro calls expanded. This option is useful when developing OmniMark programs that use complex macros.
-f argsfile: an abbreviation of the -argsfile option.
-ftrace: Causes a trace of function calls and returns to be written to the #ERROR stream.
-haspauth: This authorizes the HASP.
-haspid: This gives the id of the HASP.
-help: causes OmniMark to display a list of its command-line options. If given, this display appears in the file named by the -log argument.
-herald: runs OmniMark in V2 compatibility mode. Declarations are optional (although if any are given, all must be given), shelf types must be given where required in V2, and if no translation-type is specified the program is a down-translation, not a V3 program.
-include include-path: specifies a directory in which to look for files to be included. If the file specified in an include declaration within the program cannot be opened, OmniMark looks for a file of the same name in directory include-path. There can be multiple occurrences of this argument on a command-line. OmniMark will inspect the directories in the order they occur on the command-line until a file of the specified name is found.
OmniMark processes include-path in a system-independent manner. To look in the include-path directory, OmniMark simply appends include-path to the front of the file name it is trying to include. This has two consequences:
1. include-path must have a trailing directory name separator as required by the running system.
2. OmniMark will not remove any directory name prefixes from a file name before appending include-path.
-i include-path: is an abbreviation of the -include argument. It is useful for shortening long commands that have multiple -include arguments.
-libpath libpath: specifies libpath, a system-specific directory name. This argument can only be used when running down-, up- and context-translations.
If the file specified as a system identifier in a library declaration cannot be opened, OmniMark looks for a file of the same name in directory libpath. There can be multiple occurrences of this argument on a command-line. OmniMark will inspect the directories in the order they occur on the command-line until a file of the specified name is found.
libpath is processed in the same manner as the argument of -include.
This argument cannot be specified when the -source and -save options have both been specified.
-l libpath: is an abbreviation of the -libpath argument. It is especially useful for shortening long command-lines that have multiple -libpath arguments.
This argument cannot be specified when the -source and -save options have both been specified.
-library library: specifies library, the system-dependent name of a file containing OmniMark library declarations and comments. It allows document-specific bindings of public identifiers to be processed without requiring modification of the OmniMark program. This facility allows OmniMark programs to be done on different systems with different organizations of files.
This argument cannot be specified when the -source and -save options have both been specified.
-limit number: specifies the maximum number of errors that may be reported before processing stops. By default, there is no limit. This option is an abbreviation for -threshold.
-linger number: specifies the number of seconds to hold onto the license after running the program. Used in shell scripts where OmniMark is called repeatedly.
-lmid: This gives the hostid of the license manager server.
-load saved-application: specifies that the saved OmniMark application is to be loaded from the system-specific file named saved-application. This option is not available with OmniMark LE.
-log output-file: is the system-specific name of a file to which any error messages produced by OmniMark are written. If this argument is not specified, error messages are written to the program's standard output. On many computer systems, they appear on the user's screen.
-nocount: turns off the message at the end of processing that gives the number of reported errors and warnings.
-noernum: suppresses SGML error code when SGML error and warning messages are displayed.
-nowait: avoids waiting for an available license.
-of output: specifies output, the system-specific name of a file into which standard OmniMark output is written. This argument is equivalent to -os OUTPUT output.
This argument cannot be specified when the -source and -save options have both been specified.
-os stream file: where stream is the name of an OmniMark stream and file is a system-dependent filename, causes OmniMark to open the specified stream to the indicated file. This argument has the same effect as the OmniMark action
```
open stream AS "file"
```
within the OmniMark program, but allows the filename to be specified by the end-user on the command-line.
More than one -os can appear on the command-line, binding more than one stream to a file.
This argument cannot be specified when the -source and -save options have both been specified.
-save saved-application: specifies that the saved OmniMark program is to be saved in the system-specific file named saved-application. This option is not available with OmniMark LE.
-source program: specifies that the OmniMark program is to be read from the file named program.
This argument cannot be specified when the -load option has been specified.
-s program: specifies that the OmniMark program is to be read from the file named program. This option is an abbreviation for -source.
This argument cannot be specified when the -load option has been specified.
-src program: an abbreviation for -source.
This argument cannot be specified when the -load option has been specified.
-submit submit: specifies submit, a system-specific directory name. If the file specified in a submit action cannot be opened, OmniMark looks for a file of the same name in directory submit. There can be multiple occurrences of this argument on a command-line. OmniMark will inspect the directories in the order they occur on the command-line until a file of the specified name is found.
submit is processed in the same manner as the argument of -include.
This argument cannot be specified when the -source and -save options have both been specified.
-temp temp: specifies temp, the system-specific name of the first temporary file OmniMark used by OmniMark for referent processing. If this argument is not specified and a temporary file is required, the first temporary file used by OmniMark is named xgml001.tmp which is created by OmniMark and deleted after use.
This argument cannot be specified when the -source and -save options have both been specified.
-temppfx temppfx: specifies temppfx, a prefix used by OmniMark to create temporary files. For example, if tmppfx is set to "/tmp/", OmniMark will use the prefix to create temporary files with absolute paths as follows: tmp/xgml001.tmp, /tmp/xgml002.tmp ... If this option is not specified, OmniMark uses the directory where it is running to create the temporary. tmppfx specifies a prefix as apposed to a path.
In fact, setting temppfx to "/tmp" will cause OmniMark to create the following temprorary files: tmpxgml001.tmp, /tmpxgml002.tmp, ... This might cause problems if you do not have write permissions in the "/" directory.
Temporary files are only required when referents are used. For this reason, tmppfx is ignored when no referents are used in the omnimark program. temp and temppfx may not be used at the same time. Also, tmppfx cannot be specified when the -source and -save options have both been specified.
-term: causes the OmniMark program to be read from standard input. An explicit input file or the -save option must be given when this option is specified.
-threshold: gives the maximum number of errors that may be reported before processing stops. By default, there is no limit.
-version: writes out the banner with copyright, date, and version information to the standard error, and then halts.
-warning: enables the display of informative messages that are normally suppressed.

2.4 When to Use the `save` and `load` Options

You may find yourself in a position where you would like to make your OmniMark program available for others to use, but you would like to retain control and ownership of the source code. One method is to provide your users with the OmniMark program as a saved application rather than as a readable program.

The way to do this is by running the command-line:

omnimark -source program -save saved-application

You may then provide OmniMark users with a copy of the saved application and some instructions on how to run it. At a minimum, these instructions will tell them to run the command-line:

omnimark input-file -load saved-application other-options...

Note that the saved-application file is binary. You may not be able to transmit it by some electronic mail systems.

Also, OmniMark LE does not support the save and load options.