2008 PROCEEDINGS FAQ: GRAPHICS AND BUILDS

Q: What is all this about graphics and source?
A: We need to be able to edit figures.  Sometimes submissions contain
   typos, use fonts that the printer doesn't have (without embedding
   them), or we need to modify color usage due to printing
   constraints. 

   Sending just an EPS or PDF is like giving somebody the binary of
   your program and expecting them to use a hex editor to make any
   required modifications.  PLEASE SEND THE SOURCE.

Q: I still don't understand... I just put the stuff through gnuplot,
   isn't EPS what you want?  (Or some tool other than gnuplot...)
A: No.  For gnuplot, you should submit the file containing the
   commands that create the plot, along with the data files which are
   to be plotted.  For other tools, the file will vary; just keep
   reading... 

Q: But TeX can't use my .plot file...  (Or .svg, .dot, or other file.)
A: True.  That's what Makefile.inc is for.

Q: Huh?
A: Look at the EXAMPLE/Makefile.inc for some inspirations.  The
   Proceedings use a very wide variety of tricks to build correctly,
   and makefile rules are the key to those tricks.

Q: Got some examples?
A: Glad you asked... by the way, after this example, there are more
   questions to be answered...

Here's an example Makefile.inc that uses most every trick to date...

# First, add your dvi file to the list of targets; and modify CLEAN.
# This is for the benefit of the top-level 'make' command.  As you
# might expect, CLEAN defines which files are generated by the build,
# and which can safely be deleted.  We'll define MINEGEN later on.
PAPERS += mine/mine.dvi 
CLEAN  += mine/mine.out $(MINEGEN)

## Please note that all leading whitespace in this section is actually
## the TAB character.  If you use spaces, make will complain.  Just
## replace the spaces with a tab, and things will work again.

