The Gloss command line

1 Usual Operation

The main command is gloss, provided as shell script and batch file. This simply calls uk.ac.bham.gloss.Gloss. The normal use is "gloss FILE.EXT.gloss" which performs the following operations. (Here, words in capital letters are not literals should be replaced with myfile or html or whatever.)

It reads mv EXT.mv from the input file's directory or from http://gloss.bham.ac.uk/lib/EXT.mv and glosses the input file with this, producing an in-memory representation of an XML filem FILE.EXT.xr.
If EXT.xsl is found in the same location as where EXT.mv was, it uses this to transform FILE.EXT.xr.
The output is printed as FILE.EXT to the same directory.
If http://gloss.bham.ac.uk/lib/EXT.mv was used then any additional files in http://gloss.bham.ac.uk/lib/EXT/* listed in http://gloss.bham.ac.uk/lib/EXT/list such as css, javascript, images or other required files, are copied to the same directory (unless they already exist there!)

In the case of xhtml and html files, this should generate elegant and standards-conforming (x)html ready to upload to a web server. The additional files such as any css files may be edited for further configuration.

2 Filename and file-extension conventions

It is often useful to have a number of different mv's all producing (say) html and all operating on files in the same directory. For this reason, the convention is to name files using the "." and "-" characters as follows.

As just described, FILE.EXT.gloss is converted to FILE.EXT using the copy of EXT.MV that is "nearest" to the source file, and possibly copying files from http://gloss.bham.ac.uk/lib/EXT/*.

For alternative versions, FILE.VER-EXT.gloss is converted to FILE.EXT (dropping the version part "VER") using the copy of VER-EXT.mv that is "nearest" to the source file, and if this is a library mv, possibly also copying files from http://gloss.bham.ac.uk/lib/VER-EXT/*.

This may sound complicated, but adherence to these conventions will help greatly in helping you remember which input files generate which output.

3 Other options

The command gloss has a great number of other options which are described in more detail here.

-help: Print a summary of options.
-out FILE: Output to the named file. The file "-" denotes standard output.
-xrout FILE.xr: Output the intermediate xr file itself rather than the xml file it represents. This may be useful for development, or because several different transformations are to be performed on it, and to avoid repeating the time-consuming glossing phase.
-xrin FILE.xr: Skip the glossing phase and read in an XR file directly instead.
-xmlin FILE: Skip the glossing phase, and read in an arbitrary XML file which will be converted to XR format before any further processing is carried out.
-in FILE: Specify the main gloss input file. The -in is usually not needed, but this form may be useful if you want to perform a gloss process and the input file does not end with the extension ".gloss". The file "-" denotes standard input.
-mv FILE.mv: Specify the mv file to use rather than have it chosen automatically.
-xsl FILE.xsl: Specify the xsl file to use rather than have it chosen automatically.
-noxsl: Specify that no xsl transformation stage is to be performed. Useful to over-ride an automatically chosen xsl stage that might be done otherwise.
-dest DIR: Specify the destination directory of the output file. The actual directory used will combine this with any path part of the named output file (if any). This is normally used when the output file name is automatically generated.
-src DIR: Specify the "source" directory of the input file. This is useful to generate output on a directory tree that is independent of the source files. The source directory MUST be an initial part of the path to the input file. Any remaining path in the input file name will be used as offset in the destination. For example, with "-in my/file/to/be/used/as/input.html.gloss", "-src my/file", and "-dest another/place", the output file will be at "another/place/to/be/used/as/input.html". Any directories not already existing will be created. This works in MS-Windows too with \ in place or /.
-force: By default, gloss does nothing if all sources are older than existing files with the same names as the output files. To force execution use -force.
-silent: Normally gloss tells you what it is doing as it goes along. This option turns this off. It doesn't turn error-reporting off.
-traceOPTION: This is for debugging and analysis and provides a (very verbose) description of everything that gloss does. The exact format of this output is under review and is subject to change. OPTION may be one or more of several possibilities, including "input", "output", "modes", "parameters", "files", etc.
-log FILE: Send a log including any trace options to FILE.
-setPARAM=VALUE: Pass a parameter value to the gloss system. This enables you to configure gloss on the command line, depending on the mv being used.