summaryrefslogtreecommitdiff
path: root/graphics/transfig-shapepatch
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /graphics/transfig-shapepatch
Initial commit
Diffstat (limited to 'graphics/transfig-shapepatch')
l---------graphics/transfig-shapepatch/README1
-rw-r--r--graphics/transfig-shapepatch/shapepatch.README265
2 files changed, 266 insertions, 0 deletions
diff --git a/graphics/transfig-shapepatch/README b/graphics/transfig-shapepatch/README
new file mode 120000
index 0000000000..21a6520dc8
--- /dev/null
+++ b/graphics/transfig-shapepatch/README
@@ -0,0 +1 @@
+shapepatch.README \ No newline at end of file
diff --git a/graphics/transfig-shapepatch/shapepatch.README b/graphics/transfig-shapepatch/shapepatch.README
new file mode 100644
index 0000000000..26e2215e80
--- /dev/null
+++ b/graphics/transfig-shapepatch/shapepatch.README
@@ -0,0 +1,265 @@
+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)
+
+
+