\pdfminorversion5\pdfsuppressptexinfo15\pdfinfoomitdate1\pdfsuppresswarningpagegroup1
\input texinfo @c The above do not work if defined after this include
@tex
\pdftrailerid{}
@end tex
@include version.texi
@c %**start of header
@setfilename msc-gen.info
@dircategory Software development
@direntry
* Msc-generator: (msc-gen)	Draw various charts from texual description.
@end direntry
@settitle Msc-generator @value{VERSION}
@c %**end of header
@copying
This manual is for Msc-generator (version @value{VERSION}, @value{UPDATED}),
a tool to draw various charts from textual description. Msc-generator originally
supported signalling charts only, and now supports graphs, via graphviz, as well.
More chart types will be added in the future.

The signalling chart part heavily borrows in concept from the 0.08 version of
Michael C McTernan's mscgen. However, it has been completely rewritten from
scratch and has a much more extensive (and only partially backwards compatible)
language. The command-line interface is fully backwards compatible with
mscgen, which enables using Msc-generator's commandline tool everywhere
where you can use mscgen, but with the richer syntax. Since version 4.5 Msc-generator
also contains an @dfn{mscgen compatibility mode}, which aims to interpret mscgen
chart descriptions in a fully backwards compatible manner.
This includes the many tools integrated with mscgen, such as Doxygen, Sphinx and
Msctexen. See the official @uref{http://www.mcternan.me.uk/mscgen/, mscgen site}.


Since version 2.2 Msc-generator also contains a Windows GUI implementing
signalling charts as OLE embedded objects. This allows inclusion of both
chart source and the rendered graphics together in a Word or Powerpoint document.

Since version 5.0 Msc-generator supports graphs via graphviz, using the exact
DOT language with some addition, such as shadows, double lines and chart designs.

At version 6.0 a block diagram language is added. It allows you to formally
specify block alignment and containment.

Version 7.0 sports a Linux and MacOS GUI that can be started using
@code{msc-gen --gui}. This GUI also works on Windows, but does not allow
embedding charts into Word or PowerPoint documents. It is possible, however,
to embed the chart text into a PNG output file.

Version 8.0 introduced a new way of embedding charts into Office documents
while allowing editing them later.

Copyright @copyright{} 2008-2024 Zolt@'an Tur@'anyi

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the @uref{https://creativecommons.org/licenses/by-sa/4.0/, 
CC BY-SA 4.0} licence.
@end quotation
@end copying

@titlepage
@title Msc-generator
@subtitle A tool to draw various charts from text description
@subtitle (version @value{VERSION}, @value{UPDATED})

@author Zoltan R. Turanyi

@c Include the Distribution inside the titlepage so
@c that headings are turned off.

@end titlepage

@contents

@ifnotinfo
@chapter Introduction
@end ifnotinfo
@node Top
@ifinfo
@top Msc-generator
@end ifinfo
@iftex
@node dummy node (otherwise intro stays empty in PDF)
@end iftex

This manual is for Msc-generator (version @value{VERSION}, @value{UPDATED}),
a tool to draw various charts from a textual description.

Please visit @uref{https://gitlab.com/msc-generator/msc-generator/-/packages} to download the
latest version.

@menu
* What's new in Msc-generator 8.6::
* Getting Started::
* Signalling Chart Language Tutorial::
* Graph Language Tutorial::
* Block Diagram Language Tutorial::
* Usage Reference::
* Reference for Common Language Elements::
* Signalling Chart Language Reference::
* Graph Language Reference::
* Block Diagram Language Reference::
@end menu

Msc-generator is a program that parses textual chart descriptions
and produces graphical output in a variety of file formats, or can
embed charts in documents, such as Word or PowerPoint.
It currently supports three kinds of charts: Message Sequence Charts
(MSCs, this is where the name of the tool comes from); general graphs
in the DOT language of graphviz; and experimental Block Diagrams.

Message Sequence Charts are a way of
representing entities and message interactions between those entities over
some time period. MSCs are often used in combination with SDL.
MSCs are popular in telecom and data networks and standards to specify how
protocols operate. MSCs need not be complicated to create or use.
Msc-generator aims to provide a simple text language that is clear to create,
edit and understand, and which can be transformed into images.
Msc-generator is a potential alternative to mouse-based editing tools, such as
Microsoft Visio.

The signalling chart part of msc-generator is heavily extended and completely
rewritten version of the 0.08 version of Michael C McTernan's mscgen.
The original tool was more geared towards describing interprocess
communication, this version is more geared towards networking.
Msc-generator  has a number of enhancements compared to mscgen.
The command-line syntax of Msc-generator is
compatible to that of mscgen, so any tool integrated with mscgen (such as
Doxygen) can also be used with Msc-generator. Since version 4.5 Msc-generator
also contains an @dfn{mscgen compatibility mode}, which aims to interpret mscgen
chart descriptions in a fully backwards compatible manner. See
@ref{Mscgen Backwards Compatibility}.

The graph part of msc-generator uses the graphviz library to lay out graphs.
It uses the DOT language to describe charts, with a few extensions.

Block Diagrams use a language similar in logic to the above two. The language
aims to capture the relation among blocks to lay them out in relation to one another.

Msc-generator builds on lex, yacc, graphviz, glpk, cairo and ImGui. A Linux/Mac and
Windows port is maintained. The Windows version is written using MFC. There is a
GUI for Linux/Mac based on ImGui (called @emph{CLI GUI} also available on Windows,
if you prefer that better than the MFC GUI).
The reference documentation of the source code of Msc-generator itself can be found at
@uref{https://msc-generator.gitlab.io/msc-generator/doxygen}.


@node What's new in Msc-generator 8.6, Getting Started, Top, Top
@chapter What's new in Msc-generator 8.6

The improvements added since version 8.5 are listed below. If you are new to
Msc-generator, you should probably jump to @ref{Getting Started}.

@itemize
@item Added chart inlining which allows to draw a chart of any type in a signalling chart 
or block diagram. This means that you can draw a signalling chart in a block or add a graph
to a signalling chart. Graphviz graphs cannot inline other charts, as this would require 
large changes to its grammar, not only simple extensions. 

In signalling charts use the @code{symbol block} or @code{symbol gv} command followed by a 
location and the inlined chart's text enclosed between @code{<<<} and @code{>>>} symbols. 

For Block Diagrams, the new @code{chart} block type can be used followed by chart type and 
the chart text similarly enclosed. See the Examples.
@item [signalling] Now you can position symbols (including inlined charts as above) in 
relation to other elements of the chart. So far you had to specify horizontal and vertical 
position in relation to entity lines and markers. Now you can position symbols left of, 
right of, above, below or even around other chart elements. See the example when searching 
for @samp{ref}.
@item [block] Added @code{aspect_ratio} attribute to blocks.
@item [block] Added @code{grid} routing type to route either horizontally or vertically.
@item [block] Added new ports to boxes, like @code{A@@s30}, which means places the end of 
an arrow at 30% of the south (downward) edge of the box.
@item [block] Improvements to arrow layout and de-overlapping
@item [block] Added @code{tangent} and @code{tangent_upside_down} for @code{label.orient} for 
arrows. These rotate the label to align with the direction of the arrow.
@end itemize

And many fixes and improvements in the CLI GUI, hinting and elsewhere:
@itemize
@item Improved contour performance by another 24%, bringing the total average 
reduction in execution time of Expand and Union operations since v8.4 to 42% 
(almost x2 speed with operation on large contours being 3-6x faster).
@item [gui] fix: Tab key moves the cursor when no indenting
@item [gui] fix: Ctrl+bksp shall only delete backwards
@item [gui] fix: Ctrl+X/C on a full line shall make Ctrl+V insert a full line (even on last line)
@item [gui] fix: pressing End shall remove selection even if at the end of the selection (even on last line)
@item [gui] fix: last character not colored   
@item [gui] fix: Shift+Left shall select only to the end of the word
@item [gui] fix: Shortcuts to dialog buttons.
@item [gui] fix: Starting help does not block the app
@item [gui] fix: Error squiggles now show up at the line ends (8.6.1)
@item [signalling] fix: note keyword with nothing after shall parse gracefully
@item [signalling] fix: byref vertical to @{@}
@item [block] fix: color token should allow negative numbers, to be used in setting @code{margin}
@item [signalling] fix: @code{adjust} shall not decrease the size of the symbol negative. Emit a warning if the symbol disappears.
@item [signalling] fix: @code{size} for symbols should also accept a number.
@item [signalling] fix: increase chart size when closing an activated entity
@item [block] fix: names for cloned unnamed blocks
@item fix: pedantic the same for inline chart CSH
@item [graph] fix: Rename Entities did not work with multiple graphs.
@item [gui] more CLI options available with GUI
@item [gui] fix: hinting (also in languages)
@item [block] fix: retail labels of joined blocks even with fill color
@item [graph] fix: a crash on Windows with A->A edges (#94, thanks Ji@v{r}@'{@dotless{i}})
@item [cli] fix: starting with --tei-mode without -S no longer crashes (8.6.1)
@item [signalling] fix: 2 kinds of crashes (8.6.3, thanks Go@"ran!)
@end itemize

@node Getting Started, Signalling Chart Language Tutorial, What's new in Msc-generator 8.6, Top
@chapter Getting started

Msc-generator is a program that parses textual chart descriptions
and produces graphical output in a variety of file formats, or can
embed in documents, such as Word or PowerPoint.
It currently supports three kind of charts: Message Sequence Charts
(MSCs, this is where the name of the tool comes from), Graphs using the
graphviz language and Block Diagrams.

On Windows Msc-generator is installing as two applications: @code{Msc-generator.exe}
and @code{msc-gen.exe}. The first is called the @dfn{MFC GUI} that can use OLE
to embed charts into PowerPoint and Word documents and is supported from
version 2.2. The latter implements the command line, but when invoked
as @code{msc-gen.exe --gui} the @dfn{CLI GUI} starts, which supports @dfn{alt-text
embedding}, see more on this in @ref{Office integration}.
You can start both GUIs directly. Clicking on a file with .signalling, .graph or
.block extension starts the MFC GUI. You can also double-click a chart OLE embedded
in a document to edit it in the MFC GUI.

Msc-generator is also supported on Debian Linux (package @code{msc-generator}) and
on MacOS (@code{brew install msc-generator}). On these platforms only the CLI GUI is
available.

@menu
* The MFC GUI on Windows::
* The CLI GUI::
* Tracking Mode::
* Auto Split::
* Collapsing and Expanding::
* The command-line tool::
* Office integration::
@end menu

@node The MFC GUI on Windows, The CLI GUI, Getting Started, Getting Started
@section The MFC GUI on Windows

@ifnotinfo
@center @image{MscGen-Window, 12cm}
@end ifnotinfo

The MFC GUI window has the usual elements of a Windows application:
menu bar, a ribbon and a status bar. We will briefy discuss these here and give
a more detailed description in @ref{Usage Reference}.

You can use the scrollbars to navigate around in the chart. You can also grab
the chart by the mouse and drag it (if not all of it fits into the window).

You can also reposition the pane of the internal editor and the error list by
clicking on their title bar and dragging them to a new location. On the example
above, the internal editor has been moved to the right side from the left (which
is the default). You can even create floating windows out of these panes.

If you accidentally close the internal editor, use the @samp{Text Editors...}
button on the ribbon and re-select @samp{Internal Editor}.

@menu
* Working with Charts::
* Zooming::
* Quick Access Toolbar::
@end menu

@node Working with Charts, Zooming, The MFC GUI on Windows, The MFC GUI on Windows
@subsection Working with Charts

Msc-generator has a built-in text editor with color syntax highlighting. You can
edit the chart description there. When you are ready, press
the @samp{Update Chart} button on the very left of the ribbon (or F2 on the keyboard)
and the visual view of the chart will get updated. There is also an option to automatically
update the chart as you type, see @ref{Options}. Any error or warning messages
will show up in the error panel at the bottom. You can click on them to jump to
the location of the error in the input file or use F8 and Ctrl+F8 to access them.
If the error is not in the main file (but in an included file or design library),
Msc-generator does not load it, but merely gives a small sound.

You can use the Main button on the ribbon or the quick access items in the window
title to load/save the file. The file format is simply
text, the very same that you edit inside Msc-generator's text editor.
You can also save the graphical rendering of the file
in various graphics formats using the @code{Main|Export...} item.
A third alternative is to export the file as a PNG image and save the chart text
with it. Then opening the PNG file, will also bring back the chart text. To do this,
you simply need to select PNG as a file format in the Open and Save dialog boxes.
Pressing the Main button you also find the usual Print and Print Preview commands.

The first pane of the Ribbon always shows the type of
chart currently opened (such as Signalling Chart, Graphviz Graph or Block Diagram).
The buttons in the second column of this pane enables you to enter tracking
mode (see @ref{Tracking Mode}); to turn automatic splitting (@ref{Auto Split})
on or off; or to enable the showing of collapse/expand controls for entity
groups and boxes (@ref{Collapsing and Expanding})@footnote{Some of these
buttons may not be available for all chart types. E.g., graphs have no heading
and thus does not support AutoSplit.}.

@ifnotinfo
@center @image{MscGen-Toolbar, 14cm}
@center @image{MscGen-Toolbar-Graph, 15cm}
@center @image{MscGen-Toolbar-Block, 10cm}
@end ifnotinfo

The third column has additional controls to govern chart appearance. The exact
controls depend on the chart type. For graphs, the layout algorithm used can be
selected here. For graphs and signalling charts there is a
design and page selector. By selecting a chart design here you can override the selection
in the source file. This is an easy way of reviewing how your chart would look
like in a particular design. See @ref{Chart Designs} for more info on chart
designs. With the page selectors, you can navigate around in multi-page charts.
If @samp{all} is selected then pagination is ignored and the whole chart is
shown. (See @ref{Multiple Pages} for more info on pagination commands for
signalling charts. For graphs each graph defined in sequence ends up in a
separate page.) Finally, for graphs using the @samp{Collapse all} and @samp{Expand all}
buttons you can collapse or expand all cluster subgraphs with a single click.

The Clipboard pane on the ribbon has two set of Copy/Paste operations:
one for text in the
text editor and a separate set for the entire chart. If you use paste for the entire
chart, then its whole content is replaced, whereas if you paste into the editor,
the content of the clipboard will be inserted.

You can also perform undo or redo from the Edit pane of the ribbon or
by pressing Ctrl+Z or Ctrl+Y. Similar search and replace operations for the text
editor can also be accessed from the Edit pane.

Finally, there is a separate button in the Edit pane to start and stop the
internal or an external text editor (see @ref{External Editor}). The latter is
useful in case you prefer to use your own editor.


@node Zooming, Quick Access Toolbar, Working with Charts, The MFC GUI on Windows
@subsection Zooming

You can zoom the chart in and out using the commands on the Zoom pane. The zoom
drop-down allows setting a specific zoom value. However, the easiest way to zoom
is to use the mouse wheel with the Ctrl key pressed.

You can easily select an appropriate zoom factor by clicking certain Zoom pane buttons.
@var{Overview} adjusts zoom to fit the entire chart into the window.
This is useful to get an overview of a chart. @var{Fit to width} changes the
zoom factor to fit the width of the chart to the current window.
Finally, @var{Original Size} sets the magnification back to
100%.@footnote{Msc-generator applies a maximum zoom factor for the @var{Overview}
and the @var{Fit to width} modes, in order to avoid a small chart being enormously
magified. This defaults to 150%. On very large screens this may prove to be a
tool small factor - thus it is possible to increase this value on the
@var{Preferences} category of the ribbon using the @var{Max Auto Zoom} edit box.}

You can also make Msc-generator apply one of the above three zoom adjustments
after every update, page change or window re-size by selecting checkboxes
besides the above command buttons.

You can also view the chart in full screen mode, by pressing F11. Mouse zooming
and panning works in this mode, as well. A small toolbar enables you to flip
pages, return to the all pages view or to toggle Auto Split (if applicable to
the chart, see below). You can exit full screen mode by pressing Escape.


@node Quick Access Toolbar, , Zooming, The MFC GUI on Windows
@subsection Quick Access Toolbar

Msc-generator allows you to select some of your most frequent commands or settings
to be displayed all the times at the @dfn{Quick Access Toolbar}. (That is not just
when their category is selected.)
The Quick Access Toolbar can be displayed above or below the ribbon.
Right of the buttons there is a small arrow opening for more actions
and a menu to customize them. This is also where you can select whether to display
the Quick Access Toolbar above or below the Ribbon.

@ifnotinfo
@center @image{MscGen-QuickAccessToolbar, 9cm}
@end ifnotinfo

@node The CLI GUI, Tracking Mode, The MFC GUI on Windows, Getting Started
@section The CLI GUI

On all supported platforms, you can start Msc-generator in the command line with the
@code{--gui} switch. This opens a GUI, where you can work with charts. Most of the
GUI is quite straightforward, here we just list a few things you may not discover
by yourself at first.

@ifnotinfo
@center @image{MscGen-CL-GUI, 9cm}
@end ifnotinfo

@itemize
@item You can use the mouse wheel to scroll and scale the editor and the chart.
@item You can drag the chart to pan.
@item You can press the @samp{Fit to window} and @samp{Fit to width} buttons in the
menu bar to scale the chart accordingly. Checking the boxes beside these buttons will
automatically re-scale the chart after each compilation.
@item Right-clicking an element in the editor brings up a context menu. You can then
rename elements (entities, graph nodes or blocks) or briefly flash the element
(arrows, entities, boxes, graph nodes, etc.) in the chart graphics. You can also
do these by pressing Ctrl-R and F4, respectively while the cursor is positioned in
the desired element.
@item Double-clicking the chart will enter @dfn{Tracking mode}. In this mode hoovering
over an element of the chart will highlight the element and select its definition
in the text editor. While in tracking mode, moving around in the text editor will
highlight the element the cursor is currently in. You can also click to select and unselect
chart elements - this is useful when explaining the chart in a screen sharing or
presentation session. See @dfn{Presentation mode} below.
@item If the chart contains multiple pages, you can use the page selector to cycle
among them. (The page selector does not appear, if the chart has only one page.)
Selecing page zero, will show all the pages.
@item If the clipboard contains an alt-text embedded chart or an alt-text encoded
chart source, the @code{Paste Clipboard} button on the menu bar becomes active. Clicking
it will paste the chart for editing. For embedded objects you can then press Ctrl+S to
save the object back to the cliboard from where you can re-insert it into PowerPoint or
Word. See @ref{Office integration} for more details.
@end itemize

@ifnotinfo
@center @image{MscGen-CL-GUI-Settings, 9cm}
@end ifnotinfo

There are also a few settings to tweak.
@itemize
@item You can set certain chart options, which will impact the chart appearance,
the errors/warnings produced, etc. By default, Msc-generator will recompile the chart
every time you change it. Unchecking @samp{Instant compilation} will prevent that.
Then you can use F2 or the @samp{Compile} button to manually compile.
@item In the middle column, you can adjust the zoom and its settings. You can also
turn @dfn{Auto heading} mode off if you do not want the signalling chart headers
to be shown always. (Auto heading has an effect only for signalling charts.)
You can also enter @dfn{Presentation mode} here. In this mode only the chart is shown,
but in full screen. You can press the Escape key to exit Presentation mode.
Double-clicking the chart in presentation mode will enter tracking mode allowing
you to explain the chart easier.
@item In the third column you can experiment with editor settings.
First, Msc-generator saves the chart text every second if the chart is associated
with a file. You can turn this off by setting @samp{Auto Save} off.
Turning @samp{Auto Paste Clipboard} on will make Msc-generator automatically open any
alt-text embedded chart copied to the clipboard and bring Msc-generator to the front.
See more on this in @ref{Alt-text embedding}.
The error squiggles provided in the editor are a subset of the error messages received
during a compilation. They are generated with color syntax highlighting and are useful
as instant error feedback for charts that take longer to compile. If you turn
@dfn{Smart indent} off, the Tab key will indent (Shift+Tab will de-indent) the line
even if you are at the end of it.
@end itemize

You can use the following command-line switches alongside @code{--gui}.
@table @code
@item -S <chart type>
Adding this will skip the welcome screen and start the GUI with a fresh copy of the
specified chart. If you also specify a filename, then here you can force its type.
@item <input filename>
The file specified will be opened. Its chart type will be deduced from its extension
or its content if it is a PNG file containing a chart (saved by Msc-generator).
@item --nodesigns
This will skip loading the design libraries as usual.
@end table

Some other switches will abort (such as @code{--utf16} to force a UTF-16 encoded input),
because the GUI does not support them, but some switches will just be silently ignored
(such as @code{-q} for quiet output).

The GUI has a settings file @code{.msc-generator-ini}, which stores window positions,
settings, the recently opened file list and the autosave. On Linux and the Mac it is placed into
@code{$HOME/.msc-genrc} by default or to @code{$MSC_GEN_RC/.msc-genrc}, if @code{MSC_GEN_RC}
is set. On Windows it is in the @code{AppData\Roaming\Msc-generator} folder.
You can freely delete this file to erase settings and history.

Finally, the command-line GUI has an example store similar to the other GUI (@xref{Example Library}).
Selecting @code{Examples} from the menu bar opens a dialog box with example snippets
demonstrating the features of each language.

@ifnotinfo
@center @image{MscGen-CL-GUI-Examples, 15cm}
@end ifnotinfo

The examples are keyword searchable, just
start typing the topic you have in mind to narrow the list of examples. You can then copy
and paste chart text from the exampes to your chart. In addition, the examples are editable
allowing you to experiment with the language there and then. (Hinting with Ctrl+Space works, too.)
Any changes made are immediately visible in the chart on the right. The examples are
reset to their original text each time you exit Msc-generator.

@node Tracking Mode, Auto Split, The CLI GUI, Getting Started
@section Tracking Mode

In both GUIs if you click an arrow, entity, graph node, block or any other visual
element on the chart, it is
briefly highlighted and the corresponding text is selected in the internal editor. This
is useful to quickly jump to a certain element in the chart text. The same way,
when pressing F4, if the cursor is inside a chart element, the element is briefly flashed.

If you double-click the chart (try the background) you enter Tracking Mode,
where you can select and highlight multiple chart elements at the same time.
Visual elements are faintly outlined just by hoovering above them. When actually
clicking on them (or pressing F4 when the internal editor cursor is inside them)
will make them actually highlighted. Then you can move on to highight more.
You can also remove highlighting from an element by clicking it again or by
pressing F4 again.

If you click the chart background or press Escape, all highlighting is removed.
Pressing Escape again will make you exit tracking mode. You can also enter tracking
mode by pressing Ctrl+T. In the MFC GUI pressing the @samp{Tracking Mode} button
on the Chart pane will also enter tracking mode.

Tracking mode is useful when you are discussing a chart (e.g., in a shared
screen session) and you want to talk about various elements.

@node Auto Split, Collapsing and Expanding, Tracking Mode, Getting Started
@section Auto Split

When working with a large signalling chart, it is sometimes needed to zoom in to an
area of it. In case the viewing area is towards the bottom of the chart,
it is often difficult to know which entity line belongs to which entity.
In such cases turning Auto Split on will result in the splitting of the
view into two parts, the upper one showing the entity headings. If
zooming is applied Msc-generator always attempts to resize the upper view
part to show the entities only.

Note that it is possible to define charts where there is no meaningful row of
entity headings at the top. In such cases, Msc-generator will get confused and
Auto Split is of no use. In case of multi-page charts, Auto Split will show
automatic headers only (Instead of @samp{newpage; heading;} use rather
@samp{newpage [auto_heading=yes];} command.)

Note that you can use the slider to change, where the chart is split, both with
and without Auto Split. The difference is that when Auto Split is on, the split
is reset to headings after a compilation or a page change.

Auto Split also works in Full Screen mode, but is available only for signalling charts.

@node Collapsing and Expanding, The command-line tool, Auto Split, Getting Started
@section Collapsing and Expanding

Msc-generator allows you to collapse boxes, entity groups (signalling charts); blocks
(block diagrams); and cluster subgraphs (graphviz graphs).
This way you can show only a simplified view of the procedure, diagram or graph described
by the chart text. E.g., instead of many arrows comprising a part of the procedure,
a simple box is shown as a summary.

@ifnotinfo
@center @image{MscGen-Controls, 4cm}
@end ifnotinfo

If you move the mouse over a chart element that can be collapsed (or is already
collapsed), control icon(s) appear at its top right corner. The control with the
minus sign collapses the element, the control with the plus sign expands a collapsed
element, while the green arrow collapses the element into a block arrow. The last
icon will only appear for boxes of signalling charts, which are not part of
a box series (@ref{Drawing Boxes}).

In the MFC GUI you can disable the showing of such controls via the red plus button on the
Chart pane. This improves compilation time a bit.

For signalling charts and block diagrams expanding and collapsing can also be set via the
@samp{collapsed} attribute (for group entities/boxes or blocks, respectively)
and hence is available for the command-line version, as well.
It is most useful, however, for interactive work.
Any collapse/expand setting via the GUI overrides the one
specified by attributes. Such overrides are saved with embedded charts, but naturally
not when the chart is saved to disk as text.

In both GUIs, double clicking any element that has controls (can be collapsed/expanded)
activates the first control (even if controls are not shown). This essentially
toggles collapse/expand status.

@node The command-line tool, Office integration, Collapsing and Expanding, Getting Started
@section The command-line tool

The command-line version of Msc-generator runs on all supported platforms.
On Windows it is installed to the same directory as the windowed application.
That directory is included in the PATH, so you can call it from anywhere.

The command line version of Msc-generator supports PNG, PDF, EPS, SVG and PPT
graphics output formats, plus EMF on Windows. It can compile and extrack chart texts
embedded in PNG and PPT files and it can also embed the result back to a
PNG or PPT file (the latter using @ref{Alt-text embedding}).

To use Msc-generator to generate a signalling chart from a text file
(containing a singalling chart description in the appropriate language)
simply type

@example
msc-gen -T pdf inputfile.signalling
@end example

To use Msc-generator to generate a graph or block diagram from a text file
(containing a graph description in the DOT or block languages, respectively )
simply type

@example
msc-gen -T pdf inputfile.graph
@end example

or

@example
msc-gen -T pdf inputfile.block
@end example

All of these will give you @code{inputfile.pdf}. You can change @samp{pdf} to get the
other file formats. If you omit the @samp{-T} switch altogether, a PNG
will be generated.

If Msc-generator has successfully generated an output, it prints
@samp{Success.}. Instead, or in addition, it may print warnings or
errors, when it does not understand something.


@node Office integration, , The command-line tool, Getting Started
@section Office integration

@menu
* OLE embedding::
* Alt-text embedding::
@end menu

@node OLE embedding, Alt-text embedding, Office integration, Office integration
@subsection OLE embedding

Since one of the main uses of
Msc-generator is to paste charts into presentations or documents, Msc-generator supports
OLE embedding of charts in the MFC GUI from version 2.2.

You can take a chart and embed it as a component in a compound document such as
a Word, Excel or Powerpoint document. To do this, copy the chart to the
clipboard by clicking on the @var{Copy Chart (OLE obj)} button and paste it into
the compound document@footnote{Make sure you paste the chart using @samp{Paste
Special...} as an @samp{Msc-generator Chart Object}.}. Later you can
edit the chart by double clicking the chart in the document@footnote{In place
editing is no longer supported from version 3.4.1.}.

Right clicking an embedded chart in a document will bring up a menu of options,
where you can select @code{Edit} or @code{Open} for editing in a separate
window; or @code{View Full Screen} to view (but not edit) the chart in full
screen.

Page, chart design and layout settings you select on the ribbon are saved
with embedded documents along with entity/box collapse/expand state. Thus if you copy
a multi-page chart to a document with a single page selected, only the selected page
will be visible in the document. (But the source text of the whole chart is stored there.)
Likewise, if you collapse/expand certain boxes or entities or subgraphs, they will show
in that state in the document. Later, if you double-click the chart and open Msc-generator,
you can change the page, design or collapse/expand status and these will update in the
document. Note that page, chart design, layout and collapse/expand settings are not
saved with the chart when saving to a text file. Only when embedded (either as OLE object,
as alt-text (see below) or into a PNG file).

See more details in @ref{Advanced OLE Considerations}.

@b{Best common practice workflow} You start editing the chart in Msc-generator.
At some point select @var{Copy Chart (OLE obj)} and then use @var{Paste Special...}
to paste into a PowerPoint or Word document (select @code{Msc-generator Signalling Chart Object}).
Then any time later, simply double-click the chart to open and edit it. Updating the chart
(with the F2 key, for example) in such a session will update the embedded graphics.

@node Alt-text embedding, , OLE embedding, Office integration
@subsection Alt-text embedding

Over the years OLE technology became increasingly outdated@footnote{For example, it still uses
16-bit Windows metafiles} and is not perfectly supported by Sharepoint and other modern Office tools.
In addition, of course, it was never supported on Linux or on the Mac, whereas Msc-generator
now has a GUI for both.

Therefore a new way to add charts to Office documents has been developed in v8.0, called
@dfn{alt-text embedding}. In this method the chart is inserted as a PNG image, where the
alt-text (a.k.a. @var{alternative text}, usually used for accessibility or
when the graphics cannot be shown) stores the chart text, language and other info. This
method of embedding requires no special OS support, like OLE and also allows to apply
various properties to the chart, such as cropping, outline, shadow, rotation, etc.
Alt-text embedding is not compatible with OLE embedding in any which way.

Both the CLI@footnote{The CLI GUI can be invoked with @code{msc-gen --gui}} and
MFC@footnote{The MFC GUI can be invoked wit @code{Msc-generator.exe} and supports
alt-text embedding since version 8.5.} GUIs of Msc-generator can now work with
alt-text embedding the following ways.

@enumerate
@item Open a PPT file (with @code{pptx} extension) and simultaneously edit all the charts
embedded in it. It is possible to copy snippets between the charts, but also to add a new one.
Note that you cannot save the PPT file, if it is opened in PowerPoint, as PowerPoint locks
the file for writing. Also, PPT files on Sharepoint drives may not merge well, when edited this
way. (CLI GUI only.)
@item Copy the currently edited chart to the clipboard using the @samp{File|Copy to clipboard} menu
item (CLI GUI) or the @samp{Copy Chart (alt-text)} ribbon button (MFC GUI). This will package the
chart text, language, collapse/expand state, design and page with a PNG rendering of the chart into
an Office document snippet. You can then paste it into PowerPoint or Word documents. (Both CLI and MFC GUIs.)
@item If you pasted an Msc-generator chart this way into a into PowerPoint or Word document and later copy
it to the clipboard from PowerPoint or Word, you can paste it into Msc-generator for editing.
This will re-use the chart text and other metadata stored with the image.
Msc-generator stores the sizing and formatting of the chart (along with other graphical elements or text
copied with the chart) so when you save, those will be preserved. Saving will happen to the clipboard
from where you can re-insert the chart back to the PowerPoint or Word document (or to another one).
If a slide contains multiple charts, you can copy all of them to the clipboard and edit all of them
simultaneously in Msc-generator (potentially copying sinppets between them). (Both CLI and MFC GUIs.
The MFC GUI can only edit one chart at a time.)
@item Finally, Msc-generator can copy the alt-text for the current chart to the clipboard. Adding this
to any graphics in PowerPoint will @emph{upgrade} the graphics to an Msc-generator chart and
Msc-generator will be able to edit it (either by opening the PPT file as #1 above or via the clipboard).
Similarly, if you copy an alt-text to the clipboard, Msc-generator can paste it as if the whole chart
has been copied. (The MFC GUI cannot copy the alt-text, but can paste it.)
@end enumerate

Turning the setting @code{Auto Paste Clipboard} on, will make Msc-generator automatically open any
chart copied to the clipboard (and come to the foreground) if the currently open chart has no unsaved
changes.

See @ref{Embedding Charts} on how to use the command-line tool to embed and extract charts into and from
PNG and PPT files.

@b{Best common practice workflow} You start editing the chart in Msc-generator.
At some point select @var{File|Copy to Clipboard} (CLI GUI) or @var{Home|Copy Chart (alt-text)} from the
ribbon (MFC GUI) and then simply paste into a PowerPoint or Word document.
(Turn @code{Auto Paste Clipboard} on.)
Then any time later (with Msc-generator running),
1) cut the chart (and maybe other graphics elements or multiple charts) to the cliboard;
2) Msc-generator pops up automatically;
3) edit the chart;
4) Save; and
5) Paste the chart(s) (and other elements) back to the PowerPoint or Word document.

@node Signalling Chart Language Tutorial, Graph Language Tutorial, Getting Started, Top
@chapter Signalling Chart Language Tutorial

In this chapter we give a step-by-step introduction into the language of
Msc-generator for signalling charts.
At the end you will master most of the language to create
charts. Further details (mostly on controlling appearance) are provided
in @ref{Signalling Chart Language Reference}.

@menu
* Defining Arrows::
* Defining Entities::
* Dividers::
* Drawing Boxes::
* Drawing Things in Parallel::
* Annotating the Chart::
* Other Features::
@end menu

@node Defining Arrows, Defining Entities, , Signalling Chart Language Tutorial
@section Defining Arrows
Message sequence charts consits of @dfn{entities} and @dfn{messages}.
The simplest file consists of a single message between two entities: a @samp{Sender}
and a @samp{Receiver}.

@multitable @columnfractions .5 .5
@item @image{ex01_csh}
@tab @image{ex01, 5cm}
@end multitable

The message may have a label, as well.

@multitable @columnfractions .5 .5
@item @image{ex02_csh}
@tab @image{ex02, 5cm}
@end multitable

A more complicated procedure would be to request some information from
a server, which, in turn, queries a backend.
Note that everything in a line after a @samp{#} is treated as a comment and is
ignored by Msc-generator.

@multitable @columnfractions .5 .5
@item @image{ex03_csh} @tab @image{ex03, 8cm}
@end multitable

Arrows can take various forms, for example they can be bi-directional or can span
multiple entities. They can also start and end at the same entity and can come from
or go to "outside"

@multitable @columnfractions .5 .5
@item @image{ex04_csh} @tab @image{ex04, 8cm}
@end multitable

Sometimes one wants to indicate that a message came from an entity not shown,
but not at the far left or right. In this case use the pipe symbol @samp{|},
like @code{a->|;}.

@multitable @columnfractions .5 .5
@item @image{exB2_csh} @tab @image{exB2, 8cm}
@end multitable

It is also possible to make use of various arrow types, such dotted,
dashed and double line. To achieve this the @samp{->} symbol need to be
replaced with @samp{>}, @samp{>>} and @samp{=>}, respectively.

@multitable @columnfractions .5 .5
@item


@image{ex05_csh}

@tab

@image{ex05, 8cm}
@end multitable

It is also possible to use different line styles for different segments
of an arrow - but all must be of the same direction. (That is, it is not
possible to write @samp{a->b<-c}, for example.)
In addition, for multi-segment arrows the dash @samp{-} symbol can be used in the
second and following segments, as a shorthand. In this case the added segment
will have the same line style as the first one.


@multitable @columnfractions .5 .5
@item


@image{ex06_csh}

@tab

@image{ex06, 8cm}
@end multitable

It is possible to change the type of the arrowhead. The arrowhead type is an
@dfn{attribute} of the arrow. Attributes can be specified between
square brackets before or after the label, as shown below. A variety of
arrow-head types are available, for a full list of arrow attributes and
arrowhead types @xref{Specifying Arrows}.

@multitable @columnfractions .5 .5
@item


@image{ex13_csh}

@tab

@image{ex13, 8cm}
@end multitable

Msc-generator generates an error if the order of entities in a multi-segment
arrow does not follow the order of the entities (either left-to-right or
back). However, sometimes it is important to show such a message zig-zagging
among the entities as one message. This is possible by @dfn{joining} arrows.
Note that the @samp{join} keyword can do more, see @ref{Joining Arrows and Boxes}.

@multitable @columnfractions .5 .5
@item @image{exB3_csh} @tab @image{exB3, 8cm}
@end multitable


Often the message has not only a name, but additional parameters, that
need to be displayed. The label of the arrows can be made multi-line
and one can apply font sizes and formatting, as well. This is achieved
by inserting formatting characters into the label text. Each formating
character begins with a backslash @samp{\}.
@samp{\b}, @samp{\i} and @samp{\u} toggles bold, italics and
underline, respectively. @samp{\-} switches to small font, @samp{\+}
switches back to normal size, while @samp{\^} and @samp{\_} switches
to superscript and subscript, respectively. @samp{\n} inserts a line
break. You can also add a line brake by simply typing the label into
multiple lines. Leading and tailing whitespace will be removed from
such lines so you can indent the lines in the source file to look nice.


@image{ex09_csh}


@image{ex09, 8cm}

Arrows can further be differentiated by applying @dfn{styles} to them.
Styles are packages of attributes with a name. They can be specified in
square brackets like an attribute that takes no value.
Msc-generator has two pre-defined styles @samp{weak} and @samp{strong},
that exits in all chart designs@footnote{You can define your own styles, as
well, @pxref{Defining Styles}.}. They will make the arrow look less or more
emphasized, respectively. The actual appearance depends on the chart
design, in this basic case they represent gray color and thicher lines
with bold text, respectively@footnote{For more on chart deisgns
@ref{Chart Designs}.}.

@multitable @columnfractions .5 .5
@item


@image{ex08_csh}

@tab

@image{ex08, 8cm}
@end multitable

Msc-generator places arrows one-by-one below each
other. In case of many arrows, this may result in a lot of vertical
space wasted. To reduce the size of the resulting diagram, a @dfn{chart
option} can be specified, which compresses the diagram, where possible.
You can read more on chart options, @pxref{Compression and Vertical Spacing}.

@multitable @columnfractions .5 .5
@item


@image{ex12_csh}

@tab

@image{ex12, 8cm}
@end multitable

You can use the @samp{angle} chart option (or attribute) to make
the arrows slanted. Simply specify a value in degrees. Note that bi-directional
arrows will not be slanted.

@multitable @columnfractions .5 .5
@item


@image{ex80_csh}

@tab

@image{ex80, 8cm}
@end multitable

Normally, Msc-generator attempts to avoid overlaps between elements by placing them
one below (or sometimes besides) each other. If you want to show messages
crossing each other, you need overlapping arrows. For this, you can use
the @code{overlap} keyword. Arrows marked such are allowed to be overlapped by
subsequent arrows.

@multitable @columnfractions .5 .5
@item

@image{ex93_csh}

@tab

@image{ex93, 8cm}
@end multitable

Finally, you can also indicate a lost message by marking the segment of the loss with an
asterisk @samp{*}.

@multitable @columnfractions .5 .5
@item


@image{ex92_csh}

@tab

@image{ex92, 8cm}
@end multitable


@node Defining Entities, Dividers, Defining Arrows, Signalling Chart Language Tutorial
@section Defining Entities

Msc-generator, by default draws the entities from left to right in the
order they appear in the chart description. In the examples above, the
first entity to appear was always the @samp{Client}, the second
@samp{Server} and the third @samp{Backend}.

Often one wants to control, in which order entities appear on the
chart. This is possible, by listing the entities before actual use.
On the example below, the order of the enties are reversed. Note that
we have reversed the first arrow to arrive to the @samp{Client} from
the right.

@multitable @columnfractions .5 .5
@item


@image{ex07_csh}

@tab

@image{ex07, 8cm}
@end multitable

Often the name of the entity need to be multi-line or need to contain
formatting characters, or is just too long to type many times. You can
overcome this problem by specifying a label for entities. The name of
the entity then will be used in the chart description, but on the chart
the label of the entity will be displayed. The @samp{label} is an
attribute of the entity and can be specified between square
brackets after the entity name, before the comma, as shown below. (You
can specify entity attributes only when explicitly defining an entity
and not if you just start using them without listing them first.)

@multitable @columnfractions .5 .5
@item


@image{ex10_csh}

@tab

@image{ex10, 8cm}
@end multitable


You can also use the colon-notation to specify entity labels, similar
to arrows. The above example can thus be written as below. Note that the
entity definitions are now terminated by a semicolon -- commas would be
treated as part of the label.

@multitable @columnfractions .5 .5
@item


@image{ex62_csh}

@tab

@image{ex62, 8cm}
@end multitable



Entities can also be specified as @samp{weak} or @samp{strong}, by
applying these styles the same way as for arrows. You can also
assign various shapes to the entity headings via the @code{shape}
attribute.

@multitable @columnfractions .5 .5
@item


@image{ex11_csh}

@tab

@image{ex11, 8cm}
@end multitable

Entities can be turned on and off at certain points in the chart.
An entity that is turned off, will
not have its vertical line displayed. This is useful if the chart has
many entities, but one is involved only in a small part of the process.
An entity can be turned off by typing @code{hide} followed by the name
of the entity. You can turn it later back on with the @code{show} keyword
followed by the entities to turn on.
When @code{hide} is used for an entity right at its
definition, it will start hidden and its heading is not drawn at the
place of definition. However, when it is later turned on, a heading
will be shown.

@multitable @columnfractions .5 .5
@item


@image{ex14_csh}

@tab

@image{ex14, 8cm}
@end multitable

Not showing an entity from the beginning of the chart can also be achieved
by simply defining the entity later. Note that
this is different from simply starting to use an entity later. When you
start using an entity without explicitly defining it first, it will appear
at the top of the chart, not only where started using it first. (See earlier
examples.)

@multitable @columnfractions .5 .5
@item


@image{ex15_csh}

@tab

@image{ex15, 8cm}
@end multitable

Sometimes the vertical space between entities is just not enough to
display a longer label for an arrow. In this case use the @samp{hscale}
chart option to increase the horizontal spacing. It can be set to a
numerical value, 1 being the default.


@multitable @columnfractions .35 .65
@item


@image{ex16_csh}

@tab

@image{ex16, 10.4cm}
@end multitable

Or you can simply set it to @samp{auto}, which creates variable
spacing, just as much as is needed.


@multitable @columnfractions .5 .5
@item


@image{ex17_csh}

@tab

@image{ex17, 8cm}
@end multitable

Alternatively, you can instruct Msc-generator to apply word wrapping to the labels
of arrows, to fit into the available space, by setting the @samp{text.wrap} chart
option to @samp{yes}.

@multitable @columnfractions .5 .5
@item


@image{ex89_csh}

@tab

@image{ex89, 8cm}
@end multitable


It is possible to define entity groups, to indicate logical relations
between various entities. Use curly braces (@samp{@{} and @samp{@}}) after an
entity definition (after any potential label and attributes).

@multitable @columnfractions .5 .5
@item


@image{ex70_csh}

@tab

@image{ex70, 8cm}
@end multitable

Instead of a group heading, you can also shade the background behind entities in
an entity group.

@multitable @columnfractions .5 .5
@item


@image{exB8_csh}

@tab

@image{exB8, 8cm}
@end multitable



It is also possible to collapse a group entity hiding details of the
process. This can be done either via the @samp{collapsed} attribute or,
on Windows, using the GUI. Elements that disappear leave a small indicator
(box with 3 dots). The collapsed entity group also includes an indicator
to show that further entities are hidden within. (Indicators can be
turned off by the @samp{indicator} chart option.

@multitable @columnfractions .5 .5
@item

@image{ex71_csh}

@tab

@image{ex71, 8cm}
@end multitable

Entities can be @dfn{activated}. This results in the entity line becoming a
thin rectangle instead. If you do this immediately after an arrow the activation
will happen at the tip of the arrow indicating that the cause of the activation
is the arrow.

@multitable @columnfractions .5 .5
@item

@image{ex88_csh}

@tab

@image{ex88, 8cm}
@end multitable


@node Dividers, Drawing Boxes, Defining Entities, Signalling Chart Language Tutorial
@section Dividers

In a message sequence chart it is often important to segment the process
into multiple logical parts.
You can use the @samp{---} element to draw a horizontal
line acorss the chart with some text, e.g., to summarize what have been
achieved so far.

@multitable @columnfractions .5 .5
@item

@image{ex18_csh}

@tab

@image{ex18, 8cm}
@end multitable

Similar to this, using the @samp{...} element can express the passage
of time by making the vertical lines dotted.

@multitable @columnfractions .5 .5
@item


@image{ex19_csh}

@tab

@image{ex19, 8cm}
@end multitable

Sometimes one merely wants to add some text to a chart. In that case
the empty element can be used either like @samp{: text;}. The symbol
@samp{|||} simply inserts an empty row.

@multitable @columnfractions .5 .5
@item


@image{ex20_csh}

@tab

@image{ex20, 8cm}
@end multitable

The above construct always places the text in the middle of the chart. Smaller
chart explanations are better done via the @code{text at} command.

@multitable @columnfractions .5 .5
@item


@image{exB1_csh}

@tab

@image{exB1, 8cm}
@end multitable

More options to comment and annotate your chart can be found in
@ref{Annotating the Chart}.

@node Drawing Boxes, Drawing Things in Parallel, Dividers, Signalling Chart Language Tutorial
@section Drawing Boxes

A @dfn{box} is a line around one part of the chart. It can be used to add textual
comments, group a set of arrows or describe alternative behavior. In
their simplest form they only contain text, but they can also encompass arrows.
A box spans between two entities, or alternatively around only one.

@multitable @columnfractions .5 .5
@item


@image{ex21_csh}

@tab

@image{ex21, 8cm}
@end multitable

The line around boxes can be dotted, dashed and double line, too, by using @samp{..}, @samp{++} or
@samp{==} instead of @samp{--}.
Boxes can also be used to group a set of arrows. To do this, simply
insert the arrow definitions enclosed in curled braces just before the
semicolon terminating the definition of the box.

@multitable @columnfractions .5 .5
@item


@image{ex22_csh}

@tab

@image{ex22, 8cm}
@end multitable

When a box contains arrows, it is not necessary to specify which
entities it shall span between, it will be calculated automatically.
Also boxes can be nested arbitrarily deep.

@multitable @columnfractions .5 .5
@item


@image{ex23_csh}

@tab

@image{ex23, 8cm}
@end multitable

You can shade boxes, by specifying the color attribute. For a full list
of box attributes and color definitions, @xref{Boxes}, and @pxref{Specifying Colors}.
It is also possible to make a box @samp{weak} or @samp{strong}.

@multitable @columnfractions .5 .5
@item


@image{ex24_csh}

@tab

@image{ex24, 8cm}
@end multitable

A number of box contours are available via the @samp{line.corner} attribute.

@multitable @columnfractions .5 .5
@item


@image{ex65_csh}

@tab

@image{ex65, 8cm}
@end multitable

Boxes can express alternatives. To do this, simply concatenate
multiple box definition without adding semicolons. These will be drawn with
no spaces between. Changing the line style in subsequent boxes impacts the
line separating the boxes, otherwise all attributes of the first box are
inherited by the subsequent ones.

@multitable @columnfractions .5 .5
@item

@image{ex25_csh}

@tab

@image{ex25, 8cm}
@end multitable

You can use @dfn{tags} to label boxes (both standalone or in a series). This can be
used to indicate alternatives, loops or optional parts of the sequence.

@multitable @columnfractions .5 .5
@item

@image{ex99_csh}

@tab

@image{ex99, 8cm}
@end multitable

You can observe in the previous example that the @samp{\#} sequence inserts
a @samp{#} character into a label. The @samp{\} is needed to differentiate
from a comment.

Finally, similar to entity groups, boxes can also be collapsed, if they are not
empty. Standalone boxes can be collapsed to an empty box or block arrow by
specifying the @samp{collapsed} attribute (or via the GUI on Windows).
This feature is useful to hide or summarize irrelevant parts of the chart and
enables quick working with large processes.

@multitable @columnfractions .57 .43
@item

@image{ex72_csh}

@tab

@image{ex72, 6.5cm}
@end multitable



@node Drawing Things in Parallel, Annotating the Chart, Drawing Boxes, Signalling Chart Language Tutorial
@section Drawing Things in Parallel

Sometimes it is desired to express that two separate process happen side-by-side.
The easiest way to do so is to write @samp{parallel} before any arrow, box or
other element.
As a result the elements after it will be drawn in parallel with it.

@multitable @columnfractions .5 .5
@item


@image{ex49_csh}

@tab

@image{ex49, 8cm}
@end multitable

It is also possible to have bigger blocks of action in parallel using @dfn{Parallel blocks}.
Consider the following example.


@image{ex26_csh}

@image{ex26, 14cm}

In the above example a central sever is querying two @code{AR}
entities, which, in turn query @code{MN} entities further. The query on
both sides happen simultaneously. To display parallel actions side by
side, simply enclose the two set of arrows between braces @samp{@{@}}
and write them one after the other. Use only a single semicolon after
the last block. You can have as many flows in parallel as you want.
It is possible to place anything
in a parallel block, arrows, boxes, or other parallel blocks,
as well. You can even define new entities or turn them on or off inside
parallel boxes.

The top of each block will be drawn at the
same vertical position. The next element below the series of parallel
blocks (the "Now I have it" box in our example) will be drawn after
the longest of the parallel blocks.


@node Annotating the Chart, Other Features, Drawing Things in Parallel, Signalling Chart Language Tutorial
@section Annotating the Chart

Often it is important to make annotations to the chart detailing what is
going on. Msc-generator supports several types of annotations, let's start with
@dfn{notes} and @dfn{comments}.
Both have a @dfn{target element} to which the note
or comment is made. Notes appear as small callouts in the chart and
should preferably contain short text. Comments, on the other hand
appear on the side and allow for more elaborate explanations.

@multitable @columnfractions .4 .6
@item

@image{ex83_csh, 7cm}

@tab

@image{ex83, 8cm}
@end multitable

Another way to explain what happens is by annotating a series of events.
This can be done by @dfn{verticals}, which are elements spanning vertically
usually besides an entity line. Here we show two of them, the @dfn{range} and
@dfn{brace} verticals, but there are more.

@multitable @columnfractions .42 .58
@item

@image{ex95_csh, 7cm}

@tab

@image{ex95, 8.5cm}
@end multitable


@node Other Features, , Annotating the Chart, Signalling Chart Language Tutorial
@section Other Features

There are a few more features that are easy to use and can help in
certain situations.

One useful feature is the
numbering of labels. This is useful if you want to insert your chart
into some documentation and later refer to individual arrows by number.
By specifying the @code{numbering=yes} chart option all labels will get
an auto-incremented number. This includes boxes and dividers, as well.
You can individually turn numbering on or off by specifying the
@code{number} attribute. You can set it to @code{yes} or @code{no}, or
to a specific integer number. In the latter case the arrow will take
the specified number and subsequent arrows will be numbered from this
value.
On the example below, we can observe that in case of parallel blocks
the order of numbering corresponds to the order of the arrows in the
source file.

@image{ex27_csh}

@image{ex27, 14cm}

Sometimes a block of actions would be best summarized by a block arrow.
This can be achieved by typing @samp{block} in front of any arrow declaration.



@multitable @columnfractions .5 .5
@item

@image{ex36_csh}

@tab

@image{ex36, 8cm}
@end multitable

Similar, many cases you want to express a tunnel between two entities
and messages travelling through it. To achieve this, just type
@samp{pipe} in front of any box definition.
You can define a series of connected or disconencted pipe
segment each with its own visual style or even encapsulate pipes.
More on this in @ref{Pipes}.

@multitable @columnfractions .41 .59
@item


@image{ex37_csh}

@tab

@image{ex37, 9.5cm}
@end multitable

Adding a title to the chart is easy. Just type @code{title:} followed by the title
text.

@multitable @columnfractions .41 .59
@item

@image{ex86_csh}

@tab

@image{ex86, 6cm}
@end multitable

Another handy feature is multi-page support. This is useful when
describing a single procedure in a document in multiple chunks. By
inserting the @code{newpage;} command, the rest of the chart will be
drawn to a separate file. You can specify as many pages, as you want.
In order to display the entity headings again at the top of the new
page, add the @code{auto_heading=yes} attribute. Breaking a page is
possible even in the middle of a box, see the following example.

@multitable @columnfractions .5 .5
@item

@image{ex28_csh}

@tab

Chunk one:

@image{ex2801, 8cm}

Chunk two:

@image{ex2802, 8cm}
@end multitable

From version 3.3 you can draw arbitrary circles and rectangles onto the chart.
They syntax is quite rich to allow free placement. You can even specify to draw
below the entity lines or over other drawn elements. More detailed description can
be found in @ref{Free Drawing}, but here are a few examples.

@image{ex74_csh}

@center @image{ex74, 12cm}

Finally, an easy way to make charts visually more appealing is through the use of
@dfn{Chart Designs}. A chart design is a collection of colors and visual style for
arrows, boxes, entities and dividers. The design can be specified
either on the command line after double dashes, or at the beginning of
the chart by the @code{msc=<design>} line.

Currently several designs are
supported. @samp{plain} was used as demonstration so far. Below we give
an example of the others.

@multitable @columnfractions .5 .5
@item


@image{ex32_csh}

@tab

The @samp{qsd} design:

@image{ex32, 6cm}

@item

The @samp{rose} design:

@image{ex29, 7cm}

@tab
The @samp{mild_yellow} design:

@image{ex30, 6cm}

@item

The @samp{omegapple} design:

@image{ex31, 7cm}

@tab
The @samp{modern_blue} design:

@image{ex33, 7cm}

@item

The @samp{round_green} design:

@image{ex34, 7cm}

@tab

The @samp{green_earth} design:

@image{ex35, 7cm}

@item

The @samp{colores} design:

@image{ex82, 7cm}

@tab

The @samp{black_on_white} design:

@image{ex81, 7cm}

@item

And the the @samp{norton_commander} tribute design.

@image{ex84, 7cm}

@end multitable

@node Graph Language Tutorial, Block Diagram Language Tutorial, Signalling Chart Language Tutorial, Top
@chapter Graph Language Tutorial

The language of the graphs (the DOT language) is documented well on the
graphviz pages at @uref{http://www.graphviz.org/, http://www.graphviz.org/}. Here we give
a brief introduction (using Msc-generator additions).

You need to start with either the @code{graph} or @code{strict graph} to specify a graph,
the second version does not allow multiple edges between the same two nodes.

After this, you can list nodes and edges enclosed between curly braces. Although there is
no need to terminate the lines with a semicolon, we suggest to do so for better readability.
Node names are underlined the first time they are used (as with signalling chart entities).

@multitable @columnfractions .3 .7
@item

@image{exA7_csh}

@tab

@image{exA7, 10cm}
@end multitable

You can use various arrow symbols (@code{->} or @code{<=}, for example) to generate
edges with different style. The @code{rankdir=LR} line instructs the DOT layout algorithm
to lay out from left to right as opposed to from top to bottom.

You can group nodes using curly braces. This is useful to add edges to all of them
in one go or to instruct the dot algorithm to lay them out on the same level.
The latter can be observed with node @samp{e1} being on the same rank
(left-right position) as @samp{D and d}. This is because
both of them are mentioned inside a set of curly braces with @code{rank=same}.
Whithout this, @samp{e1} would have been laid out right of @samp{D and d} as it
happens with @samp{e2}.

@multitable @columnfractions .4 .6
@item

@image{exA8_csh}

@tab

@image{exA8, 8cm}
@end multitable

On the example above you can also see how to assign attributes.
The @code{label} attribute can be substituted with the colon-syntax, but
note that for graphs, you need to use two colons to indicate the label (as opposed to
signalling charts), since single colons are used to indicate ports and compass direction.
The latter is useful to impact at which angle an edge arrives/leaves the node. In the
example above @code{sw} represents southwest, and the @code{==} arrow symbol results
in an edge with no arrows, but double-lined.


Graphviz supports many attributes for nodes, edges and layout algorithms, try experimenting.
You can also use the text formatting escapes for labels used by the signalling chart syntax, but only
if you specify your label with the double colon syntax.
Note that due to the peculiar design of graphviz the @code{style} attribute can have values that
affect the line, fill or the shape of nodes. Multiple such values can be specified separated
using the attribute multiple times.

@multitable @columnfractions .45 .55
@item

@image{exA9_csh}

@tab

@image{exA9, 8cm}
@end multitable


You can use the @code{subgraph} keyword to make a part of the graph separate. By
graphviz convention, if you select a name that begings with @samp{cluster_} the
subgraph will be visibly shown. This convention is only honoured by some of the
layout algorithms. As a syntactic sugar, Msc-generator defines the @code{cluster}
keyword, that prepends @samp{cluster_} to the name you supply and automatically
sets the label@footnote{If you do
not specify any name, a numeric one is generated, but is not used as label.}

@multitable @columnfractions .45 .55
@item

@image{exB0_csh}

@tab

@image{exB0, 8cm}
@end multitable

More details on the syntax of graphviz and the Msc-generator extensions can be found in
@ref{Graph Language Reference}.



@node Block Diagram Language Tutorial, Usage Reference, Graph Language Tutorial, Top
@chapter Block Diagram Language Tutorial

Very often the DOT language is used to lay out blocks in a certain geographical
arrangement, e.g., for organizational charts, or similar.
This is hard, since graphviz aims to generate a layout automatically and one
has to tweak and workaround the layout algorithm by, for example, inserting
invisible nodes, etc. This is the primary motivation for the Block Diagram
language: to be able to control, how nodes of a diagram are laid out.
This language targets network diagrams, architecture figures, software stack
figures and any figure, where blocks are arranged and this arrangement conveys meaing.
Of course, we have many mouse-based variants, but sometimes it is just easier
to do it via text. It also integrares well to command-line document toolchains,
such as tex or doxygen.

@menu
* Defining and Arranging Blocks::
* Arrows and Lines::
@end menu

@node Defining and Arranging Blocks, Arrows and Lines, Block Diagram Language Tutorial, Block Diagram Language Tutorial
@section Defining and Arranging Blocks

The simplest diagram is (from Andrew Tannenbaum's famous book) two connected blocks.

@multitable @columnfractions .5 .5
@item

@image{exC0_csh,,1cm}

@tab

@image{exC0, 1.5cm}
@end multitable

This is essentially an arrow specification with the participating blocks
automatically created (using default shape, label, layout and other attributes).
A more detailed version can be seen below.

@multitable @columnfractions .5 .5
@item

@image{exC1_csh,,2cm}

@tab

@image{exC1, 3cm}
@end multitable

Here each block is first defined to be a @dfn{box}, which essentially dictates its shape.
After the @code{box} keyword comes the @dfn{name} of the block that is used
later to specify the arrow. These names also become the label of the block if you do
not specify any other label. In this example, we do - after the colon comes the label.
Note that you do not have to name a block, names can be omitted. They are needed only
if you want to refer to the block later (such as for an arrow).

Note that you can omit the @code{box} keyword. In that case the block is created only
if it has not been created previously. If it has, only its attributes are changed,
such as in the case of block @code{B} below. Blocks that are created take their
attributes from the @dfn{running style}, which can be set by the @code{use} command.
Any block or arrow created after that is impacted by any attributes setting after
@code{use}. There is in fact two running styles, one for blocks and one for arrows.
They can be set via the @code{blocks use} and @code{arrows use} command. Writing just
@code{use} will impact both.

@multitable @columnfractions .5 .5
@item

@image{exD6_csh,,3cm}

@tab

@image{exD6, 6cm}
@end multitable


If just listed one after the other, the blocks are laid left-to-right. This is
called a @dfn{row}. You can make blocks go top-to-bottom by inserting them into
a @dfn{column}, or @dfn{col} for short. On the figure below, blocks @code{B}
and @code{C} are part of an nunnamed column, where block @code{A} and the
unnamed col are in a row (that is laid left-to-right). The @code{space} command
is used to insert a bit of extra blank space between block @code{A} and the
unnamed column.

@multitable @columnfractions .5 .5
@item

@image{exC2_csh,,2cm}

@tab

@image{exC2, 1.5cm}
@end multitable

You can also see that it is easy to specify several arrows at once, by listing
multiple destinations (or sources) in a comma-separated list.


If you want to enclose two blocks in another block, add them as @dfn{content}.
In the example below the unnamed col has been replaced to an unnamed box.
We use the @code{boxcol} keyword, this is the same as @code{box}, but arranges
its content in a column instead of a row by default.
After the @code{boxcol} keyword, attributes can be specified in square brackets, similar
to other languages of Msc-generator. In particular, we set the corners of the
unnamed box to round.

@multitable @columnfractions .5 .5
@item

@image{exC3_csh,,3cm}

@tab

@image{exC3, 2cm}
@end multitable

Next, we can add a label to a @dfn{container block}, that is, one which has
content. This, however, moves blocks @code{B} and @code{C} downwards
messing up the symmetry of the arrows. This is because in a row elements are
vertically centered by default, thus block @code{A} is vertically centered
to the unnamed container block right to it. (Note also that blocks in a column
are also centered horizontally by default. Note also, that you can define
multiple block with one @code{box} command.)

@multitable @columnfractions .6 .4
@item

@image{exC4_csh,,3cm}

@tab

@image{exC4, 3cm}
@end multitable

To fix the arrow asymmetry problem, we can add a named column (@code{BC})
inside the container box and make block @code{A} align to that vertically.
For this we use the
@code{middle} attribute on the block @code{A}. This makes the block's middle
to vertically align to the middle of another block.
This way we can override the default row alignment between block @code{A} and
the unnamed container block.
Note that you can forward reference @code{BC} even before it was defined.

@multitable @columnfractions .6 .4
@item

@image{exC5_csh,,3.7cm}

@tab

@image{exC5, 3cm}
@end multitable

Adding this extra column is a bit cumbersome just to group blocks for alignment.
You can shortcut
it by listing a group of blocks directly in the @code{middle} attribute.
Msc-generator will calculate the middle (or top, bottom or any other part)
of the blocks combined and will align there.

@multitable @columnfractions .6 .4
@item

@image{exE7_csh,,3cm}

@tab

@image{exE7, 3cm}
@end multitable

Continuing the example, we could add two more blocks with different alignment.
The attributes @code{top} and @code{bottom} make the top and the bottom of
the block to align to that of another block. Note that the blocks @code{A}
and @code{E} are laid out further apart from one another - this is the only
way to fulfill the alignment requirements we have specified via the attributes.

@multitable @columnfractions .7 .3
@item

@image{exC6_csh,,4cm}

@tab

@image{exC6, 3cm}
@end multitable

You can use the @code{below}, @code{above}, @code{leftof} and @code{rightof}
@dfn{alignment modifiers} in front of any block to place it in relation to
the previous block. In the example below, @code{below} refer to the big container
@code{Cont}, so block @code{N} is placed below it. In turn, @code{leftof} refers
to block @code{N}, so block @code{M} is placed left of it.@footnote{Alignment
modifiers also result in side-by-side placement (subject to the respective
margins). Thus @code{below} means that the Y coordinate of the bottom of the
previous block (plus its bottom margin) equals to the Y coordinate of the current
block (minus its top margin).}

@multitable @columnfractions .7 .3
@item

@image{exC7_csh,,5cm}

@tab

@image{exC7, 3cm}
@end multitable

In addition to @code{middle}, @code{top} and @code{bottom} there are three more
alignment attributes that can be used to govern horizontal alignment. They
are called @code{center}, @code{left} and @code{right}. Since I always confuse @code{middle}
(the vertical one) and @code{center} (the horizontal one), Msc-generator also has
four aliases to these two: @code{xcenter}, @code{xmiddle}, @code{ycenter}
and @code{ymiddle} to disambiguite which axis is along with we seek the center position.

As value for these attributes, you can specify not only a block name, but also
a part of the block after the at sign @code{@@}. Furthermore, alignment modifiers
can be followed by a block so that they can work no blocks other than the previous
ones.

@multitable @columnfractions .55 .45
@item

@image{exC8_csh,,3cm}

@tab

@image{exC8, 5cm}
@end multitable

It is possible to have not only boxes, but any arbitrary shape for a block.
This can be achieved via using the @code{shape} keyword followed by the name
of the shape instead of the @code{box} keyword. As a shorthand, the asterisk
symbol (@code{*}) can also be used. A handful of basic shapes are defined
in the default design library and can be used. You can also add text without any
borders or background. This is useful as explanatory notes. Those can be added with the
@code{text} command as seen below.

@multitable @columnfractions .5 .5
@item

@image{exD3_csh,,3cm}

@tab

@image{exD3, 4cm}
@end multitable

You can define your own shapes via the @code{defshape} command, but
 defining a separate shape for something simple is often too complicated.
To this end, Msc-generator allows you to @dfn{join} blocks that
are overlapping or touching. Joing blocks will remove any internal lines and keep
a single contour. Below you can see 4 blocks without and with an additional
@code{join} command.

@multitable @columnfractions .54 .22 .22
@item

@image{exF7_csh,,4.5cm}

@tab

@image{exF6, 2.5cm}

@tab

@image{exF7, 2.5cm}
@end multitable

Note that the fill of the joined blocks is kept, together with any label.
You can assign any line, fill or shadow attributes to the joined block, which
override the line, fill and shadow attributes of the original blocks. By default,
only line attributes are on, thus the joined block has no fill or shadow.

Another way to define a new block is to @dfn{encircle} a set of existing blocks.
This can be done by the @code{around} keyword. In the middle figure of the below
example you can see that we use two boxes (@code{A1} and @code{A2}) and an oval
(@code{A3}) to encircle various boxes. On the right figure, we have added
the @code{join} command at the last line of the example, which combined the two
boxes. Note that even if @code{A3} does not touch or overlap with @code{A1} or
@code{A2}, it can still be part of the join.


@multitable @columnfractions .4 .3 .3
@item

@image{exF9_csh,,4cm}

@tab

@image{exF8, 3.5cm}

@tab

@image{exF9, 3.5cm}
@end multitable

Such @code{around} blocks have no fill by default.
Note that we have used @dfn{compound names} when specifying the boxes to encircle.
Each of the four column had a name (@code{x}, @code{y}, @code{z} and @code{v}),
but inside the columns the box names were re-used
(@code{a}, @code{b}, @code{c} and @code{d}). To name a specific block you can use
the name of the containing block to disambiguite before the block name.

When drawing diagrams, a technique is often used to indicate that we have several
instances of a block. This technique can be expressed by prepending the
@code{multi} keyword in front of any block definition.

@multitable @columnfractions .5 .5
@item

@image{exG0_csh,,4cm}

@tab

@image{exG0, 7cm}
@end multitable

You can apply a number after the @code{multi} keyword to specify how many copies
do you want, the default is 3. You can still refer to any blocks contained within
(@code{B.o} in the example) and two more blocks: @code{front} and @code{back} to
refer to the first and last in the series of copies.

You can also copy an already existing block. This is a quick way to define larger diagrams.
You can give the copy a name, change its attributes or even replace its content (or add to it).

@multitable @columnfractions .45 .55
@item

@image{exG8_csh,,6cm}

@tab

@image{exG8, 7cm}
@end multitable


@node Arrows and Lines, , Defining and Arranging Blocks, Block Diagram Language Tutorial
@section Arrows and Lines



You can use various arrow symbols (as in other languages) to impact the appearance of
the arrow. like @code{>>} or @code{=>}.
You can even use symbols without arrowheads (@code{--}, @code{..},
@code{++} and @code{==}) to get a simple line..
In addition, you can specify additional attributes in square brackets after the arrow.
These include line, arrowhead and text attributes.

@multitable @columnfractions .5 .5
@item

@image{exD0_csh,,4cm}

@tab

@image{exD0, 5cm}
@end multitable

You can add labels to arrows simply using the colon label syntax.
You can also add further labels after the arrow, specifying their position
along the arrow as percentage of length. By default the labels are placed above
the arrow, you can influence it via the @code{label.pos} attribute. If you
indicated the @code{mark} keyword before the label, a small mark will be added
to the arrow. This mark is an arrowhead defaulting to @code{gvstyle=tick}.

@multitable @columnfractions .5 .5
@item

@image{exC9_csh,,4.3cm}

@tab

@image{exC9, 5cm}
@end multitable

Now, it might be that you would like to route the long connection below the
container block. In such cases you can use the @code{via} attribute for an
arrow. You can name a block and any of @code{top}, @code{left}, @code{right}
or @code{bottom} after it. The arrow will try to go that way.

@multitable @columnfractions .5 .5
@item

@image{exD2_csh,,4cm}

@tab

@image{exD2, 5cm}
@end multitable

Arrows are routed around blocks in-between the two ends of the arrow.
This can be prevented by setting the @code{allow_arrows} attribute.

@multitable @columnfractions .5 .5
@item

@image{exD1_csh,,4cm}

@tab

@image{exD1, 5cm}
@end multitable



Arrows can start and end not only at blocks.
Based on the block layout, you can specify 2D coordinates on the diagram, which can
serve as start, end and waypoints for arrows.

To specify a coordinate, use two block sides, separated by a comma and enclosed in parenthesis,
for example: @code{(a@@top, b@@right)}. You can also add offsets in pixels, like
@code{(a@@top+10, b@@right-5)}.

@center @image{exG1, 12cm}

Arrows can be laid out using several algorithms. Use the @code{routing} attribute
and choose one between @code{horizontal}, @code{vertical}, @code{grid}, @code{straight},
@code{manhattan}, @code{polygon} or @code{curvy}. (Grid means either horizontal or vertical.)
In case of @code{polygon} and @code{manhattan}, you can set @code{line.corner} to influence
the appearance and make the vertices smoother via @code{line.corner=round}.
The default is @code{curvy}.

@center @image{exE1, 13cm}

In case of @code{vertical}, @code{horizontal} or @code{grid} the line will be drawn in the middle
of the vertical or horizontal overlap of the two blocks, respectively.

@multitable @columnfractions .6 .4
@item

@image{exG2_csh,,2.5cm}

@tab

@image{exG2, 5.5cm}
@end multitable

You can govern where arrows end via @dfn{ports}, similar to graphviz. These
should be specified after the block name and the at symbol (@code{@@}).
Boxes have one port on each side and vertex. You can also use a @dfn{compass point} as port.
Each of these also influence the direction in which the arrow shall leave
or arrive at the block. With the @code{distance}
attribute you can govern, how wide a certain block (or all blocks) are
routed around or - in case of starting and ending blocks - how wide an arc
the arrow makes at its start or end. The default is 5 pixels for the former
and 10 pixels for the latter.

@multitable @columnfractions .6 .4
@item

@image{exH9_csh,,3cm}

@tab

@image{exH9, 5cm}
@end multitable

Each shape may define its own ports (besides the compass points, which are valid
for all shapes). For example, the shape @code{actor} has one compass point for each
hand and leg, plus its head.
In the below example, we also use a @dfn{direction marker} in addition to the port
to explicitly govern the direction the arrow start in or ends from.
(The attribute @code{label.align} determines where on the arrow the label is placed
with 0 being its start and 100 being its end (default is 50). @code{label.pos} on the other hand specifies
which side of the arrow the label is (default is above).)

@multitable @columnfractions .6 .4
@item

@image{exI0_csh,,4cm}

@tab

@image{exI0, 5cm}
@end multitable

If two arrows would overlap at their start or end, they are automatically shifted a
bit to show up as separate arrows. (Note, as well, that the arrowheads follow the
curvature of the arrow. The @code{xmul} attribute simply makes them longer.)

@multitable @columnfractions .5 .5
@item

@image{exI7_csh,,3cm}

@tab

@image{exI7, 5cm}
@end multitable



You can use a syntax similar to arrows to specify separator lines.
Note that the default routing for lines is @code{straight}, which does not
go around blocks in the way, but just crosses them.
If you set @code{routing=curvy}, the line will route around blocks in the
way arrows do, see the red line on the example below.

@multitable @columnfractions .6 .4
@item

@image{exG4_csh,,3.5cm}

@tab

@image{exG4, 4cm}
@end multitable

Finally, a more elaborate version of lines, labels and markers. Note that
the plain numbers used in the coordinates are interpreted relative to the
inner margin of their container block. (If there is no outer block then to
the diagram canvas.) The numbers after the @code{mark}
commands are not followed by a percentage sign, so they are interpreted
as pixels from the beginning of the line.

@multitable @columnfractions .55 .45
@item

@image{exH8_csh,,3.5cm}

@tab

@image{exH8, 4cm}
@end multitable



@node Usage Reference, Reference for Common Language Elements, Block Diagram Language Tutorial, Top
@chapter Usage Reference

In this section we explain details of the GUIs. Throughout the chapter we will talk about the
MFC and CLI GUIs mixed.

@menu
* Multiple Chart Types::
* Design Library::
* External Editor::
* Internal Editor::
* Example Library::
* Renaming elements::
* Options::
* Scaling Options::
* Working with Multi-page Charts::
* Advanced OLE Considerations::
* Autosave and Recovery::
* International Text Support::
* Command-Line Referece::
* Fonts::
@end menu

@node Multiple Chart Types, Design Library, Usage Reference, Usage Reference
@section Multiple Chart Types

From version 5.0 Msc-generator supports multiple chart types. Each chart type
has its own textual language, which are similar to some extent (use attributes
in square brackets, options and curly braces to structure the chart).

Both GUIs supports color syntax highlighting, hinting, auto-complete,
small indent, element controls and tracking for all (most) languages. The
GUIs ask what type of chart do you want to create every time it is started or
when a new chart is created.

Each language has a set of assiociated file extensions. By default, the file
extension is used to determine the type of chart when a file is opened in the
GUI or processed on the command line. This can be overridden on the command
line with @code{-S}. There is always a @dfn{primary} extension for each language,
this is used to name the language (on the command line) and also for chart designs,
see below.

The currently supported languages and their extensions is listed below (the
first extension is the primary one).

@multitable @columnfractions .18 .22 .6
@headitem Chart type
@tab Extensions
@tab Comment
@item Signalling Chart
@tab .signalling, .msc
@tab This chart type is the original chart type of Msc-generator.
@item Graphviz Graph
@tab .gv, .graph, .dot
@tab This language is the superset of the DOT language.
@item Block Diagram (experimental)
@tab .block
@tab This language describes block diagrams for architecture or software stack figures.
@end multitable

The first panel on the Home tab of the MFC GUI displays the current file type and the controls
relevant for that given chart type. For example, on the picture below, the
controls for graphs are shown. Compared to signalling charts there are two
differences. First, you can also select the graphviz layout algroithm to apply. This is
equivalent to using @code{layout=<layout>;} inside a graph. Second, you can
collapse and expand all cluster subgraphs with one click. (Applicable only when the
@samp{dot} layout algroithm is used.)

@ifnotinfo
@center @image{MscGen-Toolbar-Graph, 15cm}
@end ifnotinfo

In the CLI GUI the design and layout can be selected in @code{Settings}.

@node Design Library, External Editor, Multiple Chart Types, Usage Reference
@section Design Library

For each of its languages Msc-generator comes with a bunch of Chart Designs
(and Shapes, see @ref{Chart Designs} and @ref{Entity Shapes}).
The designs available can be viewed in the design selector combo box on the ribbon
(MFC GUI) or in @code{Settings} (CLI GUI).

The files describing the chart designs (and shapes) are of the same language
that the language of the chart they provide designs for. These files shall
have the primary extension of the chart type.

Note that you should define only designs and shapes in design libraries (for
languages that support them). Colors, styles and procedures shall be defined
as part of a design. If you want to define one color, style or procedure to be
available without applying a design, add them to the @code{plain} design.
Any styles, colors or procedures defined in a design library outside a design
will probably be unavailable later - however, the behaviour is undefined and
Msc-generator may generate errors for this in the future. Similar, avoid commands
in the design library that actually generate chart elements.

On Windows the file describing the default designs and shapes are installed
besides the executable. On Linux and the Mac these files are incorporated into the
executable so that msc-gen can be a standalone file.
Specifically on Windows at startup for each supported chart type Msc-generator
looks for a file called @code{designlib.xxx} in the directory where the
executable is located (xxx is the primary extension of the chart type). If
not found, the file @code{original_designlib.xxx} is searched (of which a
default one is placed there by the installer)@footnote{This mechanism was provided
to enable the user to (re)define chart designs and is retained for backwards
compatibility only. (The idea was that @code{original_designlib.xxx} is
overwitten, when a newer version of Msc-generator is installed, whereas
@code{designlib.xxx} is not. The current recommended practice is to
add your own designs to new files in the roaming AppData folder, see below.}.
If any found, the content is parsed as regular chart text before any user chart text.

You are free to create and modify your own design
files@footnote{However, please avoid any construct in design, which result in
visual elements. Also try not to create files that result in warnings, errors.}.
Designs (and shapes) defined in these will be added to the list of available
designs in the GUI and can be referred to from files processed via the command
line. On Linux and the Mac place your design files to the @code{.msc-genrc/} folder,
that will be searched for under your HOME directory or
your folder of preference specified by the @code{MSC_GEN_RC} environment variable.
On Windows place these to the roaming appdata folder, which is under
@code{Users\<user name>\AppData\Roaming\Msc-generator} on Windows 7 and 8.
Any file in the above directories with the primary extension of a supported
chart type will be read by Msc-generator in no specified order before processing
your chart. All other files are silently ignored.

@node External Editor, Internal Editor, Design Library, Usage Reference
@section External Editor

Although there is a built-in editor in Msc-generator GUIs, you can also use an
external text editor of your choice with the MFC GUI. When you press Ctrl+E or click on
@samp{Text Editors...|External Editor...} button on the ribbon, an external
text editor is started, where you can edit the chart description. If you perform
save in the text editor, the chart drawing is updated, so you can follow your
changes visually. Also, if there were errors or warnings, they are displayed in the
usual manner. If you select an error, Msc-generator will instruct the external
editor to jump to the location of the error (if the external editor supports
this functionality.)

During the time you are working with an external editor, the built-in text
editor becomes read-only. You can exit the external editor any time to return to
the built-in one. By pressing Ctrl+E or clicking on the @samp{Text
Editors...|External Editor...} ribbon button again, Msc-generator attempts to
close the external editor (which will probably prompt you to save outstanding
changes).

You can select the text editor to start in @code{Preferences|External Editor}.
You can select between the Windows Notepad, Notepad++ or any editor of your
preference. The author finds Notepad++ a very good editor, so I included
specific support@footnote{You can download Notepad++ from
@uref{http://notepad-plus.sourceforge.net/}}.

Since version 4.6 Msc-generator supports unicde characters via both UTF-8 and
UTF-16 input, thus any of these can be used by the external editor to save
the file. See @ref{International Text Support} for more.


@node Internal Editor, Example Library, External Editor, Usage Reference
@section Internal Editor

Since version 2.3 (MFC GUI) or 7.0 (CLI GUI) Msc-generator has an internal text editor
integrated with the GUI. Via tracking mode, you can quickly jump to a particular element in the
text, but can also quickly see, what is the result of a specific line.

In the MFC GUI there is a separate Ribbon category governing options for the internal editor.
On its first pane you can toggle if you want the current line highlighted and/or line
numbers displayed. The other features of the internal editor are explained below.
If you accidentally close the internal editor, use the @samp{Text Editors...} button on the
Edit pane of the Home category to turn it back on.

@ifnotinfo
@center @image{MscGen-Options2, 15cm}
@end ifnotinfo

The CLI GUI supports the same features, but has less customization options (in @code{Settings})
for simplicity.

@menu
* Smart Indent::
* Color Syntax Highlighting::
* Typing Hints and Autocompletion::
@end menu

@node Smart Indent, Color Syntax Highlighting, Internal Editor, Internal Editor
@subsection Smart Indent

The internal editor supports automatic indentation for TAB, RETURN and BACKSPACE
keys and braces. TAB and Shift+TAB works also with selections as in most programming
editors. Selecting a block of text (or using Ctrl+A to select the entire file) and
pressing TAB or Shift+TAB has the same effect as if applied to each line separately.

In addition Msc-generator detects the beginning of multi-line labels and attribute
lists and can align all subsequent lines of the label or attribute list to the
first.

The parameters of automatic indentation can be set on the @code{Indent} panel of the
@code{Internal Editor} ribbon category.
Checking the @code{Auto Smart Indent} check box makes the tool
automatically indent after presing RETURN, BACKSPACE, opening or closing braces and
square brackets. This way indentation is automatic as you type.

The @code{TAB auto-indents} checkbox governs what happens
when you press the TAB key. If it is on, the whole line of the cursor
(or the whole selection) is auto-indented.
If it is off, simply a TAB character is inserted or the whole selection
indednted uniformly by the TAB size, set below.

The amount of space added by smart indent can be set in the
next four edits. @code{instructions} govern how much
instructions inside braces are indented; @code{attributes}
are used to indent attribute lists; @code{blocks} govern, how a
subsequent block in a parallel block, box or pipe series is indented,
while @code{inside} governs, how anything else inside an instruction
is indented, such as options in an option list, entities in an entity list, etc.

Finally, the last two check-boxes govern, if special indentation for labels
and attribute list are applied or not. See the below figure for explanation.

@image{ex59_csh, 9cm}

@node Color Syntax Highlighting, Typing Hints and Autocompletion, Smart Indent, Internal Editor
@subsection Color Syntax Highlighting

The internal editor also supports Color Syntax Highlighting.
On the @code{Internal Editor} pane you can select one of four color schemes.
There are four pre-defined schemes: Minimal, Standard, Colorful and Error oriented.
The first three applies increasing amount of
color, while the last is a minimalist scheme but with potential errors heavily
highlighted@footnote{We note here that all four schemes underline entities at
their first use. This is to help you avoid a mis-typed entity name.}.
At the moment you can not customize individual colors in the schemes.
The examples in this document were colored using the @samp{Standard} color
scheme.

In the preferences it is also possible to select to underline parse error
locations (see @code{Hint Errors as You Type}).
In this case you get instant feedback on syntax problems. Finally,
it is also possible to request error messages for any error that has been
underlined in the internal editor (see @code{Hint Errors in Window}).
These explanatory messages appear in the
same window as compilation errors, but they are prefixed with @samp{Hint}.
If the error they refer to is corrected, they disappear.

Note that during text edit Msc-generator does not perform a full parsing
of the text to enhance performance. For example, correctness of attribute names
and values is not verified, merely syntax.

@node Typing Hints and Autocompletion, Options, Color Syntax Highlighting, Internal Editor
@subsection Typing Hints and Autocompletion

When turned on, the internal editor can also provide suggestions on how to
complete the phrase you started typing, when pressing Ctrl+Space.
You can use the up/down arrow
keys to select between the offered alternatives and press enter or TAB to
select it. Alternatively, you can continue typing the keyword or hit any
non-alphanumeric character, which will automatically select the highlighted
hint and continue after.

The hints provided are associated with a small icon showing the type of the
symbol. On the example below, an entity name (@samp{a}), an option name,
a keyword, a design name and a style name is shown.

@ifnotinfo
@center @image{hint_combined, 3cm}
@end ifnotinfo

Various attribute values offer a graphic representation to ease
selection.@footnote{Shapes defined in the current file do not appear with
a thumbnail representation. Only shapes defined in design libraries do.}
The items in italics do not represent actual text to be inserted into the
chart, so you cannot select them. They are more like descriptions of what
you can write there.

@ifnotinfo
@center @image{hint_values, 15cm}
@end ifnotinfo

On the @code{Internal Editor} category of the ribbon you can control how much
suggestions you will get and how
they are displayed. You can turn hints entirely off.
The two bottom checkboxes in the @code{Auto Completion} panel
govern if the list of hints is grouped along dots (to reduce the
length of the list) and if hints that are not matching what you have typed
so far shall be removed or not.
If grouping is on, attributes starting with the
same text, such as @code{line.color} and @code{line.width} appear as a combined
entry as @code{line.*}. Pressing the dot @samp{.} key will automatically
auto-complete the common part.
If filtering is turned on, only those hints are
displayed which begin the same as the word under the cursor. If you continue
typing, the list is narrowed by every character. If filtering is off all values
valid at the location of the cursor are shown.

Msc-generator can provide you hints even without pressing the Ctrl-Space. In the
subsequent panel you can govern in what language contexts do you want to
receive such automatic hints. In general it is best to experiment with these settings
and see what you like.

If you press Ctrl+Space and there are meaningful suggestions, the hint box pops up
even if automatic hints are turned off. If there is only one possible way to finish
what you have started typing, that ending is automatically inserted
(word auto-completion).

@node Example Library, Renaming elements, Internal Editor, Usage Reference
@section Example Library

Msc-generator languages have quite many features and are not easy to learn.
Hints provided by Ctrl+Space helps you to explore what attributes an element
has and what potential values can these attributes take.

In addition to hints, Msc-generator contains an interactive example library
demonstrating the features of each of its languages@footnote{For the dot
language, we only demonstrate the Msc-generator additions.}. Just press the
@code{Examples} button on the Chart panel of the Home category of the ribbon.
A dialog box appears (close with the Esc key) listing the examples, the chart
text for the selected example and the resulting chart.

@ifnotinfo
@center @image{MscGen-Examples, 15cm}
@end ifnotinfo

The example list can be narrowed by keyword search, just start typing the keyword
you are interested in.

The examples are editable. When you make a change to an example, the result of it is
immediately reflected in the chart to the right. This allows you to quickly experiment
with the language without changing the chart you work on. Any changes you make to the
examples will be forgotten the moment you exit Msc-generator.

@node Renaming elements, Auto Split, Tracking Mode, Usage Reference
@section Renaming elements

Right-clicking an entity name (for signalling charts), a block name (for block diagrams)
or a node name (for graphs) brings up the context menu for the internal editor. In that
there is a @code{Rename...} menu item, which replaces all occurrence of this name in the
source file to something else. Note that this does not replace the @emph{label} of the
entity (if you have specified one), block or node (which will be shown in the compiled
graphics), but how it is referred to from the source file. The resulting chart, diagram
or graph remains visually the same after such a rename. (Unless you use some entity names
as label.) However, it enables you to quickly change how you refer to these elements.

In case of signalling charts the value of the @code{relative} entity attribute
(@ref{Entity Attributes}) is the name of another entity. These attribute values
are not renamed - you need to manually adjust the name.

In case of block diagrams, names are hierarchical. That is a @code{box B} inside
a @code{box A} is called @code{A.B} in its full name - even if it can be referenced
as just @code{B} from within @code{A}. (More than two levels of nesting is possible.)
When you click on a name with multiple levels (such as @code{A.B}) only one part of it
will be renamed - based on where you click. Only the actual block specified by the
clicked name is renamed (even if there are blocks with the same name elsewhere), but that
block is renamed at every place it is mentioned (even in attribute names and alignment
modifiers, @ref{Alignment modifiers}.

It is possible to perform the replace only in one part of the source text. Simply select
the desired part and click on the element to rename (may be outside the selection). Only
the mentions of this entity inside the selection will be replaced. This allows you switch from
using one element to another (spilt a single element into two).
Using the name of an already existing element will make the renamed ones refer to the already
existing element (merge two elements into one).



@node Options, Working with Multi-page Charts, Renaming elements, Usage Reference
@section Options

In the MFC GUI selecting the @code{Preferences} category on the ribbon allows you to set a
few options of Msc-generator.

@ifnotinfo
@center @image{MscGen-Options, 15cm}
@end ifnotinfo

In the first category you can specify what is the text of the chart that pops up when a new
chart of the current type is created. Just press the button and the current text will become the
default for the current chart type. You can place your frequently used constructs here to be readily
available when you start a new chart; or just delete everything here to start
real empty.

Under @samp{Options} you can set a few compilation options. When pedantic is set
Msc-generator enforces stricter language interpretation. For signalling chart, it
means generating a warning if an entity is not declared explicitly before
use. For graphs, it means generating a warning for each use of directed edges in
undirected graphs and vice versa (graphviz does not allow such mixing), but when
turned off, mixing directed and undirected edges in a graph becomes possible.
For Block Diagrams, it prevents auto-generating an block when mentioned without
a @samp{box} or similar keyword. This allows forward referencing blocks in arrow
definitions (by avoiding their creation instead of referencing a later definition).
Turning the second option on will supress the generation of warning
messages altogether (including the ones generated due to the pedantic option).
Checking the third option will show the full path of the filename in error messages.
This is useful when using @code{include} and suspecting the precise identity of
the included file with an error.
When @samp{Ask char type} is set, Msc-generator displays the list of available
chart types at startup and when creating an empty document and you can select one.
If unchecked, the last file type is used always.
When @samp{Technical Info} is ticked, a summary of the compilation is shown among the
errors and during compilation colored progress indicators show the various stages of
compilation. This is mostly for debugging.
In the third column you can control automatic behaviour. @samp{Auto paste clipboard}
makes Msc-generator to automatically paste the content of the clipboard, whenever an
alt-text embedded chart is copied to it. (Except when you have unsaved changes in the
currently edited chart. In that case you can use the @samp{Paste Entire Chart} button
in the @samp{Home} ribbon category.) Checking @samp{Auto Save} will save the chart
text every time you make changes (except for OLE embedded charts). Finally,
@samp{Instant compilation} will recompile the chart every time you make changes.

On the @samp{Appearance} panel you can first select the color of the tracking overlay
(what flashes when you click on a chart element).
@samp{Show Page breaks} governs if a dashed line is drawn to show where page breaks
are when watching all of the pages. See @ref{Multiple Pages} for more
information. Lastly you can also set the maximum zoom factor selected by the
@var{Overview} and @var{Fit to Width} automatic zoom modes. You may want to
increase this for very large screens. See @ref{Zooming}.

The @samp{Mscgen compatibility} panel is applicable only to signalling charts and
governs how Msc-generator switches to backwards compatibility mode with mscgen.
See @ref{Mscgen Backwards Compatibility} for more.

On the last panel you can specify which external text editor to use.
You can select any editor using the first option.
In this case you have to give a command-line
to start the editor and one to invoke to jump to a certain line by
pressing the button to the right.  The latter
can be omitted if the editor does not provide a command line option to jump to
a certain location in an existing editor window. Use @samp{%n}
for the filename and @samp{%l} for the line number; these will be replaced
to the actual filename and linenumber at invocation.

@node Working with Multi-page Charts, Scaling Options, Options, Usage Reference
@section Working with Multi-page Charts

Msc-generator supports multi-page charts. These may be useful when you want,
e.g., to print a long signalling chart. For signalling charts you can manually
start a new page by typing the  @code{newpage;} command or let Msc-generator
automatically paginate for you. See more in @ref{Multiple Pages}. In case of
graphs, each graph is laid out to a separate page. Block Diagrams have no
pagination at present.

You can select on the ribbon/menu bar which page to view. This
setting is also saved with embedded charts, and of course only the selected page
is shown in the container document. You can also select to view all pages. When
viewing all pages, Msc-generator marks page breaks with a dashed or dotted line
for manual and automatic page breaks, respectively, and also prints page numbers
to the left. This behaviour can be turned off in the preferences. (See @ref{Options}.)

When you embed a multi-page chart (either as OLE object or via alt-text embedding) to
a document, you can chose to show only one page of it. The text of the whole chart
will always be saved in the embedding, so later you can easily change the page displayed.
Simply select the page before copying to the clipboard (or saving an already embedded
chart).

In the MFC GUI the last pane on the Home category of the ribbon governs automatic
pagination. The first checkbox turns it on.
The paper size can be selected in @samp{Print|Print Setup...}, whereas margins,
page alignment and scaling can be selected in Print Preview.
Ticking the the second checkbox will result in a heading to be displayed for
the active entities at the top of every page.

In the MFC GUI you can preview a multi-page chart before printing using the Print Preview
option from the main menu. It behaves similar to Print Preview in other programs.

@ifnotinfo
@center @image{MscGen-PrintPreview, 14cm}
@end ifnotinfo

Here you can print or export to PDF@footnote{When you export a multi-page chart
from Print Preview, Msc-generator automatically exports to a multi-page PDF file.
When you use the Export option from the main menu, Msc-generator asks what you want.}.
You can also set Automatic Pagination and Auto Headings from here, but you can also
set, how the chart pages are sized; how they are
aligned within the physical pages and also what margins to apply. The former option
can take @dfn{Fit width} and @dfn{Fit page}@footnote{They correspond to the @code{-s=width}
and @code{-s=auto} command-line options, respectively.}. In the former case the scaling
factor is selected to fit the width of the chart to the page, this is perhaps the most
useful selection to print long charts combined with automatic pagination. In the latter
case, the scaling is set uniformly for all pages to fit the longest one. With automatic
pagination this is in effect equivalent to @dfn{Fit width}.


@node Scaling Options, Advanced OLE Considerations, Working with Multi-page Charts, Usage Reference
@section Scaling Options

If the chart is exported to a PNG image then after selecting the
filename an additional dialog box appears where you can set scaling options.
In all but the last option the original aspect ratio of the chart is kept.
After the @samp{No scaling} option the native size of the chart is shown.

@ifnotinfo
@center @image{MscGen-ScaleOptions, 7.5cm}
@center @image{MscGen-ScaleOptions-CLI, 7.5cm}
@end ifnotinfo

@node Advanced OLE Considerations, Autosave and Recovery, Scaling Options, Usage Reference
@section Advanced OLE Considerations

@menu
* Graphics of Embedded Charts::
* Linking::
@end menu

@node Graphics of Embedded Charts, Linking, , Advanced OLE Considerations
@subsection Graphics of Embedded Charts

The technology used to embed charts into other document, called OLE, has certain
limitations on graphics@footnote{Only drawing operations permitted in old-style
Windows Metafiles (developed in 16-bit Windows times) are permitted by design.}.
To work around these, Msc-generator employs a few simplifications.

@itemize
@item Due to clipping limitations, certain arrowheads, like @samp{line}
draw differently on signalling charts.
@item Due to font limitations, the label of slanted arrows on signalling charts
are drawn with limited resolution and looks somewhat different than non-slanted text.
@item Due to missing gradient fill support, gradient fills and shadows are
approximated. At large magnification this becomes visible.
@item Due to the limited size of the coordinate space, placement of elements in
very large charts appear imprecise.
@item Due to lack of transparency support, transculent areas (such as pipes)
are drawn on a bitmap, a @dfn{fallback image} and then inserted, see below.
@end itemize

If a chart contains a lot of fallback images, the size of the embedded object
can become large, several megabytes for a chart. To control the size of the
embedded chart and eventually that of your container document,
for embedded charts a new category ("Embedded Object") appears on
the ribbon, allowing you to adjust the quality of the fallback images.

Note that this issue is fixed in newer versions of Microsoft Office, which
are able to compress the images in embedded objects.

@ifnotinfo
@center @image{MscGen-EmbeddedOptions, 8cm}
@end ifnotinfo

When this category is selected, Msc-generator shows the chart as it will appear
in the container document. Fallback image locations are briefly highlighted
when switching to this category. The ribbon category shows how large the embedded
object will be (if not compressed by the container applications) and what
percentage of the chart is drawn on fallback images (if any).
There is a slider allowing you to set the resolution of the fallback images.
You can observe the resulting image size and visual quality immediately.

@node Linking, , Graphics of Embedded Charts, Advanced OLE Considerations
@subsection Linking

You can also choose to insert a Link to a copied chart instead of embedding it
into the document. In this case updating the source chart will get
reflected in the document, as well. You can also insert a link to only a page
of a chart, by copying that page to the clipboard via the drop-down menu of the
@var{Copy Entire Chart} button.

Note, however, that you cannot insert a link to a chart that is not saved on
disk, but is yet @samp{Untitled}. In addition, not all container applications
implement the full range of linking features.
@itemize
@item LibreOffice and OpenOffice do not allow links to be inserted into documents.
You can only embed charts in their documents.
@item Microsoft PowerPoint allows links to be inserted into a slide, but does
not allow other programs to link to a chart embedded in a slidepack. This includes
the case when you want to insert a link into a slidepack that points to a chart
embedded in the very same slidepack.
@item Microsoft Excel implements full linking features, that is it allows
you to insert links into worksheets, but also allows you to insert a link pointing to
a chart embedded in a worksheet into other documents (or the same worksheet). You
can even insert links that point to a single page of a chart embedded in a worksheet.
(You can do this by opening the embedded object in Msc-generator and select
@samp{Copy Page #1}, and use Paste Special to insert a link.)
@item Microsoft Word allows you to insert link to charts that are saved in files
or are embedded in some other container (such as an Excel worksheet). It also allows
others (including Word itself) to link to a full chart embedded in a Word document,
but does not allow linking to a page of a chart embedded in a word document.
If you invoke @samp{Copy Entire Chart} or @samp{Copy Page #x} from within
Msc-generator for a chart embedded in a Word document, the link will not work.
However, if you copy the chart to the clipboard from Word (and then you can copy
all of it) then if you insert a link via Paste Special, you will geta valid link.
@end itemize

There is a suspected bug in
Word 2003 that fails linking to a single page of a chart embedded in a Word document.
@footnote{To link to a full chart embedded in Word, make sure you place chart
to the clipboard using Word and not using Msc-generator.}

@node Autosave and Recovery, International Text Support, Advanced OLE Considerations, Usage Reference
@section Autosave and Recovery

Since version 5.0 the MFC GUI supports the Restart Manager introduced to Windows
in Vista. That is, if Msc-generator crashes (or needs to be stopped due to an installation), its status
is saved and is automatically restarted.

The documents you are working on are autosaved.@footnote{The autosave location is
@code{C:\Users\<username>\AppData\Local}, you can manually recover autosaved files
from there.} Clicking on the @samp{Autosave and Recovery} category on the ribbon
opens a list of autosaved files on the side.@footnote{Any autosaved version of
the currently open document is omitted from the list.} Double-clicking a file will
recover it either by overwriting the current chart text or by inserting it at
the cursor (you can select after double-clicking). You are also offered the option
to delete the autosaved file after recovrey. On the ribbon you can filter the
list of autosaved file to the current chart type and make Msc-generator to
open the list of autosaved files at startup. You can also delete all autosaved
files at once.@footnote{If you filter the list of autosaved files to the current
chart type then clicking the @samp{Delete autosaved files currently showing}
button will not delete the autosaved files of other chart types.}

Note that in the rare event of an Msc-generator crash@footnote{The graphviz
library crashes on some chart input. This is something I cannot easily fix. Hence
the addition of the autosave and recovery functions.} the restart function kicks
in only if the application was open for more than 60 seconds (to prevent restart
loops). Your documents are autosaved even before this time, nevertheless.

The CLI GUI has a simple autosave and recovery mechanism. The chart text (and context)
is saved rougly every second or if you exit the program without saving your work.
When Msc-generator is opened next time, you can recover the last autosave. Note that
if you start Msc-generator with a filename, your autosave will be overwritten and lost.
Also note that multiple running instances of the CLI GUI perform autosave to the same
location overwriting each other constantly.

@node International Text Support, Command-Line Referece, Autosave and Recovery, Usage Reference
@section International Text Support

Msc-generator supports international text via both UTF-8 and UTF-16@footnote{UTF-8
is a superset of ASCII, where international characters are encoded in multiple bytes
all larger than 127 (which is the largest ASCII character). In contrast, in UTF-16
all characters are encoded on two bytes, ASCII and international characters alike.
The UTF-16 file usually start by the characters 0xff and 0xfe and their order
determines in which order the two bytes of a character comes. UTF-8 is widely
used in Linux and other Unix systems, whereas Windows has adopted UTF-16 as the system
encoding. Msc-generator supports both file formats and both byte orders of UTF-16.}.
The type of encoding is determined automatically when the file is loaded.
If it is ASCII or valid UTF-8, it is treated as so. Else it is treated as UTF-16. The
Windows GUI displays the detected encoding on the status bar. You can change it by double
clicking the indicator on the status bar - next time you save the file, it will be saved
using the encoding displayed there. Below is an example of a simple chart shown in the
language tutorial in my native language, Hungarian.

@multitable @columnfractions .5 .5
@item @image{exA6_csh}
@tab @image{exA6, 8cm}
@end multitable

The CLI GUI only supports UTF-8.

Note that not all font faces contain characters for all possible unicode codepoints.
This has to be considered when selecting a font@footnote{In signalling charts you
can select a font via the @code{text.font.face} chart option or attribute,
in graphs use the @code{fontname} attribute, whereas in Block Diagrams you need
@code{use text.font.face=<fonname>;}. On Linux/Mac, where @code{fontconfig} is used
to select the fonts, specifying the @code{text.font.lang} attribute along with the
font face (see @ref{Fonts}), will try to select a font having glyphs for the specified language.}.
If you mix characters of different languages, you need to ensure that they are
displayed via a font that has coverage for all those characters.

In labels, you can use the @code{\$} escape followed by exactly four hexadecimal digits,
to insert any unicode character to a label, e.g., @code{\$00a9} inserts the copyright
symbol.

Note that if you plan to use non-ASCII characters in the chart text you need to
select a font that can display them not only in the chart, but also for the internal
editor. See @ref{Fonts}.

@node Command-Line Referece, Fonts, Advanced OLE Considerations, Usage Reference
@section Command-Line Referece

@menu
* Label Maps::
* Coloring Input Files::
* Embedding Charts::
* Text Editor Integration::
@end menu

The syntax of the command-line version is the same on all platforms@footnote{The
only two exceptions are in how pathnames are written on Windows and Linux/Mac and where the
design libraries (e.g., @code{designlib.signalling}) will be searched.}.

Note that the command line syntax below is a superset of the command-line options
of the mscgen tool. This means that by renaming @code{msc-gen} to @code{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 Msctexen@footnote{This
is thanks to the original mscgen author Michael McTernan and many others}. For more
on the compatibility of the languages see @ref{Mscgen Backwards Compatibility}.

@example
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
@end example

Use @code{msc-gen --help} for detailed command-line summary.

@node Label Maps, Coloring Input Files, , Command-Line Referece
@subsection Label Maps

When you specify @option{lmap} as output file format, Msc-generator creates a text file
with one line for each text label in the chart@footnote{Note that box tags are not included in
the label map.} (and no graphics output). The default extension
will be @code{.map}. The lines in the output file contains the followin information separated by
space.

@verbatim
<type> <page> <x1> <y1> <x2> <y2> <first line>
@end verbatim

The @code{type} character tells, what chart element contained this label. The following characters
are possible

@table @code
@item A
Arrow, including block arrows (including boxes collapsed to arrows)
@item E
Entity heading. Each appeareance of the entities will result in one line.
@item B
Box that has content (unless collapsed)
@item b
Box that contains just a label (or collapsed)
@item P
Pipes
@item V
Verticals (all forms, including boxes, block arrows, ranges, braces and brackets)
@item D
Divides, titles, subtitles, discontinuity lines and plain text (like @code{[label="aaa"];}).
@item N
Floating notes
@item C
Comments (on the side or at the end)
@end table

The second item @code{page} gives which page the label is on. One label is mentioned only once
even if it spans multiple pages.

The following four numbers give the upper left and lower right
corner of the bounding box of the label (and not the corresponding element). It is given in pixels
for bitmap output and in logical coordinates matching the logical size of the output image for
vector graphics output.  The coordinates are relative to the top left corner of the page origin
and are rounded to integers for ease of use.
So if you run Msc-generator twice, once with a graphics output format
and once with label map output (leaving all scaling and other swicthes the same), the coordinates
of the label map shall match the graphics output perfectly.

Finally the line ends with the first line of the label (which may contain spaces), potentially with the
number prepended (if any) in the number format used in the chart (e.g., roman numbers). Note that the
coordinates specify the bounding box of the entire label, not just the first line given here.

In this release of Msc-generator, label maps are not emitted for graphs.

@node Coloring Input Files, Embedding Charts, Label Maps, Command-Line Referece
@subsection Coloring Input Files

Using @option{-T csh} produces a colorized version of the input file text.
Specifically, the output is a text file according to the signalling chart
language (irrespective what the input language was). The output contains
a single colon-label divider using the formatting escapes described in
@ref{Text Formatting}. Running msc-gen on the resulting text output again
(interpreting it as a signalling chart), will produce a colorized version
of the original input text as graphical output. This is how the color text
version of the examples in this document were produced.

@node Embedding Charts, Text Editor Integration, Coloring Input Files, Command-Line Referece
@subsection Embedding Charts

You can embed chart text in PNG files by using the @code{-e}. Then you can use this PNG
file as an input file (and open it in the GUIs, too). You can extract the source text
from a PNG file by using @code{-T src}.

You can also embed charts in PPT files, by using @code{-T embed} and specifying an existing
@code{pptx} file as output. This will append a slide and place the chart in the middle of it.
Using @code{-T embed:<slide>} will place the chart on an existing slide, identified by its
number. Numbers start from 1 and you get an error if the slideshow does not have as many slides.
Finally, specifying @code{-T embed:<slide>:<chart>} will @emph{replace} an existing chart on
the given slide. Charts on a slide are numbered from one in Z-order, where chart #1 is the
one on the back.

You can extract the source text from a PPT file, by appending the slide and
chart number after the input filename, like @code{msc-gen my.pptx:2:1}. Adding @code{-T src}
will save the chart text, but other output graphics formats are also possible. The following
example updates the chart with a given design.

@example
msc-gen my.pptx:2:1 -T embed:2:1 -o my.pptx --design=round_green
@end example

In order to see what slides contain what charts, use @code{msc-gen --list-embedded my.pptx}.

@node Text Editor Integration, , Embedding Charts, Command-Line Referece
@subsection Text Editor Integration

The options here are inteded for integration with text editors.
They may change in the future.
Please contact the author if you want to integrate with a text editor.

Using @option{--tei-mode} will put msc-gen into @emph{Text Editor Integration mode},
where it expects a series of input files on its standard input and produces
color syntax highlighting, quick error, text indentation or hints/autocomplete
information on the standard output. These are produced via a quick parsing of the
input text and are intended to be fast enough to be ran for every keystroke pressed.
(At least for input files of reasonable sizes, say 64K.)
Parsing in this mode is limited, thus not all errors are caught, but most are.
Msc-gen reads and parses all the design libraries
at startup and remains running for several input files - again to save time. (Reading
design files can be avoided via option @option{--nodesigns}, as usual.)

On the standard input msc-gen expects a text line with a series of space separated letters, each optionally followed
by a number, then a new line character. After this shall come the text of
an input chart, terminated by a zero byte. The letter in the first line determines
what kind of output is expected on the standard output (see below). The output is also
terminated by a zero byte. All the above can then be repeated until the standard input
is closed. In that case, msc-gen closes the standard output and exits with success.

Msc-gen uses the standard error to produce critical error messages (ones that do not
pertrain to the correctness of input text, such as bad combination of options, etc.).

The type of the chart has to be specified via option @option{-S} and cannot be changed later.
(Similar, if the design libraries change, msc-gen need to be restarted.)
The text of the input can only be ASCII or UTF-8, but not UTF-16. Input or output filenames
are invalid, so are the options @option{-i} and @option{-o}. A host of other options to
manipulate graphics output (sizing, pagination, etc.) are simply ignored.

The following table summarizes, what letters can be used in the first line of the input
and what effect they have.
If you specify more than one letters in the first line separated by spaces, all output
for them will be returned separated by an empty line. Thus if you want to get both the coloring
information and the quick errors in one pass, use @code{C E} in the first line. The order of the
letters in the first line do not matter, output is ordered as below in the table. You can specify
one letter several times, but it has no effect. In case the letter requires parameters, that of
the last mention will take effect.

@table @code
@item C
In response to @code{C}, msc-gen emits a description of how to color the input.
Each line describes a particular contigius area of the input file colored the
same way in the format below.

@code{<first_pos>-<last_pos>: <color_id> <red> <green> <blue> <bold> <italics> <underline>}

The first two numbers mark the first and the last position of the color range
starting from 1. If the color range consists of a single character, the
two values are equal.
In case of UTF-8 encoding, multi-byte characters are counted as one thus the
position is not a byte index.
The different line endings (CR, LF or CRLF) are all understood, with CRLF
counted as one character.

The @code{color_id} is a number between 0 and 36 denoting what kind of
color do we talk about. The table further below summarizes the values. The rest of the numbers
on the line give actual colors and font flags (associated with the default color scheme).

@item D<pos>,<insert>
Similar to @code{C}, this emits coloring information, but only a delta compared to a previous run.
This may be beneficial to reduce the amount of coloring results generated by msc-gen. Also, if the
text editor supports incremental updates in coloring, this may also reduce the work of updating coloring
after simple changes.

The delta can only be compared if a single (but perhaps multi-character) insertion or deletion were
made to the input file. @code{<pos>} represents the caret position @emph{after} which the characters
were inserted or deleted, while @code{<insert>} tells us how many were inserted (negative number for deletes).
If you have specified the @code{N} letter, you can omit the chart text entirely from after the first line
for deletions. For insertions, you just need to specify the characters inserted (which have to be as many)
as the @code{<insert>} you specified.
By default (no @code{N} added), msc-gen still expects the full chart text on its input.
If the chart text given to msc-gen was modified
in a different way compared to the original than the parameters of the @code{D} command indicate the
resulting delta will likely be wrong. The returned coloring info will contain @code{color_id} of @code{0}
for texts that were colored before, but now coloring has to be removed.

Note that the delta computation algorithm assumes that the text editor maintains coloring before @code{<pos>}
and shifts coloring information after the insertion. That is, if a single character was deleted at position
@code{5}, a blue colored character at position @code{3} will remain blue (and hence this can be omitted
from the delta) and a red character originally at position @code{7} (now at position @code{6}) will remain
red at its new position. This is how any sane text editor having text formatting shall work.

You can only specify one of @code{C} or @code{D} at the line, the latter takes effect.

@item E
Msc-gen will emit quick errors, for highlighting during editing.
(Not all errors are caputred, such as attributes not applying, etc.
This is to speed up the process.)
The output contains a character range @code{<first_pos>-<last-pos>} followed by
a textual description. The text editor may underline these locations and assign ballon tooltips
for them.

@item H<pos>
If the letter in the first line is @code{H} a nonnegative number shall be appended (with no space).
In this case msc-gen will return the possible list of auto-completions,
when the cursor is at the number specified. This position is a caret position, value zero is
before the first character in the file, value 1 is after it. In case of UTF-8 input each character
counts as 1, even if multi-byte. Thus if the first character takes two bytes, then the position 1
will start at byte #2.
The list returned consists of one line per hint and the hints are neither grouped nor filtered
(see @ref{Typing Hints and Autocompletion}). There are seven fields separated by the @code{\x01}
character.
@enumerate
@item The hint text. This is to be shown to the user.
@item The string to insert.  If empty then use the hint text above.
@item @code{1} if the hint is selectable (can actually be inserted to the chart) and @code{0},
if it is only explanatory.
@item The RGB color of the hint: three, comma separated integers between [0..255].
@item @code{1} if the hint text shall be bold, @code{0} otherwise.
@item @code{1} if the hint text shall be italics, @code{0} otherwise.
@item The description of the hint in english to be used as a tooltip. Newline characters are
replaced to character @code{\x02} in order to avoid confusion with newlines separating the hints.
@end enumerate
If the cursor is at a location where the user can type a new identifier (and not just one of the
values among the hints), the first hint will have its hint text equal to the asterisk ('@code{*}').
This shall be honoured by not expanding to one of the hints when the user presses the space or a
non alphanumeric character.

@item I<pos>
In this case the position is also a character position as for @code{H}, but smart indentation
information is returned. Text editors can use it when the user presses TAB or RETURN keys,
or when the user has typed a brace or square bracket to the beginning of a line.
Msc-gen will return four numbers separated by a space and terminated by a newline.

@itemize
@item The character index of the beginning of the line containing @code{<pos>}.
@item The byte index of the first character of the line containing @code{<pos>}.
In case of a pure ASCII input this equals the first number.
@item The current number of whitespace (tabs count as a single whitespace) at the
beginning of this line. If the line contains only whitespace this number is the
total number of characters in that line.
@item The suggested number of whitespace at the beginning of the line (which is the
complete line if there is only whitespace). Note that for empty lines the correct
indentation may change after the first character is typed.
@end itemize

Note that if you would like to indent several lines at once, you need to actually indent
the first one (by adding/removing spaces) and then re-parse the resulting file and do it
for the second line, etc. This is because the calculated indent depends on lines above.

@item N
If this letter is added to the line, the chart text following the first line can be missing. (It is ignored
if present all the way to the terminating zero character.) The text of the previous run is re-used, but
parsed again. It is useful, when the text has not been changed, but we want hints at a different location.
@end table

Note that @code{C}, @code{D}, @code{E} and @code{H} will result in a  re-parse of the chart text, so
it is a good strategy to send them all in once to be done with a single re-parsing as opposed to
send them one-by-one with @code{N}, which results in a fresh re-parse again.
@code{I}, on the other hand can work from a previous parse.

And the code for the @code{color_id} is as follows.
@table @code
@item 0
Regular text (if a character is not listed, its color defaults to this).
@item 1
A keyword, like commands or @code{parallel}
@item 2
A partially typed keyword
@item 3
An msc-gen only keyword
@item 4
The equal sign
@item 5
The semicolon sign
@item 6
The colon character
@item 7
The comma character
@item 8
A symbol, e.g., arrows, box symbols, etc.
@item 9
An mscgen symbol, e.g., arrows, box symbols, etc.
@item 10
An opening or closing brace @{@}
@item 11
An opening or closing bracket []
@item 12
An opening or closing parenthesis ()
@item 13
The name of a design
@item 14
The name of a style
@item 15
The name of an entity
@item 16
The name of an entity when first occures in the file
@item 17
The name of a color
@item 18
The description of a color other than a name
@item 19
The name of a marker
@item 20
The name of a marker partially written
@item 21
The name of a procedure
@item 22
The name of a file to include
@item 23
The name of a procedure parameter ($xxx)
@item 24
The name of a chart option
@item 25
The name of a chart option partially written
@item 26
The name of an mscgen-only chart option
@item 27
The name of an attribute
@item 28
The name of a attribute partially written
@item 29
The name of an mscgen-only attribute
@item 30
The value of an attribute
@item 31
Emphasized part of the attribute value (usually variables)
@item 32
The text of a label, either after a colon or between quotation marks
@item 33
The text of a label escape, such as '\n'
@item 34
A place where an error was detected.
@item 35
The inverse of error formatting (used only internally)
@item 36
A comment
@end table

@node Fonts, , Command-Line Referece, Usage Reference
@section Fonts

For signalling charts the fonts used for labels, comments, etc. can be selected
in 5 ways (listed in decreasing order of preference).
@enumerate
@item Using the \f(@dfn{font name}) and/or the \l(@dfn{language code}) text formatting
escape sequences@footnote{Use the @url{https://www.ietf.org/rfc/rfc3066.txt, RFC 3066} style
language names. See a list of examples @url{http://www.i18nguy.com/unicode/language-identifiers.html, here}.}.
These can be applied even in the middle of a label.
@item Using the @code{text.font.face} and/or the @code{text.font.lang} attributes, in which
case they apply to the whole label. The value of these attributes can also be set by styles.
@item Using the @code{text.font.face} and/or @code{text.font.lang} chart options. They
affect all subsequent labels (until the next closing brace, if any).
@item Using the @code{-F} command-line option.
@item By setting the @code{MSCGEN_FONT} and/or @code{MSCGEN_FONT_LANG} environment variables.
@end enumerate

The fonts available are system dependent.
On Windows, you can use all the Windows fonts available, but only OpenType and
TrueType fonts provide correct alignment.
On Linux or Mac, FontConfig is used and you can use fonts installed with it. Use the @code{fc-list}
command to list available fonts. Pick the family name in the list for use in Msc-generator.
You can also specify the language you want (see above), this impacts the font selected so that
it contains the glyphs needed by the language you specify.

For graphs, the selection is similar, but the name of the attribute is @option{fontname} and
there you need to use the @code{node [fontname=<face>];} to impact all subsequent nodes. There
is no way to set the language except from the @code{\l()} text formatting escape.

For Block Diagrams the precedence is similar to that of the Signalling Charts,
but instead of the @code{text.font.face} chart option, you can change the
running style via the @code{use text.font.face=<font>;} command. (And similar for the language.)

On the Windows GUI you can use the last panel of the @samp{Internal Editor}
ribbon category to select the font of the internal text editor. The two checkboxes
can be used to filter the list of font families offered by the lisbox below them.
Note that if you plan to use non-ASCII characters in the chart text you need to
select a font that can display them not only in the chart, but also for the internal
editor.

Finally, when you start Msc-generator with the @code{MSCGEN_NOFONT} environment variable set
(to any non-empty value other than @samp{0}), no fonts will be drawn to the output.
The area occupied by any text will be left empty (but included in layout calculation).
This is useful for testing.

@node Reference for Common Language Elements, Signalling Chart Language Reference, Usage Reference, Top
@chapter Reference for Common Language Elements

Msc-generator languages all share a common underlying logic and design.
@itemize
@item They all define elements and relations between elements, such as entities and arrows for
signalling charts; nodes and edges for graphs; and blocks and arrows for block diagrams.
@item These elements and relations usually can have a text label, the format of which (such as bold or italics)
can be influenced via @dfn{text formatting escapes}.
@item These elements and the relations all have @dfn{attributes} to govern appearance, which can be specified
in square brackets.
@item Attributes can be collected in @dfn{styles}, which can be applied to elemets and relations in a simple way.
@item Each element and relation type has a @dfn{default style}, which can be changed to change the appearance
for all such elements or relations.
@item Curly braces can be used to group elements and to isolate a @dfn{scope} - any changes to styles or colors
are limited to the current scope.
@item You can define @dfn{designs}, which contain styles, colors and can be applied to the whole chart to change
its appearance in one go. These are collected into @dfn{design libraries}, which are read at program startup and
are available by default.
@item You can also include other files in the middle of the any document.
@item You can define and later replay @dfn{proecedures} to avoid frequent copy/paste and reuse frequent constructs
instead.
@end itemize

This chapter contains all the language elements that are common to all or most chart
types supported by Msc-generator.
Variations specific to each language are indivially described.

@menu
* Labels::
* Text Formatting::
* Links::
* Numbering::
* Specifying Colors::
* Common Attributes::
* Scoping::
* Defining Styles::
* Chart Designs::
* Defining Shapes::
* Procedures::
* Variables::
* File Inclusion::
@end menu


@node Labels, Text Formatting, Reference for Common Language Elements, Reference for Common Language Elements
@section Labels

Entities, arrows, boxes, pipes, dividers (signalling charts), nodes, edges and clusters
(graphs) and blocks (block diagrams) all have a @code{label} attribute,
which specifies the text to be displayed for the element. Each element
displays it at a different place, but the syntax to describe a label is
the same for all.
For entities (signalling charts), nodes and clusters (graphs)
the label defaults to the name of the elements, while for the rest
it defaults to the empty string. Labels have to be quoted if they contain
any character other than letters, numbers, underscores and the dot, or if they
start with a dot or number or end with a dot.
You can use all character formatting features in labels, @pxref{Text Formatting}.

To avoid typing @code{[label="..."]} many times it is possible to specify
the label attribute in a simpler way.
After the definition of the element, just type a colon (two colons for graphs),
the text of the label unquoted and terminate with a semicolon
(or opening brace @samp{@{} or bracket
@samp{[}). You can write attributes before or after such a @dfn{colon-label}.
Thus all lines below result in the same text.

@image{ex50_csh}

If the label needs to contain a
opening bracket (@samp{[}), opening brace (@samp{@{}),
hashmark (@samp{#}) or a semicolon (@samp{;}) use quotations or
preceed these characters by a backslash @samp{\}@footnote{This character is
often called the @dfn{escape character} making an @dfn{escape sequence}
together with the character it follows.}. This is needed since these
characters would otherwise signal the end of the label (or the beginning of a
comment). If you want a real backspace, just type @samp{\\}.

When using the colon notation, heading and trailing spaces are removed
from the label. If these are needed, place the entire label between two
quotation mark @samp{"}@footnote{In this case there is no need to escape the
opening bracket or brace, the hashmark or the semicolon, since the end of the label
is clearly indicated by the terminating quotation mark. If, on the other hand
you need quotation marks in the label use @samp{\"}. Also,
you cannot break the text in multiple lines in the input file, you have to
use the @samp{\n} escape to insert line breaks. This @dfn{colon-quotation-mark}
mode is availale only for signalling charts and is provided only for backwards
compatibility with mscgen.}.

@multitable @columnfractions .6 .4
@item

@image{ex51_csh}

@tab

@image{ex51, 6cm}
@end multitable

Labels can span multiple lines. You can insert a line break by adding the
@samp{\n} escape sequence. Alternatively you can simply break a label and
continue in the next line. In this case leading and trailing whitespace is
removed from each line.

@multitable @columnfractions .5 .5
@item

@image{ex52_csh}

@tab

@image{ex52, 8cm}
@end multitable

@node Text Formatting, Links, Labels, Reference for Common Language Elements
@section Text Formatting

Any text displayed in the chart may contain @dfn{formatting escapes}.@footnote{For
graphs only labels specified via the double-colon notation interpret escape sequences this way.
If you assign a label via the @code{label=} attribute, the escape sequences will be interpreted
as graphviz escape sequences, see @uref{http://www.graphviz.org/doc/info/attrs.html#k:escString}.}
Each formatting escape begins with the
backslash @samp{\} character. You can also use the backslash to place special
characters into the label. Below is the list of escape sequences available.

@table @code
@item \n
Inserts a line break.
@item \-
Switches to small font.
@item \+
Switches to normal (large) font.
@item \^
Switches to superscript.
@item \_
Switches to subscript.
@item \b
Toggles bold font.
@item \B
Sets font to bold.
@item \i
Toggles italics font.
@item \I
Sets font to italics.
@item \u
Toggles font underline.
@item \U
Sets font to underlined.
@item \f(@var{font face name})
Changes the font face. Available font face names depend on the operating system
you use. (See @ref{Fonts}.) If you specify no font, just @code{f()}, the font used at
the beginning of the label is restored.
@item \l(@var{font language code})
Changes the language of the font. On Windows it is ignored. On FontConfig-based
systems (Linux, Mac) you can use an RFC3066-style language specifier, typically
a 2-letter ISO language code, such as @var{ja} for Japanese or @var{zh} for Chinese.
This code is used to select the font file which includes the characters or the given
language. (See @ref{Fonts}.) If you specify no code, just @code{l()}, the font used at
the beginning of the label is restored.
@item \0..\9
Inserts the specified number of pixels as line spacing below the
current line.
@item \c(@var{color definition})
Changes the color of the text. Color names or direct rgb definitions can
both be used, as described in @ref{Specifying Colors}. No quotation is needed.
You can also omit the color and just use @option{\c()}, which resets the color
back to the one at the beginning of the label.
@item \s(@var{style name})
Applies the specified style to the text@footnote{Note that the @option{\s}
formatting escape was used to switch to small font in 1.x versions of
Msc-generator (since 2.0 @option{\-} is used for that). In order to work with
old format charts, if the style name is not recognized, Msc-generator will give
a warning but fall back to using small font.}. Naturally only the @code{text.*}
attributes of the style are applied. You can omit the style name and specify
only @option{\s()}, which resets the entire text format to the one at the
beginning of the label@footnote{Any formatting escapes strictly at the beginning
of a label (up to the first non-formatting escape or literal character) are
included in the text format, so if you start a label with @samp{\b} then
@samp{\s()} will restore a bold font. To prevent this use the @samp{\|} escape
to create an invisible non-formatting character.}.
See @ref{Styles} for more information on styles.
@item \S(@var{shape}|@var{height}|@var{fillcolor})
Inserts a shape into the text as a single character. Shapes can be arbitrary
forms described by polygons or bezier curves and are defined using the
@code{defshape} command, see @ref{Defining Shapes} for more information. This escape allows
drawing arbitrary things everywhere, where a label is permitted. Within the
escape sequence, you first need to specify the name of the shape, then optionally
its height (default is the font size) and optionally its fill color (default is
transparent fill). The latter option takes effect only for shapes having a
fill section, see @ref{Defining Shapes}. You can omit the height
(@code{\S(@var{shape}||@var{fillcolor})}) or the fill color
(@code{\S(@var{shape}|@var{height})}) or both (@code{\S(@var{shape})}).
@item \mu(@var{num})
@itemx \md(@var{num})
@itemx \ml(@var{num})
@itemx \mr(@var{num})
@itemx \mi(@var{num})
Change the margin of the text or the inter-line spacing. The second character
stands for up, down, left, right and internal, respectively. @samp{num} can be any
nonnegative integer and is interpreded in pixels.
Intra-line spacing comes in addition to the line-specific
spacing inserted by @option{\0..\9}. Defaults are zero.
You can also omit the number, which restores that particular value to the one
in effect at the beginning of the label, such as @option{\mu()}.
Note that for signalling charts, Msc-generator always adds enough left and right
margins to arrow labels to avoid overlapping the label with the arrowhead.
Thus if you specify less margin, it may not show as you expect.
@item \mn(@var{num})
@itemx \ms(@var{num})
Changes the size of the normal or small font. This applies only to the label,
where used, not globally for the entire chart. Defaults are @code{\mn(16)\ms(10)}.
You can also omit the number, which restores that particular value to the one
at the beginning of the label.
@item \pl \pc \pr
Changes the identation to left, centered or right. Applying at the beginning of
a line (t.i., before any literal character) will apply new identation to that
line and all following lines within the label.
Applying after the beginning of a line will only impact subsequent lines.
@item \@{ \[ \" \; \# \@} \]
These produce a literal @samp{@{}, @samp{[}, @samp{"}, @samp{;}, @samp{#},
@samp{@}} or @samp{]}, respectively, since these are characters with special
meaning and would, otherwise signal the end of a label. The last two can
actually be used without the backslash, but result in a warning.
@item \$xxxx
This escape can be used to insert any unicode character into a label, via its codepoint.
Specify the codepoint in hexadecimal using exactly four hex digits. E.g., @code{\$00A9}
will result in the copyright symbol. See more on international characters in
@ref{International Text Support}.
@item \|
This escape is a non-formatting escape that generates no output. It can be used
at the beginning of a label to delimit those formatting escapes that are included
in the default formatting restored by the @samp{\s()} escape and used to format
the label number, from those which are just to be applied at the beginning of the
label.
@item \N
This escape marks the position of the label number within the label. If omitted
the number is prepended to the beginning of the label (after the initial formatting
escapes). If no number is specified for the label, this escape has no effect.
You can specify @samp{\N} multiple times, with each occurrence being replaced by
the number. Note that if you omit @samp{\N}, the number inserted at the beginning of
the label is augmented by the value of the @option{numbering.pre} and
@option{numbering.post} options, whereas with the @samp{\N} option, those are
not used.
@item \r(@var{refname})
This escape inserts the number of the referenced element. Use the @code{refname}
attribute to name elements. Similar to the @samp{\N} escape, the value of the
@option{numbering.pre} and @option{numbering.post} options are ignored.
When no name is given (that is @samp{\r()}) the escape is equivalent to @samp{\N}.
@item \L(@var{link target})
@itemx \L()
This escape shall be used in pairs to assign a hyperlink to the text in between the two.
The target of the link shall be specified in the first escape, whereas the second shall
be empty. For example: @code{a->b: A \L(http://abc.com)link\L() to abc.com.;}
The link target cannot contain closing parenthesis. If it contains opening square brackets
(@code{[}), opening curly braces (@code{@{}), semicolons or hash marks, which normally
terminates colon labels, use quotation marks around the label, such as
@code{a->b: "A \L(http://abc.com/#x)link\L() to abc.com/\#x.;}
Note that @dfn{tag labels} of signalling chart boxes can also contain links.
See more in @ref{Links} below.
@item \*
In Block Diagrams, adding this to the label of a block, will insert the
name of the block there. Using this as a default label (e.g., via
@code{use label="\*";}) makes the label default to the name of the block.
@end table

Font size commands (including superscript or subscript) last until the
next font size formatting command. For example in order to specify a subscript
index, use @code{label="A\_i\+ value"}.

Any unrecognized escape characters in a label are removed with a warning.
Unrecognized escapes and plain text in @code{text.format} attributes is
ignored with a warning.

Note that the @code{text.*} chart options can be used to set the default
text formatting for signalling charts and block diagrams. See @ref{Text Formatting Attributes}
for details.

@node Links, Numbering, Text Formatting, Reference for Common Language Elements
@section Links

Hyperlink info can be added to labels (or parts of labels). This is useful when the resulting
image is embedded into web pages. Hyperlinks are not (yet) exported into a PDF or SVG
file. Currently link information can be extracted via the
@code{-T ismap} command-line option, which provides an NCSA formatted ismap file.
Such files are used by Doxygen, for example, so this feature is most applicable to
Doxygen integration. (If you specify a link target as @code{\ref Name} then
Doxygen will point to a function or class named @code{Name} in the documentation
created by Doxygen.)

In the MFC GUI, links are visible and if they represent a URL they are clickable.
In the CLI GUI they are not.

To add a hyperlink to a label, use two @code{\L()} escape in a pair, making the text
between them to point to the link target. The target of the link shall be specified as the
parameter to the first @code{\L()} escape. In this case the link target may not contain
closing parenthesis@footnote{If the link target contains opening brace, hashmark, semicolon
or symbols, which terminate a colon label, use quotation marks around the label - it is not
possible to use escapes such as @code{\[} inside a link target.}. Using this method
it is possible to add several links to (different parts of) the same label.

In signalling charts, you can also use the @code{url} attribute. This makes the whole label
a hyperlink. The value of the attribute is the target of the link.
You cannot use both mechanisms to the same label. Note that you can only use the
first method to add hyperinks to @dfn{box tags}.

Links also change formatting. In the plain design, they became blue and underlined. In signalling
charts, this is
governed by the @code{text.link_format} chart option and attribute. Any formatting escape
sequence you specify as value to this chart option or attribute will be applied at the
beginning of the link text and de-applied at the end.

@multitable @columnfractions .68 .32
@item

@image{exA1_csh, 12cm}

@tab

@image{exA1, 5cm}
@end multitable

@node Numbering, Specifying Colors, Links, Reference for Common Language Elements
@section Numbering

Signalling chart arrows, boxes and dividers (any element with a label, except entities)
and block diagram blocks can be auto-numbered. It is a useful feature that allows easier
reference to certain steps or blocks from explanatory text.
At present numbering is not implemented for graphs.
To auto assign a number to an element, simply set its @code{number}
attribute to @code{yes}. You can also assign a specific number,
in that case the element will get that number and subsequent elements
will be numbered (if they have @code{number} set to @code{yes}) from that
number upwards.

Notes and comments (signalling charts) will not increase numbering, instead they carry the
number of the element they are referring to. If the target element had no number
comments will have none, even if numbering is turned on for them.

Styles can also control numbering. If a style has its @code{number} attribute
set to @code{yes} or @code{no}, any element that you assign the style to
will have its attribute set likewise. See @ref{Styles} for more.

In order to minimize typing, the @code{numbering} chart option can be
used. It can be set to @code{yes} or @code{no} and serves as the default for
freshly defined elements. You can set the value of @code{numbering} at any
time and impact elements defined thereafter. You can use scoping to enable or
disable numberig for only blocks of the chart, @pxref{Scoping}.

Most of the time you just declare @code{numbering=yes} at the beginning
of the chart and be done with it. However, if you want to control that only
some parts of the elements (e.g., only concrete messages and not boxes, for
example) got a number, you may need the other alternatives.

@multitable @columnfractions .5 .5
@item

@image{ex63_csh}

@tab

@image{ex63, 5cm}
@end multitable

If numbering is turned on for a label, the number is inserted at the beginning of
the label and is followed by a semicolon and a space by default.
More precisely, the number is inserted
after any initial text formatting sequences, so that it has the
same formatting as the label itself (see @ref{Text Formatting})@footnote{You can use the
@option{\|} formatting escape to insert a non-visible break into a stream of
formatting escapes. The number will be inserted there.}.
The above default can be changed by inserting the @option{\N} escape sequence
into a label.
This causes the number appear where the @option{\N} is inserted, as opposed
to the beginning of the label. In this case, the colon and the space is omitted,
only the number itself is inserted.

The colon and space can be changed to some other value by setting the
@code{numbering.post} chart option to the string you want to append to the number.
Similar, any string the @code{numbering.pre} option is set to will be
prepended to the number (empty by default). Both options are ignored when using
the @option{\N} escape sequence to set the label position.

Note that for the last two arrows formatting escapes were added to the
@option{numbering.pre} option. These are reversed by the @samp{\s()} escape
in the @option{numbering.post} option. See @ref{Text Formatting} for more details.

The format of the number can be set with the @code{numbering.format} chart option.
You can specify any of @samp{123}, @samp{iii}, @samp{III}, @samp{abc}, or
@samp{ABC} for arabic, lowercase and uppercase roman numbers or lowercase and
uppercase letters, respectively@footnote{Using @samp{arabic}, @samp{letters} or
@samp{roman} is also valid (both uppercase or lowercase).}. You can also prepend
or append any text before or after the above strings, those will be prepended or
appended to the number (and will be included also when the number is inserted via
the @samp{\N} escape).

If you want to specify an increment other than one, use the
@option{numbering.increment} option with a nonzero integer. You can even count
backwards using a negative increment. In case of multi-level numbering (see below)
this applies to the last level,

Note that the value of the @option{numbering} options is subject to scoping,
that is any change lasts only up to the next closing brace.

Note also, that when using roman numbers or letters, you can use such numbers as
the value of the @option{number} attribute, as shown below for @samp{7c}.

It is also possible to have multi-level numbering (such as 1.1).
To achieve this, use the @option{numbering.append} chart option and specify
the format of the second level including any separator. Use the same format
as for @option{numbering.format} above.

It is possible to change the format of a multi-level label via the
@option{numbering.format} option. Simply use multiple of the number format
strings (such as @samp{123} or @samp{roman}) as in the @samp{Exotic format} line of
the example above. If you use less number format strings than the current number
of levels (as in the @samp{Only the last number} line of the example),
Msc-generator displays only the end of the number, omitting levels from the top.
Those levels, however, are still maintained, just are not displayed.

The @option{numbering.append} option can only be used to add levels. There is no
explicit way to decrease the number of levels, you have to use scoping to achieve
that. On the example above, the second level appended in the scope of
@samp{Alternative #1} is cancelled at the end of the scope, so we need to
append a second level also in @samp{Alternative #2}, which then restarts from
@samp{a}.

@multitable @columnfractions .5 .5
@item

@image{ex64_csh}

@tab

@image{ex64, 6.5cm}
@end multitable

Finally, if an element is named, you can
reference the number of that element in another label using the @code{\r(name)}
escape sequence.
Signalling chart elements can be named using the @code{refname} attribute, while
block diagram blocks can simply have their name at their definition.
Note that the value of the @code{numbering.pre} and
@code{numbering.post} options are ignored when inserting the number of a
referenced element, similar to how the @code{\N} escape inserts numbers.
Specifying an empty @code{\r()} escape inserts the number of the current element
and is thus equivalent to @code{\N}.


@node Specifying Colors, Common Attributes, Numbering, Reference for Common Language Elements
@section Specifying Colors

Msc-generator has a number of color names defined initially, among them: @code{none},
@code{white}, @code{black}, @code{red}, @code{green}, @code{blue}, @code{gray}
and @code{lgray}, the first for completly transparent color, and the last for
light gray. Graphviz has a different set of default color names, so we adopted those
for graphs. When you specify a color by name, no quotation marks are needed.

Color names in signalling charts and block diagrams can be appended with a
@samp{+} or @samp{-} sign and a number
between [0..100] to make a color lighter or darker, respectively, by the
percentage indicated. Any color +100 equals white and any color-100 equals
black. Aliases can be further appended with a comma and a value between [0..255]
(or [0..1.0] similar to RGB values). This specifly color opaqueness: 0 means
fully transparent and 255 means fully opaque.

@multitable @columnfractions .65 .35
@item

@image{ex56_csh}

@tab

@image{ex56, 5cm}
@end multitable


You can specify colors giving the red, green and blue components.
For graphviz graphs precede them by hash-marks (@code{#}) and use hexadecimal
numbers, six digits in total.

For signalling charts and block diagrams
separate the R, G and B components by
commas. An optional fourth value can be added for the alpha channel to control
transparency. Values can be either between zero and 1.0 or between 0 and 255. If
all values are less than or equal to 1, the former range is
assumed@footnote{This mechanism allows both people thinking in range [0..1] and
in [0..255] to conveniently specify values. (Internally values are stored on 8
bits.)}. If any value is negative or above 255 the definition is invalid.
Note that you must not enter spaces between the color name, its lighter/darker
or transparency modifier or between the RGB values.
You can mark a color a @dfn{overlay} color by prepending the @samp{++} symbol.
An overlay color applied to an attribute is not set as the color value. Instead, it
is overlaid over and thus is combined with the existing color. (See the arrows in the
example above.) You can also assign an overlay color to a style or a color name (see
below). (This is how their @code{weak} style is implemented.)

For charts other than graphviz graphs, it is possible to define your own color names
using the @code{defcolor} command as below.

@example
defcolor @var{alias}=@var{color definition}, ... ;
@end example

Color names are case-sensitive and can only contain letters, numbers,
underscores and dots, but can not start with a number or a dot and can not end
with a dot. Aliases can also be later re-defined using the @code{defcolor}
command, by simply using an existing alias with a different color definition.

Msc-generator honors scoping for colors, as well.
Color definitions (or re-definitions) are valid only
until the next closing brace @samp{@}}. This makes it possible to override
a color only for parts of the chart, returning to the default later. Note that
you can start a new scope any time by placing an opening brace. See @ref{Scoping}
for more on scopes.

@node Common Attributes, Scoping, Specifying Colors, Reference for Common Language Elements
@section Common Attributes

@menu
* Line and Fill Attributes::
* Shadow Attributes::
* Text Formatting Attributes::
* Styles::
@end menu

Attributes can influence how chart elements look like
and how they are placed. There is a set of attributes that apply to several
types of elements, so we describe them collectively here.

Attribute names are case-insensitive. Attributes can take
string, number or boolean values. String values shall be quoted
in double quotes (@samp{"}) if they contain non-literal characters or
spaces@footnote{Specifically for signalling charts and block diagrams: strings that contain
characters other than letters, numbers, underscores or dots, must be quoted.
If the string starts
with a number or a dot or it it ends with a dot, it must also be quoted.
The only exception to this are built-in style names, @pxref{Defining Styles} or
color definitions containing commas and + or - signs, see @ref{Specifying Colors}.
For graphviz graphs strings can not start with number and can only contain
alphanumeric characters - else they have to be quoted.}.
Quoted strings themselves can contain quotation marks by preceeding them
with a backslash, like @samp{\"}.
Numeric values can, in
general be floating point numbers (no exponents, though), but for some
attributes these are rounded to integers. Boolean values can be
specified via @code{yes} or @code{no}. The syntax
of color attributes is explained in @ref{Specifying Colors}.

The attributes below can be part of a @dfn{style}, see @ref{Styles}.

@node Line and Fill Attributes, Shadow Attributes, Common Attributes, Common Attributes
@subsection Line and Fill Attributes

Currently line and fill attributes apply only in signalling charts and block diagrams.
Graphviz has a totally
different way of specifying line appearance via the @code{style=} attribute. Further
languages planned to be added will use the below attributes.

@table @code
@item line.color
Specifies the color of the lines, see @ref{Specifying Colors} for the syntax.
@item line.width
Specifies the width of the line in pixels. In case of double or triple lines
this is not the total width of the compound line, but only that of an individual
components. E.g., a double line with @code{line.width=1} is three pixels wide in total.
@item line.type
Specifies the type of the line. Its value can be
@code{solid}, @code{dotted}, @code{dashed}, @code{long_dashed}, @code{dash_dotted},
@code{double}, @code{triple}, @code{triple_thick} or @code{none}.
@item line.corner
For boxes-like elements this attribute specifies how the corners of the box
are drawn. Its value can be @code{none}, @code{round}, @code{bevel}, @code{note}.
It has sometimes effect on other elements. Signalling chart arrows pointing to
the same entity use this. Also arrows in block diagrams are impacted.
@item line.radius
Specifies the size of the corner above. In some cases it is also used to specify
the turning radius of turning arrows (see @code{line.corner} above).
@end table
@multitable @columnfractions .55 .45
@item

@image{ex53_csh}

@tab

@image{ex53, 6cm}
@end multitable

@table @code
@item fill.color
Defines the background of an element covering an area.
Specifying @code{none} results in no fill at all (transparent).
@item fill.color2
If this attribute is specified then the fill gradient will not be between
@code{fill.color} and a lighter variant, but between @code{fill.color} and
the value specified here. If no gradient specified or @code{button} is used,
this attribute has no effect.
@item fill.gradient
Defines the gradient of the fill. It can take five textual values
@code{up}, @code{down}, @code{in}, @code{out} and @code{button}. The first two
results in linear gradients getting darker in the direction indicated. The second
two results in circular gradients with darker shades towards the center or edge
of the entity box, respectively. The last one mimics light on a button. In addition,
it can also be set to a numerical value, which result in a linear gradient
and specifies the angle of it.
@end table

@ifdocbook
@image{ex54_csh}
@image{ex54, 8cm}
@end ifdocbook

@ifnotdocbook
@multitable @columnfractions .45 .55
@item
@image{ex54_csh}
@tab
@image{ex54, 8cm}
@end multitable
@end ifnotdocbook

@node Shadow Attributes, Text Formatting Attributes, Line and Fill Attributes, Common Attributes
@subsection Shadow Attributes

@table @code
@item shadow.offset
If not set to zero, then the element will have a shadow (default is 0).
The value of this attribute then determines, how much the shadow is offset
(in pixels), in other words how "deep" the shadow is below the entity or box.
In graphviz, this attribute is called @code{shadow_offset}.
@item shadow.color
The color of the shadow. This attribute is ignored if shadow.offset is 0.
In graphviz, this attribute is called @code{shadow_color}.
@item shadow.blur
Specifies how much the shadow edge is blurred (in pixels).
E.g., if shadow.offset is 10 and
shadow.blur is 5, then half of the visible shadow will be blurred. Blurring is
implemented by gradually changing the shadow color's transparency towards fully
transparent.
This attribute is ignored if @code{shadow.offset} is 0.
In graphviz, this attribute is called @code{shadow_blur}.

@end table

@ifdocbook
@image{ex55_csh}
@image{ex55,6cm,,,.png}
@end ifdocbook

@ifnotdocbook
@multitable @columnfractions .58 .42
@item
@image{ex55_csh}
@tab
@image{ex55,6cm}
@end multitable
@end ifnotdocbook

@node Text Formatting Attributes, Styles, Shadow Attributes, Common Attributes
@subsection Text Formatting Attributes

These attributes can be used to change the appearance of text labels. They
are basically alternatives to @dfn{text formatting escapes}, see @ref{Text Formatting}.
They do not apply to graphs: Graphviz labels can only be styled using text
formatting escapes in a colon-label. Other languages have them.

@table @code
@item text.ident
This can be @code{left}, @code{center} or @code{right} and specifies
the line alignment of the label. The default is centering, except for non-empty
boxes in signalling charts, where the default is left. It can be abbreviated as simply @code{ident}.
@item text.color
Sets the color of the label.
See @ref{Specifying Colors} for the syntax of colors.
@item text.bgcolor
Sets the background color of the label, none by default.
@item text.font.face
Specify the font face family using this attribute, such as @option{Arial} or
@option{Helvetica}. The fonts available depend on the platform. See @ref{Fonts}.
@item text.font.lang
Specify the language for which you seek glyphs. This has effect only on Mac/Linux,
see @ref{Fonts}.
@item text.font.type
Select between normal or small font, superscript or subscript using the values
@code{normal}, @code{small}, @code{superscript} and @code{subscript},
respectively.
@item text.bold
@itemx text.italic
@itemx text.underline
You can set them to @code{yes} or @code{no}.
@item text.gap
@itemx text.gap.up
@itemx text.gap.down
@itemx text.gap.left
@itemx text.gap.righ
These four attribues can be used to set the margins around the label in pixels.
If you set @code{text.gap}, it sets all four to the same value.
@item text.gap.spacing
This sets the line spacing in pixels.
@item text.size.normal
@itemx text.size.small
These sets the height of the normal font type (see @code{text.font.type} above)
or the height of small, superscript and subscript, respectivel.
@item text.format
Takes a (quoted) string as its value. Here you can specify any of the
text formatting escapes that will govern the style of the label,
@pxref{Text Formatting}. Specifying them here or directly at the beginning of
the label has the same effect, so having this attribute is more useful for styles.
@item text.link_format
Similar to the above, you can specify the formatting applied to links. See @ref{Links}.
@item text.wrap
Used in signalling charts only.
Can be set to @code{yes} or @code{no}. If disabled (default), the label will follow
the line breaks inserted by the user. If enabled, these line breaks are ignored
and the line is typeset to fill available space, @pxref{Text Formatting}.
@end table

@node Styles, , Common Attributes, Common Attributes
@subsection Styles

Styles are packages of attribute definitions with a name. Applying a style
to any element can be easily done by simply stating the name of the style
whereever an attribute is allowed. See in the example below, how the
@code{strong} and @code{weak} styles are applied to entities.

@multitable @columnfractions .5 .5
@item

@image{ex11_csh}

@tab

@image{ex11, 8cm}
@end multitable

For signalling charts styles can contain any of the attributes listed in
@ref{Signalling Chart Attributes and Styles}. For graphs any graphviz attribute can be
part of a style. For block diagrams, the applicable attributes are listed in
@ref{Block Attributes} and @ref{Arrows in Block Diagrams}.
If a style contains an attribute not applicable for the element that you apply the style to,
that attribute is simply ignored. For example, applying a style with
@code{fill.color=red} attribute setting to an arrow, will ignore this attribute
since arrows take no fill attributes.

You can define your own styles or redefine existing ones. See @ref{Defining Styles}
for more on this.


@node Scoping, Defining Styles, Common Attributes, Reference for Common Language Elements
@section Scoping

Each time an opening brace is put into the file, a new @dfn{scope} begins.
Scopes behave similar as in programming languages, meaning that any color name,
style or procedure definition take their effect only within the scope, up to the
closing brace. Thus if you redefine a style just after an opening brace,
the style returns to its original definition after the closing brace.
(See @ref{Defining Styles}.)

In signalling charts scoping also applies to the @code{numbering} (including pre, post, format
and append), @code{compress}, @code{vspacing}, @code{indicator}, @code{angle} and @code{text.*}
chart options.
Any changes to these take effect only until the next closing brace.
Scoping explicitly does not apply to @code{background.*} and @code{comment.*}
options. Those take effect until the next such option or all the way to the
bottom of the chart. The option @code{hscale} is global, the last value you set
will be used, irrespective of scope.

Similar, with block diagrams scoping applies to all chart options, except
@code{background}.

You can nest scopes arbitrarily deep and can also manually open a new scope, such as below.
This practically has no effect in any of the languages other than limiting
the effect of an attribute or color/style definition.

@example
...numbering is off here...
@{
    #number only in this scope
    numbering=yes;
    ...various elements with numbers...
@};
...other elements with no numbers...
@end example

For graphs, this opens an unnamed
subgraph - but that has no effect on layout. For block diagrams there is actually
no effect. For signalling charts the layout will be the same as in case
when they are not enclosed in braces (including the handling of @code{compress},
@code{vspacing}, @code{keep_with_next} and @code{keep_together} attributes
and the use of @code{parallel} and @code{overlap} keywords). This is
true only if you do not change the @code{layout} attribute of the block, but use the default, see
@ref{Parallel Blocks}. Thus if you mark
an element between the braces with @code{parallel} elements after the closing
brace can be laid out besides it.
Marking the entire block with @code{overlap} or @code{parallel} will make
elements after the block to be laid over or besides the entrie block, respectively.
See @ref{Parallel Keyword}.

@node Defining Styles, Chart Designs, Scoping, Reference for Common Language Elements
@section Defining Styles

It is possible to define a group of attributes as a style and later
apply them collectively, see @ref{Styles}.

Styles can be defined using the @code{defstyle} command,
as below.

@example
defstyle @var{stylename}, ... [ @var{attribute}=@var{value} | @var{style}, ... ], ... ;
@end example

First you list the name of the style(s) to define then the attributes and
their intended values.
Similar to color names, style names are case-sensitive and can only contain
letters, numbers, underscores and dots, but can not start with a number or a dot and
can not end with a dot.
You do not have to specify all possible attributes, just those you want to
modify with the style. The rest of the attributes will remain unspecified.
When you apply the style to an element, attributes of the element that are
unspecified in the syle are left unchanged.

You can also enlist styles among the attributes. In this case the
newly defined style inherits all the attributes specified in that style.
If you apply a style to an element, those attributes of the style, which
not applicable to that particular element type are simply ignored. For example,
applying a style including @code{fill.color} to an arrow will silently ignore
the value of the @code{fill.color} attribute.

The same syntax above can be used to extend and modify styles. You can add
new attributes to an existing style or modify existing attributes. This is
when listing multiple styles comes in handy. You can set attributes to the
same value in multiple styles in a signle command.
Re-defining an existing style do not erase the attributes previously
set in the style. Only the new attribute definition is added - changing the
value of the attribute if already set in the style.

It is also possible to unset an attribute by specifying
the attribute name, followed by the equal sign, but no value.

There are a number of default, built-in styles that govern the default appearance
of elements. By modifying these you can impact, e.g., all the arrows in a
chart or all edges in a graph. This is how chart designs operate: by modifying the built-in styles.

If you want to change
a set of attributes for multiple elements (such as both for arrows and
dividers) simply list these separated by commas before the attributes.

@image{ex58_csh}

It will apply to both.

In addition to default styles, most languages have a number of @dfn{refinement styles}.
Such styles may contain some attributes set and are applied after and in addition to
default styles. For example, after applying the default @code{arrow} style to
a message in a signalling chart or an arrow of a block diagram, specified as @code{a=>b;},
an additional refinement style, named @code{=>} is applied, making the arrow double-lined.

Redefining refinement enables you to quickly define, e.g.,
various arrow styles and use the various symbols as shorthand for these.

Thus, in summary the actual attributes of an element are set using the following logic.
(There are minor variances for each language.)
@enumerate
@item If you specify an attribute directly at the element (perhaps via applying
a style), the specified value is used@footnote{If you specify the attribute
several times, the last one is used.}.
@item Otherwise, if the attribute is set in the refinement style (at the
point and in the scope of where the element is defined), the value there
is used.
@item Otherwise, if the attribute is set in the default style of the element,
the value there is used.
@item Otherwise (if they exist in the language), the value of the applicable chart option is used,
e.g., @code{text.*} for signalling charts. In order for these chart options to be effective
default styles usually have no value specified for these attributes. You can set
these attributes in styles, e.g., to set font type for empty boxes,
which will take precedence over chart options.
@end enumerate



@node Chart Designs, Defining Shapes, Defining Styles, Reference for Common Language Elements
@section Chart Designs

A chart design is a collection of color, style and procedure definitions and
values of certain chart options.
For signalling charts the value
of the @code{hscale}, @code{numbering}, @code{compress}, @code{vspacing}, @code{text},
@code{background} and @code{comment} options are included. For numbering you can turn it
on or off and specify the format of the top level number - but you cannot
specify multiple levels. For block diagrams the @code{background} and the @code{conflict_report}
chart options can be made part of designs.

Note that color, style and procedure definitions are local to a scope (take effect only within) and
can be stored in designs. Shape and design definitions on the other hand are global
and as such can not be added to designs.

Except for graphs, we differentiate are @dfn{full designs} and @dfn{partial designs}.
A full design contains
a value for all the chart options, default colors and styles. A partial design
contails values only for some of these. E.g., the @code{thick_lines} design
is a partial one - it merely makes all lines of width 2 in all the default styles,
but leaves color, line type, fill or any other attribute or chart option unchanged.

In signalling charts you can apply a full style using the @code{msc = <design_name>}
chart option and a partial style using @code{msc += <style_name>}.
For graphs and block diagrams use @code{usedesign <design_name>} (for all designs).
Note that it is
best to apply a full design at the first line of the chart, as any chart option
specified before it will likely be overwritten by applying a full design. You can
apply a full or partial design inside any scope, the effect will last only whithin
the scope.

Currently the following partial designs ship with Msc-generator for signalling charts: @code{hcn},
@code{thick_lines}, @code{all_blue}, @code{feng_shui_notes}. The first one
simply sets @code{hscale} to auto and turns on compression and numbering.
The second one makes lines of all default styles of width 2. The third
makes the color of lines in all default styles blue. The last makes
notes rounded and red on yellow background.
Block diagrams have the same, except @code{hcn}. Try them.

You can define or re-define chart designs by using the syntax below.

@example
defdesign @var{designname} @{
   [ msc=@var{parent design} | usedesign @var{parent design} ]
   [ msc+=@var{partial design} | usedesign @var{partial design}]
   @var{options}, ...
   @var{color definitions}, ...
   @var{style definitions}, ...
   @var{procedure definitions}, ...
@}
@end example

First you can name an existing full design to inherit from using the @samp{msc=} option or via
@samp{usedesign @var{parent design}}.
If specified the design will become a full design, too.
Thus in each such design definition the default styles are always present and
fully specified.
If omitted, the style will become a partial style.
Then you can specify optional multiple @samp{msc+=} or @samp{usedesign} options to bring in partial designs.
Finally, you can define colors, styles and procedures in any order and/or set one or more of the
attributes mentioned above.

It is possible to add your design definitions to a file having the
@code{.signalling}, @code{.graph} or @code{.block} extension and making them available
in all charts for use. See @ref{Design Library}.

@node Defining Shapes, Procedures, Chart Designs, Reference for Common Language Elements
@section Defining Shapes

This section describes how you can define new shapes that can be used in
entity headings of signalling charts or as block shapes in block diagrams.
Note that shapes are not (yet) available in graphs.

To define a new shape use the @code{defshape} command.


@example
defshape @var{shape_name} @{
   @var{defining lines};
   ...
@};
@end example

The @var{shape_name} is the name of the shape to define.
You can use letters, numbers, underscores and dots; and you must start with a letter.
Each @var{defining line} shall start with a capital letter, one of the list below. After this letter
comes a space delimited list of arguments, terminated by a semicolon.
Comments can start with a hashmark @samp{#} as usual and empty lines are also permitted.

@table @code
@item S
Starts a new @dfn{section} in the new file. Each shape may contain three optional
sections. You shall include the number of the section after the @code{S} separated
by a space. Sections contain paths, which describe the shape. Anything that comes
after this line will belong to this section all the way until the next @code{S} or
the end of the shape definition.
@table @code
@item 0
Section 0 specifies the background of the shape. This shall be a (set of) closed
path(s), which will be filled by Msc-generator using the value of
@code{fill.color} attribute.
@item 1
Section 1 specifies the foreground of the shape. This shall be a (set of) closed
path(s), which will be filled by Msc-generator using the value of the
@code{line.color} attribute.
@item 2
Section 2 specifies an alternative, additional way to specify the foreground.
It shall be
a set of potentially open paths, which will be drawn (stroked) using the
value of the @code{line.color} attribute. Contrary to section 1, other line
attributes will also be applied, such as @code{line.width} and
@code{line.type}.
You can specify both Section 1 and 2, in this case both will be drawn.
@item 3
Section 3 is a combination of Sections 0 and 2. Whatever shape is specified 
will be filled with @code{fill.color}, as well as have its path stroked with 
@code{line.width} and @code{line.type}. Only closed subpaths will be filled.
Using Section 3 is equivalent to specifying the same path twice, once in a 
Section 0 then in a Section 2.
@end table
@item M
This command is used within the specification of a path, and moves the (imaginary)
cursor to a given point. Two space-separated numbers after the @code{M} specifies
the x and y coordinates. Note that you can use floating-point numbers and
any scaling or position---Msc-generator will normalize the size of each shape based
on their height.
@item L
This command is used within the specification of a path, and draws a straight line
from the current position of the (imaginary) cursor to a given point.
Two space-separated numbers after the @code{L} specifies the x and y coordinates.
@item C
This command is used within the specification of a path, and draws a curved line
from the current position of the (imaginary) cursor to a given point.
Six space-separated numbers after the @code{C} specifies the x and y coordinates
of the target point and two control points, respectively. The curved line is
computed as a cubic bezier curve.
@item E
This command is used within the specification of a path, and closes a path.
It takes no arguments.
@item T
This optional item specifies where the entity label shall be drawn if the
shape is used in a signalling chart entity heading. This place will also
be used if the shape is applied to a block diagram block, which has content.
It takes two points
(four numbers) as arguments specifying the opposing corners of a rectangle.
If this line is omitted, the label will be displayed below the shape.
This line can be specified before, inside, between or after sections.
@item H
This optional item specifies which portion of the shape shall be shown
in the hints popup box on Windows in the internal editor
(see @ref{Typing Hints and Autocompletion}). This also takes 4 numbers specifying
a rectangle as above. If omitted the whole shape is shown (on a miniature scale).
This line can be specified before, inside, between or after sections.
@item P
This optional item can be used to define a @dfn{port}. Ports are currently
used by Block Diagrams, but we plan to extend support to Graphs, as well.
After the letter you need to specify an X and an Y coordinate and a name
(containing letters, numbers, underscores and dots). Optionally a @dfn{direction}
can also be associated with a port by adding a number at the end. This number
signifies at what angle arrows leave or arrive at the port. It is interpreted
in degrees clockwise from the north (top) direction. So east is 90, left is 270.
@end table

See @ref{Design Library} to see where to find and put your own files defining Shapes.



@node Procedures, Variables, Chart Designs, Reference for Common Language Elements
@section Procedures

Procedures allow you to store some chart text and replay it later. They are useful
to save typing, promote re-use instead of copy/paste. Since procedures can take parameters
their result can be customized.

To define a procedure, use the @code{defproc} command.

@example
defproc @var{proc_name} @{
   ...@var{chart text for procedure}...
@};

defproc @var{proc_name}(@var{$param_name}[=@var{default value}, ...) @{
   ...@var{chart text for procedure}...
@};
@end example

You can list parameters and their (optional) default value, as well. Parameter names
should begin with the dollar sign (@code{$}). They can be used anywhere a string or number
is needed, such as for attribute values, attribute names, entity and node names, etc.
You can not invoke a keyword using a parameter.

@image{exBB_csh}
@image{exBB, 15cm}

The @code{\Q()} text formatting escape can be used to substitute a parameter value into
a label.
The tilde (@code{~}) character can be used to append or prepend string constants to a
parameter, enabling string composition. In graphviz the @code{+} character can also be used.
The double-dollar special symbol (@code{$$}) can be used to denote an string that is always
unique for each procedure replay but when printed it is empty. This can be used, when you want to
define a node (or entity or marker for signalling charts) for each time the procedure is replayed,
but you do not want to pass a procedure parameter to compose with (such a @code{$group_name} above).

@image{exBC_csh}
@image{exBC, 15cm}

As you can see you can fall back to the default value of parameters, even if they are not the last one.

It is possible to replay a procedure within another procedure. Do not use recursion. It is not allowed
to define a procedure in another procedure, however. If you replay a procedure inside another one,
the parameters of the outer procedure will not be visible in the inner procedure.

When you refer to a style, color or procedure name, or an entity, node or marker
from within a procedure definition, their value will be substituted at the place of the replay.
Thus their existence cannot be verified at the time
of definition. A full parsing and verification is performed at replay. In order to avoid repeating
error messages as much as possible, if an error is already caught at procedure definition time,
the procedure cannot be replayed.

Color Syntax Highlighting is also limited for procedures, for example, styles cannot be determined
to exist, so they are never marked for error.

Styles and colors defined inside a procedure are local to that procedure (since the procedure has its
own scope). If you want to export these after a replay, you can use the @code{[export=yes]} attribute at
the procedure definition. This enables you to create procedures that define styles based on some parameters.

@multitable @columnfractions .4 .6
@item

@image{exBD_csh}

@tab

@sp 12
@image{exBD, 9cm}
@end multitable

Finally, inside procedures you may use conditional statements that execute or don't based on the
value of some parameters. After the @code{if} statement you can use either a single parameter or
two strings (potentially composed of multiple substrings with @code{~}) compared with one of the
following operators: @code{<=}, @code{<}, @code{==}, @code{>}, @code{>=} and @code{<>} (the latter
for non-equal). String comparison is UTF-8 and not numeric (thus "2" is larger than "10"). If you
use only a single parameter, the condition is true if the parameter is any non-empty string.

@multitable @columnfractions .5 .5
@item

@image{exBE_csh}

@tab

@image{exBE, 8cm}
@end multitable

Note that you can use braces to include more than one statement for the then or else branches.

@node Variables, File Inclusion, Procedures, Reference for Common Language Elements
@section Variables

In addition to procedure parameters strings preceeded by a dollar sign (@code{$}) can also denote
variables. Variables, just like procedure parameters can contain strings or numbers and can be
used anywhere where an attribute, entity, marker, block or node name or attribute value is needed.
Similar to procedure parameters, you can use the tilde (@code{~}) character to prepend or append
strings with variables.

One big difference between variables and procedure parameters is that variables can be used outside
and independent of procedures. This allows conditional statements (@code{if}) to be used outside parameters.

You may want to use variables for two reasons. One is to save typing. A long and often repeated
attribute value may be shortened (and potentially replaced everywhere in one go). The second
reason is to influence the operation of procedures without needing to pass a lot of parameters.

You can define or set the value of a variable using the @code{set} command.
The @code{<value>} must either be a number or an alphanumeric string - any other string must be
enclosed in-between quotation marks.
@example
set $<name> = <value>;
@end example

@multitable @columnfractions .5 .5
@item

@image{exH0_csh}

@tab

@image{exH0, 8cm}
@end multitable


Note that you can use the @code{set} command to change the value of parameters inside a procedure.

Variable definitions honour scoping, thus a variable defined in a scope is not available after
the scope has been closed (after the closing brace). It is, however, available in any nested
scope. This includes procedures replayed (to any depth). Variable lookup inside procedures happens
during replay, thus you can refer to variables inside procedures (even if the variables are defined
later in the input file). Any value change made to a variable remains in effect
after a scope closure.

@node File Inclusion, , Variables, Reference for Common Language Elements
@section File Inclusion

It is possible to include the text of another file in the current chart, similar to how it works in the
C preprocessor. Use the @code{include} command followed by a filename in quotation marks.
Currently the file is searched only in the directory of the file containing the @code{include} command.
You can use relative or absolute paths to include files from other directories.

On Windows, you can use both forward and backward slashes to separate directories, but due to text escape
sequences you need to double backslahes. Thus on Windows both are valid syntax:

@example
include "../file.signalling";
include "..\\file.signalling";
@end example

You can include other files from included files, in arbitrary depth.

When you issue an @code{include} command, parsing continues in the specified file and returns to
the original one - just after the include command. Certain errors (such as opening braces without
closing pairs) may cause errors in the original file - try including only totally correct files.

Note that Color Syntax Highlighting does not parse include files. Any styles, colors or procedures
defined there may be marked as undefined in the original file.

Note that if you want to define a set of procedures, designs or shapes you frequently use,
in the Windows GUI it is better to place them in a design library (@ref{Design Library})
as opposed to including them at the beginning of your file.
Design libraries are pre-parsed when the GUI starts up and are not re-parsed again
at compilation. In addition any styles or designs defined in them are taken into account by Color Syntax
Highlighting.

@node Signalling Chart Language Reference, Graph Language Reference, Reference for Common Language Elements, Top
@chapter Signalling Chart Language Reference

@menu
* Titles::
* Specifying Entities::
* Specifying Arrows::
* Boxes::
* Pipes::
* Verticals::
* Specifying Dividers::
* Notes and Comments::
* Parallel Blocks::
* Signalling Chart Attributes and Styles::
* Chart Options::
* Multiple Pages::
* Free Drawing::
* Commands::
* Mscgen Backwards Compatibility::
@end menu

@node Titles, Specifying Entities, Signalling Chart Language Reference, Signalling Chart Language Reference
@section Titles

The @code{title} and @code{subtitle} commands can be used to specify titles
for the chart. You must supply a label, perhaps using the colon syntax.

@example
title: This is a title;
subtitle: This is a subtitle;
@end example

The title and subtitle include text and a box around the text - the latter
being omitted in the @samp{plain} design. You can turn it on by setting
the @samp{line.*} and @samp{fill.*} attributes.
The default attributes are taken from the default styles @code{title} and
@code{subtitle}, changing these will affect all titles in the chart.
Entity lines are not drawn behind the titles by default, this can be changed
by setting the @code{vline.*} attribute.

@node Specifying Entities, Specifying Arrows, Titles, Signalling Chart Language Reference
@section Specifying Entities

Entities can be defined at any place in the chart, not only at the
beginning.


Entity names
can contain upper or lowercase characters, numbers, dots and underscores.
They are case sensitive and must start with a letter or
underscore and cannot end in a dot. If you want other characters,
you have to put the entity name between quotation marks every time it is
mentioned.
This, however, makes litte sense: you can set the label of the entity to
influence how the entity is called on the drawn chart.

It is also possible to define entities without attributes (having all
attributes set to default) by typing

@example
@var{entityname}, ...;
@end example

It is also possible to change some of the attributes later in the chart,
well after the
definition of the entity. The syntax is the same as for definition ---
obviously the name identifies an already defined entity.

Note that typing several entity definition commands one after the other
is the same as if all entity definitions were given on a single line.
Thus
@example
a;
b;
c;
@end example

is equivalent to

@example
a, b, c;
@end example


Also, @code{heading} commands are combined with the definitions into a
single visual line of entity headings.

@menu
* Entity Positioning::
* Group Entities::
* Entity Attributes::
* Implicit Entity Definition::
* Entity Headings::
* Entity Shapes::
@end menu

@node Entity Positioning, Group Entities, Specifying Entities, Specifying Entities
@subsection Entity Positioning

Entities are placed on the chart from left to right in the order of
definition. This can be influenced by the @code{pos} and
@code{relative} attributes.

Specifying @code{pos} will place the entity left or right from its default
location. E.g., specifying @code{pos=-0.25} for entity @code{B} makes @code{B}
to be 25% closer to its left neighbour. Thus @code{pos} shall be specified in
terms of the unit distance between entities. (Which is 130 points - a historic
value kept for backwards compatibility.)

The next entity @code{C}, however, will always be from a unit distance from the
entity defined just before it, so in order to specify a 25% larger space, on the
right side of entity @code{B}, one needs to specify @code{pos=0.25} for
@code{C}.

@multitable @columnfractions .5 .5
@item

@image{ex43_csh}

@tab

@image{ex43, 8cm}
@item

@image{ex40_csh}

@tab

@image{ex40, 7.48cm}
@item

@image{ex41_csh}

@tab

@image{ex41, 8cm}
@end multitable

The attribute @code{relative} can be used to specify the base of the
@code{pos} attribute. Take the following input, for example.
In this case @code{C} will be placed halfway between @code{A} and
@code{B}.

@multitable @columnfractions .5 .5
@item

@image{ex42_csh}

@tab

@image{ex42, 3.84cm}
@end multitable


Note that specifying the @code{hscale=auto} chart option makes entity
positining automatic. This setting overrides @code{pos} values with
the exception that it maintains the order of the entities that can be
influenced by setting their @code{pos} attribute. @xref{Chart Options}.
In most cases it is simpler to use @code{hscale=auto}, you need @code{pos}
only to fine-tune a chart, if automatic layout is not doing a good job.

@node Group Entities, Entity Attributes, Entity Positioning, Specifying Entities
@subsection Group Entities

A group entity can contain other entities. Groups can be nested arbitrary deep.
To specify a group entity, use curly braces after an entity definition (but
before the colon or comma). Between the braces you can list entity definitions,
style/color definitions or chart options@footnote{Only some of the chart options can be
used, the ones that merely change the context and do not draw. E.g. the
@samp{background} options cannot be used. Practically only the @samp{indicator} chart
option makes any sense.}. The curly braces open a new scope, so
any style or color definition or chart option takes its effect only within the
group of entities between the curly braces. See @ref{Scoping} for more information.

Any entity you specify in the group must be a newly defined entity. It is not
possible to place already defined entities into a group. Similar, an already
defined entity cannot be made a group entity later by adding entities to it.
Nor can a group be later extended with additional entities.

The position of a group entity is derived from its members so the @samp{pos} and
@samp{relative} attributes cannot be used.

Group entities can be @dfn{collapsed}, by setting the @samp{collapsed} attribute
to yes (or via the GUI on Windows). A collapsed group entity does not
show its member entities, but is displayed as a non-grouped entity. Arrows and
boxes in the chart are modified (or even removed) to reflect the collapse.
If the @samp{indicator} attribute of the entity is set to yes, a small
indicator is shown both inside the collapsed entity and for each arrow or box
removed.

Setting the @code{large} attribute makes the group entity span the entire height
of the chart in the background as opposed to drawing a group entity heading.
See the difference below. This is in effect only if the group entity is not
collapsed.

@multitable @columnfractions .4 .6
@item

@image{exB9_csh, 7cm}

@tab

@image{exB9, 9cm}
@end multitable




@node Entity Attributes, Implicit Entity Definition, Group Entities, Specifying Entities
@subsection Entity Attributes

The following entity attributes can only be set at the definition of
the entity.
@table @code
@item label
This specifies the text to be displayed for the entity. It can contain
multiple lines or any text formatting character. @xref{Text
Formatting}. If the label contains non alphanumeric characters, it must be
quoted between double quotation marks.
The default is the name of the entity.
@item pos
This attribute takes a floating point number as value and defaults to
zero. It specifies the relative horizontal offset from the entity
specified by the @code{relative} attribute or by the default position
of the entity. The value of 1 corresponds
to the default distance between entities. See a previous section for
an example.
Grouped entities cannot have this attribute.
@item relative
This attribute takes the name of another entity and specifies the
horizontal position used as a base for the @code{pos} attribute.
Grouped entities cannot have this attribute.
@item shape
This attribute takes the name of the shape you want for the entity
headings. See @ref{Entity Shapes}.
@item shape.size
This attribute specifies the size of the shape to use for the entity
headings. Only has effect if a valid shape is specified via the
@code{shape} attribute. It takes one of @code{tiny}, @code{small},
@code{normal}, @code{big} or @code{huge} with @code{small} as default.
You can also use @code{auto}, which makes the shape large enough to
contain the label. This setting is valid only for shapes that define
a position for the label. (See the @code{T} command in @ref{Defining Shapes}.)
For shapes that define a label position if you set a specific size, the
label's size is scaled to fit the shape (well, the label position in it).
In contrast, if you set @code{auto}, the size of the shape is scaled so
that it fits the size of the label.
@item collapsed
This attribute can be used to collapse a group entity. Only group
entities can have this attribute.
@item indicator
If set to yes (default) a small indicator will be displayed in a collapsed
entity and also for any arcs that disappeared because of the collapse of this
entity. On non-collapsed group entities it has no effect. Only grouped entities
can have this attribute.
@end table

The following attributes can be changed at any location and have their
effect downwards from that location.

@table @code
@item show
This is a binary attribute, defaulting to yes. If set to no, the entity
is not shown at all, including its vertical line. This is useful to
omit certain entities from parts of the chart where their vertical line
would just crowd the image visually. The commands @samp{show} and @samp{hide}
followed by entity names are shorthands for setting or clearing these attributes.
See more on entity headings in @ref{Entity Headings}.
@item active
This is a binary attribute, defaulting to no. If set the entity line becomes
a thin long rectange indicating that the entity is active. You can set the fill
of the rectangle via the @samp{vfill.*} attributes. The commands @samp{activate}
and @samp{deactivate} are shorthand for setting or clearing this attribute.
Uisng the keywords is equivalent to setting the attributes, except that when
the keywords are used just after an arrow, the activation/deactivation will take
place immediately at the tip of the arrow, and not after.
@item color
This sets the color of the entity text, the box around the text and
the vertical line to the same color. It is a shorthand to specify
@code{text.color}, @code{line.color} and @code{vline.color} to the same value.
@item line.*
@itemx vline.*
@itemx fill.*
@itemx vfill.*
@itemx text.*
@itemx shadow.*
See @ref{Common Attributes} for the description of these attributes.
@item aline.*
@itemx atext.*
@itemx arrow.*
These attributes can be used to set the line, text and arrowhead attributes of
arrows starting from this entity. Their use is described in @ref{Arrow Appearance}.
Note they do not apply to block arrows.
@end table

@node Implicit Entity Definition, Entity Headings, Entity Attributes, Specifying Entities
@subsection Implicit Entity Definition

It is not required to explicitly define an entity before it is used.
Just typing the arrow definition @code{a->b;} will automatically
define entities @samp{a} and @samp{b} if not yet defined. This
behaviour can be disabled by specifying the @option{--pedantic}
command-line option or specifying @code{pedantic=yes} chart option.
@xref{Chart Options}. Disabling implicit
definition is useful to generate warnings for mis-typed entity names@footnote{
To this end, color syntax highlighting underlines an entity name appearing
the first time. This allows quickly realizing if the name of an entity is
misspelled.}.

Implicitly defined entities always appear at the very top of the chart. If
you want an entity to appear only later, define it explicitly.

@node Entity Headings, Entity Shapes, Implicit Entity Definition, Specifying Entities
@subsection Entity Headings

By default, when an entity is defined, its heading is drawn at that location. If
the entity name is preceeded by the @code{hide} keyword or the @code{show=no}
attribute is specified at the entity definition then the entity heading is not
drawn at the location of the definition. It is drawn later, if/when the entity
is turned on by using @code{show} followed by the entity name or by setting
@code{show=yes}. Note that multiple entities can be listed after both
@code{show} and @code{hide}. It is also possible to specify other attributes for
entities after these keywords.

Mentioning an entity after its definition either preceeded by @code{show} or
with @code{show=yes} will cause
an entity heading to be drawn into the chart even if the entity is already shown.
This can be useful for long charts, see @ref{Defining Entities} for examples.

You can display all of the entity headings using the @code{heading;} command, as
well. This command displays an entity heading for all (currently showing)
entities. This may be useful after a @code{newpage;} command, @pxref{Commands}.
However, the best practice is to use @samp{newpage [auto_heading=yes];} instead,
since it only shows the heading when the chart is viewed per-page (which is the
same for page breaks inserted by automatic pagination).

Using the @code{show} and @code{hide} commands in themselves with no entity
specified after, will make @emph{all} entities show or hide. (Same with
@code{activate} and @code{deactivate}.) See the example below.

@multitable @columnfractions .27 .73
@item @image{exBF_csh, 5cm}
@tab @image{exBF, 11cm}
@end multitable

Note that entity related commands are merged. Thus saying @code{show; hide A;}
will show all entities, except @code{A} in a single line of entity headings.
If you want to manipulate entities in separate visual lines, insert a @code{nudge;}
command in between the entity manipulating commands (as at the end of the example
above).

@node Entity Shapes, , Entity Headings, Specifying Entities
@subsection Entity Shapes

The shape of an entity heading can be altered from the default box-like
appearance to something custom using the @code{shape} attribute. Its value
is a string, the name of the shape. The actual appearance of shapes is defined
in separate files. Msc-generator comes with a few default shapes (their name
all start with @code{def.}), but you can define your own shapes or add third-party
Defining Shapes. See @ref{Defining Shapes} for more.

For some shapes, the label of the entity is written inside the shape, for some
it is written below. This is decided by the author of the shape. If the label is
written inside, it is scaled to fit. You can influence the size of the shape via the
@code{shape.size} attribute, which takes the values @code{tiny}, @code{small},
@code{normal}, @code{big}, @code{huge} or @code{auto} with @code{small} as default.

Note that the above two attributes can be set in the @code{entity} and
the @code{entitygroup_collapsed} style, which will influence all entities in a chart
at once.

@node Specifying Arrows, Boxes, Specifying Entities, Signalling Chart Language Reference
@section Specifying Arrows

Arrows are probably the most important elements in a message sequence
chart. They represent the actual messages.
Arrows can be specified using the following syntax.

@example
@var{entityname} @var{arrowsymbol} @var{entityname} [@var{attr} = @var{value} | @var{style}, ...];
@end example

@var{arrowsymbol} can be any of @samp{->}, @samp{<-} or @samp{<->}, the
latter for bidirectional arrows. @code{a->b} is equivalent to
@code{b<-a}.
This produces an arrow between the two entities specified
using a solid line. Using @samp{>}/@samp{<>}, @samp{>>}/@samp{<<>>} or
@samp{=>}/@samp{<=>}, will result in dotted, dashed or double line
arrows, respectively.
These settings can be redefined using styles, @pxref{Defining Styles}.
There are two more arrow symbols for you to re-define: @samp{==>} and
@samp{=>>} (with reverse and bi-directional variants, too: @samp{<==>} and
@samp{<<=>>}). These default to
double lines, with the latter having sharp arrowheads, as well.

It is possible to omit one of the entity names, e.g., @code{a->;}.
In this case the arrow
will expand to/from the chart edge, as if going to/coming from an
external entity. Using the pipe symbol @samp{|} as start or endpoint
instead will still make the arrow go to (or come from) no specific entity,
but not at the very end of the chart, but immediately after the last entity
(or before the first one).

@multitable @columnfractions .45 .55
@item

@image{exB5_csh, 6.5cm}

@tab

@image{exB5, 8cm}
@end multitable

You can also use the @code{start before} and @code{end after} keywords
after the arrow specification to precisely indicate where the arrow should
start and/or end. You need to specify an entity afterwards and optionally
an offset. The terms @samp{before} and @samp{after} should be understood
in the direction of the arrow, so if an arrow is right-to-left, then
@code{start before X} makes the arrow start right of entity @code{X}.
A positive offset moves the arrow endpoint even further from the entity
specified. (In the example above @code{start before X +10} would move the
start of the arrow even more to the right. The offset is specified in pixels.
The default distance from the entity (to which offset is added) is 30 pixels
times the value of the @code{hscale} (and exactly 30 for @code{hscale=auto}).

It is possible to specify multi-segment arrows, such as @code{a->b->c}
in which case the the arrow will expand from @samp{a} to @samp{c}, but
an arrow head will be drawn at @samp{b}, as well. This is used to
indicate that @samp{b} also processes the message indicated by the
arrow. The arrow may contain any number of segments, and may also start
and end without an entity, e.g., @code{->a->b->c->d->;}. As
a syntax relaxation, additional line segments can be abbreviated with a
dash (@samp{-}), such as @code{a<=>b-c-d;}. Subsequent segments inherit
the line type and direction of the first one. This enables quick
changes to these attributes with minimal typing, as only the first
arrow symbol needs to be changed. As a further possibility, different
arrow symbols can also be used for different segments, such as
@code{a->b=>c>>d-e;}, but all the arrow symbols must be of the same
direction. It is therefore not possible to mix arrows of different directions,
such as @code{a->b<-c;} or @code{a->b<->c;}. Note that specifying different
arrow symbols affect only the line attributes of the segments by default,
but they can also impact the arrowhead, text or other attributes, see
@ref{Arrow Appearance} below.

If the entities in a multi-segment arrow are not listed in the same
(or exact reverse)
order as in the chart, Msc-generator gives an error and ignores the arrow.
This is to protect against unwanted output after rearranging entity order.

Arrows can also be defined starting and ending at the same entity,
e.g., @code{a->a;}. In this case the arrow will start at the vertical
line of the entity and curve back to the very same line. Such arrows
cannot be multi-segmented.

Only non-grouped entities can be used in an arrow definition.
If an entity used to define an arrow is not shown due to the collapse of
its group entity, Msc-generator will automatically use the collapsed
group entity when drawing the arrow, instead. If the arrow becomes degenerate
(spanning between only a single collapsed group entity) or disappears
entirely, an indicator will be shown instead, if the @samp{indicator}
attribute of the collapsed group entity was set to yes (default).

@menu
* Lost Messages::
* Arrow Attributes::
* Arrow Appearance::
* Block Arrows::
@end menu

@node Lost Messages, Arrow Attributes, Specifying Arrows, Specifying Arrows
@subsection Lost Messages

Sometimes one want to express that a message is lost. You can do this in
Msc-generator in two ways. Either, you can add an asterisk between the two
entities where the message is lost; or you can add a 'lost at' clause after
the arrow specification before the label or attributes. This causes a small @code{x}
to be drawn at the place specified and the dimming of the remainder of the
arrow.

@multitable @columnfractions .5 .5
@item

@image{ex91_csh}

@tab

@image{ex91, 8 cm}
@end multitable

The first three ones are the quick one. The message lost will be indicated
around the entity after or before the asterisk. Specifically, it will be
between this and its neighbouring visible entity. If that visible entity
is also part of the arrow, the loss will be at one third the distance between
them, else it will be halfway.
Using the second form, you can specify exactly where the loss happened.
It can be placed onto an entity, left or right from it, or between two entities.
These are specified as @samp{lost at <entity>}, @samp{lost at <entity>-},
@samp{lost at <entity>+} or @samp{lost at <entity1>-<entity2>}, respectively.
You can add two plus or minus symbols to increase distance.
You can also specify any offset in addition by adding a number after,
such as in @samp{lost at <entity> <number>}. The number will be interpreted in
pixels and shifts the vertical left or right depending on its sign.

The appearance of the loss symbol (the @code{x}) can be influenced using the
@code{x.line.width}, @code{x.line.color} and the @code{x.size} attributes. The
latter takes the same values as arrowhead sizes: @code{tiny}, @code{small},
@code{normal}, @code{big} or @code{huge}, with @code{small} as default.

The appearance of the lost portion of the message can also be influenced via the
@code{lost.text.*}, @code{lost.line.*} and the @code{lost.arrow.*} attributes. Anything
specified here will be added to the text, line and arrowhead format of the arrow.
Currently only the color of the line and the arrowhead is overlaid with
@code{++white,128} (for plain designs),
making them weaker, but you can change to dash lines, specifly a narrower line or
empty arrowheads.

@node Arrow Attributes, Arrow Appearance, Lost Messages, Specifying Arrows
@subsection Arrow Attributes

Arrows can have the following attributes.
@table @code
@item label
This is the text associated with the arrow. See @ref{Labels} for more information
on how to specify labels. In Msc-generator the first line of the label is
written above the arrow, while subsequent lines are written under it.
Future versions may make this behaviour more flexible.
@item text.*
All text formatting attributes described in @ref{Common Attributes}
can be used to manipulate the appearance of the label@footnote{A
special note on left and right text margins (to be specified via @code{\ml()}
and @code{\mr()} escapes). Msc-generator always adds enough text margins
to prevent the label to overlap with the arrowhead. Thus, if you specify less
margin, it will have no effect.}.
@item number
Can be set to @code{yes}, @code{no} or to a number, to turn numbering
on or off, or to specify a number, respectively. See @ref{Numbering}.
@item refname
Can be set to any string and is used to give a name to the arrow, which can
be used to reference this arrow. Use the @code{\r(name)} escape in labels
to insert the number of the referenced arrow. See @ref{Numbering}.
@item compress
Can be set to @code{yes} or @code{no} to turn compressing of this arrow
on or off. See @ref{Compression and Vertical Spacing}.
@item vspacing
Can be set to a number interpreted in pixels or to the string @code{compress}.
Governs how much vertical space is added before the arrow (can be negative).
This attribute is another form (superset) of the @code{compress} attribute;
@code{compress=yes} is equivalent to @code{vspacing=compress}, whereas
@code{compress=no} is equivalent to @code{vspacing=0}.
@item angle
This takes a number in degrees and makes the arrow slanted. Arrows pointing
to the same entity cannot have such an attribute. This attribute takes its
default value from the @code{angle} chart option (or is zero in the absence of
such an option, which corresponds to horizontal arrows).
@item slant_depth
This is similar in effect to the @code{angle} attribute, but instead of specifying
the angle of the slant in degrees, you can use this attribute to specify how many
pixels shall the end of the arrow be below the start of it. If you specify both
the @code{angle} attribute and @code{slant_depth} the latter takes effect.
@item color
This specifies the color of the text, arrow and arrowheads. It is a shorthand
to setting @code{text.color}, @code{line.color} and @code{arrow.color} to the
same value.
@item line.color, line.width
Set the color and the width of the line, @pxref{Common Attributes}.
@item line.corner
This attribute specifies how the line shall be drawn at corners. It impacts
boxes and entities drawn with this line, for arrows it is effective for
arrows that start and end at the same entity. Its value can be @code{none},
@code{round}, @code{bevel} or @code{note}. See the example below.
Setting @code{line.corner} without @code{line.radius} will result in the
default radius of 10.
@item line.radius
For arrows starting and ending at the same entity, this specifies the roundness
of the arrow corners. 0 is fully sharp (equivalent to @code{line.corner=none},
positive values are meant in pixels, a negative value will result in a single
arc (for any corner setting). If only @code{line.radius} is set and not
@code{line.corner} the result will be a round corner.
@end table

@multitable @columnfractions .5 .5
@item

@image{ex44_csh}

@tab

@image{ex44, 8 cm}
@end multitable

@table @code
@item arrow.size
The size of the arrowheads. It can be @code{epsilon}, @code{spot}, @code{tiny},
@code{small}, @code{normal}, @code{big} or @code{huge}, with small as default.
@item arrow.color
The color of the arrowheads.
@item arrow.type
Specity the arrowhead type. The values can be @code{half}, @code{line},
@code{empty}, @code{solid}, which draw a single line, a two-line arrow,
an empty triangle and a filled triangle, respectively. The above 4 types
also exist in @code{double} and @code{triple} variants, which draw two or
three of them. @code{sharp} and
@code{empty_sharp} draws a bit more pointier arrowhead, filled or empty,
respectively. Even more pointed are @code{vee} and @code{empty_vee}.
@code{diamond} and @code{empty_diamond} draws a filled or empty diamond, while
@code{dot} and @code{empty_dot} draws a filled or empty circle.
The last four has non-symmetric versions, where the dot or diamond is not
drawn on the entity line, but before it: @code{nsdiamond}, @code{empty_nsdiamond},
@code{nsdot} and @code{empty_nsdot}.
Specifying @code{none} will result in no arrowhead at all. This
attribute sets both the @code{endtype} and @code{midtype}, see below.
@item arrow.endtype
Sets the arrow type for arrow endings only. This refers to the end of
the arrow, where it points to. In case of bidirectional arrows,
both ends are drawn with this type. It defaults to a filled triangle.
@item arrow.midtype
This attribute sets the arrowhead type used for intermediate entities of
a multi-segment arrow. It defaults to a filled triangle.
@item arrow.skiptype
This attribute specifies what to draw for entities the arrow passes over
but does not stop at. E.g., if we have three entities @samp{a}, @samp{b}
and @samp{c}, then an arrow specified as @code{a->c}, will pass over entity
@samp{b}. This attribute defaults to none, but another suitable value is
@code{jumpover}, which draws a small half-circle.
@item arrow.starttype
This attribute sets the arrowhead type used at the starting point of an
arrow. It defaults to no arrowhead.
@item arrow.xmul
@itemx arrow.ymul
These attributes change the width or the height of the arrowhead. The default
value is @samp{1}. They are multipiers, thus the value of @samp{1.1} results
in a 10% increase, for example.
@end table

@multitable @columnfractions .53 .47
@item

@image{ex45_csh, 9cm}

@tab

@image{ex45, 7.5 cm}
@end multitable

@table @code
@item arrow.gvtype
@itemx arrow.gvendtype
@itemx arrow.gvmidtype
@itemx arrow.gvskiptype
@itemx arrow.gvstarttype
Use these attributes to set the corresponding arrowhead using the graphviz-
style arrowhead specification syntax. This syntax is a superset of what graphviz
supports and is not really meaningful for block arrows. Setting any of
@code{arrow.*type} or @code{arrow.gv*type} will erase the other attribute, since
these govern the same property of the arrow.

You have a set of basic forms @code{normal} (a regular filled triangle),
@code{inv} (filled triangle in inverse direction), @code{vee} (a v shape),
@code{crow} (v shape in the reverse direction), @code{tee} (a thick line
perpendicular to the arrow line), @code{tick} (a thin line perpendicular
to the arrow line), @code{box} (a square), @code{diamond}, @code{dot},
@code{curve} (a half circle line) and @code{icurve} (in the reverse direction).
Msc-generator supports the following additional basic forms: @code{sharp},
@code{line} and @code{jumpover}, which are the same as for the @samp{arrow.type}
attribute above; and @code{sbox}, @code{sdiamond} and @code{sdot}, which are
symmetric versions of @code{box}, @code{diamond} and @code{dot},
respectively.@footnote{This is because @code{box}, @code{diamond} and @code{dot}
in graphviz are drawn before the target, in conflict with Msc-generator beahviour
for @samp{arrow.type}. Thus, if you specify @samp{arrow.type=dot}, you will get
a dot centered on the arrow line; while if you use @samp{arrow.gvtype=dot}, you
will get one before the entity line.}

You can combine the basic forms by appending them, such as @code{normalnormal},
which is a double filled triangle. You can create arbitrary long combinations.
The first form specified will be the tip of the arrow closest to the entity line
with the remaining forms following behind.

Some of the forms may be prepended by the letter @code{o} to create a non-filled
version, such as @code{odot} or @code{onormal}. You can use the @code{l} or @code{r}
letters to draw only half of the arrowhead which falls on one side of the arrow line,
such as @code{lbox}, @code{rcurve} or even @code{olnormal}.

Inserting a size modifier will change the size of the subsequent forms, such as
@code{spotdotsmallnormal}, will draw a smaller dot and a larger triangle. Since
the term @samp{normal} is both a size and a type, if you mean the size, use
@code{sizenormal}.
In addition to size modifiers, you can also insert any color name.
Finally, you can also insert one of the following attributes: @code{lwidth} to
change the line width of the arrowhead; @code{ltype} to change the line type of
the arrowhead; @code{color} to change the color of the arrowhead (e.g., to an
rgb value); @code{xmul}, @code{ymul} or @code{mul} to apply a (cumulative) multiplier
to the x or y dimension of the arrowhead or to both. These attributes must be
terminated with a pipe symbol (@code{|}) and when using them the attribute value
must be enclosed in quotation marks, such as
@code{arrow.gvtype="xmul=0.2|normal|color=12,34,56|dot"}. See the examples below.

Note that you can use these attributes to set arrowhead style for block arrows,
but in that case only one form can be given (you can use @code{stripes} and
@code{triangle_stripes}, but cannot use @code{line}, @code{curve}, @code{icurve},
@code{jumpover} and @code{crow}. Also, line/color attributes have no effect.
All in all, you are better off not using the graphviz syntax for block arrows.
@end table

@multitable @columnfractions .57 .43
@item

@image{exBA_csh, 16cm}

@tab

@image{exBA, 6.5 cm}
@end multitable

@table @code
@item lost.text.*
The values specified here will be added to the values of @code{text.*}
when drawing the label of the lost part of the message.
@item lost.line.*
The values specified here will be added to the values of @code{line.*}
when drawing the line of the lost part of the message.
@item lost.arrow.*
The values specified here will be added to the values of @code{arrow.*}
when drawing the arrowheads in the lost part of the message.
@item x.size
The size of the loss symbol for lost messages.
It can be @code{tiny}, @code{small}, @code{normal}, @code{big} or
@code{huge}, with normal as default.
@item x.line.width
@itemx x.line.color
The linewidth and color of the loss symbol for lost messages.
@end table

Note that default values can be changed using styles, @pxref{Defining Styles}.


@node Arrow Appearance, Block Arrows, Arrow Attributes, Specifying Arrows
@subsection Arrow Appearance

There are a number of factors influencing how an arrow appears. In this section
we describe the order of precedence among them. See @ref{Defining Styles} for
more information on styles.

@enumerate
@item Attributes specified after the arrow definition always take precedence.
@item If an attribute is not specified after the arrow definition, it takes
its value from a refinement style, such as @code{->} or @code{=>}. In case
of multi-segment arrows, which use multiple types of arrow symbols, such as
@code{a->b=>c} each refinement style is applied in the order the arrow points.
Thus in the case of @code{a->b=>c} any attribute specified in style @code{=>}
takes precedence over the value (if any) specified in @code{->} for the same
attribute. The same order (the order towards the destination end of the arrow)
is applied even if the arrow is specified backwards, as @code{c<=b<-a}.
For bidirectional arrows, the order is as written in the  input file.
Line attributes are special, because they are also recorded and applied to
the respective segments. (This is why normally refinement styles only
specify line attributes. Specifying the arrowhead could also make sense,
but those are not applied to individual segments, but to the whole arrow.)
@item If a line, text or arrowhead attribute is not specified in any of the
refinement styles applied it takes its value from the @code{aline.*},
@code{atext.*} or @code{arrow.*} attribute of the source entity, respectively.
(For bidirectional arrows, first entity written in the text file.) Since refinement styles
usually overwrite the line type, it makes more sense to set e.g., line color
in these attributes, if you want to automatically highlight arrows starting
from a specific entity.
@item If an attribute is not specified via any of the ways above, it takes
its default value from the @code{arrow} default style. (Chart designs change this
to impact all arrows.) This style is guaranteed  a value for all attributes,
except @code{text.*}.
@item Finally, unspecified @code{text.*} attributes take their values from the
value set in the @code{text.*} chart options (used to globally set the font
for example) or, if none set, a default font.
@end enumerate

@node Block Arrows, , Arrow Appearance, Specifying Arrows
@subsection Block Arrows

When typing @code{block} in front of any arrow definition, it will become
a @dfn{block arrow}. The label of a block arrow is displayed inside it.
In addition to the attributes above, block arrows also have fill and shadow
attributes, similar to entities.

All arrowheads explained above for regular arrows are supported, except the
@code{double} and @code{triple} ones. In general, types with @code{empty} in
them, draws a variant of the arrowhead which is not taller that the body of the
block arrow. The ones with @code{line} draw the same as the ones without.
Three additional types @samp{empty_inv}, @samp{stripes} and
@samp{triangle_stripes} types are supported, as well.
See the example below for a detailed list of all types supported for block arrows.

@multitable @columnfractions .58 .42
@item

@image{ex67_csh, 10cm}

@tab

@image{ex67, 6 cm}
@end multitable

If the arrow has multiple segments and the type of the inner arrowheads is
either of @code{half}, @code{line}, @code{empty}, @code{solid} or @code{sharp}
the block arrow is split into multiple smaller arrows. In this case the arrow
label is placed into the leftmost, rightmost or middle one of the smaller
arrows, depending on the value of the @code{text.ident} attribute.

It is also possible to use different arrow symbols leading to different line types,
but only if the middle arrow type is such that the arrow is split into multiple
contours. If not, the whole arrow is drawn with the line type of the first segment.

@image{ex38_csh}

@image{ex38, 7cm}

Block arrows do not accept the @code{arrow.skiptype} attribute and are not
impacted by setting the @code{aline.*}, @code{atext.*} or the @code{arrow}
attribute of their source entity. However, they can be slanted using the @code{angle} attribute.

@node Boxes, Pipes, Specifying Arrows, Signalling Chart Language Reference
@section Boxes

@menu
* Box Series::
* Box Tags::
@end menu

Boxes enable 1) to group a set of arrows by drawing a rectangle around them; 2)
to express alternatives to the flow of the process; and 3) to add comments to
the flow of the process. The first two use is by adding a set of arrows to the
box, while in the third case no such arrows are added, making the box
@dfn{empty}.

The syntax definition for boxes is as follows.

@example
[box] @var{entityname} @var{boxsymbol} @var{entityname} [@var{attr} = @var{value} | @var{style}, ...]
@{ @var{element}; ... @};
@end example

The @code{box} symbol is optional at the beginning of the line.
The @var{boxsymbol} can be @samp{..}, @samp{++}, @samp{--} or @samp{==} for
dotted, dashed, solid and double line boxes, respectively.

As with arrows the two entity names specify the horizontal span. These can be
omitted (even both of them), making the box auto-adjusting to cover all the
elements within. If there are no elements within and you omit one or both
entities the default is to span to the edge of the chart. Specifying the entity
names therefore, is useful if you want a deliberately larger or smaller box, or
if you specify an @dfn{empty} box. Contrary to arrows, you can use group
entities when specifying a box. The box will then cover all member entities in
that group. Specifying the leftmost or rightmost member entity instead of the
group entity makes a difference only if the group entity is collapsed. In the
former case the box may disappear, in the latter case it will not. See the
example below.

@multitable @columnfractions .48 .52
@item

@image{ex73_csh, 7.8cm}

@tab

@image{ex73, 8cm}
@end multitable

Boxes take attributes, controlling colors, numbering, text
identation quite similar to arrows. Specifically boxes also
have a @code{label} attribute that can also be shorthanded, as for
arrows. For example: @code{..: Auto-adjusting empty box;} is a valid
definition. The valid box attributes are @code{label},
@code{number}, @code{refname}, @code{compress}, @code{vspacing}, @code{color}, @code{text.*},
@code{line.*}, @code{shadow.*} and @code{fill.*}. The latter
specifies the background color of the box, while @code{line.*}
specifies the attributes of the line around. Note that @code{color} for
boxes is equivalent to @code{fill.color}. @code{text.ident}
defaults to centering for empty boxes and to left identation
for ones having content.

After the (optional) attributes list, the content of the box can be
specified between braces @samp{@{} and @samp{@}}. Anything can be
placed into an box, including arrows, dividers, other
boxes or commands.
If you omit the braces and specify no content, then you
get an empty box, which is useful to make notes, comments or
summarize larger processes into one visual element by omitting the
details.

@node Box Series, Box Tags, Boxes, Boxes
@subsection Box Series

If a box definition is not followed by a semicolon, but another
box definition, then the second box will be drawn directly
below the first one. This is useful to express alternatives, see the below
example.

@multitable @columnfractions .5 .5
@item

@image{ex25_csh}

@tab

@image{ex25, 8cm}
@end multitable

The subsequent boxes will inherit the fill, line and text attributes
of the first one, but you can override them. The line type of subsequent boxes
(@samp{--} in the example) will determine the style separating the boxes ---
the border will be as specified in the first one.
The horizontal size of the combined box is determined by the first
definition, entity names in subsequent boxes are ignored.

Boxes can be collapsed, similar to group entities. The @samp{indicator}
attribute governs if collapsed boxes show a small indicator to indicate
that there is hidden content inside.

@node Box Tags,  Pipes, Box Series, Boxes
@subsection Box Tags

Boxes can also have @dfn{tags}, which are small enclosed labels at the
top-left corner of the box. Tags are useful to label the content of the box,
such as alternatives, loops or optional sections, while keeping the ability
to add a regular box label, as well.

To specify a tag, use the @code{tag} attribute, and specify the label
of the tag. If the label contains non-alphanumeric characters (or spaces),
you need to put them in between quotation marks. You can specify the
appearance of the tag via the @code{tag.line.*}, @code{tag.fill.*} and the
@code{tag.text.*} attributes. Especially the @code{tag.line.corner}
attribute can be used to influence the bottom right corner of the tag
(but not the other corners).

@multitable @columnfractions .5 .5
@item

@image{ex99_csh}

@tab

@image{ex99, 8cm}
@end multitable


@node Pipes, Verticals, Boxes, Signalling Chart Language Reference
@section Pipes

By typing @code{pipe} in front of a box definition, it is turned into a pipe.
Pipes can represent tunnels, encapsulation or other associations (e.g., encryption)
in networking technologies. Using them one can visually express as messages travel
within the tunnels or along other associations.

Pipes take all the attributes of boxes, plus two extra ones, called @code{solid}
and @code{side}. @code{solid} controls the transparency of the pipe. It can be
set between 0 and 1 (or alternatively 0 and 255, similar to color RGB values).
The value of 0 results in a totally transparent pipe: all its contents is drawn
in front of it. The value of 1 results in a totally opaque pipe, all its content
is "inside" the pipe, not visible. Values in between result in a
semi-transparent pipe. @code{side} can be set to @code{left} or @code{right} and
governs which side the pipe can be looked into from@footnote{Beware that if you
embed the chart in a Windows document, then using a lot of transparency can
increase the size of the embedded object excessively.}.

For pipes the @code{line.radius} attribute governs, how wide the oval is at the
two ends of the pipe. The default value is 5. Note that @code{line.corner} has
no effect for pipes. Both @code{line.radius} and
@code{side} can only be set on the first of the pipe segments, see below.

@multitable @columnfractions .5 .5
@item

@image{ex39_csh}

@tab

@image{ex39, 8cm}
@end multitable

On the example above one can observe, that the last two pipes are smaller
than the first two, even though they have exactly the same two arrows within.
This is because in case of the first two arrows the label of the pipe itself
is visible at together with the two arrows within.
In contrast, the last two pipes are fully opaque so the pipe label can be drawn
over its content.

Note the two @code{defstyle} commands before the pipes, as well. They are
re-defining the default fill for pipes. You can read more about this in
@ref{Defining Styles}.

Similar to boxes multiple subsequent pipe definitions can be placed after each
other without a semicolon. In case of boxes this results in a series of vertical
connected boxes. In case of pipes this results in a series of horizontal pipe
segments besides each other. However, contrary to boxes only one set of content
can be specified.

@image{ex66_csh}

@image{ex66, 15cm}

@node Verticals, Specifying Dividers, Pipes, Signalling Chart Language Reference
@section Verticals

In contrast to arrows that span from left-to-right, a @dfn{vertical} is an element 
that spans up and down. It can be 

@itemize
@item a box or a block arrow;
@item a @dfn{brace} or @dfn{bracket}, to show grouping of things;
@item a @dfn{range} to mark a time period and to comment on it; or
@item a @dfn{pointer} which points from one point at an entity's timeline to another
representing some cause/effect or a timer. This also has a version, where the pointer
"lost" (e.g., to indicate a timer expiring).
@end itemize

@example
vertical [@var{shape}] @code{leftof}|@code{rightof} [@var{refname}] [@var{attributes}...];
vertical [@var{shape}] [@var{from}] @var{symbol} [@var{to}] [at @var{position}] [@var{attributes}...];
@end example

First you have to specify what kind of a variant you want.
The @var{shape} keyword can be one of @code{box}, @code{block}, @code{brace},
@code{bracket}, @code{range} or @code{pointer} or can be omitted (defaults to @code{block}
for a block arrow). These variations result in different shapes, see the examples further down.

Then you have two methods to specify where the vertical should be placed.
Using the first method the vertical is displayed left or right of another chart element.
We call such verticals @dfn{by ref} verticals, as they are placed in reference to another
element. That element can either be specified via its @var{reference name} as set by the 
@code{refname} attribute; or, if the @var{refname} is omitted, the element before the 
vertical is used. The preceding element may be a list of elements enclosed between curly braces, @code{@{} 
and @code{@}}, see the example below.@footnote{When you align a vertical (or symbol) to a parallel block series, which has
@code{one_by_one_merge} layout and the vertical (or symbol) spans @emph{above} the parallel
blocks the parallel block cannot be shifted down to make room for the vertical as its 
elements are scattered around (being merged with other elements). Note that for this 
reason Msc-generator attempts to use @code{one_by_one} layout even if you specify
@code{one_by_one_merge}, but there would be no difference - such as when the block in which
the parallel block is has no sibling parallel block. If that is not possible, then the 
@code{one_by_one_megre} algorithm is used and if the attached vertical (or symbol) spans
above the parallel block, a warning is emitted (which can be disabled by adding the 
@code{layout_warning=no} attribute to the vertical (or symbol)). See @ref{Parallel Blocks} for details
of these two layout algorithms.}. Such verticals (similar to @var{by ref symbols}, see 
@ref{Symbols}) are attached to the element they refer to and layout considers them together.

@multitable @columnfractions .5 .5
@item

@image{exJ5_csh}

@tab

@image{exJ5, 7cm}
@end multitable

The second method uses @dfn{markers} to specify the vertical's position.
Markers can be placed with the @code{mark} command to mark a vertical position.
(See more on marking at the end of this section.)
In this case, the vertical is ignored during layout, and is placed at the position
after all other elements are laid out. Horizontal space is reserved for it, unless
the @code{makeroom} attribute is set to @code{no}.

The example below repeats the example above with the second method. 
The third line places a marker named @code{top} just
below the enitiy headings. Then this marker is referenced by the vertical as the
upper edge of it. The other marker is omitted in the example, it is then assumed
to be the current vertical position.
The mark command can have an @code{offset} attribute, which takes a number and
shifts the position down by that many pixels (up for negative numbers).

@multitable @columnfractions .5 .5
@item

@image{ex46_csh}

@tab

@image{ex46, 7cm}
@end multitable

The second method is beneficial, if you cannot easily group the elements using curly 
braces, such as in the example below.

@multitable @columnfractions .5 .5
@item

@image{exJ6_csh}

@tab

@image{exJ6, 7cm}
@end multitable



There are two built-in markers, that are available without the @code{mark} command:
@code{chart.top} and @code{chart.bottom} referring top the top and bottom of the
entire chart, respectively.

Between the two positions, one of the
box or arrow symbols can be used: @samp{--}, @samp{..}, @samp{++},
@samp{==}, @samp{->}, @samp{=>}, @samp{>} or @samp{>>}. If we omitted the
@var{shape} specifier these symbols result in a box or a block arrow.
The arrow symbols can be used in bidirectional or reverse variants, as well.
For ranges and pointers the box symbols result in no arrowheads, for
braces and brackets there is no difference between the box and arrow symbols,
they only control the line style.

You can omit both markers. In this case the vertical spans besides the chart
element before it. You can group a set of chart elements with curly braces and
specify a vertical immediately after to make it span along the entire group.
(This is a simpler way than to use the @code{mark} command.)
You can even omit the @var{symbol} making it default to @code{->}@footnote{But
you cannot omit both the @var{shape} and @var{symbol}.}. The above chart
can also be written as below.

@multitable @columnfractions .5 .5
@item

@image{ex98_csh}

@tab

@image{ex98, 7cm}
@end multitable

Verticals can contain a label, which can be rotated 90 degrees compared to
other elements. This can be set via the @code{side} attribute, which specifies
from which direction the text is readable from (@code{left}, @code{right} or @code{end},
which means the regular horizontal typeset).
If you sent @code{side=end} to typeset the label horizontally, you can use
word wrapping by setting @code{text.wrap=yes}. If you do so (even if via the
default text attribute), you must specify a text width for each such vertical
to do the wrapping in. Use the @code{text.width} attribute for this purpose.
Verticals with vertically typeset text ignore the @code{text.wrap} attribute and
do no label word wrapping.

The text after the @samp{at} keyword determines the horizontal location of
the vertical. The horizontal position is defined in relation to entity positions.
It can be placed onto an entity, left or right from it, or between two entities.
These are specified as @samp{<entity>}, @samp{<entity>-}, @code{<entity>+} or
@samp{<entity1>-<entity2>}, respectively. You can also specify any distance from
an entity by adding a number after the first form, such as in @samp{at <entity> <number>}.
The number will be interpreted in pixels and shifts the vertical left or right
depending on its sign. Use a space before the number.

@multitable @columnfractions .5 .5
@item

@image{ex47_csh}

@tab

@image{ex47, 7cm}
@end multitable

You can also omit the @code{at} clause, which results in the vertical being placed
besides the entities it spans (by default on the right side of them using
@samp{<entity>+}). If, however, the @code{side} attribute is set to @code{right}
(to mean that the text is readable from the right direction), the vertical is
placed left of the entities is spans besides.

Verticals specified to be besides an entity (with @samp{<entity>-}, @samp{<entity>--},
@samp{<entity>+} or @samp{<entity>++} horizontal locations)
are placed further from the entity line
if there are boxes or elements in the way. Only those elements are considered,
which are specified in the input file before vertical.
If the vertical references markers below it, it may overlap
with later elements, thus it is a good idea only to mark the top of the vertical
and specify the vertical itself at the bottom location (as in all the
examples)@footnote{Note that Msc-generator does not lay out verticals entirely correctly
in relation to parallel blocks.}.
The @code{makeroom} attribute is a boolean value defaulting to yes.
When it is turned off verticals are not considered when
entity distances are calculated with @code{hscale=auto}.
When @code{makeroom} is on, Msc-generator attempts to take the vertical into account
when laying out entities.
In a well-designed case you can even nest verticals,
as a vertical specified earlier will be considered
by subsequent verticals  (but only if its @code{makeroom} attribute is set to yes).

@multitable @columnfractions .36 .64
@item

@image{ex96_csh, 6cm}

@tab

@image{ex96, 9.5cm}
@end multitable

Below is a picture demonstrating all shapes of verticals. Here are a few tips on them.

The radius of the curves of the brace vertical can be adjusted with the
@code{line.radius} attribute and defaults to 8. The width of the bracket vertical
can also be influenced with the same attribuet. In addition you can set the
@code{line.corner} attribute to @code{round} or @code{bevel} to influence the
corners of the bracket. The range vertical can display either an arrow
or just a simple line depending on whether you use the arrow or box symbols.
In case you specify an arrow, you can adjust the arrowhead via the @code{arrow.*}
attributes.

@multitable @columnfractions .36 .64
@item

@image{ex97_csh, 7.5cm}

@tab

@image{ex97, 9.5cm}
@end multitable

The pointer vertical can be marked with an asterisk as being lost.
If so it displays the same loss symbol that is used at lost
messages (see @ref{Lost Messages}) and you can use the @code{x.size} and
@code{x.line.*} attributes to control its appearance. Note that you cannot
control the exact location of the loss symbol (via the @code{lost at} construct),
it is always at the bottom of the pointer.

Finally, about the @code{mark} command. You can mark a position between chart
elements or the centerline of an arrow or box. This can be expressed via the
@code{centerline} attribute (the @code{yes} and @code{destination} values are
equivalent.) In order for this to work, the marker must be immediately after
an arrow or box. Note that other elements do not have centerline.
Distinguishing source and destination centerlines (you can also use @code{left} 
and @code{right} in addition to @code{source} and @code{destination}) makes sense
only for slanted arrows or arrows starting and ending at the same entity. 
You can also add the @code{offset} attrinute to specify certain number of pixels
above (negative) or below (positive) the position. This can be used in combination
with centerline, if needed.

@multitable @columnfractions .5 .5
@item

@image{exB7_csh, 9.5cm}

@tab

@image{exB7, 7.5cm}
@end multitable

Note that in these complex cases the layout engine makes its best attempt at
automatic horizontal spacing and compression, but sometimes it fails. Please
report especially annoying cases.


@node Specifying Dividers, Notes and Comments, Verticals, Signalling Chart Language Reference
@section Dividers

Dividers are called like this as they divide the chart to parts.
Three types of dividers are defined. @samp{---} draws a horizontal line
across the entire chart with potentially some text across it.
@samp{...} draws no horizontal line, but makes all
vertical entity lines dotted, thereby indicating the elapse of time.

The third type of divider @samp{|||} represents a simple vertical space.
This can also be specified
by entering just attributes in square brackets. The extreme @samp{[];}
simply inserts a lines worth of vertical space. You can add text, too by
specifying a label. See @ref{Dividers} for examples.

Dividers take the @code{label}, @code{color}, @code{text.*},
@code{line.*}, @code{compress}, @code{vspacing}, @code{number} and @code{refname} attributes
with the same meaning as for arrows.
In addition, the type of the vertical line can be specified
with @code{vline.*}, with @code{vline.type} defaulting to @code{dotted} for @samp{...}
dividers and to @code{solid} for @samp{---} dividers. Other values
are @code{dashed}, @code{none} and @code{double}. Again, note that the default
values can be changed by using styles, @pxref{Defining Styles}.


@node Notes and Comments, Parallel Blocks, Specifying Dividers, Signalling Chart Language Reference
@section Notes and Comments

The @samp{note}, @samp{comment} and @samp{endnote} commands enable you to make
annotations to the chart that are visible to the reader.
Notes are placed onto the chart drawing area in a callout;
comments are placed onto a column left or right from the
chart; whereas endnotes are placed at the bottom of the chart.
Notes are suitable for shorter comments, whereas the latter two
fit longer explanations better.

@multitable @columnfractions .45 .55
@item

@image{ex85_csh, 6cm}

@tab

@image{ex85, 9cm}
@end multitable

Each note, commend and endnote has a @dfn{target element}. The target element is the element
preceeding the @samp{note}, @samp{comment} or @samp{endnote} command@footnote{Note that some
elements cannot be targets, such as chart options. In this case the preceeding
element becomes the target.}. In case of notes the tip of the callout will point
to the target element, whereas side notes will be typeset beside their target.
You can issue multiple notes, comments and/or endnotes to the same target. If numbering is
enabled for a note, comment or endnote, it inherits the numbering of its target (if any).

The syntax is simple, issue one of the three commands with attributes.
You must specify a label, but similar to arrows or entities, the colon syntax can be used.

@example
note: This is a note [attributes];
note at <tip>: Note pointing to <tip> [attribute];
comment: Comment text [attributes];
endnote: Endnote text [attribuest];
@end example

Note and comment text is typeset in a smaller font by default.
You can change both of the above by changing the @samp{note}, @samp{comment} or
@samp{comment} styles.

@menu
* Notes::
* Comments and Endnotes::
@end menu

@node Notes, Comments and Endnotes, , Notes and Comments
@subsection Notes

For notes the tip of the callout can be guided using the @code{at} keyword. After it you can
spacify either an entity or a marker. This is useful if you want to make a note to a specific
part of an arrow.

You can use the @code{note.pointer} attribute to define, what the tip looks
like. It can take four values: @code{none}, @code{callout}, @code{arrow} or
@code{blockarrow}.

The position of the note is selected automatically by Msc-generator, but you can
influence the choice via the @code{note.pos} attribute. It can take one of the
following values: @code{near}, @code{far}, @code{left}, @code{right}, @code{up},
@code{down}, @code{left_up}, @code{left_down}, @code{right_up} or @code{right_down}. The
first two can be used to specify the distance from the element, whereas the rest
dictate which direction the note shall be. You can set this attribute twice if
needed, once for distance and a second time for direction.

The @samp{note} style contains text, fill and line attirbutes and also @samp{note.layout} and
@samp{note.pos} to define default note layout.

@image{ex87_csh}

@image{ex87, 14cm}

@node Comments and Endnotes, , Notes, Notes and Comments
@subsection Comments and Endnotes

Comments can be set either to the left or the right side of the chart as dictated by the
@code{side} attribute. This attribute can also take the value @code{end}, which will turn
the comment to an endnote. In fact endnotes are comments with their @code{side} attribute
set to @code{end}.
So you can convert all your comments to endnotes by
redefining the @code{side} attribute of the @samp{comment} style, as below.
For ease of use the @code{comment.text} and the @code{comment.side} chart options
can also be used to set comment properties@footnote{These are equivalent to changing the
@samp{comment} style. There is no such shortcut for endnotes, yet.}.

@example
defstyle note [text.size.normal=16, text.size.small=10];
defstyle comment [side=end];
comment.side=right;
comment.text.italics=yes;
@end example

When the chart contains comments on the side a line is drawn separating the comments
from the chart text. You can change the properties of this line via the
@samp{comment.line.*} chart options. Only the width, color and type of the line
can be changed (not its radius or corner). You can turn this line off by
selecting the @samp{none} line type. Similar, the background of the comments can be set
via the @samp{comment.fill.*} chart options. These options can also be made part of designs.
Finally, the space available on the side for comments can be adjusted with the
@code{hspace left|right comment} command, see @ref{Spacing}.

@node Parallel Blocks, Chart Options, Notes and Comments, Signalling Chart Language Reference
@section Parallel Blocks

Sometimes it is desired to express that two (or more) separate processes happen
side-by-side. @dfn{Parallel blocks} allow this. Simply place the the parallel
blocks between @samp{@{@}} marks and write them one after the other, as in
@ref{Drawing Things in Parallel}. You can specify as many parallel blocks as you
want. The last (and only the las) parallel block shall be followed by a semicolon. The order of
the blocks is not much relevant, with the exception of numbering, which goes in the
order the blocks are specified in the source file. It is possible to place
anything in a parallel block, arrows, boxes, or other parallel blocks, as well.
Below the series of parallel blocks the next element will be drawn after the
longest of the parallel blocks.

There are two ways to lay out parallel blocks. They differ in how they handle
cases when elements from the individual blocks would overlap. For non-overlapping
cases they function the same way. The first algorithm, called @code{one-by-one}
places elements from blocks one by one always taking the next element from the
block which is currently the shortest (has its bottom end the highest). Elements
are placed so as to avoid overlap between them. The other algorithm, called
@code{overlap} lays out the blocks independently and allows overlap.
The algorithm to use can be selected by the @code{layout} attribute that can be
specified for the entire parallel block series before the first block.

@multitable @columnfractions .5 .5
@item

@image{exA5_csh, 6cm}

@tab

@image{exA5, 5cm}
@end multitable


The @code{one_by_one} algorithm has a variant, called  @code{one_by_one_merge},
which behaves differently in case of nested parallel blocks. If you apply this
algorithm to the inner parallel block, they will be merged with the outer
blocks (but not the one the nested block is inside). In contrast, @code{one_by_one} 
results in laying out the inner parallel blocks on their own as if they were 
a single element.

@multitable @columnfractions .5 .5
@item

@image{exA2_csh, 7cm}

@tab

@image{exA2, 7cm}
@end multitable

Note that with @code{one_by_one} and @code{one_by_one_merge} Msc-generator
not only avoids overlap between elements, but in addition keeps a minimum distance
between two elements. This means that arrows to/from the same entity cannot be
drawn completely besides each other, since in that case they would touch.
Thus one of them is drawn a little lower. If this is not intended, use @code{overlap}.

@multitable @columnfractions .4 .6
@item

@image{exA4_csh, 5cm}

@tab

@image{exA4, 9cm}
@end multitable

If you use the @code{overlap} algorithm, you can also specify vertical alignment
of the individual blocks via the @code{vertical_ident} attribute, which can be
set to @code{top}, @code{middle} or @code{bottom}.

@multitable @columnfractions .4 .6
@item

@image{exA3_csh, 6cm}

@tab

@image{exA3, 4.5cm}
@end multitable

The default behaviour is @code{one_by_one_merge}, which allows fine parallelism,
but avoids ugly overlaps@footnote{Setting the @code{classic_parallel_layout} chart
option to @code{yes} causes the default to be @code{overlap}, because prior v3.6
the only algorithm available was @code{overlap}. This chart option is now deprecated
and will be removed in future releases. Use @code{layout=overlap} instead.}.

You can mark entire parallel block series, with the @code{parallel} and @code{overlap} keywords
(and attributes). This results in elements after the entire parallel block series to be
laid out besides and over the elements in the parallel blocks, respectively. In addition,
you can set the @code{keep_with_next} and @code{keep_together} attributes to influence
automatic pagination.

@smallindentedblock
Parallel block serieses also have @code{compress} and @code{vspacing} attributes. These
govern, how they are laid out under the previous element.
For block series with @code{layout=overlap} and @code{layout=one_by_one}, first the entire
block series is laid out without regard to already placed elements. Then, if compress is
on (or @code{vspace=compress} is set, which is equivalent) the whole block series
is moved upwards as one until some parts of it bump into an already placed element.
If a nonzero vertical spacing is used, the whole block series is shifted down such that the
requested spacing appears between the top of the block series and the prior element.

For @code{layout=one_by_one_merge} with @code{compress=yes} the first elements of
the parallel blocks are individually moved upwards until they hit one of the elements above.
In case a positive @code{vspacing} is specified, the behaviour is the same as for
@code{layout=one_by_one}. The @code{compress} and the @code{vspacing} attribute of
the first element in each parallel block can modify this behaviour (e.g., by adding vertical spacing).

Note that if the @code{vspacing} chart option is set to a positive number, the @code{vspacing}
attribute of parallel blocks is set to zero instead of this number by default. This is to avoid
having this vertical space twice: once for the parallel block series and once for the first elements
in the blocks. You can nevertheless assign a nonzero vertical space for the block series
by manually specifying the @code{vspacing} attribute for the parallel block.
If case of @code{vspacing=compress} or @code{compress=yes} chart options, the corresponding
attribute of parallel block series is set according to the value of the chart option.
@end smallindentedblock

One design goal with @code{layout=one_by_one_merge} was that in case the parallel
block series contains just one block, it should get laid out exactly as if its content were not
enclosed between @samp{@{@}} marks. This allows you to put @samp{@{@}} marks
around any set of elements, creating a new scope (see @ref{Scoping}), where any changes
to styles or options take effect only inside the scope.

@menu
* Parallel Keyword::
* Overlap Keyword::
* Joining Arrows and Boxes::
@end menu


@node Parallel Keyword, Overlap Keyword, Parallel Blocks, Parallel Blocks
@subsection Parallel Keyword

Specifying the keyword @code{parallel} in front of an element will make the
rest of the chart be drawn in parallel with it. To be more precise the effect only
lasts till the end of the scope, so elements after the next closing brace
will be drawn sequentially under@footnote{This is how this works exactly: first, the
element marked with @code{parallel} is placed. Then the rest of the elements
in the scope are placed below it and are moved as one block up at most to
the top of the element marked with @code{parallel}. The move stops if any
element in the block being moved bumps into an already placed element,
thus overlaps are avoided.}.

You can place @code{parallel} in front of really any element, including
entity definitions or even series of parallel blocks. You can even combine several
elements using braces.

@multitable @columnfractions .4 .6
@item

@image{ex57_csh}

@tab

@image{ex57, 10cm}
@end multitable

@node Overlap Keyword, Joining Arrows and Boxes, Parallel Keyword, Parallel Blocks
@subsection Overlap Keyword

Sometime one explicitly wants two elements to overlap. One prime case is
to show slanted messages to cross each other. You could do it via parallel blocks
allowing overlap via @samp{layout=overlap} but that is a bit cumbersome for
overlapping short parts. A shorthand is offered by the @code{overlap} keyword.

Specifying this keyword in front of any element will result in ignoring this
element at the layout of subsequent elements. The next element will be laid out
exactly at the same vertical position as the element marked with @code{overlap}
drawing on top of it. Subsequent are then laid out below and can still overlap
the element marked with @code{overlap}. This effect is in place till the next
closing brace (or the end of the file).

Thus this keyword is similar to the @code{parallel} keyword, but it allows direct
overlap, not just side-by-side layout.

@multitable @columnfractions .4 .6
@item

@image{ex94_csh}

@tab

@image{ex94, 8cm}
@end multitable

@node Joining Arrows and Boxes, , Overlap Keyword, Parallel Blocks
@subsection Joining Arrows and Boxes

The @code{join} keyword can be used to connect arrows to other arrows or boxes.
In its simplest form one arrow can be joined to another. If the second arrow is
a continuation of the first arrow and they overlap, then a curly connecting
segment is added as in case of the first example below. Note that this is
done only if the two arrows have the same directionality; either the second comes
after the first one or they are both bi-directional; they have a common end; and
they overlap. Note that the first arrow can be an arrow starting and ending at
the same entity, but the second cannot. If you want that use the @code{side}
attribute, as illustrated on the second example below.

If the two arrows do not overlap, they will be simply laid out aligned by their
centerline. It is possible to mix any type of arrow, including block arrows,
irrespective of directionality. The arrows do not have to connect (but cannot
overlap). This construct enables you to have a different label for
each joined arrow part. Note that each joined arrow may be multi-segment itself.

Finally, you can also include boxes in a join series. You can leave the end of
the arrows towards the box unspecified. In this case the arrow will connect
to the side of the box. Note that you cannot join a box directly to another,
an arrow must come in between.

@multitable @columnfractions .45 .55
@item

@image{exB4_csh, 7cm}

@tab

@image{exB4, 8cm}
@end multitable

You cannot specify @code{parallel} or @code{overlap} for an element if you
specify @code{join}. Any @code{parallel} or @code{overlap} keyword specified
for a join series, on the other hand, will apply to all elements of the join
series.

@node Signalling Chart Attributes and Styles, Chart Options, Parallel Blocks, Signalling Chart Language Reference
@section Signalling Chart Attributes and Styles

@menu
* Appearance::
* Word Wrapping and Long Labels::
* Compression and Vertical Spacing::
* Default and Refinement Styles for Signalling Charts::
@end menu

@node Appearance, Word Wrapping and Long Labels, , Signalling Chart Attributes and Styles
@subsection Appearance

@table @code
@item line.*
Specifies the apprarance of the line for the element.
For arrows and dividers it is the horizontal line.
For block arrows, boxes, pipes and entities this is the line around the element.
@code{line.radius} effects only on arrows starting and ending in the same
entity (see @ref{Arrow Attributes}); for entities and boxes, this
specifies the size of the corners.
For pipes, it specifies the width of the oval, in other words
from how left we look at the pipe.
@item vline.*
Specifies the color, width or type of the vertical line stemming from
entities. This is useful to indicate some change of state for the
entity. @code{vline.radius} and @code{vline.corner} has no effect.
These attributes can be used for entities and dividers.
@item fill.*
Defines the fill of the box, entity, block arrow or pipe.
@item shadow.*
Defines the shadow for boxes, entities, block arrows and pipes. Currently no
shadow can be specified for simple arrows.
@item arrow.*
Arrowhead formatting attribues, described in detail in @ref{Arrow Attributes}.
@item lost.text.*
@itemx lost.line.*
@itemx lost.arrow.*
The values specified here will be added to the values of @code{text.*}
@code{line.*} or @code{arrow.*} when drawing the text, line or arrowheads
of the lost part of the message, @pxref{Lost Messages}.
Only applicable for arrows.
@item x.size
@itemx x.line.*
The controls the appearance of the loss symbol for lost messages, @pxref{Lost Messages}.
@item tag.line.*
@itemx tag.fill.*
@itemx tag.text.*
These attribues applie only to boxes (applicable to the @code{box}, @code{emptybox}
and @code{box_collapsed} style) and govern the style of tags, if the @code{tag}
attribute of the box is set. (The @code{tag} attribute is not part of the style,
you must set it individually on each box you want to have a tag.)
@item shape
This attribute takes the name of the shape you want for the entity
headings. See @ref{Entity Shapes}.
They can be made part of style but have effect only on enities.
@item shape.size
This attribute specifies the size of the shape to use for the entity
headings. Only has effect if a valid shape is specified via the
@code{shape} attribute. It takes one of @code{tiny}, @code{small},
@code{normal}, @code{big} or @code{huge} with @code{small} as default.
They can be made part of style but have effect only on entities.
@item note.layout
@itemx note.pos
These govern how notes are laid out. See @ref{Notes and Comments} on how to use them.
They can be made part of style but have effect only on notes.
@item side
This attribute can take either @code{left} or @code{right}. For pipes it specifies
which side the pipe can be looked from into. For verticals it tells which side
the text can be read from. For comments it specifies which side of the chart the
comment is placed on. It has no effect on any other elements.
@item solid
This attribute can be used to set the transparency of a pipe.
See @ref{Pipes} for more information.
@item number
This attribute giverns if the arrow, box, etc.@: is numbered or not.
See @ref{Numbering} for details.
@item compress
If this attribute is set to @code{yes}, the element is drawn as close
to the ones above it as possible without touching those. It is useful
to save space, see @ref{Compression and Vertical Spacing} for a detailed description.
@item vspacing
Can be set to a number interpreted in pixels or to the string @code{compress}.
Governs how much vertical space is added before the element (can be negative).
This attribute is another form (superset) of the @code{compress} attribute;
@code{compress=yes} is equivalent to @code{vspacing=compress}, whereas
@code{compress=no} is equivalent to @code{vspacing=0}.
@item collapsed
This attribute can be used for group entities and boxes to collapse them.
@item indicator
If this is set to yes on a collapsed group entity or box, indicators will
show hidden entities and other chart elements.
@end table

The attributes below can be specified for most elements, but cannot be made part
of a style

@table @code
@item label
This gives the label of the element (for elements having one). It can be abbreviated
with the colon notation, see @ref{Labels}.
@item url
This assigns a link target to the label, such as an URL or a Doxygen target.
Note that @dfn{box tags} cannot be turned into a link
using this attribute, use the @code{\L()} escape instead. See
@ref{Links} for more info.
@item refname
Use this attribute to name the element for later reference. Used primarily to
refer to elements via their numbers using the @samp{\r(name)} escape in labels.
@item draw_time
Use this attribute to draw elements earier or later and thereby control how
they overlap. See more in @ref{Symbols}.
@item parallel
This can take a @code{yes} or a @code{no} and is equivalent to prepending the
element with the @code{parallel} keyword, see @ref{Parallel Blocks}.
@end table

@node Word Wrapping and Long Labels, Compression and Vertical Spacing, Appearance, Signalling Chart Attributes and Styles
@subsection Word Wrapping and Long Labels

Before Msc-generator 3.6 the user was required to manually specify line breaks in labels.
Using the @code{text.wrap} attribute you can instruct Msc-generator to break lines
automatically depending on how much horizontal space is available. For labels with this
attribute set the line breaks of the source file inside the label are ignored.
However, the line breaks inserted into the label via the @code{\n} escape sequence
are still honoured. You can set the @code{text.wrap} attribute of labels globally
via the @code{text.wrap} chart option, but you can also override this setting
individually for each label.

@menu
* Word Wrapping for Signalling Charts::
* Word Wrapping for Block Diagrams::
@end menu

Word wrapping is not available for graphviz graphs.

@node Word Wrapping for Signalling Charts, Word Wrapping for Block Diagrams, Word Wrapping and Long Labels, Word Wrapping and Long Labels
@subsubsection Word Wrapping for Signalling Charts

You cannot set this attribute for signalling chart entities.
Their label is always typeset with @code{text.wrap=no} exactly as you specify
in the source file.

Note that this feature is most useful if you do not use automatic horizontal
scaling @code{hscale=auto}, since in that case the distance between entities is determined
from the size of the labels - and with @code{text.wrap=yes} there is no inherent size
for most labels. For notes, which float and whose width is not detemined by the spacing of
entities, a new @code{width} attribute is inserted, which can specify the width of the note
making word wrapping meaningful.

You have effective 3 easy way to typeset long labels.
@itemize
@item Word wrapping: Use @code{text.wrap=yes} (and perhaps a fixed @code{hscale}),
in this case the long labels wrap into multiple lines.
@item Automatic scaling: Use @code{hscale=auto} and no word wrapping, in this case
entities are spaced apart, so that there is enough space for all labels.
@item None: No word wrappig or automatic scaling (default): long labels expand beyond their
available space, which may be sometimes ugly.
@end itemize

You can some combinations, as well.
@itemize
@item Even with @code{hscale=auto} you can make some long labels word wrap by
applying @code{text.wrap=yes} only to the specific arrow, box, divider or comment.
Specifying a long label with word wrapping will not cause entities to be spaced apart
to make room for it, but instead the label is typeset into the space available
(determined by other labels). Adding horizontal spacing with the @code{hspace} command
can be applied to manually push entities somewhat apart (but perhaps not to the full
length of the long label, which will be wrapped into the space available).
@item Even with a fixed @code{hscale} You can push entities further by using the
@code{hspace} command and thereby make enough room for a long label. You can create
exactly as much as needed by using the label text as the argument for @code{hspace},
see below
@end itemize

@multitable @columnfractions .4 .6
@item

@image{ex90_csh, 7.5cm}

@tab

@image{ex90, 9cm}
@end multitable

@node Word Wrapping for Block Diagrams, Compression and Vertical Spacing, Word Wrapping for Signalling Charts, Word Wrapping and Long Labels
@subsubsection Word Wrapping for Block Diagrams

For block diagrams, this setting only takes effect if you
specify a concrete size (as in pixels) for the block and not when its size is
made equal to another block. Since all blocks have a default size, this is
practically always the case, unless you set the size (width or height for
left or right oriented labels) to the size of another block (or blocks).

Since Msc-generator always increases the size you specify to accommodate the label
(and the content of the block), if you specify a too small size, word wrapping
will be performed to the width necessary for the longest word in the label.

Note that if the label's orientation (set via @code{label_orient}) is vertical,
you need to set @code{height} instead of @code{width}.

@multitable @columnfractions .52 .48
@item

@image{exF5_csh, 9cm}

@tab

@image{exF5, 7cm}
@end multitable




@node Compression and Vertical Spacing, Default and Refinement Styles for Signalling Charts, Word Wrapping and Long Labels, Signalling Chart Attributes and Styles
@subsection Compression and Vertical Spacing

In this section we explain how Msc-generator sets the vertical space between
elements. It can apply a set amount of vertical space or can use the
@dfn{compression} mechanism. The latter aims to reduce the height of
chart graphics by vertically pushing chart elements closer to each other.
See the two examples below copied from the end of @ref{Defining Arrows}.
They differ only in that the second begins with @code{compress=yes}.

@multitable @columnfractions .5 .5
@item

@image{ex08, 8cm}

@tab

@image{ex12, 8cm}
@end multitable


Each element (except entities) has a @code{compress} and a @code{vspacing}
attribute. When the former is set to
@code{yes}, the element is first placed fully under the element before it, then
it is shifted upwards until it bumps into some already drawn element. The same
effect can be achieved by using @code{vspacing=compress}. If compression is not
used the element is placed below the previous element by the value of the
@code{vspacing} attribute (understood in pixels). E.g., using @code{vspacing=10}
adds 10 pixels between the element and the element before it. The
@code{vspacing} attribuite is the superset of the @code{compress} attribute,
setting @code{compress} to @code{yes} or to @code{no} is equivalent to
@code{vspacing=compress} and @code{vspacing=0}, respectively.

Compression and vertical spacing can be set individually for each element,
but to save typing by
setting the @code{compress} or @code{vspacing} chart option, you can effectively set the
@code{compress} or @code{vspacing} attribute of all elements after.
This is similar, how the
@code{numbering} chart option effects the @code{number} attribute. If you then
want to exempt specific elements from compression or add more space individually
(so that they are somewhat further from the element above),
just specify the @code{compress} or @code{vspacing} attribute for
the element in question.

Styles can also influence compression and vertical spacing
the same way as numbering, that is you can
set the @code{compress} or @code{vspacing} options for a style,
which will effect compression and vertical spacing of elements
you assign the style to.

Note that to insert extra vertical spacing you can also use the
@code{vspace} command, see @ref{Spacing}.

@node Default and Refinement Styles for Signalling Charts, , Compression and Vertical Spacing, Signalling Chart Attributes and Styles
@subsection Default and Refinement Styles for Signalling Charts

For signalling charts styles can contain any of the attributes listed in
@ref{Signalling Chart Attributes and Styles}. Styles are explained more in
@ref{Defining Styles}.

There is a built-in default style for each signalling chart
element: @code{arrow}, @code{box}, @code{emptybox}, @code{divider},
@code{blockarrow}, @code{pipe} @code{entity}, @code{entitygroup},
@code{symbol}, @code{indicator}@footnote{The style @code{indicator} determines
the appearance of the small symbols that indicate elements hidden due to a
collapsed box or entity group.}, @code{title}, @code{subtitle}, @code{note},
@code{comment}, @code{endnote}, @code{vertical}@footnote{referring to
vertical boxes and block arrows}, @code{vertical_brace},
@code{vertical_bracket}, @code{vertical_range}, @code{vertical_pointer},
@code{symbol}@footnote{referring to all symbols} and
@code{text}@footnote{referring to @code{text at} commands}.

There are also predefined styles for grouped entities and boxes
for when they are collapsed: @code{entitygroup_collapsed},
@code{box_collapsed} and @code{box_collapsed_arrow}, the latter is used when a
box is collapsed to a bidirectional arrow. Attributes of large entitygroups default
to the @code{entitygroup_large} style.

The following refinement styles are defined further governing the appearance of elements
@itemize
@item
for arrows: @samp{arrow_self}, @samp{->}, @samp{=>}, @samp{>}, @samp{>>}, @samp{==>} and @samp{=>>}.
@footnote{@samp{arrow_self} is applied to arrows starting and ending at the same
entity after and in addition to style @samp{arrow}.
The others are applied (potentially after @samp{arrow_style} to line segments,
also for bi-directional arrows.
Thus there is no separate @samp{<->} style, for example.}.
@item
for block arrows: @samp{block->}, @samp{block=>}, @samp{block>} and
@samp{block>>}.
@item
for boxes: @samp{--}, @samp{==}, @samp{++} and @samp{..}
@item
for pipes: @samp{pipe--}, @samp{pipe==}, @samp{pipe++} and @samp{pipe..}
@item
for dividers: @samp{---} and @samp{...}
@item
for verticals: @code{vertical->}, @code{vertical>}, @code{vertical>>}, @code{vertical=>},
@code{vertical--}, @code{vertical++}, @code{vertical..} and @code{vertical==}.
@end itemize

Redefining refinement styles enables you to quickly define, e.g.,
various arrow styles and use the various symbols as shorthand for these.
Usually style names containing non-letter characters have to be quoted,
but for the above styles the parser is expected to recognize them without
quotation. So both below are valid.

@image{ex61_csh}

Finally there are two more pre-defined styles for signalling charts: @code{strong} and @code{weak}.
By adding these to any element you will get a more and less emphasized look,
respectively. The benefit of these compared to making elements stronger or
weaker by yourself is that they are defined in all chart designs
in a visually appropriate manner. Thus you do not need to change anything
when changing chart design just keep using them unaltered.

As a related comment we note that chart designs modify all the above styles and the
default value for the @code{hscale}, @code{compress}, @code{vspacing}, @code{numbering},
@code{indicator}, @code{angle} and @code{text} chart options, too.

Thus, in summary the actual attributes of an element are set using the following logic.
@enumerate
@item If you specify an attribute directly at the element (perhaps via applying
a style), the specified value is used@footnote{If you specify the attribute
several times, the last one is used.}.
@item Otherwise, if the attribute is set in the refinement style (at the
point and in the scope of where the element is defined), the value there
is used. For arrows starting and ending at the same entity, two refinement
styles are applied, first @samp{arrow_self}, then the one based on the arrow
symbol. (In the latter only line styles are set, so this is why you can use e.g.,
@code{=>} to make an arrow double-lined.)
@item Otherwise, if the attribute is set in the default style of the element,
the value there is used.
@item Otherwise, the value of the applicable chart option is used, such as
@code{text.*}, @code{compress}, @code{vspace}, @code{indicator}, @code{numbering},
@code{auto_heading} and @code{angle}. In order for these chart options to be effective
default styles usually have no value specified for these attributes. You can set
these attributes in styles, e.g., to set font type for empty boxes,
which will take precedence over chart options.
@end enumerate




@node Chart Options, Multiple Pages, Signalling Chart Attributes and Styles, Signalling Chart Language Reference
@section Chart Options

Chart options are global settings that impact overall chart appearance or
set defaults for chart elements.
Chart options can be specified at any place in the input file, but
typically they are specified before anything else. The syntax is as below.

@example
@var{option} = @var{value}, ... ;
@end example

The following chart options are defined.
@table @code
@item msc
This option takes a chart design name as parameter and sets, how the
chart will be drawn. It is usually specified as the first thing in the file
before any other chart option. However, it can be specified multiple times,
in which case its effect takes place downward from the chart option. If not
specified then the @samp{plain} design is used.
Note that this option can be overridden from the command line and also from
the Windows GUI.
Also note that only full designs can be applied with the @samp{=} symbol,
partial designs shall use @samp{+=}.
See @ref{Chart Designs} for more on chart designs.
@item hscale
This option takes a number or @code{auto}, and specifies the default
horizontal distance between entities. The default is 1, so to space
entities wider apart, use a larger value. When specifying @code{auto}
entity positions will be automatically set according to the spacing
needs of elements. In this case the @code{pos} attribute of entities will be ignored
except when influencing the order of the entities. See the end of
@ref{Defining Entities} for examples.
Similar to @code{msc}, if you specify this attribute multiple times, the
last one takes precedence.
@item numbering
This option takes @code{yes} or @code{no} value, the default is no.
Any element you define will take the default value of its @code{number}
attribute from this option. See more on numbering in @ref{Numbering}.
@item compress
This option takes a boolean value, and defaults to off.
Any element you define will take the default value of its @code{compress}
attribute from this option. See more on numbering in @ref{Compression and Vertical Spacing}.
@item vspacing
Can be set to a number interpreted in pixels or to the string @code{compress}.
Governs how much vertical space is added before each element (can be negative).
This option is another form (superset) of the @code{compress} option;
@code{compress=yes} is equivalent to @code{vspacing=compress}, whereas
@code{compress=no} is equivalent to @code{vspacing=0}.
@item angle
Specifies the default value for arrow slanting. Its value is measured in
degrees, can take values from 0 to 45 degrees and its default value is zero.
@item indicator
Similar to the @code{compress} option above this chart option can be
used to influence the default value of the @code{indicator} attribute
for grouped entities and boxes. The simplest way to turn all indicators
on or off is to specify this chart option at the beginning of the file.
@item auto_heading
Sets the default value for the @samp{auto_heading} attribute of @samp{newpage}
commands. Setting to yes will cause all @samp{newpage;} commands to create
an entity heading on the subsequent page making additional @samp{heading;}
commands unnecessary. The default is no.
@item classic_parallel_layout
If set to yes, parallel blocks are laid out with an old algorithm, which
allows and ignores overlaps between the elements in the different
parallel blocks.
Defaults to no, and is kept only for backwards compatibility.
@item pedantic
This option takes a boolean value. It defaults to no, but can also
be set by the command line or using @code{Edit|Preferences...} on Windows.
When turned on, then all entities must be defined before being used. If an
entity name is not recognized in an arrow or box definition an
error is generated. However, the implicit definition is accepted.
Setting pedantic affects only the definitions after it and you can
set it multiple times on and off. However it makes little sense.
@item text.ident
@itemx text.format
@itemx text.color
@itemx text.wrap
This chart option can be used to set the default text format. It will be
the default for all labels. Any styles or attributes specified will
overwrite the formatting specified here. Its syntax is the same as that of
the @code{text.*} attributes.
@item numbering.pre
@itemx numbering.post
These options specify what shall be prepended and appended to label numbers.
Their default value is the empty string and a semicolon followed by a space,
respectively. The value of these options are ignored when a label number is
inserted due to the @samp{\N} escape sequence. See @ref{Numbering} for more.
@item numbering.format
Specifies the format of automatic numbering for labels. Can be an arbitrary
string (usually quoted) and may also contain formatting escapes. Any occurrence of
@samp{123}, @samp{arabic}, @samp{iii}, @samp{roman}, @samp{abc}, @samp{letters}
(or uppercase versions) will be replaced to the actual number in the specified
format. The string can contain multiple of the strings above, that will be
interpreted as a multi-level numbering format. It is an error to describe
more levels than the chart has at the location of the option. In this case
an error is printed and the option is not changed.
Describin fewer levels will result in Msc-generator omitting the top level
numbers from labels. For example, if the numbering is at 2.4.1 and one specifies
@samp{123.123} for number format, Msc-generator will display only 4.1.
Such truncation, however, will not change the number of levels, merely how the
number is displayed.
@item numbering.append
This option can be used to append a new level to numbering. Its syntax is the same
as for @option{numbering.format}. E.g., opening a second level of arabic numbers
separated by a colon from the first level can be done by specifying @samp{.123}
(use quotation marks). It is possible to add more than levels at once. All added
levels start from the value of 1 (or @samp{i} or @samp{a}, for roman numbers or
letters, respectively).
@item numbering.increment
Sets the amount added to the number for every new numbered element. Specifying
negative values will make counting go backwards.
@item background.color
@itemx background.gradient
These are similar to @code{fill.*} attributes and specify the background
color of the chart. By default the background is set to white in the @emph{plain}
design of every language. You can change the background color multiple times,
each change taking effect at the place where you issue the background chart option.
This is usefult to split your chart to multiple sections visually.
By setting @code{background.color=none} the background will be transparent for the
rest of the chart.
@item file.info
It takes a (quoted) string of human-readable text as value. It is useful to describe
what is this file and what it contains. It is used so far only to annotate design
libraries, so that if you open an OLE object with a shape not present in your
system you can get some info on what file it is from.
You can specifythis option multiple times their values get concatenated.
@item file.url
It takes a quoted URL as value providing a potential place to download this
file from.
@end table

@multitable @columnfractions .4 .6
@item

@image{ex60_csh, 5cm}

@tab

@image{ex60, 9cm}
@end multitable

@table @code
@item comment.line.*
@itemx comment.fill.*
If you have comments on the chart these govern the background of the comments and the
attributes of the line separating the comments from the chart. As with background
changing them applies downwards from the point of the chart option. See @ref{Notes and Comments} for
more information on comments.
@end table


@node Multiple Pages, Free Drawing, Chart Options, Signalling Chart Language Reference
@section Multiple Pages

Msc-generator supports multi-page charts. These may be useful when you want
to print a long chart. Also, when you only want to show some parts of a
chart in a compound document, but want to keep the rest of the text, too.
In the latter case just put the parts to show on a different page and
show only that page in the compound document.

By default the whole chart is a single page. The chart can be manually broken
into multiple pages by inserting @samp{newpage;} commands. The chart then can be
viewed either as a whole or page by page. You can have as many pages in a
document as you want. Adding the @samp{[auto_heading=yes]} option to the command
will result in displaying an automatic entity heading at the top the page after
the page break - but only when the chart is viewed page-by-page. If you want
this for all such manually inserted, simply set the @samp{auto_heading} chart
option to yes.

You can also make Msc-generator to paginate the chart for a given page size. On
the command line this is available via the @samp{-p -a} options, on Windows,
there is a checkbox on the ribbon. You can ask Msc-generator to insert headings
to the top of the new pages by specifying @samp{-ah} or ticking the @samp{Auto
Headings} checkbox.

The command-line version of Msc-generator creates as many output files as
many pages there are. If there is more than one page, it appends the page
number to the filename you specify. Specifying the @samp{-p} option for PDF
output allows you to have a single, multi-page output file. In the Windows
GUI if you export from Print Preview to PDF, a sinlge multi-page file is
created using the page size, orientation, margins and alignment selected
in Print Preview.

@node Free Drawing, Commands, Multiple Pages, Signalling Chart Language Reference
@section Free Drawing

Sometimes one wants to add simple drawing elements to a chart, such as circle
an arrowhead or comment, dots or other shapes. Msc-generator supports naturally
only limited drawing capabilities, but here they are.

@menu
* Spacing::
* Symbols::
* Inlining other charts::
* Inline text::
@end menu

@node Spacing, Symbols, , Free Drawing
@subsection Spacing

Arbitrary vertical space can be added using the @code{vspace} command.

@example
@code{vspace} @var{number} [@var{attributes}];
@code{vspace:} @var{label} [@var{attributes}];
@end example

In the first form the vertical space is specified as a number in points.
In the secod form, the height of the given label will be used. This command
also has a specific attribute, called @code{compressable}, which specifies
if the space should be ignored if compress is on. It defaults to @code{no}.

Horizontal spacing between the entities can be controlled either via the
@code{pos} and @code{relative} entity attributes or can be made fully automatic
by specifying @code{hscale=auto;}, see @ref{Entity Positioning} and
@ref{Chart Options}.

The @code{hspace} command is useful in the latter case to force a certain
horizontal distance between two (not necessarily neighbouring) entity. The
space can be larger than the one specified with @code{hspace} if the layout
requires so, but never smaller.

@example
@code{hspace} @var{entity}-@var{entity} @var{number} [@var{attributes}];
@code{hspace} @var{entity}-@var{entity}: @var{label} [@var{attributes}];
@code{hspace left comment} @var{number} [@var{attributes}];
@code{hspace right comment} @var{number} [@var{attributes}];
@end example

The syntax is similar to that of the @code{vspace} command, both a number or
a label can be used to specify the horizontal distance. Before the distance,
the two entities need to be specified. Any one can be omitted, in this case the
distance is proscribed between the edge of the chart and the entity@footnote{Note
that the edge will not be the physical edge, merely the invisible line from which
arrows connect to when only one entity is specified, such as @code{a->;} or
@code{->a;}.}. Two special versions of the @code{hspace} command exist to specify
the spacing for the comments on the right and left sides.

The @code{hspace} command can be specified anywhere in the file with the same
effect.

@multitable @columnfractions .4 .6
@item

@image{ex75_csh, 5cm}

@tab

@image{ex75, 8cm}
@end multitable

@node Symbols, Inlining other charts, Spacing, Free Drawing
@subsection Symbols

Currently Msc-generator can draw circles (ellipses), ellipses (three dots),
cross symbols (a big @samp{X}), arbitrary shapes, 
rectangles (optionally with text) or just plain text.
We call these @emph{symbols}.

@example
@code{symbol} @var{symbol_type} @var{rel_pos} [@var{refname}] [@var{attributes}];
@code{symbol} @var{symbol_type} @code{at} @var{entity} [@var{attributes}];
@code{symbol} @var{symbol_type} @var{marker}-@var{marker} @var{hpos1} @var{hpos2} [@var{attributes}];
@end example

By specifying either @code{arc}, @code{rectangle}, @code{...}, @code{text},
@code{cross} or @code{shape} after the @code{symbol} keyword one instructs
Msc-generator to draw
one circle/ellipsis, rectangle, ellipses, plain text@footnote{We have to note
that @code{text} is just syntactic sugar for a @code{rectangle} with no line or
fill. Rectangles can also contain text.}, a cross symbol or a shape, respectively.
The position of the symbol can be specified three ways as above.

The first (most natural) method places the symbol relative to another element. This 
element can be specified using its @code{refname} attribute. If the @var{reference name} 
is omitted, then the last element before the symbol is used. (This is similar to how 
Verticals can be laid out, see @ref{Verticals}.) The @var{rel_pos} can be one of
@code{leftof}, @code{rightof}, @code{above}, @code{below} or @code{around} specifying
what relation the symbol shall be to the referenced element. The @code{around} option
will also size the symbol to encompass all of the referenced element, useful for
@code{cross}, @code{rectangle} or @code{arc}. Using this placement method makes the
symbol a @emph{by ref} symbol. Such symbols (and verticals) are positioned in relation
to another element and are laid out together with that element. If there are multiple 
such @var{by ref} symbols (or verticals) attached for an element, they are laid out
in the order they appear in the source file. For such symbols the following additional
attributes are available.

@table @code
@item align
This specifies where along the side of the referenced element the symbol shall be placed.
It can be set to @code{left}, @code{center} or @code{right} for @code{above}/@code{below}
and @code{top}, @code{center} or @code{bottom} for @code{leftof}/@code{rightof}. The 
@code{above_centerline}, @code{centerline} and @code{below_centerline} values are also available
for @code{leftof}/@code{rightof}. Not applicable for @code{around}. The default is @code{center}.
@item offset
This shall be a number (defaults to 0). The symbol is shifted by this number of pixels 
left (negative) or right (positive) for @code{above}/@code{below} and up (negative) or 
down (positive) for @code{leftof}/@code{rightof}. Not applicable for @code{around}. 
@item distance
This shall be a number (defaults to 0). The symbol is placed by this number of pixels
further away from (positive) or closer to (negative) the referenced element. For @code{around}
it effectively expands or shrinks the symbol (applying a distance on all 4 sides).
@item adjust
This attribute can be used to adjust the left/right/top/bottom edge of th symbol after 
placement. You can specify one to four numbers. If one is specified, it applies to all
edges, if two they apply to left/right, respectively, if three, they apply to left/right/top,
and if four they apply to left/right/top/bottom. The numbers are interpreted as pixels.
@end table

@multitable @columnfractions .55 .45
@item

@image{exJ2_csh, 10cm}

@tab

@image{exJ2, 7cm}
@end multitable

The second method (using @code{at}) places the symbol at the horizontal position of an entity.
You can also use @code{--}, @code{-}, @code{+} or @code{++} to place the symbol left or right 
of the entity line (or maybe a bit further out) and you can also use a number after the entity
to shift the symbol to the right (positive) or to the left (negative).
The symbol is drawn at the vertical position where they are specified in the file, just like 
regular elements and the space occupied by the symbol is considered at layout.

@multitable @columnfractions .6 .4
@item

@image{exB6_csh}

@tab

@image{exB6, 5cm}
@end multitable


With the third method, the symbol will be placed after the layout of the chart.
The layout engine will ignore the symbol when placing other elements and the symbol 
may end up drawn overlapping other elements (this may be your intention).
You have complete freedom in selecting both its horizontal and vertical position.
Vertical position is specified via markers, similar as for verticals, see @ref{Verticals}.
The vertical size of the object can be specified two ways. Either you specify two
markers (as above), in which case the symbol will vertically span from one to the
other; or you omit one of the markers, in which case the @code{ysize} attribute
specifies the height (in points)@footnote{In case of rectangles
and text, you can use the natural size of the label you specify as the height of
the symbol by omitting the @code{ysize} attribute. If you specify a shape, it is
enough to specify one of the sizes, the other will be calculated to keep the
original aspect ratio of the shape.}.
If the dash is in front of the marker, the
bottom of the symbol will be aligned with the marker. If the dash is after the
marker, then the marker designates the top of the symbol.
In the example below we see three rectangles. One stretches between two markers,
the second is bottom aligned, while the third is top aligned.

@multitable @columnfractions .35 .65
@item

@image{ex76_csh}

@tab

@image{ex76, 9cm}
@end multitable

The horizontal position of the symbol is specified via one or two @emph{horizontal
position specifiers}. They specify the horzontal position of either the
left or right edge of the symbol or of its center. This is governed by the
first keyword

@example
@code{left}|@code{center}|@code{right} @code{at} @code{entity}-@code{entity} [@code{number}]
@code{left}|@code{center}|@code{right} @code{at} @code{entity}--
@code{left}|@code{center}|@code{right} @code{at} @code{entity}-
@code{left}|@code{center}|@code{right} @code{at} @code{entity} [@code{number}]
@code{left}|@code{center}|@code{right} @code{at} @code{entity}+
@code{left}|@code{center}|@code{right} @code{at} @code{entity}++
@end example

Then, after the @code{at} keyword one specifies either one entity with
additional modifiers or two entities. In the former case
the horizontal position will be at the middle of the entity's line or somewhat left
or right of it depending on the modifiers. In the latter the horizontal position
will be between the two entities. Two of the forms can also take a number, which
is interpreted as pixels and will shift the position to the right for positive
values and to the left for negative values.

If you specify two such horizontal position specifiers one after the other, they
describe both the placement of the symbol and its width. If you specify one,
the width of the symbol can be specified using the @code{xsize}
attribute@footnote{Similar to height, in case of rectangles
and text, you can use the natural size of the label you specify as the width of
the symbol by omitting the @code{xsize} attribute.}.
This may sound a bit complicated, so here is an example with 5 in-line symbols.

@image{ex77_csh}

@image{ex77, 10cm}

Whether the symbol is drawn behind or in front of other elements can be controlled
by the @samp{draw_time} attribute. It can take the following values.

@table @code
@item before_background
Elements with this property will be drawn before the background. This has effect
only if the background is transparent (to some degree or part).
@item before_entity_lines
Elements with this property will be drawn before the entity lines are laid out in
the order as they are specified in the chart description.
@item after_entity_lines
Elements with this property will be drawn just after the entity lines are laid
out, but before regular elements are drawn.
@item default
This is the default, elements with no @code{draw_time} will be drawn this time
in the order as specified in the chart description.
@item after_default
Elements with this property will be drawn last, after all the above elements
in the order as they are specified in the chart description.
@end table

Note that from v3.3.4 any element can specify the @code{draw_time} attribute. It
will not impact the layout only the drawing order (what is called the
@emph{z-order}).


@multitable @columnfractions .4 .6
@item

@image{ex78_csh, 16cm}

@tab

@image{ex78, 10cm}

@end multitable

As you can see the first (leftmost) rectangle was drawn below the entity lines,
the second (middle) one between the entity lines and the arrows, while the last
(rightmost) one was drawn on top of the arrows.

Finally we show a few examples of how symbols may be used.

@image{ex79_csh}

@image{ex79, 10cm}

@node Inlining other charts, Inline text, Symbols, Free Drawing
@subsection Inlining other charts

You can use the @code{symbol} command to include an entire chart using any language that
Msc-generator supports. The syntax is the same as for other symbols (@ref{Symbols}), but the
@var{symbol_type} shall be the name of the language @code{signalling}, @code{gv} or @code{block},
see @ref{Multiple Chart Types}. After the @var{symbol_type} you can specify the location where to
insert and the text of the other chart enclosed between @code{<<<} and @code{>>>} symbols.

@image{exJ3_csh}

@image{exJ3}

Any feature of the included language can be used, including defining procedures, designs or including
files. No reference, entity, block or node name is shared between the parent chart and the included one.
At layout the inlined chart is considered as a simple rectangular block. Note that a correspoinding feature
is avaliable for Block Diagrams, see @ref{Block Types and Definition}.

@node Inline text, , Inlining other charts, Free Drawing
@subsection Inline text

Sometimes one just wants to add some text to the diagram and in this case the @code{symbol text}
syntax may be a bit heavy and difficult to do. As an easier way to do that Msc-generator offers the
@code{text at} command.

@example
@code{text at} @var{pos} [@var{attributes}]: label;
@end example

This draws just text (you must specify a label) at the vertical position the command is written.
You can use simple horizontal position specifiers, like below to place the text centered in-between
two entities; left of an entity, centered around an entity or right of an entity. You can optionally
specify a number, which will be interpreted as a pixel offset to the right (negative value to the left.)

@example
@code{entity}-@code{entity} [@code{number}]
@code{entity}-- [@code{number}]
@code{entity}- [@code{number}]
@code{entity} [@code{number}]
@code{entity}+ [@code{number}]
@code{entity}++ [@code{number}]
@end example

You can influence the default appearance via the @code{text} built-in style.

@multitable @columnfractions .6 .4
@item

@image{exA0_csh, 10cm}

@tab

@image{exA0, 5cm}

@end multitable



@node Commands, Scoping, Free Drawing, Signalling Chart Language Reference
@section Commands

Besides entity definitions, arrows, dividers, boxes, parallel
block definitions and options, msc-generator also has a few commands.

@table @code
@item nudge
This command inserts a small vertical space useful to misalinging two
arrows in parallel blocks, @pxref{Parallel Blocks}.
@item hspace
This command forces horizontal distance between two (not necessarily negighbouring)
entity. See @ref{Spacing}.
@item vspace
This command inserts an arbitrary size vertical space, see @ref{Spacing}.
@item newpage
This command starts a new page, @pxref{Multiple Pages}.
@item heading
This command displays all entity headings that are currently turned on.
It is useful especially after a newpage command.
Note that if there are any immediately preceeding or following entity definition
commands before or after @code{heading}, only one copy of the entity headings
is drawn.
@item show
@itemx hide
Prepending these in front of an entity definition (or later mention) will set the
@samp{show} attribute of those entities (there can be a comma separated list) to
yes or no, respectively.
Using them alone with no following entity names, will show or hide all entities
of the chart defined before this point. (Just a shorthand to save typing a lot of entity names.)
Specifically @code{show} will show all hidden entities. If you want to display
a heading for all entities, follow it by a @code{heading} command.
@item activate
@itemx deactivate
Prepending these in front of an entity definition (or later mention) will set the
@samp{active} attribute of those entities (there can be a comma separated list) to
yes or no, respectively. In addtion, when these commands are used to activate or
deactivate certain entities immediately after an arrow, the activation or deactivation
will take place at the tip of the arrow and not after it. This is to indicate that
the activation or deactivation happened as a result of the arrow. This effect
is not applied if an entity is activated or deactivated by setting its @code{active}
attribute.
Using them alone with no following entity names, will activate or deactivate all entities
of the chart that currently show. (Just a shorthand to save typing a lot of entity names.)
The activation status of hidden entities is left unchanged.
@item mark
This command creates a @dfn{marker} by storing the vertical position of this command.
Symbols, verticals and notes can then refer to this location. See @ref{Verticals} for
more information.
@item note
@itemx comment
@itemx endnote
These commens are useful to annotate the chart, @pxref{Notes and Comments}.
@item symbol
@itemx text
These commands can be used to draw arbitrary graphics to the chart, @pxref{Free Drawing}.
@item defcolor
This command is used to define or re-define color names, @pxref{Specifying Colors}.
@item defstyle
This command is used to define or re-define styles, @pxref{Defining Styles}.
@item defdesign
This command is used to define new designs, @pxref{Chart Designs}.
@item defshape
This command is used to define new shapes, @pxref{Defining Shapes}.
@end table

@node Mscgen Backwards Compatibility, , Commands, Signalling Chart Language Reference
@section Mscgen Backwards Compatibility

Msc-generator was forked (and completely re-written) from mscgen version 0.08
and is a superset of the language of that version even today.
During the years the original tool has developed quite a lot and now contains
features that are not present or not compatible with that of Msc-generator.
From version 4.5 Msc-generator aims to support all the features and syntax of
mscgen to provide a true superset of features. Since there are conflicts in
the syntax, full support is possible only in a special @dfn{mscgen compatibility
mode} of Msc-generator.

By default, Msc-generator enters this mode, if the chart text starts with
@code{msc @{}. This is because mscgen requires you to start your chart like this,
but Msc-generator does not@footnote{If you specify a design, like @code{msc=qsd @{}
Msc-generator will NOT enter compatibility mode.}.
You can force or prevent mscgen compatibility mode using appropriate command-line
switches (@code{--force-mscgen} and @code{--prevent-mscgen}, respecively) or
preference settings in the MFC GUI. Also, on the MFC GUI, the @code{mscgen-compat}
indicator of the status bar turns to red in compatibility mode. (The CLI GUI
always operates in @dfn{autodetect} mode.)

Msc-generator attempts to be liberal in what it accepts in both modes. That is,
Msc-generator attributes are available also in mscgen mode (So you can, for example,
use vertical constructs, hide or show entities, let entities be defined later or
use the style mechanism.)
Similar, mscgen attribute names and chart options are understood even when not
in mscgen compatibility mode. This includes the hashmark syntax for color
specifications, like @code{text.color="#c0ffff"}.
For attributes or other syntax I intend to deprecate a warning is given.

A major tool for backwards compatibility with mscgen is the @code{mscgen}
partial design, which contains new styles for arrowhead symbols. E.g.,
the symbol @code{->} represents a filled triangle arrowhead in Msc-generator,
while it represents a half line arrowhead in mscgen. Using the @code{mscgen}
design via the @code{msc+=mscgen;} command sets (when not in mscgen compatibility
mode) the styles as used by mscgen. In mscgen compatibility mode, such styles
are automatically applied.

Some mscgen attributes are interpreted by Msc-generator not exactly the same way
as in the mscgen tool due to the different internal workings. The below hold for both
the compatibility and regular modes of Msc-generator.
@itemize
@item The @code{textbgcolor} attribute of mscgen in empty boxes is interpreted
as @code{fill.color}, as in mscgen. It is not possible to have a different fill
color and text background for an empty box.
@item The @code{wordwraparcs} chart option is interpreted as @code{text.wrap},
resulting in word wrapping for all text. Since in mscgen boxes are word
wrapped by default, the @code{mscgen} design sets word wrappin in the
@code{emptybox} style. This command sets it everywhere (as intended in mscgen).
@item The @code{arcskip} attribute of mscgen makes an arrow slant down to the
vertical position of the next arrow. This is approximated with a fixed
@code{slant_depth}.
@item Line breaks in quoted strings are accepted by mscgen (and by Msc-generator
in mscgen mode). This is not the case when not in mscgen mode. In general I think
it is a bad idea. Use the @code{\n} text formatting escape or use colon labels.
@end itemize

There are a few conflicting syntax though that must be interpreted differently
in the two modes.
@itemize
@item The arrows symbols @code{::} and @code{:>} exist only in mscgen mode.
These conflict with colon label syntax. You can use @code{==>} instead of the
latter one in both mscgen mode and outside (to represent a double line arrow
with a filled triangle arrowhead).
@item The @code{-x} arrow symbol is used to indicate loss in mscgen mode. This
arrowsymbol is not understood outside the mscgen mode. Replace it with
@code{->*} instead.
@item The @code{->*} broadcast arrow construct is interpreted in mscgen mode only,
since in Msc-generator it means a lost arrow. Even in mscgen mode
it is interpreted as a broadcast arrow only if there is no target entity after the
asterisk. If there is one (which is not valid mscgen syntax), it is interpreted
as a lost arrow according to Msc-generator syntax.
@item The @code{hscale} attribute in mscgen mode is interpreted as setting the
width of the chart to 600 pixels times the specified value. In Msc-generator
it is interpreted as setting the inter-entity distance to 130 pixels times the
specified value (and can of course be set to @code{auto} to automatically select
the spacing between the entities). Due to user feedback the @code{hscale} attribute
is interpreted the Msc-generator way even in compatibility mode@footnote{After
all the point of the compatibility mode is to enable migration towards Msc-generator
features.}.
@item Since @code{--}, @code{..} and @code{==} are arrow symbols (representing
headless arrows, essentially just lines), they cannot be used to define empty boxes
in mscgen mode using syntax like this: @code{a==b [label="label"];}, because
in mscgen this is a line, not an empty box. So you need to prepend the @code{box}
keyword to indicate that this is supposed to be a box.
@end itemize

@node Graph Language Reference, Block Diagram Language Reference, Signalling Chart Language Reference, Top
@chapter Graph Language Reference

Msc-generator supports an extended version of the DOT language, which is fully
backwards compatible with the original saving two exceptions.

@itemize
@item New keywords cannot be used as node names. These are @code{defstyle},
@code{defproc}, @code{replay}, @code{defdesign}, @code{usedesign}, @code{include},
@code{cluster}, @code{if}, @code{then} and @code{else}. If you want these as nodes
put them in-between quotation marks.
@item Msc-generator does not support graphviz HTML labels. They get parsed, but
interpreted only as text.
@end itemize

The language of the graphs (the DOT language) is documented well on the
graphviz pages at @uref{http://www.graphviz.org/, http://www.graphviz.org/}.
Below we just list the additions by Msc-generator.

@menu
* Graph Attributes::
* Default and Refinement Styles for Graphviz Graphs::
* Clusters::
@end menu



@node Graph Attributes, , , Graph Language Reference
@section Graph Attributes

Msc-generator allows you to specify node, edge and subgraph labels via a colon syntax
similar to signalling charts (see @ref{Labels}). However, since colons are already
used in the DOT language to express node ports, two colons shall be used to
start labels, like @code{node::label;}. Such colon labels are terminated by
semicolons and opening square brackets or braces - even if in DOT, nodes can be
separated via commas or even spaces. When a label is specified via the colon notation
all text formatting escapes used by signalling charts can be used (see @ref{Text Formatting}).
Note that in this case it is not possible to use the escape sequences of graphviz
(such as @code{\N} to insert the name of the node).

The format of labels (sepecified either via the @code{label} attribute or
the colon notation above) can be influenced via the @code{label_format} attribute.
Assigning a series of text formatting escapes to this attribute (see @ref{Text Formatting})
will apply their effect to the label. Note that the formatting is only applied
to the label of the node, edge or cluster subgraph, not to any of headlabel,
taillabel or xlabel. Labels can contain links via the @code{\L()} escape, the formatting
of which can be set with the @code{link_format} attribute. On the other hand, the
@code{URL}, @code{href}, @code{target}, @code{tooltip},
@code{labelURL}, @code{labeltarget}, @code{labeltooltip},
@code{edgeURL}, @code{edgehref}, @code{edgetarget}, @code{edgetooltip},
@code{headURL}, @code{headtarget}, @code{headtooltip},
@code{tailURL}, @code{tailhref}, @code{tailtarget}, @code{tailtooltip} attributes are ignored.

Msc-generator supports shadows for nodes and cluster subgraphs, via the @code{shadow_offset},
@code{shadow_blur} and @code{shadow_color} attributes. Read more on these in
@ref{Common Attributes}.

Since the style attribute of graphviz can take multiple values separated by commas,
like @code{style="dotted,filled"} it is hard to work with it using the Msc-generator style system.
For example, if in an Msc-generator style you define @code{defstyle node [style=filled];}, and later you
create a node as @code{a [style=dotted];}, the attribute would normally completely overwrite the
style of the node removing the fill. So in Msc-generator, the @samp{style}
attribute is applied specially. Any assignment to this attibute will @dfn{add} a new value in a comma
separated way, so @code{a [style=dotted, style=filled];} is equivalent to @code{a [code="dotted,filled"];}.
If you want to @dfn{remove} a previously added component, use the minus sign, such as
@code{style="-filled"}. If you want to drop previous values to style and have the current value be the
only one, use an exclamation mark like @code{style="!bold"}.

Finally, there are a few rules on how attributes can be specified, which are somewhat
against the logic of other Msc-generator languages.
@itemize
@item You can use a comma separated list of node names to define nodes, but be aware that
any attribute you specify will apply to all nodes in the list. So in @code{a, b, c::Label;} all three
nodes will have the same label. (This is from the original DOT language.)
@item Attributes after an edge will apply to the edge and not to the last node. So in
@code{a->b [color=red];} the edge will be red and not node @code{b}.
(This is from the original DOT language.)
@item You can assign attributes to subgraphs in the subgraph heading via square brackets.
For example: @code{subgraph cluster_one [style=rounded] @{...@};}.
(This is an Msc-generator extension, in the original language you can only specify
subgraph attributes inside the subgraph.)
@end itemize



@node Default and Refinement Styles for Graphviz Graphs, Clusters, , Graph Language Reference
@section Default and Refinement Styles for Graphviz Graphs

You can define and redefine @dfn{styles}. As with signalling charts a style is a package
of attributes with a name (see  @ref{Defining Styles}).
Any attribute can be assigned to styles (even @code{label}).

To apply a style to a node, edge or subgraph, use its name alone enclosed in square
brackets, like @code{ a->b::Label [style];}. You can have another square bracket after or before
with additional attributes, like @code{ a->b::Label [color=red][style][arrowhead=onormal];}.

Graphviz has a default style for edges, nodes, cluster subgraphs and graphs
named @code{edge}, @code{node}, @code{cluster} and @code{graph}, respectively.
The default style for graph, node and edge can be set using the @code{graph},
@code{node} and @code{edge} commands as well, such as

@example
node [shape=record];
@end example

Msc-generator allows you to collapse cluster subgraphs. Such collapsed subgraphs
show up as nodes, but will have @code{cluster_collapsed} as the default style
(boxes with double lines in the plain design). Similar edges that were pointed to
nodes inside the collapsed cluster, will have the style @code{edge_collapsed}.

If you want to adjust an attribute for all versions of an arrow symbol (forward, backward,
bidir and arrowless) list all of them in the @code{defstyle} command, such as in
@verbatim
defstyle ->>, <<-, <<->>, --- [color=red];
@end verbatim
Note that no quotation marks are needed for these special style names. (Otherwise non-
alphanumeric names need to be enclosed in quotation marks.)
Specifically, Msc-generator has the following refinement styles for arrows:
@samp{->}, @samp{=>}, @samp{>}, @samp{>>}, @samp{->>} and
@samp{==>}, to represent single, double, dotted, dashed line; double arrowhead and double line,
respectively. The last arrow type is provided for you to re-define, by default it is the same
as @samp{=>}. You can also use them backwards (such as @samp{<-}) or bidirectionally
(@samp{<->}). There is also a directionless variant for both, whithout arrowheads:
@samp{--}, @samp{==}, @samp{..}, @samp{++}, @samp{---} and @samp{===}.

Note that when using the @code{edge} command to set the default style for edges,
not only the @code{edge} style is modified, but all refinement styles, too.
This is to produce the same output as graphviz for the same input files.
If you want to modify only the @code{edge} style, use the @code{defstyle edge} command.

Msc-generator supports design definitions, for graphs as well. Use the @code{defdesign}
command to define a named design, like below.
@verbatim
defdesign omegapple {
    defstyle node [color="#d23f7a", style=filled,
        fillcolor="#c20a50:#f3cedc", gradientangle=270,
        fontcolor=white, penwidth=2, label_format="\b"];
    defstyle cluster [color="#c20a50", style=dashed,
        fontcolor="#c20a50"];
    defstyle edge [penwidth=2, fontcolor="#270210"];
}
@end verbatim
You can invoke such designs via the @code{usedesign} command like @code{usedesign opegapple}.
You can also select among the designs on the GUI.

Thus, in summary the actual attributes of an element are set using the following logic.
(There are minor variances for each language.)
@enumerate
@item If you specify an attribute directly at the element (perhaps via applying
a style), the specified value is used@footnote{If you specify the attribute
several times, the last one is used.}.
@item Otherwise, if the attribute is set in the refinement style (at the
point and in the scope of where the element is defined), the value there
is used.
@item Otherwise, if the attribute is set in the default style of the element
in any of the designs applied, the value in the last design that has this attribute
is used.
@end enumerate


@node Clusters, , Default and Refinement Styles for Graphviz Graphs, Graph Language Reference
@section Clusters

When using the @code{dot} layout algorithm, graphviz makes it possible to make subgraphs visible
by drawing a rectangle around the nodes inside the subgraph. By convention this feature is
activated if the name of the subgraph starts with @samp{cluster}.
In Msc-generator,
you can use the @code{cluster} keyword instead of @code{subgraph}, to create a visible
subgraph. You do not need to append the @samp{cluster_} prefix to its name. Also,
whatever name you specify will also become the default label. Omitting the name will
result in an empty label and an auto-generated name, like @samp{cluster_xxx}, where
@samp{xxx} is an auto-incremented number.

Msc-generator also supports cluster subgraph collapsing/expansion. When in the
GUI, you hoover over a cluster subgraph, a collapse icon (red minus sign) appears
at the top-right corner of the cluster. (Similar to how it happens with
boxes and group entities in signalling charts.) Clicking that (or double
clicking anywhere in the cluster) collapses the subgraph into a single,
double-lined node of shape box. In the GUI there are buttons to collapse or
expand all subgraphs with one click.

When collapsing a subgraph multiple edges from within the subgraph to the same node
outside will be kept if the graph is not @code{strict}. Use the @code{collapse_strict=yes;} chart
option to remove duplicate edges on collapsing a subgraph. In this case @code{edge_collapsed}
style is applied to the remaining edge. Similar, nodes that result after the collapse of a subgraph
are applied the @code{cluster_collapsed} style instead of @code{cluster}.




@node Block Diagram Language Reference, Graph Language Reference, , Top
@chapter Block Diagram Language Reference

A block diagram consists of @dfn{blocks} and @dfn{arrows}. Blocks can contain other
blocks - these has to be specified immediately after the containing blocks enclosed
in braces. Blocks that contain other blocks are called @dfn{container blocks} or
@dfn{containers}. Putting one block into another has two consequences. First, the
container is resized to be able to cover all its content. If you want to place
a block outside or overlapping with the contour of a container, add it outside.
Second, the name of the container will become the name prefix of all its content
blocks, see @ref{Block Name Resolution}. The most common block is a rectangle
(or box for short), but other shapes can be used (and defined), as well.

Arrows can be specified anywhere in the chart and their location has
significance only in when they are drawn (in Z order) or if they contain
coordinates referring to their parent. In the latter case the identity of
the parent matters. Note also that blocks not defined at the time of defining
an arrow may get auto-created if @code{pedantic=no;} chart option is
specified (the default). So defining an arrow before or after the blocks it
uses is different.

@menu
* Block Name Resolution::
* Block Types and Definition::
* Block Attributes::
* Block Layout::
* Arrows in Block Diagrams::
* Replicating parts of the Diagram::
* Chart Options and Commands::
@end menu

@node Block Name Resolution, Block Types and Definition, Block Diagram Language Reference, Block Diagram Language Reference
@section Block Name Resolution

Blocks may have a name, which is useful if you want to later refer to them
(to align other blocks or to specify arrows). Several blocks may have the same name,
but if you refer to them the reference must be unambiguous. Using a (full) block name
twice is not good practice.

You can refer to a block using its @dfn{full name}, which is the dot-separated
list of its parents and its name. So if block @code{C} is inside block @code{B},
which is inside block @code{A}, then the full name of @code{C} is @code{A.B.C}.
(See the red block in the example below.)

@multitable @columnfractions .5 .5
@item

@image{exG5_csh,,5cm}

@tab

@image{exG5, 6cm}
@end multitable

You can also omit the common prefix of the place of reference and the block.
For example, the black arrows in the above example are inside the blocks @code{A.B}
and @code{A} and they refer to blocks @code{C}/@code{D} with the same prefixes,
that is to blocks @code{A.B.C}/@code{A.B.D} and @code{A.C}/@code{A.D}, respectively.

Similar, the blue arrow, refers to blocks @code{B} and @code{B.D}, which have
the full name @code{A.B} and @code{A.B.D}, respectively. Using the full name is
not needed because we refer to them from within block @code{A}. In contrast,
the green arrow must use the full name of block @code{A.D}, in order to avoid
confusion with block @code{A.B.D}, which is within the same block as the green
arrow.

In short, name resolution is local and I think fairly intuitive. If you do not give
a block a name, all its content will have the same name prefix as their parent.
In other words, one level of naming is skipped.

Note that the special block names @code{prev}, @code{next}, @code{first} and
@code{last} cannot be given to a block. (See more on them later.) They always refer to a block within the
same parent. Also names including dots cannot be assigned to blocks for now, to
avoid introducing an extra level in the name hierarchy.


@node Block Types and Definition, Block Attributes, Block Name Resolution, Block Diagram Language Reference
@section Block Types and Definition

There are several types of blocks.

@enumerate
@item @emph{Boxes} are the most common type. They are rectangular in shape, may have rounded
or bevelled corners, may contain a label and/or other blocks. They can be defined
via the @code{box <name>} or @code{boxcol <name>} commands.
The former will have its content oriented left-to-right (as a row), while
the second top-to-bottom (as a column), see more on block alignment below.
The name is case sensitive and optional.
@multitable @columnfractions .65 .35
@item

@image{exH1_csh,,2.8cm}

@tab

@image{exH1, 4cm}
@end multitable
@item @emph{Shapes} behave like boxes, but may have arbitrary shape, defined by the
@code{defshape} command. They can be defined
via the @code{shape <shape> <name>} command or using an asterisk as a shorthand
@code{*<shape> <name>}. The name is case sensitive and optional.
@code{text} is a special kind of shape, that has no outline or fill, just a label.
You can invoke it via the @code{text <name>} command, usually adding the label.
@multitable @columnfractions .5 .5
@item

@image{exH2_csh,,2.5cm}

@tab

@image{exH2, 4cm}
@end multitable
@item Any box or shape can be made into a @dfn{multiblock series} by specifying
the @code{multi} keyword
and an optional number before them. This makes the original block appear in several
overlapped versions. The content (if any) is kept only once: for the front block
in the series. The name of content blocks remain the same as without the multi clause. That is,
in case @code{multi box A @{ box B;@}} block @code{B} will have the full name
@code{A.B}. The name @code{A} will refer to the entire multiblock series, while
@code{A.front} and @code{A.back} will only refer to the front or back block of the series.
These may be important when routing arrows to elements of a block series.
You can use the optional number after the @code{multi} keyword to specify the number
of instances (defaults to 3) and the @code{multi_offset.x} and @code{multi_offset.y}
attributes to specify in which direction and how much shall the subsequent instances appear.
@multitable @columnfractions .5 .5
@item

@image{exH3_csh,,3cm}

@tab

@image{exH3, 4cm}
@end multitable
@item @emph{Invisible containers} are rectangular blocks that contain other blocks, but
have no visual appearance: no line, fill or shadow and no label either. They have
zero margin, as well. They are only used to group other boxes and to govern their
default layout. They can be defined using the @code{row <name>}, @code{col <name>} or
@code{cell <name>} commands and their name is also case sensitive and optional. Using
@code{row <name>} or @code{col <name>} will result in a default row or column arrangement
of blocks inside, respectively. In contrast, blocks in a @code{cell} are continued to
be laid out by default as in the parent block. @code{cell} is useful when you want to
temporarily break a row or column, add a small comment, for example, and then
continue the row or column, as in the example below.
@multitable @columnfractions .5 .5
@item

@image{exG9_csh,,3cm}

@tab

@image{exG9, 6cm}
@end multitable
@item Other charts (of any language supported by Msc-generator) can be included as a block.
This is done via the @code{chart <language> <name>} command. The name is case sensitive and optional.
After potential attributes, you can specify the chart to include enclosed between @code{<<<} 
and @code{>>>} tokens. The natural size of the block will be the size of the included chart.
@multitable @columnfractions .5 .5
@item

@image{exJ4_csh,8cm}

@tab

@image{exJ4, 8cm}
@end multitable
@item There are two special kinds of blocks, that do not appear, but control layout only.
@dfn{Spaces} are merely adding extra distance between two blocks in an easy way
without any visual appearance. You can define them via the @code{space <number>}
command, where the number is a distance in pixels added and is
optional.@footnote{If the number is omitted space will try to add "just the right amount"
of space. Currently this is the not so clever, fixed 10 pixels, but it may changle later.}
@dfn{Breaks} do not even add space, merely separate blocks in a sequence, see
@ref{Default alignment}. You can add them, via the @code{break;} command.
@item You can encircle other blocks via the @code{around} command. List the blocks
to include separated by plus signs and follow by a box or shape specification.
Msc-generator will prepare a block as big as to just include the listed blocks
into its content area. You can specify a label, too. You can also specify content,
which will be included into the content area, but will by default be in no
aligment relation to the encircled blocks. I am not sure what this feature is good
for. By default around blocks have no fill.
@multitable @columnfractions .6 .4
@item

@image{exH4_csh,,3cm}

@tab

@image{exH4, 2.5cm}
@end multitable
@item You can define blocks that are @dfn{joins} of other blocks. Use the
@code{join} keyword followed by the blocks to join separated by plus signs.
This is useful to quickly create new shapes from existing ones, such as an
L-shape from two boxes.
@multitable @columnfractions .6 .4
@item

@image{exH5_csh,,4cm}

@tab

@image{exH5, 3cm}
@end multitable
The unison of the surface area of those other blocks is taken to be the surface of the
join block. No name, label or content can be specified. Join blocks can have only
line, fill and shadow attributes (not even alignment as their position is fully
determined by the joined blocks). If they have any of the above three attribute set,
the corresponding attribute in the joined blocks is removed. Thus, for example,
if the join block has line attributes (the default), the joined blocks do not draw a line.

On the example below, we created three blocks (original), then joined them with
leaving only the line attribute of the join set (Line); or unsetting line and
setting fill attributes (Fill); or unsetting line and setting shadow attributes
(Shadow). Note that the second is useful to apply a smooth gradient fill to the
entire joined area and that in this case the joined area must be drawn before the
blocks joined (so that the fill is behind them). In the last example the join
only draws the shadow.

@center @image{exG3, 14cm}

@end enumerate

Blocks (except space and break) can be followed by attributes, see @ref{Common Attributes}
(including a colon-label, see @ref{Labels}) and contained blocks enclosed in braces.

The definition of blocks and arrows must be ended with a semicolon (@samp{;}).
However, if a block contains other blocks, its closing brace (@samp{@}}) does not
have to be followed by a semicolon (to adhere to C syntax better). In fact, no
closing brace in Block Diagrams needs a semicolon after (including design definitions, etc.).

Block and shape definition commands can be used to define multiple blocks in
one command. Simply list multiple names separated by commas instead of a
single name. You must give a name to all blocks defined like that. Any attributes
and content you specify will apply to all blocks defined that way.

@multitable @columnfractions .5 .5
@item

@image{exI5_csh,,1.5cm}

@tab

@image{exI5, 6cm}
@end multitable

If the @code{pedantic} chart option is set to @code{no} then
you can define blocks without the @code{box} keyword or without specifyin a shape,
just by typing the block name. (Unnamed blocks cannot be defined this way.)
The block created will take its attributes from its default style and the running style.
Its shape will be taken from the running style (defaults to a box).

You can specify more than one block name separated by commas. If you specify any
attribute (including a potential colon label), it will apply to all the blocks
defined. However, if there already exists a block with the name you list
no new block will be created, only its attributes will be updated. This is
true if the block of a given name exists outside this scope.
Finally, block names used in arrow specifications will also get auto-created.
Let us see a few examples.

@center @image{exI2_csh,15cm}
@center @image{exI2,5cm}

Note that the above makes it impossible to forward-reference a block from
an arrow definition (as it will get auto-created). To allow that you need
@code{pedantic} set to @code{yes}. In that case, blocks can only
be created by the @code{box} or @code{shape} commands or via the asterisk
abbreviation. You can still change their attributes later, however.

@node Block Attributes, Block Layout, Block Types and Definition, Block Diagram Language Reference
@section Block Attributes

Blocks support a number of attributes governing their visual appearance.
Any of the below attributes can be made part of styles (even @code{label}).

@table @code
@item label
Blocks may have a label, that can be specified using the colon syntax as described
in @ref{Labels}. They can contain formatting escapes, see @ref{Text Formatting}.
Specific to Block Diagrams is the @code{\*} escape, which is replaced to the
name of the block (if any).
@item text.*
Text formatting attributes are described in @ref{Text Formatting Attributes}.
Word wrapping is also available via @code{text.wrap}, see
@ref{Word Wrapping for Block Diagrams}.
@item number
Numbering is used similar to Signalling Charts, see @ref{Numbering}.
@item line.*
@itemx fill.*
@itemx shadow.*
These attributes apply fully to blocks. Boxes, in particular also honour
@code{line.corner} and @code{line.radius}. See @ref{Common Attributes} for more.
@item margin.top
@itemx margin.bottom
@itemx margin.left
@itemx margin.right
These can be used to set the margin around the block. Any nonnegative number will
do. Using the @code{margin} attribute sets all four of the above to the same value.
Alternatively, you can specify four comma separated values, to set all four margins,
like @code{margin=10,10,5,5}. The order is top, bottom, left and right.
@item imargin.top
@itemx imargin.bottom
@itemx imargin.left
@itemx imargin.right
These can be used to set the margin inside the block.
This value is used only when the block contains other blocks or a label.
Any nonnegative number will
do. Using the @code{imargin} attribute sets all four of the above (plus also 
@code{imargin.label}, see below) to the same value.
Alternatively, you can specify four comma separated values, to set all four margins,
like @code{imargin=10,10,5,5}. The order is top, bottom, left and right.
The default is 10 pixels for boxes (via the default style @samp{container}) and 0 
pixels for shapes (via the default style @samp{container_shape}). For boxes and
shapes with no content (but perhaps a label) all values default to 0 (via the default
style @samp{block}).
@item imargin.label
Use this attribute to set the distance between the label and the content of the block
in pixels. Any nonnegative number will do. Only applicable if the block has both
a label and content. Note that setting the @code{imargin} attribute to a single
number will also set this attribute. See above. Also, the default value for this
attribute is the same as for the other @code{imargin.*} attributes above.
@item content_margin
If the block has content (or is @code{around} some other blocks), setting this to
false (which is the default) will ignore the margins of the contained blocks, when deteriming the size
of this (the containing) block. The margins of the contained blocks will still be
applied, when determining their position in relation to one another.
For example, setting this to false and all @code{imargin} values to zero results in
the contained blocks actually touch the container. As a shorthand, you can also set this attribute to
a number, which is equivalent to setting it @code{false} and applying the number to
@code{imargin}. Similar to @code{imargin} you can set all four internal margins
using four comma separated values.
@item width
@itemx height
@itemx size
These set the size of the block. @code{size} is a shorthand for setting both
@code{width} and @code{height} to the same value. Alternatively, you can specify
two numbers separated by a comma to set both height and width, such as
@code{box [size=10,20];}.
If the block contains other blocks, this is
a minimum size - the block can be larger if needed. Otherwise Msc-generator
attempts to make the block exactly this big. If the block has a label larger than
this size, it may be increased to make room for the label depending on the value of the
@code{label.mode} attribute (defaults to @code{enlarge}). You can also specify the name
of another block. In this case the two blocks will have the same height and/or width.
You can even specify a list of other blocks separated by plus signs (@code{+}).
In this case the size of the block having this attribute will be equal to the space
occupied by the blocks listed (and not the sum of their size). Thus if blocks
@code{A} and @code{B} are far from each other, setting the width of a block @code{C}
to @code{width=A+B} will include the distance between @code{A} and @code{B}.
@multitable @columnfractions .4 .6
@item

@image{exE8_csh}

@tab

@image{exE8, 6cm}
@end multitable
@item aspect_ratio
Enforces a certain X/Y ratio for the block. Cannot be used if both the width and height
are set. The value is a floating point number, such as @code{aspect_ratio=1.5} or a
ratio (width divided by height), such as @code{aspect_ratio="3:2"}.)
@item label.pos
Used to set the position of the label inside the block. Five values are valid:
@code{above} (above the content and top aligned), @code{below} (below the content
and bottom aligned), @code{left} and @code{right} (left or right of the content
and left/right aligned. For blocks without content it can also be @code{center}
in which case the label is centered both horizontally and vertically.
@item label.align
If @code{label.pos} is @code{above} or @code{below}, this can be @code{left}, @code{right} or
@code{center}. If @code{label.pos} is @code{left} or @code{right},
this can be @code{top}, @code{bottom} or @code{middle}. It is used to specify
the label's alignment in the direction not set by @code{label.pos}.
You can also use a percentage number for finer control. Value @code{0} means
@code{left} or @code{top}; value @code{100} means @code{right} or @code{bottom};
while value @code{50} means center or middle. You can use any value between
0 and 100, but not outside.
@item label.orient
Governs the orientation of the label. It can take four values,
@code{normal}, @code{upside_down}, @code{left} or @code{right}. The default is the
first one, which is normal, left-to-right reading.
@item label.mode
It dictates what to do when both a label and the size of a block is set.
The default value @code{enlarge} will result in scaling the block to accommodate the
label. Using @code{scale} will scale down the text to fit the label. Especially
useful for shapes. Finally, @code{scale_2d} will also scale the text, but differently
in the two dimensions.
@item allow_arrows
If set to yes, arrows do not go around this block, but can cross it.
Note that for individual arrows, you can allow crossing of a block via
the @code{cross} and @code{cross_all} arrow attributes, see @ref{Arrows in Block Diagrams}.
@item multi_offset
@itemx multi_offset.x
@itemx multi_offset.y
These govern how many pixels subsequent instances in a multiblock series are
shifted compared to the previous one. If both are set to a positive number
the next element will come left and up by the number of pixels specified.
Specifying a negative number will reverse the given direction. Setting
@code{multi_offset} is equivalent to setting the x and y direction to the same
value.
@item draw_before
@itemx draw_after
You can specify one or more blocks (separated by plus signs or via repeating the attribute)
the block shall be drawn before or after. You can use only one of the two attributes for any
diagram elements. Setting one will automatically clear the other.
@item collapsed
@itemx indicator
Setting this attribute on a visible block (@code{box}, @code{boxcol} or @code{shape}) that
contains other blocks will skip drawing the visible block. Instead a small indicator
is drawn to show that there are hidden elements. You can disable the indicator using the
@code{use indicator=no} command or via the @code{indicator} block attribute.

Note that if you disable the indicator for a collapsed block, its base style will become
@code{block} and not @code{container} or @code{container_shape} (see below), as is the case for
blocks with content.
@end table

Block also rely on a few built-in styles. The attributes of each block default to
the style @code{block} if they are empty and to the style @code{container}
or @code{container_shape} (for boxes and shapes, respectively) if they contain
other blocks.@footnote{Thus now we have 3 basic default style for blocks.
@code{block} is for boxes and shapes that have no content, just maybe a label.
@code{container} is for boxes having content, while @code{container_shape} is for
shapes having content. The reason for all these is to allow different internal margins
by default. Of these three only @code{container} has a nonzero default imargin,
specifically 10. The other two has @code{imargin=0}.}
Then a style for each shape is applied (if found) that has
the name @code{shape_<shapename>}, that is @code{shape_box} for boxes or
@code{shape_oval} for the shape @code{oval}. These apply to the specific shape
irrespective of whether that is a container or a blocks. They can be used to set shape
specific margin, for example.
The shapes @code{around}, @code{join}, @code{indicator} and @code{text} serve as basic
styles for the respective block types, while @code{invis} is used for invisible blocks
such as @code{row}, @code{col}, @code{cell}, @code{break} or @code{space}. Finally,
the special styles @code{col} and @code{row} are used to set default alignment for blocks
in a column or row, respectively. See @ref{Default alignment} below.

There are two more special styles, called the @dfn{running styles}. They are applied to every block
and arrow (respectively) created and can be modified via the @code{use}, @code{arrows use} and
@code{blocks use} commands, with the first one having an effect on the running styles for both
arrows and blocks. These commands enable
quickly setting the attributes of all following blocks and/or arrows. Note that similar to
all other style modifications, any change made to the running styles is in effect only
till the end of the scope, see @ref{Scoping}. Thus on the example below,
the red line color only applies to block @code{B} and the arrow between @code{A}
and @code{B}, but the margin is also applied to block @code{C}.

@multitable @columnfractions .4 .6
@item

@image{exF1_csh}

@tab

@image{exF1, 6cm}
@end multitable


@node Block Layout, Block Layout Conflicts, Block Attributes, Block Diagram Language Reference
@section Block Layout

@menu
* Default alignment::
* Alignment modifiers::
* Content placement inside another block::
* Block Layout Conflicts::
@end menu

The layout of blocks is central to the block diagram language. It is governed
primarily by the @dfn{alignment attributes} of each block. We have quite a number
of them, but they are quite easy to remember.
Four are for horizontal alignment: @code{left}, @code{center}, @code{right}
and @code{xpos}
and four are for vertical alignment: @code{top}, @code{middle}, @code{bottom} and @code{ypos}.
Since the words center and middle are easy to mix, @code{xmiddle} and @code{xcenter}
can be used for @code{center} and @code{ymiddle} and @code{ycenter} for @code{middle}.

These attributes govern, where the sides or the centerline of the block is placed
in the horizontal or vertical direction. As value you can name any side or centerline
of any other block (in the same direction only). If you only specify a block name
the same side/centerline is used, that is @code{left=A} means @code{left=A@@left}.

When you set one of the four side attributes (@code{left}, @code{right},
@code{top} or @code{bottom}) it refers to the visible side of the block.
If you want to align to the side of the block @dfn{including margins}
prepend these four values with the letter @code{m} both as attribute
names and attribute values, e.g., @code{mleft=a@@right} or @code{top=b@@mbottom}.
Note that setting either of @code{left} or @code{mleft} both set the position of the left side,
so setting one will overwrite the other - they are effectively the same attribute
with the margin as difference.
On the below example you can see that block @code{B} is aligned to
block @code{A} without marging in the X direction and with margins in the Y direction.

You can not select a side for @code{xpos} or @code{ypos}, just a block. It is equivalent
to setting both @code{left}/@code{right} or @code{top}/@code{bottom} to the same block
effectively resulting in the same width or height as the referenced block.

@multitable @columnfractions .6 .4
@item

@image{exD4_csh}

@tab

@image{exD4, 2cm}
@end multitable

You can specify multiple blocks separated by the plus sign (@code{+}) as value
to any of the alignment attributes. In this
case Msc-generator takes the bounding box of the listed blocks and aligns to that.
If you specify the @code{m} letter after the @code{@@} symbol, the bounding box
is calculated from the listed blocks with their margin.

@multitable @columnfractions .6 .4
@item

@image{exF0_csh}

@tab

@image{exF0, 2.5cm}
@end multitable


In addition to the tokens representing box sides or centers, you can align to
any part of a block by appending a percentage number after the @code{@@} symbol.
The value @code{0%} is equivalent to @code{top} (or @code{left}), while
@code{100%} represents @code{bottom} (or @code{right}). Naturally @code{50%}
means @code{middle} (or @code{center}). However, you can also specify any other
number, even smaller than zero or larger than 100%. (You can omit the percent sign.)
You can use the @code{m} letter even with percentage numbers, such as
@code{left=A@@m33%}, which means the left thirdpoint of the span between the
left side of A minus its left margin and right side of A plus its right margin.

@multitable @columnfractions .6 .4
@item

@image{exE9_csh,,4.5cm}

@tab

@image{exE9, 3cm}
@end multitable

Finally, you can also add a pixel offset at the end of alignment attribute values.
Positive values mean right or down. Thus the full syntax
for alignment attributes is as below.

@example
[block[+block]...][+-offset][@@[m](token|percentage)[+-offset]]
@end example

Where
@itemize
@item @code{token} can be one side or @code{middle}/@code{center};
@item @code{percentage} is a number with an optional percentage sign;
@item if no blocks are specified, @code{prev} is assumed;
@item if no at (@code{@@}) symbol (and parts after) is specified the
token value defaults to the attribute we set; and
@item only one of the two @code{offset} values can be present.
@end itemize

A second way to specify block alignment is to align it to its parent. In this case
the @code{@@} symbol shall be omitted and the syntax becomes as below.

@example
[m]percentage%[+-offset]]
[m][offset]
@end example

If you specify a percentage, it refers to the position between the inner margins of the parent.
Thus, @code{top=10%} will place the top of the block close to the upper internal margin of the parent,
while @code{0%} and @code{100%} refers to alignment to the top or bottom internal margin of the parent,
respectively. Specifying an offset is added in pixels to the position designated by the percentage.
Specifying only an offset (no percentage sign) will be a pixel position added to the top or left
internal margin. Prepending a @code{m} character will use space covered by the content part of the
parent block ignoring any inner margin.@footnote{For shapes this is the area specified by the @code{T}
line in a @code{defshape} command, see @ref{Defining Shapes}. For boxes this is the inner edge of
the box line. If the corners are bevelled or rounded, this is the largest rectangle that fits into
the box.}@footnote{Note that when referring to the parent the presence of the 'm' character will
@dfn{ignore} the inner margin, whereas when refferring to another block, the presence it will
@dfn{include} the outer margin. This is so that the most common case would not need the 'm'
character.}

Of course, all contained blocks must end up between the inner margins.
Thus when you specify the above, do not use percentages outside the 100% region.
Also, bear this in mind when ignoring the inner margin, e.g., do not specify @code{top=m0%}
unless the inner margin is zero, since this by definition dictates a block to be outside.
When the attribute specified violates this rule, it will be ignored with an error,
see @ref{Block Layout Conflicts}.

After applying all alignment attributes, exactly one or two of each direction triplet
has to be specified. (@code{xpos} and @code{ypos} immediately specifies two of them.)
If only one is specifed, the block's size will determine the other side.
That is, in case of specifying @code{top=A}, but neither of @code{bottom} or @code{middle}
the bottom side will be determined by adding the height of the block in question.
If two of the triplet are specified, they also act as a size specifier, so
@code{left=A, right=A} makes the block as wide as @code{A}.

@multitable @columnfractions .65 .35
@item

@image{exD5_csh}

@tab

@image{exD5, 4cm}
@end multitable

You can use @code{prev}, @code{next}, @code{first} and @code{last} instead of
a block name. These refer to the block specified before the current one, the one
specified after, the first or last block within this parent block.@footnote{Specifically,
this is not the first and last element within the @dfn{scope}, since you can open
new scopes any time. This is the first or last block, who has the same parent
block.}
This allows
easy default values. For example, @code{mleft=prev@@mright, ycenter=prev} will
align just right of the previous block - in a row including outer margins.
Note that you must avoid using
@code{prev} and @code{first} on the first element inside a block and
@code{last} and @code{next} on the last one. These generate an error.

@node Default alignment, Alignment modifiers, Block Layout, Block Layout
@subsection Default alignment

In order to avoid specifying each attribute by hand, a mechanism of automatically
setting these attributes is in place. If you set none of a triplet for a block,
and it is not a single child, it inherits the alignment attributes from
the @emph{running style} for that direction. Two styles @code{row} and
@code{col} are defined containing the default alignment attributes for
row and column-oriented arrangement, respectively. The @code{box}, @code{shape}
and @code{row} blocks automatically add the style @code{row} to the running style,
while the @code{boxcol} and @code{col} blocks add the style @code{col}. You can
also manually add these styles by adding @code{use col;} or @code{use row;}
anywhere. Subsequent boxes will be arranged such.

@multitable @columnfractions .65 .35
@item

@image{exE6_csh}

@tab

@image{exE6, 2cm}
@end multitable


The @code{col} style can be defined as

@example
defstyle col [mtop=prev@@mbottom, center=prev];
@end example

making each block "stick" to the previous one from below and to center horizontally
to it.
Applying it to a block or to the running style will make these the default value
for that and any following block.

Note that, since applying this to the first block would case an error (there is no
@code{prev} of a first block and it also cannot align to itself), alignment
attributes referring to invalid @code{prev}, @code{next}, @code{first} or @code{last}
block names are silently ignored if the attribute is coming from a style. If, on
the other hand, you specify @code{top=prev@@bottom} on a first block
explicitly, you will get an error.

Unfortunately, the above definition is not sufficient,
since if we have a series of blocks and assign a
custom alignment for one in the middle, then it will stop "sticking" to the
previous one. Like on the example below (where we specified all alignment
attributes manually, to prevent any of the defaults to apply.
This makes blocks @code{A} and @code{B} (as a group) unrelated to any other
block vertically. (Clearly block @code{B} "sticks" to block @code{A}, but none
of them have any other vertical alignments.) Since Msc-generator strives to
minimize the size of each block, it will overlap blocks @code{A} and @code{B} with
blocks @code{C} and @code{D} to minimize the height of the unnamed column they are in.

@multitable @columnfractions .65 .35
@item

@image{exE3_csh}

@tab

@image{exE3, 1.5cm}
@end multitable

To prevent this and always provide a suitable default the style @code{col}
is actually defined such that each block "sticks" to both to its previous and next blocks.

@example
defstyle col [mtop=prev@@mbottom, mbottom=next@@mtop, center=prev];
@end example

This can lead to unwanted effects, if you specify alignment for two blocks in a
row, with specifying no special alignment for the block in between them. On the figure
below we tied block @code{M} and @code{O} to the left and right side of the row above
and kept the default (sticky) behaviour for block @code{N} in-between. We gave
on where to position block @code{N}, just that it shall align to the blocks left and
right to it. Msc-generator has chosen to break the stickiness between blocks @code{N}
and @code{O} quite at random.@footnote{Specifically, alignment requirements of blocks
deeper in a nester block hierarchy or earlier in the source file take precedence,
if the two alignment has the same priority. See @ref{Block Layout Conflicts}.}

@multitable @columnfractions .5 .5
@item

@image{exE4_csh,,4cm}

@tab

@image{exE4, 5cm}
@end multitable

To fix this situation, clear one of the alignment attributes of @code{N}, like below.

@multitable @columnfractions .5 .5
@item

@image{exE5_csh,,4cm}

@tab

@image{exE5, 5cm}
@end multitable

This prevented inheriting the default alignment attribute @code{left}
but still allowed all other alignment attributes (specifically @code{right})
to apply to block @code{N}.

To summarize the rules for inheriting alignment attributes:

@itemize
@item If a block has none of its alignment attributes set in a direction
(where a direction can be @emph{horizontal}@footnote{...with the horizontal alignment
attributes being: @code{left}, @code{center}, @code{right},
@code{mleft}, @code{xcenter}, @code{xcenter}, @code{mright} and @code{xpos}} or @emph{vertical}),
it inherits the alignment attributes of the running style in that direction.
The two directions are independent.
@item If a block has none of its alignment attributes set in a direction,
but some are @emph{cleared} (set to empty), then it inherits the
alignment attributes of the running style in
that direction, with the exception of the cleared ones.
@item If a block has any of its alignment attributes set in a direction,
it inherits none of the alignment attributes in that direction.
@end itemize

Finally, sometimes one wants to break this mutual alignment reference between
two neighbouring boxes, perhaps, because alignment will be fully specified
for the subsequent one and we don't want the former one to keep "sticking" to it.

@multitable @columnfractions .6 .4
@item

@image{exF2_csh, 6cm}

@tab

@image{exF2, 4.5cm}
@end multitable

While this can be done by clearing one attribute of @code{D} (@code{right=}),
it is not so intuitive. So as syntactic sugar
we can use the @code{break;} command. Any alignment attribute
referencing this zero-sized block is silently dropped (even values, you explicitly assign).

@multitable @columnfractions .6 .4
@item

@image{exF3_csh, 6cm}

@tab

@image{exF3, 3cm}
@end multitable


@node Alignment modifiers, Content placement inside another block, Default alignment, Block Layout
@subsection Alignment modifiers

Sometimes one wants to depart from the row or column-like arrangement enabled
by the above mechanisms. For this you can use the @dfn{alignment modifiers}
that can be written before any block definition. They can be of two kind:
@dfn{major} and @dfn{minor}. Major alignment modifiers are
@code{leftof}, @code{rightof}, @code{above} or @code{below}. Writing them
before any block places that block in the given relation to the previous block
(and center/middle aligned in the other direction).
You can also use minor alignment modifiers @code{top}, @code{bottom}, @code{left}
or @code{right}, which only set alignment in one direction making the new block
align at the specified side.
You can use two major alignemnt modifier of them like @code{below leftof box A;}, which will place @code{A}
diagonally south-west from the previous block. Note that the next block will
continue to use the default row or column like layout, that is be left or below
and middle or center aligned to the @emph{previous} (so far last) block,
such as block @code{H} is aligned to @code{G} on the figure below.

@multitable @columnfractions .5 .5
@item

@image{exD7_csh}

@tab

@image{exD7, 4cm}
@end multitable

You can also specify one major and one minor alignment specifier, like
@code{below left} to override the center alignment in the horizontal direction
and make it left aligned.

You can specify one or more blocks after the alignment modifiers (use the plus
sign (@code{+}) to separate them) if you want to relate to a block other than the
previous one. When using several blocks, Msc-generator will align to their bounding
box, similar to how attribute values are interpreted.

@multitable @columnfractions .5 .5
@item

@image{exF4_csh}

@tab

@image{exF4, 3cm}
@end multitable

You can also specify an offset in addition to (or instead of) the block(s) after
alignment modifiers. This number will be added appropriately.

@multitable @columnfractions .5 .5
@item

@image{exG6_csh}

@tab

@image{exG6, 7cm}
@end multitable

Note that the blocks/number and the second alignment modifier may come in any order.

You can also specify a coordinate after alignment modifiers. This is less
useful, so I do not give an example here.

If you specify alignment modifiers before a definition of multiple blocks,
it will only apply to the first one. For example, in the example below only
block @code{C} is below block @code{A}, whereas block @code{D} simply follows
block @code{C} following the default row alignment. The same way, you can apply
alignment modifiers after the definition of the block, but if you do it for
a series of blocks, it only applies to the first one (@code{C.F} in the example
below).

@multitable @columnfractions .5 .5
@item

@image{exI6_csh,,2cm}

@tab

@image{exI6, 4cm}
@end multitable


@node Content placement inside another block, Block Layout Conflicts, Alignment modifiers, Block Layout
@subsection Content placement inside another block

There are two more attributes governing alignment. By default a block
is just as big as needed to contain its contained blocks. However, we can specify
an explicit size larger than this; it may have a very large label that makes it bigger
than its content; or its sides may be aligned so that it ends up being larger.
In this case the @code{content.x} and @code{content.y} attributes govern,
how the contained blocks are placed inside. They can take the following values:
@code{left/top}, @code{center/middle}, @code{right/bottom} or @code{justify}.

If you specify @code{justify} the blocks that are laid out in relation to their
previous or next block will not necessarily "stick" to that previous or next block.
Additional space
may be added to have a justified layout inside the parent. It may sound complicated,
but in most practical cases it just works.

@multitable @columnfractions .6 .4
@item

@image{exD8_csh,,5cm}

@tab

@image{exD8, 5.5cm}
@end multitable


Inside a shape the content is placed into the area specified by the
@code{T} command (used for labels in signalling charts). The whole shape will be
sized to be able to contain its contained blocks. On the figure below,
we define a simple triangular shape with fill (the part after @code{S 0;})
on the area, where content can go (the box designated at the last line)

@multitable @columnfractions .7 .3
@item

@image{exD9_csh,,4.5cm}

@tab

@image{exD9, 3.8cm}
@end multitable

Note that apart from sizing containers appropriately Msc-generator makes
no attempt to avoid overlaps. Blocks go where
you specify them and if they overlap they are simply drawn like that.



@node Block Layout Conflicts, Arrows in Block Diagrams, Alignment modifiers, Block Layout
@subsection Block Layout Conflicts

As you may have guessed it is easy to create conflicts between alignment attributes.
E.g., @code{top=A@@bottom, bottom=A@@top} is an obvious conflict, that cannot be
satisfied. More complicated cases may also arise. For example, below all three
boxes are left of another one.

@example
box A [left=C@@right, size=10];
box B [left=A@@right, size=10];
box C [left=B@@right, size=10];
@end example

Or in this example the two attributes of @code{c} cannot be met at the same time.

@example
box A [top=B, size=10];
box B [bottom=A, size=10];
box C [top=A@@bottom, middle=B];
@end example

Note that when specifying or processing alignment attributes the order of their
specification is indifferent.
Msc-generator does not work by placing one block and align any blocks referring to
it afterwards. Instead, it solves the constraint requirements as a linear problem
using the simplex algorithm.
Thus specifying @code{top=B@@bottom} in block @code{A} is equivalent to specifying
@code{bottom=A@@top} in block @code{B}. Hence, in case of conflicts it is hard
to pinpoint which attribute actually caused the conflict with which other attribute.

Msc-generator has a set of priority levels for resolving conflicts. Attributes explicitly specified
for the block or part of a style explicitly assigned to the block take highest priority.
Any attribute coming from the running style comes second (e.g., specified via the
@code{use col;} command), then come the default content arrangement of blocks,
such as the fact that blocks in @code{boxcol} are arranged in columns.
Lastly any attribute coming from the default style takes fourth
priority and default values are the lowest. If an attribute explicitly specified
cannot be fulfilled (because other such conflicting attributes), Msc-generator
creates an error naming the attribute it ignores to resolve the conflict.
If other, lower priority attributes need to be removed (because they conflict
something of the same or higher priority than themselves) Msc-generator generates
a warning. You can suppress these warnings via the @code{conflict_report} chart
option. It can be set to any of @code{off} (no conflict warnings at all),
@code{style} (warnings if an attribute from the running style is ignored),
@code{default} (warnings even if attributes from content or default styles are ignored) or @code{full}
(warning for all ignored attributes). The default is @code{off}.

When two alignment attributes with the same priority conflict, the one belonging
to a block deeper in a nested block hierarcy takes precedence. In case the two
block are contained in the same number of blocks (such as two block inside the same
container) the one specified earlier in the source file takes
precedence.@footnote{When an object is copied, its content may be reordered
(see more on copying later) and content can be added/removed, too. In this case
the precedence between attributes of the content blocks is according to the newly created
order, even if an element later defined is inserted before an element earlier defined.}

In addition to emitting an error or warning when an attribute conflicts with
attributes of higher priority, it also attempts to figure out which higher priority
attribute may be the one the conflict is with and indicates it to you.@footnote{Specifically,
for every layout conflict error or warning emitted, it cycles through all the higher
priority attributes and checks if the layout can be solved by removing them. This
algorithm does not find any solution if a conflict is caused by a combination of multiple
higher priority attributes.}

@node Arrows in Block Diagrams, Replicating parts of the Diagram, Block Layout, Block Diagram Language Reference
@section Arrows in Block Diagrams

@menu
* Defining Arrows and Lines::
* Ports and Directions::
* Fine-tuning Arrow Ends::
* Automatic De-Overlapping at Arrow Ends::
* Defining Coordinates::
* Arrow Labels and Markers::
* Arrow and Line Attributes::
@end menu

@node Defining Arrows and Lines, Ports and Directions, , Arrows in Block Diagrams
@subsection Defining Arrows and Lines

Arrows (and lines) can be defined between any two blocks using @dfn{arrow symbols}.
When you specify a block as start or end of an arrow, its center is targeted.
Alternatively, you can specify @dfn{port} for the block (if some other place than its
center is needed) or a @dfn{coordinate} instead of a block as start and/or endpoint.

If the arrow (or line) starts (or ends) at a block (or at a coordinate having the
same, single block in the specification of both X and Y coordinates) and the
arrow starts from the inside of the block, it is clipped to go only to the perimiter
of the block. This can be turned off by setting the @code{routing.clip_block} attribute
to @code{no}.

Currently the
usual four arrow symbols are supported: @code{->} for solid line, @code{>} for dotted
line, @code{>>} for dashed line and @code{=>} for double line. They can point backwards
so @code{A->B;} is equivalent to @code{B<-A;}. Bidirectional arrows (@code{<->}, @code{<>},
@code{<<>>} or @code{<=>}) or simple lines (@code{--}, @code{..}, @code{++} or
@code{==}) are also valid.

You can specify multiple blocks and coordinates on both sides of the arrow symbol
separated by commas.
In this case an arrow is added from each block on the left side to each block on
the right side (using the same arrow symbol). This is an easy way to quickly add
a lot of arrows.

You can chain arrow definitions, so @code{A->B->C;} is equivalent to @code{A->B; B->C;}.
You can use different arrowheads in a chain and can have more than one block, so
@code{A->B,C<=D;} is equivalent to @code{A->B; A->C; B<=D; C<=D;}.

You can specify attributes for arrows in square brackets after the arrow specification.
Attributes apply to all arrows if you have several blocks, but only for the latest
arrow symbol in a chain. For example, @code{A->B,C [attr1] <=D [attr2];} makes
the first set of attributes to apply to the first two arrows (staring from @code{A})
and the second set of attributes to the second two arrows (starting from @code{D}).

@multitable @columnfractions .6 .4
@item

@image{exE0_csh}

@tab

@image{exE0, 3.2cm}
@end multitable

Note that if the @code{pedantic} chart option is set to @code{no} (the default) then
any block used to define an arrow will automatically get created if it has not
been defined before.

@node Ports and Directions, Fine-tuning Arrow Ends, Defining Arrows and Lines, Arrows in Block Diagrams
@subsection Ports and Directions

When an arrow or line starts or ends in a block, you can add a @dfn{port} after the block name
and the 'at' symbol ('@code{@@}').@footnote{Ports and directions work similar
to graphviz, with the exception of using the 'at' symbol ('@code{@@}') instead of the
colon ('@code{:}') to separate the block, the port and the direction. In graphviz
the direction is called a @dfn{compass point}, because one can only use a compass
point to specify a direction.}
This will make the arrow or line start or end at the part of the
block denoted by the port. Shapes can define where ports lie, see @ref{Defining Shapes}.
Boxes have eight ports defined (@code{topleft}, @code{top},
@code{topright}, @code{bottomleft}, @code{bottom}, @code{bottomright}), but you can 
also use @code{n}, @code{s}, @code{e} and @code{w} (for north, south, east and west, 
respectively) followed by a pecentage to specify a port along the perimiter of the block.
The direction specifies the side of the block, whereas the percentage specifies the 
position along that side. 

In addition to the above ports, you can apply a @dfn{compass point} to any block
as a port. These can be @code{n}, @code{ne}, @code{e},
@code{se}, @code{s}, @code{sw} or @code{w} and will make the arrow start/end at the
countour of the block seen in the specified compass point from its center. You can also
specify a number in degrees, which is interpreted as clockwise from the north (top)
direction. 

@multitable @columnfractions .6 .4
@item

@image{exI3_csh}

@tab

@image{exI3, 3.2cm}
@end multitable


In addition to ports you can also specify a @dfn{direction},
which govern, what direction the arrow or line leaves the block. This can be any of the
above compass points (or degree numbers), or @code{perp}, which is a direction
perpendicular to the contour of the block.

@multitable @columnfractions .6 .4
@item

@image{exI1_csh,,5cm}

@tab

@image{exI1, 5cm}
@end multitable

Ports usually have a default direction. This equals the direction of the compass point or
degree number if that is used as a port.
If you omit the direction after specifying a port then the default direction of the
port is used. If the port has no default direction or there is no port specified
(like, for example, with the simple @code{a->b;}), the direction will point towards
the other end of the arrow or line.

When you specify a direction (via a port default or explicitly), Msc-generator
starts the arrow in the given direction, before gradually turning to where the arrow
must go. This is done by setting a waypoint 10 pixels from the contour of the block
in the direction you specify. If you want a larger or smaller distance (leading to
a wider or tighter arc) you can use the @code{distance} attribute for the starting or
ending blocks. That is the line below will result in a tight arc at the block a,
but a wider arc at block b.

@example
a@@ne -> b@@nw [distance=a@@5, distance=b@@20];
@end example

Setting the @code{distance} for all blocks also impacts the waypoint distance, but only
if set to a value larger than 10. If you want to reduce the waypoint below 10, use the
@code{distance} attribute specifically for the starting or ending block as in the above
example.

@node Fine-tuning Arrow Ends, Automatic De-Overlapping at Arrow Ends, Ports and Directions, Arrows in Block Diagrams
@subsection Fine-tuning Arrow Ends

Msc-generator allows you to fine-tune the exact location of the arrow endpoints.
There are two kinds of modification after you have selected an arrow end via
blocks and ports.
@itemize
@item Shift the endpoint by a fixed amount of pixels along the X and/or Y axis. For this
add @code{+x<pixels>} or @code{-x<pixels>} after the block and/or port/dir specification. You
can add either or both an X and an Y coordinate offset.
@item Shift in relation to the block of the endpoint. In this case add a percentage, like
@code{+x<percent>%} or @code{-x<percent>%}. Note that this is a relative shift added to the
endpoint calculated from block and/or port/dir specification. Thus for example
@code{a+x10%->b} will start the arrow from coordinate @code{(a@@60%, a@@50%)} (a bit to the right
from the center of @code{a}), since in the absence of a port the arrow starts from
the middle of the given block.
@item Make the arrow longer or shorter. This can be achieved by simply adding or
substracting a pixel amount to the arrow end specification by appending @code{+<pixel>}
(no @code{x} or @code{y}) or @code{-<pixel>}. Negative values make the arrow shorter,
positive values longer. Lengthening of a curvy arrow is made by continuing it in a
straight line. You can also add a percentage, which is calculated from the
original length of the arrow.
@end itemize

You can mix and match any number of the above modifiers after the block/port/dir
specification - they will be cumulated and their order is irrelevant. The shift
operations will be applied first, then the length modifier ones. They can be combined
with both @code{via} attributes and any routing algorithm.

@center @image{exI4_csh,15cm}

@node Automatic De-Overlapping at Arrow Ends, Defining Coordinates, Fine-tuning Arrow Ends, Arrows in Block Diagrams
@subsection Automatic De-Overlapping at Arrow Ends

If you define multiple arrows between two blocks normally they would overlap.
If you specify multiple arrows from a block using the same port and direction,
they will start overlapping. Normally neither of these overlaps are pleasant,
so Msc-generator aims to @dfn{de-overlap} arrow ends by shifting them apart a
bit.@footnote{Arrow ends specified via coordinates, where both the X and Y
coordinate uses the same, single block and the arrow endpoint is inside that
block, will also get de-overlapped. This is a good way to specify a port for
a block, whose shape does not have the port position, you need.}

For each arrow you can specify the @code{routing.arrow_distance} attribute to specify
how many pixels to set them apart. Msc-generator takes the width of the arrows into
account, but not the width of their arrowhead. If you specify zero, then the given arrow
will not be modified.

@multitable @columnfractions .5 .5
@item

@image{exI8_csh,,4cm}

@tab

@image{exI8, 6cm}
@end multitable

After shifting the endpoints, arrows may still overlap, for example if they go around
the same block they will follow the contour of that block. By setting
@code{routing.block_others} to @code{yes} (the default) on the arrow drawn earlier
will prevent any later arrows that had overlapping ends with it from crossing it
or getting closer to it than @code{routing.arrow_distance}. You can specify
a number via @code{routing.order} to govern in which the arrows in overlapping by their
end are re-laid out after their endpoints have been shifted. Note that arrows never block
other arrows that have no overlapping ending with them.

@multitable @columnfractions .5 .5
@item

@image{exI9_csh,,6cm}

@tab

@image{exI9,,5cm}
@end multitable

Below we show a more complicated example, where we want all three arrows to go between
blocks @code{y} and @code{v}. This is complicated, because if we draw the either the
black or the arrow first, it will go very close both to @code{y} and @code{v} and will
leave no room for the other arrow (red or black, respectively). So we engineer
to draw the red before, but proscribe a larger distance between it and @code{y} to leave
room for the black arrow. The black arrow is then assigned a @code{routing.order} of 1.
(Which is larger than the default of 0 and will cause the black arrow to be drawn after
the red.) Adding the same distance to the blue arrow will ensure its overlap with the
red one (and hence the proper de-overlapping and no crossing).

@multitable @columnfractions .5 .5
@item

@image{exJ1_csh,,7cm}

@tab

@image{exJ1,,7cm}
@end multitable

You can specify @code{routing.try_harder} to @code{yes} to make Msc-generator
try all permutations in the order of how the arrow ends are shifted. Doing a complete
search is quite slow, so this is not recommended for a large set of overlapped arrow 
ends. If not set, we stop the search as soon as a layout is found, where no arrow
overlaps with another in the group of overlapping arrow ends.

Note that if two arrows go on the exact same path they will be routed together. To split 
them to different paths, set the @code{routing.allow_joint_layout} attribute to @code{no}
for one of them. (This attribute defaults to @code{yes}.) 
In the below example we have the same situation for two pairs of arrows
(one pair from block @code{A} to @code{C} and another pair from block @code{C} to @code{E}).
The first pair is routed together, but the second pair is not.

@multitable @columnfractions .5 .5
@item

@image{exJ7_csh, 7cm}

@tab

@image{exJ7, 6cm}
@end multitable



@node Defining Coordinates, Arrow Labels and Markers, Automatic De-Overlapping at Arrow Ends, Arrows in Block Diagrams
@subsection Defining Coordinates

Coordinates can be specified using values similar to the value of alignment attributes
(see @ref{Block Layout}). You need two of those separated by a comma and enclosed
in parenthesis. All the possibilities of how to form these values apply, with the
difference that if you omit the at symbol and the parts after (just specify a block
or blocks with or without an offset), the center of the block(s) is taken (with the
offset potentially). A few examples
@table @code
@item (A,B)
The center of A and the middle of B.
@item (A+10, B@@top)
10 pixels right of the centerline of A and the top of B.
@item (A+B, A+B)
The midpoint of the bounding box of A and B
@item (A@@33%, B@@m33%)
The left thirdpoint of A (ignoring its margins) and the top thirdpoint of B
(including its margins).
@item (10,20)
A coordinate relative to the parent's inner margin's (top-left corner).
@item (50%+10, 0)
Ten pixels right of the vertical centerline of the parent at the top internal margin of it.
@item (m0%+15, 100%)
Fifteen pixels right of the inner line of the parent and at the bottom inner margin of it.
For a detailed explanation on how the 'm' character modifies number-only coordinates
referring to the parent, see @ref{Block Layout}.
@end table

@multitable @columnfractions .6 .4
@item

@image{exG7_csh}

@tab

@image{exG7, 2cm}
@end multitable

If you use a coordinate at least on one end of an arrow, you can omit one of
the coordinates. This will result in a horizontal or vertical arrow, taking
the omitted coordinate from the other end.

After coordinates, you can also specify a direction (but not a port number) after the
@code{@@} symbol. You can use both compass points and degrees as for blocks. A second
@code{@@} symbol with a number may follow the direction specifying the distance of
the waypoint (since there is no block to attach a distance to). After that you can
further add fine-tuning modifiers to the arrow end as specified in @ref{Fine-tuning Arrow Ends}.
Thus this is a valid arrow: @code{(a@@10,b@@20)@@sw@@10+x10-5}.

If an arrow (or line) starts (or ends) at a coordinate, where the specification of both the
X and Y coordinates contain the same single block, that block is used to clip the arrow
(if the arrow starts inside the block). This allows coordinates to be used to specify a
location for the block not exposed as a port. For such arrow ends, arrow de-overlapping
is also executed as explained in @ref{Automatic De-Overlapping at Arrow Ends}. Arrows starting
from coordinates which have different or multiple blocks in the X and Y coordinate specification
do not get de-overlapped.

@node Arrow Labels and Markers, Defining Coordinates, Defining Arrows and Lines, Arrows in Block Diagrams
@subsection Arrow Labels and Markers

You can add labels and @dfn{markers} to arrows/lines.
Markers are dots, tick marks, etc. along the line.

To add a single label, simply add a label to the arrow using the @code{label} attribute
or the colon-label syntax as for blocks: @code{a->b: This is the label.;}
The position of the label can be set using the @code{label.align} attribute, with
the values of 0 and 100 representing the start and end of the arrow (with values
proportionally in between, but you can also have negative values or above 100%).
With @code{label.pos} you can set how the label is placed
in relation to the arrow line. It can take one of @code{left}, @code{right}, @code{above},
@code{below} or @code{center}, the latter meaning onto the line.

To add a single marker, use the @code{label.align} to set its position and
optionally the @code{marker.type} attribute to set its shape, using any of the arrowhead types
listed in @ref{Arrow and Line Attributes}. You can apply to any of the arrowhead attributes
to @code{marker.*}, specifically @code{marker.type}, @code{marker.gvtype} (to set the
arrowhead type in graphviz style), @code{marker.size} and @code{marker.color}.

You can add more labels by specifying them in curly braces after the arrow. Their syntax is
as follows.

@example
[mark] [extend] <position> [<attributes>];
@end example

@code{<position>} is specified as a) a percentage number (followed by a percentage sign);
b) a percentage number (followed by a percentage sign) followed by an optional sign and an offset
number in pixels; or c) an offset number in pixels (no percentage sign). The percentage number is
interpreted so that 0% means the start of the arrow, 100% means its entire length. A positive
percentage number is measured from the start of the arrow forward, while a negative value means
measuring it from the end of the arrow backwards. Thus, 99% is the same as -1%. The offset value
is then added/substracted from this position (interpreted in pixels). If only a pixel value is
specified, a positive value is measured from the start of the arrow forward, a negative value backward.

If you specify @code{extend}, the start of the measurement changes: for positive values we start
to measure from the end of the arrow forward (beyond the end of the arrow), for negative values we
start measuring from the start of the arrows (before the start).
It is actually simpler than it sounds, here are a few examples.

@multitable @columnfractions .5 .5
@item

@image{exH6_csh,,4.8cm}

@tab

@image{exH6, 7cm}
@end multitable

Adding the @code{mark} keyword before the position will add a marker at the
designated position. In this case there is no need to specity a label, if
you just want the marker. The default type for markers is @code{marker.gvstyle=tick},
which is a thin line perpendicular to the arrow line.

Among attributes you can use @code{marker.*} to set the marker style;
@code{label}, @code{text.*}, @code{label.pos} and @code{label.orient} to specify
the label and its details; and @code{line.*}, @code{fill.*} and @code{shadow.*}
to specify a box around the label.

As a shorthand, you can omit the curly braces and simply specify the labels
after the arrow specification.

The label orientation can be influenced with @code{label.orient} the same way as for blocks,
but for arrow labels, two more values are available: @code{tangent} and @code{tangent_upside_down}.
These rotate the label to match the tangent of the arrow line at the label position. Layout 
makes an effort to lay out the label to be readable left-to-right, but you can also request
it to be upside down with @code{tangent_upside_down}.

@multitable @columnfractions .65 .35
@item

@image{exJ8_csh, 11cm}

@tab

@image{exJ8, 5cm}
@end multitable


@node Arrow and Line Attributes, , Arrow Labels and Markers, Arrows in Block Diagrams
@subsection Arrow and Line Attributes


The following attributes apply to arrows. All of them can be made part of a style,
except @code{via} and @code{routing.order}.

@table @code
@item line.*
These set the line style of the arrow. See @ref{Common Attributes} for more.
@code{line.corner} and @code{line.radius} is used when the @code{routing}
attribute is set to @code{polygon}.
@item text.*
@itemx label.*
These attributes specify one label of the arrow.
@item marker.*
Together with @code{label.align} these specify one marker on the arrow.
@item via
Sometimes you want to better influence what path the arrow takes. In this case
use the @code{via} attribute. You can specify any of the four sides of any block, for example
@code{block@@top} or any corner, such as @code{block@@bottomleft}.
The arrow will go around the named block on that side.
You can also specify a coordinate - this will be a mandatory waypoint for the
arrow.
You can specify any number of @code{via} attributes mixing the blockside and
coordinate types as you wish. The arrow will visit them in the specified order.
Note that Msc-generator
still tries to pick the shortest route (while staying on the specified side of the
specified block(s) and going through the mandatory waypoints).
Also note that if the arrow starts from or ends at a block and due to the
@code{via} attributes it goes through that block several times, it is trimmed
to the first crossing.
@multitable @columnfractions .5 .5
@item

@image{exE2_csh}

@tab

@image{exE2, 4cm}
@end multitable
@item cross
@itemx cross_all
You can specify these attributes several times, if needed. Their value can be a block name
(or a list of block names separated by plus signs). The arrow or line is allowed to cross
any block, if listed in the @code{cross} attribute; or any block and its children if listed
in the @code{cross_all} attribute. This complements the @code{allow_arrows} attribute of blocks.
While that attribute allows any and all arrows to cross the block it is set on, the
@code{cross} and @code{cross_all} attributes can be specified selectively per arrow.
@item distance
This attribute dictates how large is the distance between the arrow and the blocks it goes around.
Setting it to single number (meant in pixels) will impact all blocks it goes around.
Setting it in the sytnax @code{<block>@@<number>} will make the arrow to use this distance only for
@code{<block>}. You can apply this attribute multiple times, or use the plus sign to list
several blocks, like @code{distance=<block>+<block>+...@@<number>}.
@item routing
This attribute governs, how arrows are laid out. If set to @code{straight}
the arrow will go between the two blocks in a straight line, potentially over
other blocks. If set to @code{horizontal} or @code{vertical}, the straight
line will be parallel to the X or Y axis, respectively. @code{grid} will make it either 
horizontal - or vertical if horizontal routing is not possible.
If set to @code{polygon}, the arrow will go the shortest path around blocks in
the way. @code{manhattan} will result in using only horizontal and vertical edges
attempting to go around blocks in the way.
For the latter two modes, the @code{line.corner} and @code{line.radius} attributes
can be used to round the vertices of the polygon. If set to @code{curvy} (default),
the arrow will avoid blocks in the way but a smoothing is applied to make the arrow
one smooth line. There are limitations to this, but Msc-generator attempts to
do a good job.

@center @image{exE1, 13cm}
@item routing.factor
This attribute governs, how the arrow layout algorithm trades off between
minimizing arrow length and minimizing the number of turns the arrow makes.
The value 0 means considering only arrow length (default), while 1 means
considering only minimizing turns. Values in between balance.
Note that arrow layout starts with a straight line between start and end (or
waypoints) and then attempts to go round blocks in-between. Thus, even if you
prefer minimizing turns, it will not by itself consider a big detour. Use the
@code{via} attribute for that.
@item routing.clip_block
If set to yes (default) arrows/lines starting/ending at a block will be clipped by
that block. Also applies if the ending is specified as a coordinate using the same,
single block in the specification of both the X and Y coordinate.
@item route.arrow_distance
Overlapping arrow endings will get spaced apart this much, see
@ref{Automatic De-Overlapping at Arrow Ends}. Default is 5 pixels.
@item routing.extend
If arrow endings get outside the block due to de-overlapping, we extend them
to the perimiter of the block, if this is set to @code{yes} (default).
@multitable @columnfractions .4 .6
@item

@image{exJ0_csh,,3cm}

@tab

@image{exJ0, 5cm}
@end multitable

@item routing.block_others
If set, it prevents overlap between the middle of arrows subject to de-overlapping,
see @ref{Automatic De-Overlapping at Arrow Ends}.
@item routing.try_harder
If set, at de-overlapping Msc-generator will try all permutations of arrow ordering 
until the best arrow layout is found (fewer turns and shorter arrows). If not set,
the search is stopped at the first layout where the de-overlapped arrows do not overlap.
@item routing.allow_joint_layout
This attribute defaults to @code{yes} meaning that at de-overlapping arrows that initially 
fully overlap Msc-generator will route this arrow side-by-side along the same path with the 
others it initially overlapped. If set to @code{no}, this arrow will be laid out 
indpendently. It can be useful if you want the arrows to go around an obstacle on different 
paths.
@item routing.order
If the above is set, the layout order of arrows is important. You can assign a number
to this attribute to govern the repeated layout of arrows after their endpoints have
been shifted due to overlaps.
@item draw_before
@itemx draw_after
You can specify one or more blocks (separated by plus signs or via repeating the attribute)
the block shall be drawn before or after. You can use only one of the two attributes for any
diagram elements. Setting one will automatically clear the other.
@end table

Arrows and lines have a single default style @code{arrow}. Then we have eight refinement
styles @code{--}, @code{==}, @code{..}, @code{++}, @code{->}, @code{=>}, @code{>} and
@code{>>}. The former four sets @code{routing=straight}, but otherwise they
are just setting the line style by default. Of course, you can change them. Arrow labels
have the default style @code{label}. This is also the default style for label-less
markers, so there you can set the default marker type, too.

@node Replicating parts of the Diagram, Chart Options and Commands, Arrows in Block Diagrams, Block Diagram Language Reference
@section Replicating parts of the Diagram

To minimize typing, Msc-generator offers tools to replicate parts of the Diagram.

First, you can define a procedure, which you can replay many times, see @ref{Procedures}.
Second, you can copy an already placed block modifying its attributes and also its content (if any).
Third, you can create many copies of a set of blocks with one line.

@menu
* Copying a Block::
* Block Templates::
* Repeating a Block Many Times::
@end menu

@node Copying a Block, Block Templates, Replicating parts of the Diagram, Replicating parts of the Diagram
@subsection Copying a Block

Using the @code{copy} command, you can repeat a previously defined block.

@code{copy <block_name> [as <new_name>] [<attributes>] [<content_update>];}

Using the @code{as} clause you can give a name to the newly created copy (so that you can reference it later).
Specifying any attribute will override the attributes of the original block. The type of the original
block cannot be changed. The content of the original block is also copied, including arrows.

After the attributes you can also specify a list of updates to the content of the block in curly braces.
Here you can use the following commands.
@table @code
@item add [before <block>] <block description>
Add a new block (of any kind) to the end of the content list, or before @code{<block>}. The added block can itself have content you can specify. Alternatively, the added block can itself be a copy or even an arrow.
@item drop <block>
Remove a block from the content list. You can specify a children using
nested dot notation, so if the block to copy contains a block @code{inner},
which in turn contain a block @code{innermost}, you can drop the latter by
saying @code{drop inner.innermost}. You can also drop several blocks, list them
separated by commas.
@item [recursive] update <block>|blocks|arrows|all <attributes>
Using this commands you can apply changes to the attributes of a block, all blocks, arrows or simply all
content of the block under copy. If you add @code{recursive}, the attribute update also applies to content
of the content recursively.
Similar to drop, you can specify a block to update that is not directly the
children of the copied block. You can also specify a list of blocks, separated
by commas - this applies the change to a specific set of contained blocks.
@item replace <block> <block description>
This command removes @code{<block>} and adds the block specified afterwards in its place. Again, similar to dropping or updating @code{<block>} can denote an
indirect child.
@item move [before <block1>] <block2>
This command moves @code{<block2>} to the end of the content list or before block @code{<block1>}. You can only reorder the content list of the copied block
here not that of any children.
@item use <attributes>
@itemx blocks use <attributes>
@itemx arrows use <attributes>
These commands (as elsewhere) update the running style impacting block and/or arrows you add
or replace subsequently.
@end table
Currently there is no way to drop or replace an arrow, but you can add arrows and replace blocks to arrows.

@node Block Templates, Repeating a Block Many Times, Copying a Block, Replicating parts of the Diagram
@subsection Block Templates

In addition to copy blocks that were previously added to the diagram, you can also define
@dfn{templates} of blocks. Block Templates are fully defined blocks (of any kind), that are
not part of the diagram. They do not appear and cannot be referenced (e.g., for alignment or arrows).
They, however, can serve as a basis of other blocks, that do appear.

To define a template, simply add @code{template} in front of any block. The name of the block becomes
the name of the template.@footnote{If you have defined the template inside another block (wierd), the full name
of the block becomes the name of the template.} The template captures the default styles and running styles
at the location of definition and replaying it will not be impacted by a later change to them.

To create an actual box from the template use the @code{copy <template>} command. Add @code{as <name>}
if you want the block created to have a different name. Note that the @code{copy} command can also be used
to copy existing blocks. If you have a template and a block of the same name, @code{copy} will use the template.
When creating a box from a template, you can change attributes and content of the template, similar to
the case of copying an existing block, see @ref{Copying a Block}.

Templates are part of the chart and do not disappear after closing the scope (at the closing brace).
Template definitions cannot be made part of design specifications, but can be part of procedures.
In the latter case replaying the procedure will result in the definition of the template at the location of the replay.
You can also create a modification of a template by copying it. Simply type @code{template} before
a @code{copy} command and the result will not be a block that appears but a template.
This construct is also suitable to create a template (possibly with modifications) from an
exitsing block - simply type @code{template copy <block_name> as <template_name>}.

@node Repeating a Block Many Times, Chart Options and Commands, Copying a Block, Replicating parts of the Diagram
@subsection Repeating a Block Many Times

This functionality is not yet implemented.

@node Chart Options and Commands, , Arrows in Block Diagrams,  Block Diagram Language Reference
@section Chart Options and Commands

You can set the following chart options by simply adding @code{<option>=<value>}
to the chart at any place. All of them can be made part of designs
(with the exception of @code{numbering.append}).
@table @code
@item numbering
@itemx numbering.*
These options control automatic numbering and are described in @ref{Numbering}.
@item text.*
These attributes can be used to set the default font in the chart.
See @ref{Text Formatting Attributes}.
@item background.color
@itemx background.color2
@itemx background.gradient
These can be used to set the background fill of the diagram. You can specify
them at any point during the diagram specification - the last setting will be used.
@item conflict_report
This option can be used to set the report level of alignment conflicts, see
@ref{Block Layout Conflicts}. You can set it multiple times and it honours
scoping - its effect lasts until the next closing brace.
@item pedantic
When set to @code{no} any block mentioned in an attribute update or arrow
that has not yet been defined, will be automatically created. This prevents
forward refrencing blocks in arrow definitions, but is handy to quickly
define a lot of blocks. See @ref{Block Types and Definition}.
@end table


Block diagrams support the generic @code{defcolor}, @code{defstyle} and @code{defshape}
commands to define colors, styles and shapes, respectively
(see @ref{Specifying Colors}, @ref{Defining Styles}, @ref{Defining Shapes});
@code{usedesign <design_name>;} to apply a design (both full or partial designs);
@code{include} to include another text file (see @ref{File Inclusion});
and @code{defproc}, @code{replay} and @code{if} commands to define and use
procedures (see @ref{Procedures}). These are all generic commands available
also in signalling charts and graphs (with some minor variations).

In addition to the commands, Block Diagrams support another command: @code{use}.
After @code{use} you can specify a list of attributes, the same way as for
any chart element (but you do not need the square brackets). This has an effect
of applying the listed attributes on all subsequent blocks and arrows
(until the scope ends, see @ref{Scoping}). This allows a quick shorthand to save typing.
The feature is implemented via a hidden @dfn{running style}, which is applied to all newly
defined blocks or arrows after the default and enhancement styles, but before
the explicit attributes. Thus the values you set this way can override default and
enhancement style values, but can be overridden by explicitly specified attributes.
Note that you can list styles after use, for example, @code{use col;} will apply
the @code{col} style to any subsequent elements, making blocks align from top
to bottom.

@bye
