Directory graphics/transfig-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)