summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/nassflow/nass_man.tex
blob: 93b76ada24cfc58d49c2c55ed7c615214a8ff382 (plain)
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
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
\documentclass[11pt,twoside]{manual}
\usepackage{nassi}
\tool{NASSI}{Typeset Nassi-Schneiderman diagrams in \LaTeX}{3}

\hyphenation{sta-te-ment}
\begin{document}

\maketitle

\begin{para}{Synopsis}
\verb"\STRUCT{struct name}{structure purpose}{statements}"

\vspace{0.25cm}
For a description of the statements see section Macros
\end{para}

\begin{para}{Description}
The {\tt Nassi} macros enable the user to create Nassi-Schneiderman diagrams in
a \LaTeX\ document. The macros can be used in any type of document, within all
the standard \LaTeX\ environments.

An NS-diagram in this context is described in macros resembling a pseudo code.
The diagram itself is defined as a structure and is build from statements.
Macros are available for all standard programming statements (if, while, action
etc.).

The Language Sensitive Editor for \LaTeX, LSA, is extended to support the
creation of NS-diagrams with the {\tt Nassi} macros.

The macros needed to create a Nassi-Schneiderman diagram in your \LaTeX\
document will be made available to you when you include the option \verb"Nassi"
in the \verb"\documentstyle" command at the start of your \LaTeX\ file, as in
the following example:
\begin{verbatim}
\documentstyle[11pt,Nassi]{article}
\end{verbatim}

An NS-diagram in the context of the {\tt Nassi} macros is called a structure.
The drawing of the diagram is based on units. A unit can be seen as the box in
which an action is described. Both the structure and the unit have an attribute,
the width. The layout of the diagram is determined from the value of these
attributes. Both can be changed by the user through macros which must be used
before the actual structure is described. They have the following effect:

\begin{itemize}
\item If both attributes have their default values, the unit width is 60 points
(there are 72 points to an inch). The width of the structure is determined by
the number of units on one line, while each unit has a minimum width of 60
points. The maximum width of a unit is the structure width. 
\item If the unit width is specified by the user the same rules apply but the
minimum width of a unit is the specified width.
\item If the structure width is specified by the user, the diagram will have
this width, while the width of each unit is determined depending on their
contents and the number of units on one line. The maximum unit width is still
the structure width. 
\end{itemize}

{\em It is recommended that users do not change both attributes for the same
structure.}

By default the text in the diagrams is typeset in the same size as the text in
the document. This will be to large.
Before starting a structure it is adviced to set the desired text size. For the 
default settings of structure and unit width \verb|\scriptsize| is recommended.

When you run into errors like {\tt overfull hbox[]} you may either have to use a
smaller text size like \verb|\tiny| or give a proper hyphenation directions
for the indicated text.

Do not forget to reset the text size to {\tt normalsize} after the structure.
\end{para}

\begin{para}{Macros}
The available macros fall into four categories:

\begin{enumerate}
\item Width settings of structure and unit. They must appear before the
structure.
\item Definition of the structure itself.
\item Statements. They must appear within the structure definition.
\item Options. They may appear before as well as within the structure
definition.
\end{enumerate}

Width setting macros are:
\begin{itemize}

\item \verb"\unitwidth=size" \\
Specifies the minimum width of a unit. Size must be given as a standard \LaTeX\
length. 

\item \verb"\nassiwidth=size" \\
Specifies the total width of the diagram. Size must be given as a standard
\LaTeX\ length.  For a diagram with the same width as the normal text the
command \verb"\nassiwidth=\textwidth" can be used.
\end{itemize}

Structure definition macro is:
\begin{itemize}

\item \verb"\STRUCT{struct-name}{struct-description}{statements}%" \\
Specifies the complete diagram. The structure name and description, which can be
a short description of its purpose, will be put above the actual diagram. The
statements of the structure, described below, must be specified as part of the
\verb"\STRUCT" command. 
\end{itemize}

Statement macros are:
\begin{itemize}

\item \verb"\ACTION{action}%" \\
Specifies a normal statement. 

\item \verb"\PROC{proc-name}{proc-description}%" \\
Specifies a special kind of action, a procedure call. The proc-name will be put
behind the proc-description text in brackets. 

