SDIA, a system for SD diagrams typesetting

• HOME
• Documentation
• SDIA Generator
• Download
• TODO, problems
• Cesky

 

SDIA

a system for SD diagrams typesetting

Version: 1.0 Date: Jun 29 2005

You can get the newest version at http://www.square.cz/sdia/

Copyright © 2000-2005 Milan Vancura <milan@ucw.cz>
SDIA is distributed under terms of MIT license, see the file COPYING.

The SDIA documentation is also available in following formats: PDF, PostScript and plain text.

Contents

1     Preface
2     Usage
2.1     Basic idea
2.2     MainStream usage
2.3     Plus hands
2.4     Advanced phantoms
2.5     Challenge commands
2.5.1     bw
2.5.2     rot
2.5.3     frame
2.5.4     txt
2.6     NOL: Hexagons
3     Technical Notes
3.1     How this works
3.2     Making own macros
4     Final word

1 Preface

This system was designed for quick making SD diagrams in Encapsulated PostScript (.eps) format usable at all operating systems with no special software needed. All you need is the (ASCII) text editor, even the most ordinary one (like vi on UNIX or Notepad on Windows). Of course you don't need to know anything about PostScript, but it could be your advantage if you want to modify the system to your special needs.

Encapsulated PostScript diagrams can be used for many typesetting programs directly: TeX (with dvips), Adobe PageMaker, Quark X-press and others. Converting PostScript to another format is not a task solved by this system. However this could be done with free programs also, for example ghostscript.

The system is not WYSIWYG - it can't be because it should be simple and usable at computers with no special SW. But maybe you will need some helper application at the beginning of learning. There is one. Open sdia_generator.html file in your HTML browser (JavaScript and CSS capable). It will help you to create your first sdiagrams and to understand how the system works. You don't need nor network connection nor any other file.

It's really easy!

2 Usage

2.1 Basic idea

There is a "master" file sdia.eps which you should copy for each new diagram you want to make. Then you need to edit 2 parts in the new copy. The user data section contains all the diagram information such as dancers. This is described in the following chapters. Now we talk about the first editable part, the BoundingBox.

BoundingBox says the size (measured in PostScript points) of the result picture to your typesetting system. Four numbers mean: left, bottom, right and top border. As you can see this is where some computing is needed, but very simple. In most cases the following heuristics works:

2.2 MainStream usage

User data contains one line for each dancer or standalone command. Standalone commands are described in Chapter Challenge commands, format of dancer line is:

2.3 Plus hands

You can use LH or RH parameter to add left or right (or both) hand for this dancer. In this case the terms `left' and `right' are meant according to the dancer's facing direction. A shape and size of the hands are computed so two dancers in a couple or mini-wave have joined hands, also four people in a star have inner hands nicely joined.

Using Hands with dancers facing h,v or x is not defined.

If you want to create more difficult diagrams you may use the fact that direction names `n',`s',`e' and `w' are the abbreviations of numbers only: n=90, w=180, s=270 and e=0. You can use another values to create dancers facing SE, SSE and so on :-) See also the `rot' command below.

Note that `h', `v' and `x' are more complicated macros - see Chapter Technical Notes.

2.4 Advanced phantoms

The next dancer parameter you can use is `ph' for phantom. This is the first time when the order of parameters is important. `ph' parameter changes all parts of dancer written on this line before `ph' command to its phantom variation.

2.5 Challenge commands

The folowing commands are standalone - placed on their own lines. They create new objects independent on any other dancer or change some general option. If they change some option, all following dancers are affected while the previous ones not - see the example near the `rot' command.

2.5.1 bw

If you use graphical signs for dancers and don't have a printer with high quality of gray halftones printing, you may need a `bw' command. It has no parameters, it simply switch the gray print to black&white one.

2.5.2 rot

This command is used to draw diagonal formations. Format of this standalone command (placed at its own line) is:

Remember that sometimes you have to recompute BoundingBox parameters.

2.5.3 frame

Sometimes you need to emphasis some subformation. This can be done with `frame' command:

2.5.4 txt

`txt' command is used to place a centered text label at some position:

2.6 NOL: Hexagons

There is a support for hexagon diagrams also. Two standalone commands for facilitation of creating the hexagons are `hexinit' and `nextthird'.

Syntax of `hexinit' and `nextthird' commands:

Firstly, the center of the formation is set with `hexinit' command. Then draw one third of the dancers' group (typicaly 4 dancers). Then use the `nextthird' command to rotate the coordinate system around the defined center about 120 degrees (1/3), draw the second group of dancers, rotate using `nextthird' again and draw the last part of dancers.

In case of symetrical diagram all three groups contain dancers with the same coordinates, only the dancers' labels differs in each group.

Of course, you need to compute BoundingBox parameters as well as hexinit parameters. In the following examples, there are both BoundingBox parameters and user data shown, place it at according places in your eps file.

3 Technical Notes

This chapter describes the PostScript background, so the PostScript knowledge is expected.

3.1 How this works

Each parameter (and "dancer name" which are PostScript macro command also) is defined as a macro which puts one {} block on the stack. Directly executable macros are used at the ends of lines: `b', `g' and standalone commands `bw', `rot', `txt', `frame', `hexinit' and `nextthird'.

`b' and `g' macros expect 4 parameters on the stack (from the top to bottom): y_coord, x_coord, angle of rotation and {} block drawing the dancer. Parameters of standalone commands are shown in their chapters.

Macros `n', `s', `e' and `w' expands to one number which means the angle to rotate from east orientation.

Macros `h' and `v' expands to two parts: a chain command (see below) which draws the opposite nose and an angle to rotate.

If something more should be exectuted, the fourth parameter of `b' and `g' (counted from the top of the stack) must be {} block which executes its own code and then get and execute the next parameter. This is called "chaining" because typical dancer's line after the first PostScript expansion looks like this:

Examples in this and following chapters show how the `clr' sdia command was implemented.

The setrgbcolor PostScript command needs three numbers betveen 0 and 1, one for red, green and blue part of color. We know we should put it to `{ ... chain }' scheme so for creating a dancer with dark red sign in it and with green hands we write the following.

3.2 Making own macros

You can add a macro command for your own dancer parameter - it must put the block of PS code in "{ ... chain}" scheme on the stack.

You can also create new graphical dancer label - "chain terminator". These macros must put the block of PS code on the stack also but the block doesn't contain the final chain command. It is a good idea to enclose the inner code between gsave..grestore pair - see sdia.eps code for useful macros and examples.

The coordinate system used in "label" macros is scaled by 0.004347 (=1/230). In this system, a size of the boy's square is 49x49 and the diameter of the girl's circle is 54.

4 Final word

Enjoy it! I hope you'll create many nice diagrams for your articles, books and teaching material - or just for fun.

All comments and improvements are welcome. Feel free to send them to my e-mail address:

Milan Vancura <milan@ucw.cz>