TeX

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

de.dante.extex.main
Class TeX

java.lang.Object
  de.dante.extex.ExTeX
      de.dante.extex.main.TeX

public class TeX
extends ExTeX

This is the command line interface to ExTeX. It does all the horrible details necessary to interact with the user of the command line in nearly the same way as TeX does.

The command line interface provides the following features:

Specifying format, input file, and TeX code on the command line.
Interacting with the user to get an input file.
Interacting with the user in case on an error

ExTeX: Command Line Usage

This program is normally used through a wrapper which performs all necessary initializations and hides the implementation language from the casual user. Since this is the default case it is described here first. Details about the direct usage without the wrapper can be found in section Direct Java Invocation.

This program – called extex here – has in its simplest form of invocation one parameter. This parameter is the name of the file to process:

   extex file.tex

The input file is sought in the current directory and other locations. Details about searching can be found in Searching TeX Files.

In general the syntax of invocation is as follows:

   extex ⟨options⟩ ⟨file⟩ ⟨code⟩

Command line parameters are the way of setting options with highest priority. The command line parameters overrule all settings in other parameter files. The command line options are contained in the table below.

⟨code⟩

This parameter contains ExTeX code to be executed directly. The execution is performed after any code specified in an input file. on the command line the code has to start with a backslash. This restriction does not hold for the property settings.

Property: extex.code

⟨file⟩

This parameter contains the file to read from. A file name may not start with a backslash or an ampercent. It has no default.
Any arguments after the file name are treated as code to be executed when the file has been processed.

Property: extex.file

-- ⟨file⟩

This parameter contains the file to read from. A file name may start with any character since it is protected by the prefix --. The file name has no default.
Any arguments after the file name are treated as code to be executed when the file has been processed.

Property: extex.file

--⟨property⟩ ⟨value⟩

The properties mentioned throughout this description can be set directly. It is even possible to set a property with any name to a value. The name is not checked checked against a list. Thus it is possible to overwrite system and user settings.

For instance the properties user.name and java.version are used at some places, but can not by set on the command line by other means.

Example: The following invocations are identical:

      extex --extex.file=abc
      extex --extex.file abc
      extex -- abc
      extex abc

-configuration ⟨resource⟩ -configuration=⟨resource⟩

This parameter contains the name of the configuration resource to use. This configuration resource is sought on the class path.

Property: extex.config

-copyright

This command line option produces a copyright notice on the standard output stream and terminates the program afterwards.

&⟨format⟩

-fmt ⟨format⟩

This parameter contains the name of the format to read. An empty string denotes that no format should be read. This is the default.

Property: extex.format

-debug ⟨spec⟩ -debug=⟨spec⟩

This command line parameter can be used to instruct the program to produce debugging output of several kinds. The specification ⟨spec⟩ is interpreted left to right. Each character is interpreted according to the following table: Description

	Spec		See
`F`	This specifier contains the indicator whether or not to trace the searching for input files.	`extex.trace.input.files`
`f`	This specifier contains the indicator whether or not to trace the searching for font files.	`extex.trace.font.files`
`M`	This specifier contains the indicator whether or not to trace the execution of macros.	`extex.trace.macros`
`T`	This specifier contains the indicator whether or not to trace the work of the tokenizer.	`extex.trace.tokenizer`

-halt-on-error

This parameter contains the indicator whether the processing should halt after the first error has been encountered.

Property: extex.halt.on.error

-help

This command line option produces a short usage description on the standard output stream and terminates the program afterwards.

-ini

If set to true then the attempt to load a format with the name derived from the prog name is omitted.

Property: extex.ini

-interaction ⟨mode⟩ -interaction=⟨mode⟩

This parameter contains the interaction mode. Possible values are the numbers 0..3 and the symbolic names batchmode (0), nonstopmode (1), scrollmode (2), and errorstopmode (3). The symbolic names can be abbreviated up to at least one character.

Property: extex.interaction

-job-name ⟨name⟩ -job-name=⟨name⟩ -jobname ⟨name⟩ -jobname=⟨name⟩

This parameter contains the name of the job. It is overwritten if a file is given to read from. In this case the base name of the input file is used instead.

Property: extex.jobname

-language ⟨language⟩ -language=⟨language⟩

This parameter contains the name of the locale to be used for the messages.

Property: extex.lang

-output ⟨format⟩ -output=⟨format⟩

This parameter contains the output format. This logical name is resolved via the configuration. Reasonable values are dvi, ps, and pdf.