\item \verb"\ACCEPT{entry-name}{statements}\ENDACCEPT%" \\
Specifies the {\tt ADA} accept statement. The entry-name will be followed by
a separate box containing the statements. 

This statement is not available for flow structures.

\item \verb"\IF{condition}\THEN{statements}\ELSE{statements}\ENDIF%" \\
Specifies an if statement with a condition and a collection of statements in the
{\tt THEN} and the {\tt ELSE} part. Neither the {\tt THEN} nor the {\tt ELSE}
part is optional. If one of them is not needed an empty statement,
``\verb"{}"'', must be used. 

\item \verb"\REPEAT{statements}\UNTIL{test}%" \\
Specifies a loop statement with a collection of statements and an
end-condition. 

\item \verb"\WHILE{condition}{statements}\ENDWHILE%" \\
Specifies a loop statement with a start-condition and a collection of
statements. 

\item \verb"\CASE{case-item}{when-statements}\ENDCASE%" \\
Specifies a case statement with a case-item and a collection of when-statements. 
The case statement can also be used to represent the \verb"ADA" select
statement by specifying \verb"select" as the case-item.

\item \verb"\WHEN{condition}{statements}%" \\
Part of a case statement. Specifies a condition and a collection of statements. 
When the case statement is used as an \verb"ADA" select statement the
condition represents the \verb"gard", \verb"delay" or \verb"else" part.

\end{itemize}

Options are:

\begin{itemize}
\item \verb"\setiftext{left-hand}{right-hand}%" \\
Specifies the text to be put on the left-hand and right-hand sides of the
condition of an if statement. Defaults are ``Y'' and ``N'' for the left-hand
and the right-hand respectively.  The scope for these settings depends on the
position of the command within the document. 

\begin{itemize}
\item If the command occurs before a \verb"\STRUCT" statement, the settings
remain valid for all \verb"\IF" statements in all following structures until
they are reset by a \verb"\setiftext" command with the same scope. (Remember to
put the \verb"\setiftext" command {\bf after} any font size changing commands). 

\item If the command occurs inside a \verb"\STRUCT" statement but outside any
other commands, the settings will remain valid for all \verb"\IF" statements in
the same structure until they are reset by a \verb"\setiftext" command with the
same scope.

\item If the command occurs inside a command within a structure, the settings
will remain valid for all \verb"\IF" statements within the command (for
instance an if statement within the then or else part of another if statement)
until they are reset by a \verb"\setiftext" command with the same scope.

\end{itemize}