# Some gnuplot command and data files
MINEPLOT := $(wildcard mine/mine-*.plot)
MINEDAT  := $(wildcard mine/*.dat)

# Graphviz sources
MINEDOT  := $(wildcard mine/mine-*.dot)
MINENEAT  := $(wildcard mine/mine-*.neato)

# Fig, dia, and inkscape source
MINEFIG  := $(wildcard mine/mine-*.fig)
MINEDIA  := $(wildcard mine/mine-*.dia)
MINESVG  := $(wildcard mine/mine-*.svg)

# Some fancy TeX diagrams to generate separately and include as
# graphics. 
MINETEXFIGS := $(wildcard mine/mine-fig-*.tex)

# We really need the EPS and PDF of all that, right?  Here's how.
# For kickers, assume that one .plot file generates multiple figures. 
MINEEPS := $(MINEPLOT:.plot=.eps) $(MINEDOT:.dot=.eps) \
	$(MINEFIG:.fig=.eps) $(MINEDIA:.dia=.eps) \
	$(MINESVG:.svg=.eps) $(MINETEXFIGS:.tex=.eps) \
	mine/mine-extra-plot.eps

# Now PDF, which might vary from EPS.  If it didn't vary, we could
# just write MINEPDF := $(MINEEPS:.eps=.pdf)
MINEPDF := $(MINEPLOT:.plot=.pdf) $(MINEDOT:.dot=.pdf) \
	$(MINEFIG:.fig=.pdf) $(MINEDIA:.dia=.pdf) \
	$(MINESVG:.svg=.pdf) $(MINETEXFIGS:.tex=.pdf) \
	mine/mine-extra-plot.pdf

# That's a lot of generated files.  Here's a variable to hold them.
# This is stuff that is required to build, but which can safely be
# deleted and re-generated on demand.
MINEGEN := $(MINEEPS) $(MINEPDF)

# It's also a lot of various sources to consider.  Let's put those in
# a variable, too.
MINESOURCES := $(MINEPLOT) $(MINEDAT) $(MINEDOT) $(MINENEAT) \
	$(MINEFIG) $(MINEDIA) $(MINESVG) $(MINETEXFIGS)

# Then we need to tell make what it needs to have to do the build...
mine/mine.dvi mine/mine-proc.dvi: \
	mine/mine.tex mine/mine-abstract.tex \
	$(MINESOURCES) $(MINEGEN)

# Then we need to tell make how to get EPS/PDF out of the figures...
# The directions for how to make mine/mine.tex into ps/pdf are
# contained elsewhere in the infrastructure, so we needn't worry about
# that part.

## gnuplot
mine/mine-%.eps: mine/mine-%.plot
	gnuplot $<

# graphviz dot files
mine/mine-%.eps: mine/mine-%.dot
	dot $< -o $@ -T ps
	ps2epsi $@ tmp.epsi
	rm -f $@
	mv tmp.epsi $@

mine/mine-%.pdf: mine/mine-%.dot
	dot $< -o $@ -T pdf

# graphviz neato files
mine/mine-%.eps: mine/mine-%.neato
	neato $< -o $@ -T ps
	ps2epsi $@ tmp.epsi
	rm -f $@
	mv tmp.epsi $@

mine/mine-%.pdf: mine/mine-%.neato
	neato $< -o $@ -T pdf

# Generic EPS-to-PDF, useful for gnuplot/dia/etc.
mine/mine-%.pdf: mine/mine-%.eps
	epstopdf $<

# Inkscape to PDF - the crop is not always necessary.
mine/mine-%.pdf: mine/mine-%.svg
	inkscape -z -B -f $^ -A $@.tmp
	pdfcrop --clip $@.tmp $@
	rm -f $@.tmp

# Inkscape to EPS
mine/mine-%.eps: mine/mine-%.svg
	inkscape -z -F -B -f $^ -E $@

# dia files - only eps is supported; the generic rule will handle
# conversion to PDF.
mine/mine-%.eps: mine/mine-%.dia
	dia --export=$@ -t eps-builtin $^

# fig files - both eps and pdf are supported
mine/mine-%.eps: mine/mine-%.fig
        fig2dev -L eps $< >$@

mine/mine-%.pdf: mine/mine-%.fig
        fig2dev -L pdf $< >$@

## Fancy TeX figures... we provide a script to do such builds.
## Note that the .tex files must be standalone LaTeX documents.
mine/mine-fig-%.eps: mine/mine-fig-%.tex
	Texmf/latex2figure $<

################################

Q: But I didn't use Inkscape, Dia, GnuPlot, Graphviz, or Fig.  Where
   does that leave me?
A: In the throes of doing things in a somewhat more painful manual
   fashion.  Depends on what you used...

Q: OpenOffice?
A: Manually generate PDF files.  Use pdfcrop to get a reasonable
   BoundingBox, then use pdftops to get EPS.  Perhaps a future
   revision of OpenOffice will be able to do this from the command
   line.  If anyone has tips, please send them in.

Q: A Screenshot or Photograph?
A: Save your screenshot as a PNG.  pdflatex should understand PNG and
   JPG formats.  You'll need to use ImageMagick's "convert" utility to
   generate EPS for latex, however.  This can be done as a
   Makefile.inc rule along the lines of the rules listed above.

Q: Some proprietary stuff?
A: Shame on you, this conference is about open source.  Try saving it
   in a compatible format.  For instance:
    - Illustrator can do .svg, but may not do it correctly.
    - Many MSOffice documents can be opened by OpenOffice and saved in
      that format.
    - Other open-source tools exist, try them.

Q: I can't convert my figure that was created with proprietaryware.
A: Re-generate it with open-source tools.  If time constraints prevent
   that, you can consider saving as EPS/PDF, and sending an
   explanation to ols-sponsors so that we don't come after you to ask
   for the source.  If your proprietaryware doesn't do these formats,
   try printing to a postscript printer on FILE: (an early Apple
   Laserwriter is fairly generic postscript), and converting the
   subsequent output.

Q: Some bitmap I scraped off the web?
A: Try using Inkscape to generate a structured-graphics version of it.
   As emphasized in the README, bitmaps are only acceptable for
   screenshots and photographs because their quality is exceedingly
   low.  Pixellization went out with the 1980's, really... :)

Q: What are some tools I shouldn't be using?
A: Bitmap tools are inappropriate for anything but screenshots or photographs.
   Bitmap tools include Tgif, bmeps, the GIMP, ImageMagick, Photoshop,
   and many, many others.  Proprietary tools that save in formats that
   do not work well with free tools are also to be avoided.  This
   includes many Microsoft products, and possibly also some Adobe
   ones such as Illustrator (folks report troubles with generated
   .svg files, but I haven't heard which versions, or if there's
   a way to force it to work).

Q: Do you recommend anything?
A: Not usually, because different tools work in different ways for
   different tasks and different people.  Personally, I like
   Dia for simple figures, Inkscape for fancy ones, and gnuplot
   to plot data and create different charts.  I don't plot data
   too often, so I get a lot of mileage out of gnuplot's extensive
   help and documentation.  Every now and then I try OpenOffice,
   which has been improving over the years.

Q: Do I need to do something else?
A: Test the converted output -- build the paper, view it under regular
   magnification and under extreme magnification.  Does it show what
   you need it to, and look sharp?  If so, you're done.  If not, you
   have more work to do -- which will vary depending on what's wrong.
   You should be able to do "make DIRS=mine" and "make DIRS=mine clean"
   and have both work correctly -- otherwise you break the entire
   proceedings (in the first case), or can potentially create a lot
   of bloat in the SVN pool, or even pick up obsolete materials
   by accident (in the second case).

Q: I can't make it work.
A: Send mail to ols-sponsors and we'll try to help, or to find someone
   who can.  We don't have a lot of spare time, or a lot of formatting
   volunteers this year.  A dozen or so volunteers could handle the
   papers comfortably -- the team consists of far fewer, alas.

=========================================