aboutsummaryrefslogtreecommitdiffstats
path: root/doc/user/dia_intr
blob: 02ab5b28363b93e2ebc604877d7c5bab1314ab6a (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
@Section
    @Tag { dia_intr }
    @Title { Introduction }
@Begin
@PP
To use the @@Diag symbol you first need to include its setup file.  For
example, suppose you have an ordinary document with tables:
@ID @OneRow @Code {
"@SysInclude { tbl }"
"@SysInclude { doc }"
"@Doc @Text @Begin"
"..."
"@End @Text"
}
Change this to
@ID @OneRow @Code {
"@SysInclude { tbl }"
"@SysInclude { diag }"
"@SysInclude { doc }"
"@Doc @Text @Begin"
"..."
"@End @Text"
}
This provides everything you need for making diagrams.
@PP
The result of the @@Diag symbol is an object in the usual way.  A diagram
is commonly made into a centred display, like this:
@ID @OneRow @Code {
"@CentredDisplay @Diag { ... }"
}
or into a floating figure, like this:
@ID @OneRow @Code {
"@Figure"
"    @Caption { ... }"
"@Diag {"
"    ..."
"}"
}
but it could be an entry in a table, a word in a paragraph, or anything
else.
@PP
Most uses of @@Diag contain a @I { nodes part } and a @I { links part }:
@ID @OneRow lines @Break {
@Code "@Diag {"
    @I { nodes part }
    @Code "//"
    @I { links part }
@Code "}"
}
This reflects @@Diag's view of the world as consisting of {@I nodes}
diagrams. @RawIndex { diagrams }
diagrams.nodespart @SubIndex { nodes part }
nodespart.diagrams @Index { nodes part in diagrams }
diagrams. @RawIndex { diagrams }
diagrams.linkspart @SubIndex { links part }
linkspart.diagrams @Index { links part in diagrams }
(circles, squares, and so on), which have to be put in their right
places and then joined with @I links (lines, arrows).  The technical
meaning of the {@Code "//"} symbol does not concern us here; it
simply serves to divide the two parts.
@PP
For example, here is a nodes part containing two nodes separated by
a @Code "@DP" symbol that (as usual) leaves some vertical space
between them:
@ID @OneRow @Tab
  @Fmta { @Col 7c @Wide A ! @Col B }
{
@Rowa
    A { @Code {
"@Ellipse { Hello, world }"
"@DP"
"@Square @I x"
} }
    B { @Diag {
@Ellipse { Hello, world }
@DP
@Square @I x 
} }
}
Node symbols like @Code "@Ellipse" and @Code "@Square" follow a familiar
pattern:  they consume the following object, which may be arbitrary, draw
a shape around it, and give back the resulting object.  To insert links, the
nodes must first be given names, called {@I tags}, using the @Code "::" symbol:
diagrams. @RawIndex { diagrams }
diagrams.tags @SubIndex { tags ({@Code "::"}) }
tags.diagrams @Index { tags ({@Code "::"}) in diagrams }
@ID @OneRow @Code {
"A:: @Ellipse { Hello, world }"
"@DP"
"B:: @Square @I x"
}
Then a link from @Code A to @Code B may be added to the links part:
@ID @OneRow @Tab
  @Fmta { @Col 7c @Wide A ! @Col B }
{
@Rowa
    A { @Code @Verbatim {
@Diag {
    A:: @Ellipse { Hello, world }
    @DP
    B:: @Square @I x
    //
    @Link from { A } to { B }
}
} }
    B { @Diag {
A:: @Ellipse { Hello, world }
@DP
B:: @Square @I x 
//
@Link from { A } to { B }
} }
}
Subsequent examples will often omit the enclosing {@Code "@Diag { }"}.
@End @Section