It is allowed to `nest' the \verb"\setiftext" commands, thus
changing the settings for a particular part of a structure or a document.

\item \verb"\underlinewhentrue%" and \verb"\underlinewhenfalse%"\\
Specifies whether a line is drawn underneath an \verb"\IF", \verb"\WHILE",
\verb"\REPEAT", \verb"\ACCEPT" or a nested \verb"\CASE" statement. To be
compatible with previous releases of Nassi the default setting is
\verb"\underlinewhenfalse%". The scope for this settings depends on the
position of the command within the document. See \verb"\setiftext" for more
information.

This option is not available for flow structures.

\end{itemize}

Note that each line within the structure, including the command itself,
{\em must} be concluded by a \%.

The text appearing (between the braces) in the structure definition and in all
statements, including the \verb"\setiftext" macro is free but must adhere to the
standard \LaTeX\ syntax. Every text is considered a paragraph in the \LaTeX\
context. 
\end{para}
                                                                  
\begin{para}{Files}
The file \verb"TEX$INPUTS:NASSI.STY" specifies the Nassi-Schneiderman macros.
\end{para}

\begin{para}{See also}
The pages on \LaTeX, LSA and FLOW in this section of the manual.
\end{para}

\begin{para}{Bugs}
\begin{itemize}
\item The {\tt Nassi} option is mutually exclusive with the {\tt Flow} option
because the same macro names are used.

\item {\tt Nassi} has a limit to the number of statement macro's in one
structure definition. For example a maximum of 26 IF macro's can be used. If
one of these limits is reached, \LaTeX\ shows some curious error messages, like
``You cannot use = as a prefix'', which have no relation at all to the real
problem.

\item Within the \verb"\ACCEPT" statement part at least one statement is
required. As dummy the \verb"\ACTION{null}" is recommended.

\item If \verb"\underlinewhentrue%" is specified and the concerning
\verb"\WHEN" statement is the tallest of all \verb"\WHEN" statements in the
\verb"\CASE" statement a double line will show. By specifying
\verb"\underlinewhenfalse%" at the end of this \verb"\WHEN" statement, this
problem can be prevented.

\end{itemize}
\end{para}

\begin{para}{Example}
The following is an example of a structure with all possible statements. The
resulting diagram is shown below.

\begin{verbatim}
\scriptsize
\STRUCT{structure name}{structure purpose}{%
  \ACTION{initial statement}%
  \PROC{proc name}{procedure purpose}%
  \ACCEPT{entry name}{%
    \ACTION{critical part}%
  }%
  \ENDACCEPT%
  \IF{condition to test}%
  \THEN{%
    \ACTION{true action 1}%
    \ACTION{true action 2}%
  }%
  \ELSE{%
    \ACTION{false action}%
  }%
  \ENDIF%
  \REPEAT{%
    \ACTION{statement to repeat}%
  }%
  \UNTIL{end condition}%
  \WHILE{start condition}{%
    \ACTION{statement to do}%
  }%
  \ENDWHILE%
  \CASE{case item}{%
    \WHEN{condition 1}{%
      \ACTION{statement to do}%
    }%
    \WHEN{condition 2}{%
      \ACTION{statement 1 to do}%
      \ACTION{statement 2 to do}%
    }%
    \WHEN{condition 3}{%
      \ACTION{statement to do}%
    }%
  }%
  \ENDCASE%
  \CASE{select}{%
    \WHEN{gard 1}{%
      \ACCEPT{entry name 1}{%
        \ACTION{statement to do}%
      }%
      \ENDACCEPT%
    }%
    \WHEN{}{%
      \ACCEPT{entry name 2}{%
        \ACTION{critical statement to do}%
      }%
      \ENDACCEPT%
      \ACTION{non critical statement to do}%
    }%
    \WHEN{}{%
      \ACTION{delay 10.0}%
    }%
    \WHEN{else}{%
      \ACTION{else actions}%
    }%
  }%
  \ENDCASE%
}%
\normalsize
\end{verbatim}
\end{para}

\newpage
\scriptsize
\STRUCT{structure name}{structure purpose}{%
  \ACTION{initial statement}%
  \PROC{proc name}{procedure purpose}%
  \ACCEPT{entry name}{%
    \ACTION{critical part}%
  }%
  \ENDACCEPT%
  \IF{condition to test}%
  \THEN{%
    \ACTION{true action 1}%
    \ACTION{true action 2}%
  }%
  \ELSE{%
    \ACTION{false action}%
  }%
  \ENDIF%
  \REPEAT{%
    \ACTION{statement to repeat}%
  }%
  \UNTIL{end condition}%
  \WHILE{start condition}{%
    \ACTION{statement to do}%
  }%
  \ENDWHILE%
  \CASE{case item}{%
    \WHEN{condition 1}{%
      \ACTION{statement to do}%
    }%
    \WHEN{condition 2}{%
      \ACTION{statement 1 to do}%
      \ACTION{statement 2 to do}%
    }%
    \WHEN{condition 3}{%
      \ACTION{statement to do}%
    }%
  }%
  \ENDCASE%
  \CASE{select}{%
    \WHEN{gard 1}{%
      \ACCEPT{entry name 1}{%
        \ACTION{statement to do}%
      }%
      \ENDACCEPT%
    }%
    \WHEN{}{%
      \ACCEPT{entry name 2}{%
        \ACTION{critical statement to do}%
      }%
      \ENDACCEPT%
      \ACTION{non critical statement to do}%
    }%
    \WHEN{}{%
      \ACTION{delay 10.0}%
    }%
    \WHEN{else}{%
      \ACTION{else actions}%
    }%
  }%
  \ENDCASE%
}%
\normalsize

\end{document}