path: root/graphics/transfig-shapepatch/shapepatch.README

ShapePatch README
==================

This file describes how to install and use the shapepar output driver for the
XWindow drawing program XFig. The current version is 3.2.4-shape-1.1. Don't use
3.2.4-shape-1, it has two bad bugs. The naming scheme is first the XFig/Transfig
version, appended shape, then the version of the patch. 

What is ShapePatch ?
====================

ShapePatch is a patch against Transfig, which adds the capability to export
XFig figures to shape definitions for shapepar. Shapepar itself is a TeX-Macro
by Donald Arsenau that allows to form a paragraph into a given shape, where the
size of the shape is automatically adjusted so that the given paragraph
completely fills the shape. There are some predefined shapes, like e.g. a heart.
So you can form any paragraph into the form of a heart by putting
\heartpar{sometext...}
inside your document. It is of course possible, to define such shapes by
oneself, but it involves that you resolve your shape into a polygon and enter
the coordinates into your TeX-Document. This is quite crucial, and this is the
point where ShapePatch comes up: It allows you to simply draw the shape you want
with XFig, and then convert it to such a shape definition either by calling
fig2dev manually, or by choosing "Export/Shape" in XFig (if you install the
additional XFig patch). 

How to install
==============

ShapePatch is distributed as a patch against transfig and xfig. So first get the
source code of transfig and xfig, and untar them. Then copy the transfig patch
into the transfig source directory, and the xfig patch respectively into the
xfig source tree. Then type

cd transfig.3.2.4
patch -p1 <transfig.3.2.4-shape-1.patch


and respectively

cd xfig.3.2.4
patch -p1 <xfig.3.2.4-shape-1.patch

Do this before you make any changes to the Imakefiles! The patches should apply
cleanly, you can then proceed as usual to compile and install XFig and transfig
(please refer to the appropriate documentation). Perhaps you have to install
additional libraries and/or change the Imakefiles in order to compile.
ShapePatch itself doesn't require any additional libraries. So before reporting
compile errors, please make sure that the clean unpatched versions of transfig
and XFig compile and work.


How to use ShapePatch
=====================

Basic shape drawing
-------------------

If you want to have a simple shape, like e.g. a circle, then construct it as
follows:

* Draw the shape (you can use rectangles, circles/ellipses, arcs, splines,
  polygons) 
* Click the "Edit" button
* Click onto the object
* In the upcoming edit panel write '+' into the comment line (without the '',
  just the plus sign)
* Save your file

Then you call fig2dev like the following:
fig2dev -L shape foo.fig foo.shape
This tells fig2dev to output the shape definition into the file "foo.shape".
Alternatively, if you have installed the xfig-shapepatch, you can just choose
"File/Export" from the XFig menu, choose "SHAPE" as the "Language" and export to
"foo.shape". Very easy, isn't it? 

Then your LaTeX file could look like the following:
\documentclass{article}
\usepackage[noheadfoot, a4paper]{geometry}
\usepackage{shapepar}
\input{foo.shape}
\begin{document}
\newshapepar{some long text that will be shaped into your foo-shape}
\end{document}

If you run this through LaTeX, you should get the proper formatting.

Complex shapes
--------------

ShapePatch uses a so called combine/subtract feature to construct more complex
shapes. For example, a shape can have holes (like the predefined \nutshape from
the shapepar package). Shapes can be combined to "melt together" forming new
shapes, and others can be cut out from this. For example, consider a cross like
this one:
   **
   **
********
********
   **
   **

You can construct it by putting two tall rectangles over each other, the one
vertically, the second horizontally, each having the comment '+'. The two
rectangles will combine to form the cross above.

If you want to construct holes, you can do this by cutting out a shape from
another, which is achieved by the comment '-'. For example, if you want to
construct the nutshape from the shapepar package, you will put a hexagon with
the comment '+' and a circle into its center with the comment '-'. 

You may have realized that the order in which the different objects are composed
is important, especially if there are holes. If you consider the nutshape
example above, if the circular hole is drawn before the hexagon, it would be
totally useless: The "hole" is cut out from nothing, and then overpainted by
the hexagon, which finally gives simply a filled hexagon. You can determine the
order of composing by setting different depths of the objects in XFig. (Use
either the edit panel or the depth button when constructing an object.) So if
you want to make sure, that the hexagon is painted first, and then the hole is
cut out, give the hexagon e.g. the depth 50 and to the hole the depth 40. You
can control this by setting the fill color of the "positive" objects to black
and to white for "negative" objects. You should then see the final shape in
XFig.  However, there is absolutely *NO WARRANTY* that this is the same, if you
have overlapping objects with the same depths. So te be sure you get what you
want, give all objects that overlap a different depth value.

Additional parameters
---------------------

