[[ Note: This text-only version of the tutorial was produced by hand from
the Impression version. It is therefore likely that there are lots of
infelicities in the formatting; in particular, font changes have been
lost. If a sentence doesn’t seem to make any sense, see whether it’s
any better if you pretend some of the words in it are in italics. :-) ]]
A mkdrawf tutorial
==================
This is a fairly gentle introduction to mkdrawf, a program for creating drawfiles. If you don’t know what a drawfile is, don’t worry: you will soon. If you don’t know what a program is, perhaps you should read some other tutorials first.
In fact, even if that’s the case you can probably get a fair way into this
tutorial, since most of it consists of instructions saying “Put this into a
file and do that with it, and see what happens”.
When you’ve worked through this tutorial, you should find most of the manual pretty easy going. Actually most of the manual is easy going anyway, but it
suffers a bit from being intended as a reference as well as a tutorial; this
document has no such ambitions, and is unashamedly incomplete; it even
contains a few (minor) lies. If it disagrees with the manual, you know which
to trust.
Running mkdrawf
---------------
mkdrawf manufactures drawfiles out of ordinary text files. There are two ways
to use it. Firstly, you can run it from the command line: entering a command
like
mkdrawf textfile drawfile
will process the file textfile and produce an output file drawfile. Secondly,
you can use the Wimp application !Drawf, which allows you to drag a text file
to its icon, whereupon it will run that file through mkdrawf and allow you to
drag the resulting drawfile somewhere to save it. The icon for !Drawf looks
like this: <<sorry...>> .
(As you might guess from the look of the icon, !Drawf will also decode
drawfiles for you, producing output suitable for handing to mkdrawf again.
There is a separate manual for !Drawf which will tell you all about this, and
more besides.)
From now on, I shall assume that you can do one of these two things. When I say “run mkdrawf on this file”, this means: either choose an output filename and
use the command-line, or else drag the file to the !Drawf icon and put the
resulting output somewhere.
Running !Draw
-------------
The easiest way to see the results of using mkdrawf is to view the files it
produces using !Draw. This program comes with every Archimedes or Risc PC, so
you should definitely have a copy; you can probably find it by clicking on an
icon labelled Apps at the left-hand side of your icon bar.
If you haven’t used !Draw before, the first thing you should do is to run it
and play around with it for a while. This should give you an idea of the sort
of thing it can do.
A drawfile is a file which !Draw can understand. A drawfile consists
basically of a number of objects (lines, curves, bits of text, that sort of
thing) strung together. In some cases (have you used the Group option on the
menu?) an object can contain a number of other objects. As this tutorial
proceeds, you will learn rather more about drawfiles than you actually want
to know.
Every time you run mkdrawf you should have a look at the output by either
double-clicking on the file it produces (after dragging it to a directory
display, if you are using !Drawf) or dragging the file to !Draw’s icon on the
icon bar. (Not quite every time; if something goes wrong and you get lots of
error messages, the resulting drawfile may be full of rubbish, or at any rate
not full of what you wanted.)
A very simple example
---------------------
Put the following into a file using your favourite text editor, run it
through mkdrawf, and look at the result using !Draw:
# This is a comment; mkdrawf will ignore it.
Path {
Move 100 100
Line 300 200
}
You can probably guess what the result of this will be before you try it.
Your guess will almost certainly be correct. This simple example actually
demonstrates quite a few things about mkdrawf, though… The first line is
self-explanatory. The remaining lines describe a single object. An object is
introduced by saying what sort of object it is; in this case, it is a path
object. (The typical drawfile consists mostly of path objects.) Further
details about the object are given within those braces {}; in this case, the
path consists of a single line segment from (100,100) to (300,200).
Coordinates are always given, as in this example, as pairs of numbers. The
unit, by the way, is the point; the ambiguity here is unfortunate but seldom
causes trouble in practice. A point is 1/72 of an inch; the spacing between
vertical lines here is about 10 points.
A slightly less simple example
------------------------------
As I already said, a drawfile typically contains several objects, one after
another. This structure is represented in the obvious way in input to
mkdrawf; namely, by putting one object description after another. Here’s an
example, which (as usual) you should try.
Path {
Move 100 100
Line 150 100
}
Path {
FillColour r220g0b0
Move 200 200
Line 300 200
Line 300 300
Close
}
Text {
Style Font "Trinity.Medium"
StartAt 200 300
Size 10 10
Text "Hello!"
}
This produces a drawfile containing three objects: two path objects and a
text object. You can probably make a pretty good guess as to what this will
look like, if I tell you that:
• colours are given as RGB values, each component going from 0 (dark) to
255 (bright);
• Size 10 10 means “I want a 10-point font”;
• Trinity is the typeface in which this tutorial is printed.
An easy exercise
----------------
Write a mkdrawf file which, when fed into mkdrawf and !Draw, produces the
following picture. <<Sorry, again.>> You are not expected, of course, to
produce the grid lines and the numbers labelling them (though you might be
able to do something approximating to them), and you should not worry about
the thicknesses of the lines. The grey colour inside the square is
r119g119b119, I think; and the text is 20-point Trinity.Medium.Italic. When
you’ve done this, check it (of course you won’t be able to check the scale)
by running it through mkdrawf and !Draw.
More about path objects
-----------------------
You may have guessed from the previous picture (or you may have noticed while
using !Draw) that all sorts of things we haven’t discussed yet are possible
with path objects; for instance, the picture includes dashed lines, lines in
colours other than black, and lines of different thicknesses. And there’s
plenty more. Anyway, here is a mkdrawf file demonstrating some more features
of path objects:
Path {
Width 2 # all dimensions, including this, are in points
OutlineColour r0g0b255 # blue lines
Style { EndCap Triangular } # !Draw will show you what this means
Move 100 100
Line 200 100
Curve 300 100 200 200 200 300 # a Bezier curve, ending at (200,300)
Line 200 400
Move 200 100 # a path can be made up of many subpaths
Line 200 300
}
What’s new here? The Width keyword allows you to say how thick you want a
line to be. The width is, like all dimensions, given in points (1/72"). It’s
a “diameter” rather than a “radius”. The Style keyword should be followed by
some stuff in braces; there are several other things you can set in there.
The OutlineColour keyword (so called in contrast to FillColour) determines
the colour of lines and curves, as distinct from the filled-in space inside
them. By the way, the usual 16-colour desktop palette doesn’t include a
colour accurately matching r0g0b255, but !Draw will happily display the best
approximation it can, and won’t throw away its information about exactly what
colour you really wanted.
The line beginning Curve is more interesting. As well as straight lines, a
path object can contain Bezier curves. A Bezier curve is described by giving
its starting and ending points — in this case (200,100) and (200,300) — and
two control points — in this case (300,100) and (200,200). The curve starts
out from its starting point, heading towards its first control point
