Next: , Previous: , Up: Usage Reference   [Contents]


7.13 Command-Line Referece

The syntax of the command-line version is the same on Linux and Windows25.

Note that the command line syntax below is a superset of the command-line options of the mscgen tool. This means that by renaming msc-gen to mscgen you can use Msc-generator’s extra features and rich language in every tool that is integrated with mscgen. These tools include Doxygen, Sphinx and Msctexen26. For more on the compatibility of the languages see Mscgen Backwards Compatibility.

Usage: msc-gen [OPTIONS] [infile]
       msc-gen --gui [OPTIONS] [infile]
       msc-gen --tei-mode -S <lang> [OPTIONS]
       msc-gen -l
       msc-gen --help
       msc-gen --version

Generic options:

--gui

In this mode msc-gen opens a GUI to work with charts. You can still specify an input file to open and/or certain options (such as -S for chart language.) See Command-line GUI for more details. This GUI does not support --utf16 input, only UTF-8.

--tei-mode

Using this option puts msc-generator into text editor integration mode. In this mode msc-gen can produce color syntax highlighting, quick error, text indent and hinting/autocomplete information. Input file(s) are read from standard input, output is written to standard output, thus no input or output filename can be specified and options -i and -o are invalid. Same with option -T option, but -S is mandatory. Option --tei-mode implies -q, as well. See Text Editor Integration for more details below.

-T type

Specifies the output file type, which maybe one of png, eps, pdf, svg, ismap, lmap, csh or emf (on Windows only). Default is png. Output type ismap generates an NCSA format ismap file contain link information, see Links. You can also specify lmap, which will not generate any graphics either, but a text file listing each label in the chart with their coordinates. This is useful if you want to assign tooltips of clickable regions. See Label Maps below for details. The output type csh is documented in Coloring Input Files.

-e

If the output type is PNG, specifying this option will embed the chart text into the PNG file as an iTXt chunk (uncompressed). In case of multiple pages (and multiple output files) all will have it embedded. Ignored with a warning if the output type is not PNG.

-o file

Write output to the named file. If omitted the input filename will be appended by the appropriate extension and used as output. If neither input nor output file is given, mscgen_out.{png,eps,pdf,svg,emf} will be used.

infile

The file from which to read input. If omitted or specified as -, input will be read from the standard input. You can optionall specify the -i switch before the input file name (for mscgen compatibility).

-S <lang>

Forces Msc-generator to interpret the input file as a specific type of chart. This overrides the guess from the filename extension. Use the primary extension of the chart type here. Current chart types are ’signalling’ for Signalling Charts and ’graph’ for Graphviz graphs.

--utf16

Forces the input file to be interpreted as UTF-16, even if it looks like UTF-8 or ASCII.

--utf8

Forces the input file to be interpreted as UTF-8, even if it does not look like it.

-p=[page size]

Full-page output. (PDF only now.) In this case the chart is drawn on fixed-size pages (following pagination) with one pixel equalling to 1/72 inches. If a chart page is larger than a physcal page it is simply cropped with a warning. Setting the scale with the -s option enables zooming. Page size can be set to ISO sizes from A0 to A6, and to US sizes, such as letter, legal, ledger and tabloid. Append a ‘p’ or an ‘l’ for portrait and landscape, respectively (except for ‘tabloid’ and ‘ledger’, which are by definition portrait and landscape, resp.). E.g., use ‘A4p’, ‘A2l’ or ‘letter_l’. Default is ‘A4p’.

-m{lrud}=‘margin

Useful only for full-page output, specifies the margin. A separate option is needed to specify the left, right, upwards and downwards margins, denoted by the second letter of the option. Margins are to be specified in inches (number only) or in centimeters, if appended with ’cm’ (no spaces). The default margin is half inches everywhere.

-va=<center|up|down>
-ha=<center|left|right>

Set the vertical and horizontal alignment within a page for full-page output.

-a[h]

Automatic pagination. Used only with full-page output. If specified, scale cannot be ‘auto’. Specifying -ah will insert a heading after automatically inserted page breaks.

-x=width

Specifies chart width (in pixels). Meant to be used for bitmaps (PNG), but works for all graphics output.

-y=height

Specifies chart height (in pixels). If only one of -x or -y is specified, the aspect ratio is kept. Meant to be used for bitmaps (PNG), but works for all graphics output.

-s=scale

Can be used to scale chart size up or down. Default is 1.0. Cannot be used together with any of -x or -y. Meant to be used for bitmaps (PNG) or full-page output (-p), but works for all graphics output. For full-page output, you can set scale to ‘width’ which results in the chart width being set to the page width, or ‘auto’, which scales such that all pages fits. For full-page output, you can specify multiple -s options, which makes msc-gen to try them in the order specified until one is found for which no pages need to be cropped. If none is such, the last one will be used and a warning will be given.

-F font

Use specified font. This must be a font name available in the local system, and overrides the MSCGEN_FONT environment variable if that is also set. See Fonts. Does not apply to graph charts.

-D design_file

Load file containing additional chart design definitions. You can have multiple of this option to load several design files, after the default ones. See Chart Designs for more info.

--nodesigns

If you specify this no design files will be loaded (no even the ones you specify with -D. This is useful to increase performance when you do not use them anyway.

--chart_option=value

Any chart option (see Chart Options) can be specified on the command line. These are overridden by options in the file. Do not use any space before or after the equal sign.

--chart_design

The design pattern of the chart can be specified on the command line (see Chart Designs). This will overridde any design specified in the file.

-Wno

No warnings displayed.

-TI

Additional Technical Info is printed about compilation.

-Pno

No progress indicator displayed.

-q

No progress indicator displayed and on success, the ‘Success.’ prompt is also elided.

-l

Display program licence and exit.

-h
--help

Display program help and exit.

--version

Display version information and exit.

Options specific to Signalling Charts:

--force-mscgen

Forces the chart to be interpreted in mscgen mode. Note that many Msc-generator attributes, commands and keywords are still recognized. This setting makes conflicting syntax be intrepreted as mscgen would do. Without this switch Msc-generator uses the mscgen mode only if the chart starts with the text msc {.

--prevent-mscgen

Prevents the chart to be interpreted in mscgen mode. Note that some mscgen attributes and symbols are still recognized. This setting makes conflicting syntax be intrepreted as Msc-generator would do. Without this switch Msc-generator uses the mscgen mode if the chart starts with the text msc {.

-Wno-mscgen

Disables warnings for deprecated constructs kept only for backwards compatibility with mscgen. Has no effect with –force-mscgen, in that case no such warnings are emitted.

--pedantic

When used, Msc-generator enforces stricter language interpretation. For signalling charts, it will generate a warning if an entity is not declared explicitly before its use. For graphs, Msc-generator will generate a warning for each use of directed edges in undirected graphs and vice versa (graphviz does not allow such mixing). When not specified, it is OK to mix directed and undirected edges in any kind of graph. For Block Diagrams, it prevents auto-generating an block when mentioned without a ‘box’ or similar keyword. This allows forward referencing blocks in arrow definitions (by avoiding their creation instead of referencing a later definition).


Footnotes

(25)

The only two exceptions are in how pathnames are written on the two systems and where the design libraries (e.g., designlib.signalling) will be searched.

(26)

This is thanks to the original mscgen author Michael McTernan and many others


Next: Fonts, Previous: Advanced OLE Considerations, Up: Usage Reference   [Contents]