You can set some additional parameters that influence the output.

  Macro name

 First, there is the macro name of the shape. If none is given, the standard
macro name is "newshapeshape" for the shape definition (i.e. the weird numbers
you should not have to care about) and "newshapepar" for the macro that calls
shapepar with the shape definition. You can change this name either by the
commandline switch -n:

fig2dev -L shape -n foo foo.fig foo.shape

gives you "fooshape" and "foopar" respectively, or by setting the comment for
the whole figure (click middle mouse button in edit mode over the drawing area).
The commandline switch overrides the figure comment.

  Centering position

The final shape will be horizontally centered on the page. Normally, the driver
should compute this quite right (it takes the center of the left+right outermost
parts of the shape), but you may want to choose this by hand. So draw a vertical
line where you want the center to be finally, and give it the comment "center".
It must be exactly this, no whitespace, no uppercase letters, no '+' or '-'
sign. This line won't appear in the shape, but tells the position that would be
in the middle of the page.

  Dimension

Because the size is adjusted automatically, you normally don't need to care
about it. But the new shapepar (>=2.0) supports a feature to use a fixed size.
The paragraph will only partly fill the shape. You can specify the dimension
used by ShapePatch by drawing a ruler line, that will become exactly the length
10 in the final output. For example, if you draw a vertical line and give it
the comment "height", then the height of this line will correspond to the
length of 10 units. Analogously, specify "width" if you want the width of a
horizontal line to become 10 units wide. You also use a rectangle for this
choice of the dimension. These lines will not show up in the final paragraph,
they are just for construction

  Construction objects

Objects that have no comment are ignored by ShapePatch. Thus if you need some
object helping you to construct the drawing (e.g. aligning objects on a circle),
you can freely draw any object you want, as long as you don't set a comment.
Objects with comments that do not comply to the requirements (starting with '+',
'-' or one of the reserved words 'width', 'height', 'center') are rejected. It
is possible to add comments, that are "real" comments, i.e. ignored by the
driver. To do this, add your comment separated with at least one blank, newline
or other non-alphanumeric character like # *after* the shape specification. So
if you have an object in the shapegroup "moon" that has the comment "full moon",
the whole string you enter looks like
+moon full moon
Only the first word "moon" counts for shapegroup. You could alse have used
+moon#full moon
or
+moon{full moon

so this is considered to be bad style, better use a blank. If your object you
want to comment is no shape, so simply start the comment with a blank character.

If you want to comment the whole drawing, then use a newline to separate the
macroname from the comment. The first line of the drawing name is taken without
further examining if it would be a valid LaTeX macro name. You would get a LaTeX
error, however. You can use the commandline switch "-n" to override the name
givan as the drawing comment. 

Independent segments
--------------------

This feature is available only in shapepar version >=2.0 
There can be separate segments of text, coupled only by the scaling factor, the
text starts in one of the shapes, after filling it jumps to the second and so
on. As an example, consider to squares situated besides each other:

***  ***
***  ***
***  ***

If you convert this figure with ShapePatch, giving both squares the comment '+',
the text will start in the left box, jump over the gap, continue in the right
box. The next line starts again in the left, and so on. If your text would be
something like "a b c d ..." you would get:

abc  def
ghi  jkl
mno  pqr

This works also with shapepar <2.0. But say, you want to have two columns, like
e.g. in a newspaper:

abc  jkl
def  mno
ghi  pqr

which is much more readible, if the gap is big. how to tell it to ShapePatch?
The solution is to use identifiers. This works only with shapepar >=2.0: If you
give the left square the comment "+1" and the right one "+2", you will get the
above result. Lets say you want the right column to be filled first:

jkl  abc
mno  def
pqr  ghi

Just give "+1" to the right box and "+2" to the left. These "1" and "2" are so
called identifiers, that say in which group of shapes this object is to put in.
It can be any alphanumeric value, and the order is determined by the
alphanumeric sort order. So we could have used "+a" and "+b" instead. Be aware,
that because of the alphanumeric sort "A" comes before "a" and "z", and numbers
may be sorted  weirdly:
1, 10, 11, 2, 3, 4, 5, 6, 7, 8, 9 ... 

 Of course, if one of the shape is composed by severaly objects, all objects
must have the corresponding identifier. For an example, look to the chessboard
or the canadian flag.

Example files
=============

With ShapePatch there should come some example XFig drawings together wth their
translation, so you can check if the program works. There are:

moon.fig:	A moon
face.fig:	A face like a smiley
music.fig:	A line of sheet music with one notehead
canada.fig:	The canadian flag - requires shapepar>=2.0
chessboard.fig:	A chessboard -  requires shapepar>=2.0


Author
======

Written by Christian Gollwitzer <auriocus@btcips73x1.cip.uni-bayreuth.de>.
License is X/MIT (cf. to source code)