Property: extex.output

-output-directory ⟨directory⟩ -output-directory=⟨directory⟩ -texoutputs ⟨directory⟩ -texoutputs=⟨directory⟩

This parameter contains the output directory. The normal output files are tried to place there. If this fails a fallback is tried additionally.

Property: tex.output.dir

-parse-first-line

This parameter can be used to force the parsing of the first line of the input file.

Property: extex.parse.first.line

-progname ⟨name⟩ -progname=⟨name⟩

This parameter can be used to overrule the name of the program shown in the banner and the version information.

Property: extex.progname

-texinputs ⟨path⟩ -texinputs=⟨path⟩

This parameter contains the additional directories for searching ExTeX input files.

Property: extex.texinputs

-texmfoutputs ⟨dir⟩ -texmfoutputs=⟨dir⟩

This parameter contains the name of the property for the fallback if the output directory fails to be writable.

Property: tex.output.dir.fallback

-version

This command line parameter forces that the version information is written to standard output and the program is terminated.

Command line parameters can be abbreviated up to a unique prefix – and sometimes even more. Thus the following invocations are equivalent:

   extex -v
   extex -ve
   extex -ver
   extex -vers
   extex -versi
   extex -versio
   extex -version

First Line Parsing

The feature of first line parsing can be enabled with the command line option -parse-first-line and the property extex.parse.first.line.

If the feature is enabled then the first line of the first input file is parsed. If this line starts with %& then the next characters up to a white-space are taken as format name to be loaded. The remaining characters up to the newline characters are ignored.

The first line is simply passed to the interpreter if it does not start with %&.

The following sample shows a first line which pre-loads the format latex.

  %&latex some comment

Settings and Command Line Parameters

Settings can be stored in properties files. Those settings are the fallbacks if no corresponding command line arguments are found.

The properties are stored in a file named .extex. It is sought in the users home directory. This determined by the system property user.home. Afterwards it is sought in the current directory. The local settings of a directory overwrite the user's setting. The user's setting overwrite the compiled in defaults

The following properties are recognized:

extex.code: This parameter contains ExTeX code to be executed directly. The execution is performed after any code specified in an input file. on the command line the code has to start with a backslash. This restriction does not hold for the property settings.; Command line: ⟨code⟩
extex.color.converter: This parameter contains the name of the configuration resource to use for the color converter.; Default:
extex.config: This parameter contains the name of the configuration resource to use. This configuration resource is sought on the class path.; Command line: -configuration ⟨resource⟩; Default: extex.xml
extex.encoding: This parameter contains the name of the property for the standard encoding to use.; Default: ISO-8859-1
extex.error.handler: This parameter contains the logical name of the error handler.
extex.error.handler: This parameter contains the logical name of the error handler.
extex.fonts: This parameter contains the name of the property indicating where to find font files. The value is a path similar to extex.texinputs.
extex.halt.on.error: This parameter contains the name of the property indicating whether the processing should stop after the first error.; Command line: -halt-on-error
extex.file: This parameter contains the file to read from. It has no default; Command line: ⟨file⟩
extex.format: This parameter contains the name of the format to read. An empty string denotes that no format should be read. This is the default.; Command line: -fmt ⟨format⟩
extex.ini: If set to true then act as initex. This command line option is defined for compatibility to TeX only. In ExTeX it has no effect at all.; Command line: -ini
extex.interaction: This parameter contains the interaction mode. possible values are the numbers 0..3 and the symbolic names batchmode (0), nonstopmode (1), scrollmode (2), and errorstopmode (3).; Command line: -interaction ⟨mode⟩; Default: 3
extex.jobname: This parameter contains the name of the job. It is overwritten if a file is given to read from. In this case the base name of the input file is used instead.; Command line: -job-name ⟨name⟩
-jobname ⟨name⟩
-job-name=⟨name⟩
-jobname=⟨name⟩; Default: texput
extex.jobnameMaster: This parameter contains the name of the job to be used with high priority.; Default: texput
extex.lang: This parameter contains the name of the locale to be used for the messages.; Command line: -language ⟨language⟩
extex.nobanner: This parameter contains a boolean indicating that the banner should be suppressed.
extex.output: This parameter contains the output format. This logical name is resolved via the configuration.; Command line: -output ⟨format⟩; Default: pdf
tex.output.dir: This parameter contains the directory where output files should be created. If the directory fails to be writable then a fallback is tried instead.; Command line: -texoutputs ⟨dir⟩; Default: none
tex.output.dir.fallback: This parameter contains the name of the property for the fallback if the output directory fails to be writable.; Command line: -texmfoutputs ⟨dir⟩
extex.paper: This parameter contains the default size of the paper. It can be one of the symbolic names defined in paper/paper.xml. Otherwise the value is interpreted as a pair of width and height separated by a space.
extex.parse.first.line: This boolean parameter controls whether the first line of the input file should be parsed. If it is true and the first line starts with %& then the following characters up to a white-space character are taken as the name of a format to be loaded.
extex.progname: This parameter can be used to overrule the name of the program shown in the banner and the version information.; Command line: -progname; Default: ExTeX
extex.texinputs: This parameter contains the additional directories for searching TeX input files.; Command line: -texinputs ⟨path⟩
extex.token.stream: This string parameter contains the logical name of the configuration to use for the token stream.
extex.trace.input.files: This boolean parameter contains the indicator whether or not to trace the search for input files.
extex.trace.font.filess: This boolean parameter contains the indicator whether or not to trace the search for font files.
extex.trace.macros: This boolean parameter contains the indicator whether or not to trace the execution of macros.
extex.trace.tokenizer: This boolean parameter contains the indicator whether or not to trace the work of the tokenizer.
extex.typesetter: This parameter contains the name of the typesetter to use. If it is not set then the default from the configuration file is used.

