Making schematics look good with "gaf export"

<CareBear\> peterbrett : hey. gaf export is f-ing awesome!

People who've been testing the gEDA "master" branch over the last few hours will have got a sneak preview of a cool new tool that will be arriving in gEDA/gaf 1.9.0. The new gaf export command-line utility lets you quickly and easily export your schematics and symbols to a variety of image formats.

I've been wanting to introduce a tool like this for a while, but it's only become possible thanks to finally finishing a couple of big features that have been cooking in my personal branches for a couple of years: a new Cairo-based rendering library for gEDA designed to be used for both rendering in gschem and for printing/exporting graphics, called "libgedacairo"; and a new gEDA configuration subsystem, which I'll write about in more detail another time.

To get started, suppose I want to create a PDF from a schematic called grey_counter_1.sch. It's very straightforward!

gaf export -o grey_counter_1.pdf grey_counter_1.sch

From the output filename that I passed to the "-o" option, gaf export will detect that I want a PDF. It'll detect the size of the drawing, centre it in the default paper (choosing some suitable margins) and generate a PDF file.

Batch generation of PostScript files

Many people previously used gschem along with the (relatively obscure) print.scm script for batch generation of PostScript files. Usually the command looked something like:

gschem -o grey_counter_1.ps -s /usr/share/gEDA/scheme/print.scm grey_counter_1.sch

Don't do this any more. It is slow (because it needs to load all of gschem's configuration), requires an graphical desktop to be running (because gschem can't start without trying to display its windows) and doesn't provide any way to directly customise formatting options without fiddling with Scheme scripts. Also, gaf export generates much nicer PDF output than PS, especially if you want to do anything with the output file other than printing. You could directly replaced the gschem command above with something like:

gaf export -o grey_counter_1.pdf grey_counter_1.sch

A Makefile rule for creating PDF files from schematic files might look like:

%.pdf: %.sch
	gaf export -o $@ -- $<

Of course, one advantage of the new tool is that it can do multi-page output. So rather than generating a whole bunch of separate PDF or PostScript files and stitching them together, you could directly generate a single PDF file with the whole of your design in it:

gaf export -o schematics.pdf grey_counter_1.sch filter_1.sch

Tweaking the output

gaf export also lets you tweak the output for different applications. Suppose I want to produce the PNG file displayed in this blog post. First, I don't care about paper sizes; I want the output file to be sized according to how large the drawing is. To do this, I can use -s auto. I can also set the margin on the output with -m 5px. I also want to print in colour (-c). So the overall command is:

gaf export -c -s auto -m 5px -o gaf_export__40160-1.png 40160-1.sym

It can also be useful to set the paper size (for example, to get suitable margins for larger paper sizes). By default, gaf export uses whatever GTK thinks the default paper size is on your system. For most people, this will be ISO A4. In addition to providing measurements directly via the -s option, the -p option lets you specify a PWG 5101.1-2002 paper name. For example, to use US "D" size paper:

gaf export -p na_d -o grey_counter_1.pdf grey_counter_1.sch

Changing default settings

The default settings for gaf export can be modified using the new gaf config command. For example, to set the default paper size for all your projects to US "Letter":

gaf config --user export paper na_letter

Or to make sure that all printing for a particular project is in colour:

gaf config -p /path/to/project/directory/ export monochrome false

Conclusion

gaf export is a fast, easy-to-use way of generating graphics files from your gEDA/gaf schematics and symbols. Along with several other new features, it will be available in the upcoming unstable gEDA/gaf 1.9.0 release.