This tutorial won't teach you how to write Z, but if you already have some idea on that, then it will show you how to mark-up that Z so that cadiz will be able to process it. Specific examples are given here; for general definitions, see the reference manual.
The formal paragraphs of a Z specification are delimited from the informal paragraphs by being enclosed within troff-like requests. Those paragraphs that have an outline are delimited by .ZS and .ZE, with the middle line of a paragraph box marked by .ZM. These can be thought of as the start, middle and end requests. They must appear at the start of a line, with the . having no space after it.
.ZS ... .ZM ... .ZE
Those paragraphs that do not have an outline are delimited by .ZH and .ZE, where .ZH can be thought of as standing for horizontal, since non-outlined paragraphs are typically one liners.
.ZH ... .ZE
The paragraph delimiters are illustrated in the example specification below.
All the facilities of troff and its preprocessors may be exploited for typesetting informal material between Z paragraphs. However, formal and informal text must be separate: cadiz's parser will fail if any informal text appears in a formal paragraph, and troff will fail if a formal paragraph appears within a larger construct, such as a keep.
cadiz ignores the informal text in a specification, recognising only the formal Z paragraphs and the directives that affect the tool's behaviour. These directives are all marked-up as individual lines, and look like troff requests starting with .Z and followed by a distinguishing letter and any arguments. For example,
.Zo sinc U+2286
directs cadiz to map all occurrences of sinc to the UCS character 2286.
Most directives must be written between formal paragraphs, not within them. There are directives for typesetting indexes, turning off typesetting, generating conjectures, and so on. A full list of directives is in the reference manual.
The troff typesetting program is run by cadiz on your behalf: your troff mark-up has to be processed by cadiz before troff can typeset it. This processing includes prettyprinting of the formal text. If your mark-up includes text to be seen by troff pre-processors, such as eqn and tbl, it should be passed through those pre-processors before being given to cadiz, as in the following example.
tbl filename.t | eqn >filename.z cadiz filename.z
The following example specification is intended to illustrate the troff mark-up that cadiz can recognise and the typesetting of formal text performed by cadiz. It is not intended to be indicative of good style but simply to provide examples of troff mark-up and typesetting. The specification is of a bicycle gearing system.
section gearsystem parents standard_toolkit |
.ZH section gearsystem parents standard\_toolkit .ZE
gearing ::= Single | Hub ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
.ZH gearing ::= Single | Hub << nn >> | Derailleurs << nn cp nn >> .ZE
Wellgeared == [ gears : gearing | gears ![]() |
.ZH Wellgeared == [ gears : gearing | gears mem ran Derailleurs ] .ZE
[X,Y] | ||
![]() |
![]() | |
![]() |
![]() | |
First : X ![]() ![]() | ||
Second : X ![]() ![]() | ||
![]() |
![]() |
![]() |
![]() ![]() | ||
![]() ![]() | ||
![]() | ||
.ZS [X,Y] First : X cp Y fx X Second : X cp Y fx Y .ZM forall x : X; y:Y dot First (x,y) = x and Second (x,y) = y .ZE
Gear | ||||
![]() |
![]() |
![]() | ||
![]() | ||||
Wellgeared | ||||
ingear : ![]() ![]() ![]() | ||||
![]() |
![]() |
![]() | ||
![]() ![]() ![]() | ||||
![]() ![]() | ||||
![]() | ||||
![]() |
.ZS Gear Wellgeared ingear : nn cp nn .ZM exists r, s : nn | gears = Derailleurs (r,s) dot First ingear < r and Second ingear < s .ZE
Bicycle [G] | ||||
![]() |
![]() |
![]() | ||
![]() | ||||
![]() |
![]() |
![]() | ||
![]() | ||||
gears:![]() | ||||
![]() | ||||
![]() |
.ZS Bicycle [G] gears:ps G .ZE
numgears : gearing ![]() ![]() | ||
![]() |
![]() |
![]() |
![]() ![]() | ||
![]() ![]() ![]() | ||
![]() ![]() ![]() ![]() ![]() ![]() | ||
![]() ![]() ![]() ![]() ![]() |
.ZS numgears : gearing fx nn .ZM forall g : gearing dot (g = Single imp numgears g = 1) and (exists x : nn dot g = Hub x imp numgears g = x) and (exists r, s :nn dot g = Derailleurs (r, s) imp numgears g = r*s) .ZE
![]() |
.ZH thrm numgears (Derailleurs (3,7)) = 21 .ZE Lemma1
The argument to .ZE is the name of this conjecture. A conjecture need not have a name. There is a tutorial on proving conjectures using cadiz.
The mark-up of specific mathematical symbols may be found by referring to the following tables in the reference manual,
Spaces, tabs and newlines in the mark-up are retained as SPACE characters in the UCS sequence. cadiz prettyprints all formal text, so extra spaces can be included to layout the mark-up neatly without affecting the typeset document.
It can be helpful to bear in mind that the troff mark-up is first converted to a sequence of UCS characters, and that it is that sequence which cadiz lexes and parses. When cadiz rejects your mark-up and you need to work out why, it is worth considering the sequence of UCS characters to which cadiz converts your mark-up. The prep tool may be helpful, as it does the same translation to UCS characters as cadiz but then just displays them in a window.
Mathematical symbols may be referred to by their troff codenames,
e.g. \(te is acceptable mark-up for ,
though you might prefer to use the name exists.
When you want to introduce a name for a new mathematical symbol,
you will need to provide a mark-up directive to tell cadiz
how to convert it to a sequence of UCS characters.
Here are some examples of mark-up directives
for symbols that are single UCS characters.
.Zo Delta U+0394 .Zo arithmos U-0001D538 .Zo rel U+2194 .Zo fss U-0001D53D .Zo clseq U+3009
Notice that four-character encodings are used for symbols on the basic multilingual plane of UCS, and eight-character encodings are used for other symbols. A similar directive exists for multiple character symbols.
.Zw dcat cat/ .Zw rtc nearrow*swarrow
The conversion of each name includes SPACE before and after it, except when the name appears in another .Zw mark-up directive.
Subscripts and superscripts can be marked-up using the arrow characters named searrow, nwarrow, nearrow and swarrow. Single-character subscripts can alternatively be marked-up using c.
The convention for operation schema names involving Greek and
characters
can be marked-up using DELTA and XI prefixes as part of the word,
as well as using \(*D and \(*C.
For example, DELTABirthdayBook and \(*DBirthdayBook.