There is another level of properties which is considered between the compiled in defaults and the user's Those are the system properties of the Java system. There system wide settings can be stored. Nevertheless, you should use this feature sparsely.

Direct Java Invocation

The direct invocation of the Java needs some settings to be preset. These settings are needed for ExTeX to run properly. The following premises are needed:

Java needs to be installed (see section Installation. The program java is assumed to be on the path of executables.
Java must be configured to find the jar files from the ExTeX distribution. This can be accomplished by setting the environment variable CLASSPATH or JAVA_HOME. See the documentation of your Java system for details.

Now ExTeX can be invoked with the same parameters described above:

   java de.dante.extex.ExTeX ⟨options⟩ ⟨file⟩

The result should be the same as the invocation of the wrapper.

Version:: $Revision: 1.33 $
Author:: Gerd Neugebauer, Michael Niedermair

Field Summary
`protected static int`	`EXIT_INTERNAL_ERROR` The constant `EXIT_INTERNAL_ERROR` contains the exit code for internal errors.
`protected static int`	`EXIT_OK` The constant `EXIT_OK` contains the exit code of the program for the success case.

Fields inherited from class de.dante.extex.ExTeX

PROP_BANNER, PROP_CODE, PROP_COLOR_CONVERTER, PROP_CONFIG, PROP_ENCODING, PROP_ERROR_HANDLER, PROP_FILE, PROP_FMT, PROP_HALT_ON_ERROR, PROP_INI, PROP_INTERACTION, PROP_INTERNAL_STACKTRACE, PROP_JOBNAME, PROP_JOBNAME_MASTER, PROP_LANG, PROP_NAME, PROP_NO_BANNER, PROP_OUTPUT_DIRS, PROP_OUTPUT_TYPE, PROP_PAGE, PROP_PROGNAME, PROP_TEXINPUTS, PROP_TOKEN_STREAM, PROP_TRACE_FONT_FILES, PROP_TRACE_INPUT_FILES, PROP_TRACE_MACROS, PROP_TRACE_TOKENIZER, PROP_TRACING_ONLINE, PROP_TYPESETTER_TYPE

Constructor Summary
`TeX(java.util.Properties theProperties, java.lang.String dotFile)` Creates a new object and initializes the properties from given properties and possibly from a user's properties in the file `.extex`.

Method Summary
`protected Localizer`	`getLocalizer()` Getter for localizer.
`QueryFileHandler`	`getQueryFileHandler()` Getter for queryFileHandler.
`protected boolean`	`initializeStreams(Interpreter interpreter, java.util.Properties properties)` Initialize the input streams.
`protected void`	`logPages(BackendDriver backend)` Write the indicator of the pages produced to the logger.
`static void`	`main(java.lang.String[] args)` This is the main method which is invoked to run the whole engine from the command line.
`protected BackendDriver`	`makeBackend(Configuration config, OutputStreamFactory outFactory, DocumentWriterOptions options, Configuration colorConfig, ResourceFinder finder, FontFactory fontFactory)` Create a new document writer.
`protected Interpreter`	`makeInterpreter(Configuration config, OutputStreamFactory outFactory, ResourceFinder finder, java.lang.String jobname)` Create a new interpreter.
`protected TokenStreamFactory`	`makeTokenStreamFactory(Configuration config, ResourceFinder finder)` Create a TokenStreamFactory.
`protected boolean`	`mergeProperties(java.lang.String arg)` Loads a properties file into the already existing properties.
`int`	`run(java.lang.String[] args)` This method provides access to the whole functionality of ExTeX on the command line.
`protected int`	`runCL(java.lang.String[] args)` Process the command line arguments.
`protected boolean`	`set(java.lang.String name, java.lang.String tag, java.lang.String[] arguments, int position)` Acquire the next argument from the command line and set a property accordingly.
`void`	`setQueryFileHandler(QueryFileHandler queryFileHandler)` Setter for queryFileHandler.
`protected void`	`useTrace(java.lang.String arg)` Acquire the next argument from the command line and use it as a specification to control the tracing features.

Methods inherited from class de.dante.extex.ExTeX

applyInteraction, applyLanguage, getBooleanProperty, getLogger, getOutStream, getProperties, getProperty, getVersion, loadFormat, loadUserProperties, logException, logInternalError, makeColorConverter, makeContext, makeDefaultFont, makeFontFactory, makeLanguageManager, makeLogFile, makeLogHandler, makeOutputFactory, makeResourceFinder, makeTokenFactory, makeTypesetter, propertyDefault, run, setErrorHandler, setLogger, setOutStream, setProperty, showBanner

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EXIT_INTERNAL_ERROR

protected static final int EXIT_INTERNAL_ERROR

The constant EXIT_INTERNAL_ERROR contains the exit code for internal errors.

See Also:: Constant Field Values

EXIT_OK

protected static final int EXIT_OK

The constant EXIT_OK contains the exit code of the program for the success case.

See Also:: Constant Field Values

Constructor Detail

TeX

public TeX(java.util.Properties theProperties,
           java.lang.String dotFile)
    throws InterpreterException,
           java.io.IOException

Creates a new object and initializes the properties from given properties and possibly from a user's properties in the file .extex. The user properties are loaded from the users home directory and the current directory.
Parameters:: theProperties - the properties to consider; dotFile - the name of the local configuration file. In the case that this value is null no user properties will be considered.
Throws:: InterpreterException - in case of an invalid interaction mode; java.io.IOException - in case of an IO Error during the reading of the properties file
See Also:: ExTeX.ExTeX(java.util.Properties, java.lang.String)

Method Detail

main

public static void main(java.lang.String[] args)

This is the main method which is invoked to run the whole engine from the command line. It creates a new ExTeX object and invokes run() on it.

The return value is used as the exit status.

The properties to be used are taken from the System.properties and the user's properties in the file .extex. The user properties are loaded both from the users home directory and the current directory. Finally the properties can be overwritten on the command line.

Parameters:: args - the list of command line arguments

getLocalizer

protected Localizer getLocalizer()

Getter for localizer.

Overrides:: getLocalizer in class ExTeX

Returns:: the localizer

getQueryFileHandler

public QueryFileHandler getQueryFileHandler()

Getter for queryFileHandler.

Returns:: the queryFileHandler

initializeStreams

protected boolean initializeStreams(Interpreter interpreter,
                                    java.util.Properties properties)
                             throws ConfigurationException

Initialize the input streams. If the property extex.file is set and not the empty string, (e.g. from the command line) then this value is used as file name to read from. If the property extex.code is set and not the empty string (e.g. from the command line) then this value is used as initial input after the input file has been processed. Finally, if everything before failed then read input from the stdin stream.

Overrides:: initializeStreams in class ExTeX

Parameters:: interpreter - the interpreter context; properties - the controlling properties
Returns:: true if the stream have not been initialized
Throws:: ConfigurationException - in case of a configuration error
See Also:: ExTeX.initializeStreams( de.dante.extex.interpreter.Interpreter, java.util.Properties)

makeInterpreter

protected Interpreter makeInterpreter(Configuration config,
                                      OutputStreamFactory outFactory,
                                      ResourceFinder finder,
                                      java.lang.String jobname)
                               throws ConfigurationException,
                                      GeneralException,
                                      FontException,
                                      java.io.IOException

Description copied from class: ExTeX

Create a new interpreter.

Overrides:: makeInterpreter in class ExTeX

Parameters:: config - the configuration object for the interpreter; outFactory - the factory for new output streams; finder - the resource finder; jobname - the job name
Returns:: the new interpreter
Throws:: java.io.IOException - in case of an IO error; FontException - in case of problems with the font itself; GeneralException - in case of an error of some other kind; ConfigurationException - in case that some kind of problems have been detected in the configuration
See Also:: ExTeX.makeInterpreter( de.dante.util.framework.configuration.Configuration, de.dante.extex.backend.outputStream.OutputStreamFactory, de.dante.util.resource.ResourceFinder, java.lang.String)

makeBackend

protected BackendDriver makeBackend(Configuration config,
                                    OutputStreamFactory outFactory,
                                    DocumentWriterOptions options,
                                    Configuration colorConfig,
                                    ResourceFinder finder,
                                    FontFactory fontFactory)
                             throws DocumentWriterException,
                                    ConfigurationException

Description copied from class: ExTeX

Create a new document writer.

Overrides:: makeBackend in class ExTeX

Parameters:: config - the configuration object for the document writer; outFactory - the output factory; options - the options to be passed to the document writer; colorConfig - the configuration for the color converter; finder - the resource finder if one is requested; fontFactory - the font factory
Returns:: the new document writer
Throws:: ConfigurationException - in case of a configuration problem; DocumentWriterException - in case of an error
See Also:: ExTeX.makeBackend( de.dante.util.framework.configuration.Configuration, de.dante.extex.backend.outputStream.OutputStreamFactory, de.dante.extex.backend.documentWriter.DocumentWriterOptions, de.dante.util.framework.configuration.Configuration, de.dante.util.resource.ResourceFinder, de.dante.extex.font.FontFactory)

makeTokenStreamFactory

protected TokenStreamFactory makeTokenStreamFactory(Configuration config,
                                                    ResourceFinder finder)
                                             throws ConfigurationException,
                                                    NotObservableException

Create a TokenStreamFactory. Implicitly the logger is used.

Overrides:: makeTokenStreamFactory in class ExTeX

Parameters:: config - the configuration object for the token stream factory; finder - the file finder for the token stream factory
Returns:: the token stream factory
Throws:: ConfigurationException - in case that some kind of problems have been detected in the configuration; NotObservableException - in case that the observer for file events could not be registered

logPages

protected void logPages(BackendDriver backend)

Write the indicator of the pages produced to the logger.

Overrides:: logPages in class ExTeX

Parameters:: backend - the back-end driver
See Also:: ExTeX.logPages(de.dante.extex.backend.BackendDriver)

mergeProperties

protected boolean mergeProperties(java.lang.String arg)
                           throws java.io.IOException

Loads a properties file into the already existing properties. The values from the file overwrite existing values.

Parameters:: arg - the name of the resource to load
Returns:: true iff the resource has been loaded successfully
Throws:: java.io.IOException - just in case

run

public int run(java.lang.String[] args)

This method provides access to the whole functionality of ExTeX on the command line. The exception is that this method does not call System.exit() but returns the exit status as result.

Parameters:: args - the list of command line arguments
Returns:: the exit status

runCL

protected int runCL(java.lang.String[] args)
             throws MainException,
                    java.io.IOException,
                    InteractionUnknownException

Process the command line arguments.

Parameters:: args - the command line arguments
Returns:: the exit code
Throws:: MainException - in case of an error; java.io.IOException - in case of an IO error; InteractionUnknownException - in case of an unknown interaction mode

set

protected boolean set(java.lang.String name,
                      java.lang.String tag,
                      java.lang.String[] arguments,
                      int position)
               throws MainMissingArgumentException

Acquire the next argument from the command line and set a property accordingly. If none is found then an exception is thrown.

Parameters:: name - the name of the argument; tag - the name of the property to set; arguments - the list of arguments; position - the starting index
Returns:: true iff the syntax is correct and the value of the property has been set
Throws:: MainMissingArgumentException - in case of an error

setQueryFileHandler

public void setQueryFileHandler(QueryFileHandler queryFileHandler)

Setter for queryFileHandler.

Parameters:: queryFileHandler - the queryFileHandler to set

useTrace

protected void useTrace(java.lang.String arg)
                 throws MainUnknownOptionException

Acquire the next argument from the command line and use it as a specification to control the tracing features. The appropriate properties are set accordingly.

Parameters:: arg - the argument
Throws:: MainUnknownOptionException - in case that the specified option letter has no assigned property to set