.LP
.EQ
delim $$
.EN

.TL
CPIC

.NH 1
Pictures vs Figures

.PP
For the purposes of this discussion a picture will be thought of as containing
some positive number of figures. The figures are drawn side by side.

.NH 1
Delimiters and Arguments

.PP
Delimit the picture with .CPS and .CPE (Charlie Pic Start/End).  The
\&.CPS line can take two real arguments, they are the radius of the
circle on which the vertices of the figures are put, and the radius of
the actual vertices. If only one argument is given it is taken as the
radius of the figures. You can change the default values to suit
yourself by doing obvious things to cpic.h. The default values are 0.4
for the figure radius and 0.02 for the vertex radius.

.NH 1
How Many Figures to a Picture

.PP
You can have as many as you like (in theory). You will need to adjust 
the default figure radius if you require alot of figures or if you have
wide labels on your figures.
The first number after the .CPS line tells how many individual figures 
there will be in this picture.

.NH 1
Defining a Figure

.PP
Each figure in the picture is specified as follows:
firstly, give the number of vertices that will be in this figure,
and then give its edge list.

.NH 2
The Figure's Vertex Count

.PP
Typically you will just want to simply say how many vertices are to be in the
next figure of this picture. This is done as one would expect, by giving the 
count alone on a line. It is also possible to define a label for each figure.
The label should be given enclosed in double quotes (") and will be placed to
the left of the figure in question. Cpic will make a primitive attempt to
estimate the width of the label. If the spacing is not correct the the width
may also be given as a third parameter.

An example is
.br
8 "Octahedron" 1.0
.br
which specifies a figure on eight vertices, labelled with the string 
"Octahedron" centred in a field one inch wide. Cpic should be able to
guesstimate the appropriate width for simple labels such as this.

.NH 2
A Figure's Edge List

.PP
Edges are specified as a b c, meaning vertex a should be joined
to vertex b with a multiplicity of c. If c is omitted it defaults to 1.
c must be less than or equal to 3. The edge list should immediately 
follow the vertex count.

The vertices will be numbered from 1 upwards. Vertex 1 will always be 
located on the same horizontal level as the centre of the figure, and
to the right of the centre. The numbering continues consecutively
anti-clockwise around the circumference. I should have added a feature
to allow for an initial rotation instead of insisting that the first 
vertex be at 0 degrees. This numbering is internal and should not be confused
with labels that might one day appear on vertices when the page is printed.

.NH 1
Labelling the Entire Picture

.PP
This is most comfortably accomplished by giving the label after the .CPE.

.NH 1
Comments etc.

.PP
Comments are allowed - a comment line is one that starts with a #. 
Blank lines are also ignored. The entire cpic specification will be
output (commented out) within the produced pic.


.NH 1
Invocation

.PP
Cpic can be run as a filter or may take file name arguments (but not
both simultaneously). Output may be sent to a file or (by default) to stdout.
Use -o <filename> to write output to a file. This will not overwrite an
existing file though, for that use -O <filename>.
The input specification will be given (commented) in the output pic.
.br
The following are valid.  

.br
.I
cpic fred.in > fred.out
.br
cpic -o fred.out fred.in 
.br
cat fred.in | cpic > fred.out
.br
cat fred.in | cpic | pic | tbl etc etc etc...
.br
.R

.NH 1
Notes

.PP
All measurements should be given in inches and as floating point
numbers, there is no need to specify the trailing "i" for inches \- the
world will probably end if you do.  The generated pic could be tidied
considerably, and I should add the ability to label vertices and an
option to give an initial rotation for each figure.  Let me know if you
want any of this done.

.NH 1
Example

.PP
You get the idea. Here is an example.

.CPS 0.3
# use figure radius of 0.3 inches.

# six figures in this diagram (six things on this line).
6 

# the first has 4 vertices.
4 "A:"
1 2 3
2 3 2
3 4

# one with 16 vertices...
16 "B:"
2 3 2
4 7 1
8 11 3
5 9
1 7
4 12
13 14

# the third.
5 "C:"
1 3
3 5
5 2
2 4
4 1

# the fourth.
2 "D:"
1 2 3

# the fifth.
8 "E:"
1 2 2
2 3
5 2 3
6 1 1
2 4 2
3 4 
4 5 2
5 6 2
6 7
7 8

# the sixth.
6 "F:"
1 2 1
4 5 2
5 6 3
.CPE

.ce
Fig 3: Six pretty little figures are shown above.



The vortex...

.CPS
1
16 "$ sigma pi 2x sub i$" 1.0
# tell cpic how long the label is as it doesn't understand eqn.

1 8
8 15
15 6
6 13
13 4
4 11
11 2
2 9
9 16
16 7
7 14
14 5
5 12
12 3
3 10
10 1
.CPE
.ce 
Fig 900: The vortex.

.PP
Here are some that are not in the default size.
.CPS 0.5 .05
3

3 "Three pictures:"
2 3 2
2 1 2

3
1 2 2
1 3 2

3
3 1 2
3 2 2
.CPE
.ce
Three lovely little babies.

.br
Goodbye
