//Translations:// [[gaf_utility.ru|Русский]]

====== gaf - gEDA/gaf Command-Line Utility ======

**gaf** provides a number of small command-line utilities for
working with schematic and symbol files, and is designed to be
used for batch processing of designs created using the schematic
editor [[gEDA:gschem_ug|gschem]]. It currently has three built-in
commands:
  * [[#gaf export]] is used to create SVG, PDF, PNG, PS and EPS files from schematic and symbol files, for printing or embedding in other documents.
  * [[#gaf config]] allows reading and writing settings in gEDA project, user and system configuration stores.
  * [[#gaf shell ]] provides a Scheme REPL for command-line batch processing of schematic data.

See the //gaf(1)// manual page for more information on the utility
options.

===== gaf export =====
The detailed description of the **gaf export** command can be
found in the //gaf(1)// manual page.

===== gaf config =====
This section describes how to set up **gschem** and **gnetlist**
using the **gaf config** command.

See the //gaf(1)// manual page for more information on the utility
options.

==== Configuration files ====
Configuration settings used to configure these programs are
written to gEDA config files.
These files are:
  * //''geda-system.conf''// for system-wide settings. The system-wide config file is sequentially searched in three places:
    * in //''${XDG_CONFIG_DIRS}/gEDA''//, see the [[http://standards.freedesktop.org/basedir-spec/latest/|XDG Base Directory Specification]] for more information on that environment variable,
    * if no system configuration was found there, in the traditional location of gEDA rc-files, i.e. in the //''${PREFIX}/share/gEDA''// directory, where ''${PREFIX}'' is a compiled default, usually //''/usr''// or //''/usr/local''// (but Debian based distributions use the //''/etc/gEDA''// directory instead),
    * and finally, if no configuration file was found yet, in an XDG default directory or, if it is not defined, in the //''/etc/xdg/gEDA''// directory.
  * //''$HOME/.gEDA/geda-user.conf''// for user settings.
  * //''path/to/a/project/geda.conf''// for your local project settings.


Note that you can edit these files manually using your favorite
text editor.

The config file format is described in this
[[http://standards.freedesktop.org/desktop-entry-spec/1.0/|freedesktop.org
standard]].

All the config files consist of sections, called groups,
containing key-value pairs.

Key values in the gEDA config files may be single numbers or
lists.  Note that unlike the [[#gaf export]] command, where
several list separators can be used, the only separator between
list values in the config files is semicolon ';'. Another difference
is that,  when using the **gaf config** command, you always have
to specify all parameters of the used list. Thus, for example, the
next command will not work properly:
  gaf config --project export size 1000
The right command will look like this:
  gaf config --project export size "1000;1000"

All sizes should be given in Adobe points (72 points = 1 inch).
Suffixes such as "pt", "mm" and others, which can be used with the
[[#gaf export]] command, do not work in the config files.

Next sections describe all existing groups.

==== export group ====
//**Table 1.**// **export** group parameters
^  Key        ^ Format                                                                ^  Default               ^
| align       | string "auto" or list of two integers in the form ''HALIGN;VALIGN''   |  auto                  |
| dpi         | integer                                                               |  96                    |
| font        | string                                                                |  Arial                 |
| layout      | predefined string: "portrait", "landscape", or "auto"                 |  auto                  |
| margins     | list of four integers in the form ''TOP;LEFT;BOTTOM;RIGHT''           |  18;18;18;18           |
| monochrome  | boolean                                                               |  true                  |
| paper       | predefined paper size string                                          |  //locale dependent//  |
| size        | string "auto" or list of two integers in the form ''HEIGHT;WIDTH''    |  auto                  |

=== align ===
Set how the drawing is aligned within the page. ''HALIGN''
controls the horizontal alignment, and ''VALIGN'' the vertical.
Each alignment value should be in the range 0.0 to 1.0. The "auto"
alignment is equivalent to a value of ''0.5:0.5'', i.e. centered.

For [[#gaf export]] command, you can use your locale's separator if
you use it without quotes. In such a case your shell will interpret
the numbers for you. You cannot do this for **gaf config**
since the align key is a string. You must use a dot as the separator
for floating point numbers when you write that string in a config
file. See [[#examples]] below.

=== dpi ===
Set the number of pixels per inch used when generating PNG output.

=== font ===
Set the font to be used for drawing text.

See the section [[#Fonts]] below for more information on fonts
selection.

=== layout ===
When using a paper size, set the orientation of the output.  If
"auto" layout is used, the orientation that best fits the
drawing will be used.

=== margins ===
Set the widths of the margins to be used.

Margins can actually be wider than the values set in a config
file since these values only specify the minimal distances from
the sheet edges, and the sizes of the chosen paper may not meet
the sizes of the printed schematic with the margins. If not
specified, default margin size is 18pt for all margins.

Note: setting less than four numbers for the margin key or using
of any unit suffixes will not work.

=== monochrome ===
Toggle monochrome or color output.

=== paper ===
Size the output for a particular paper size.

Legal paper sizes are described in the
[[ftp://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn10-20020226-5101.1.pdf
| PWG 5101.1-2002 Standard]] (''iso_a4'', ''iso_a3'',
''na_letter'', ''na_legal'', etc).
The default paper size depends on the current locale. For instance,
it is ''A4'' when ''ru_RU.UTF-8'' is used whereas it is ''letter''
for the ''en_US.UTF-8'' locale.

=== size ===
Size the output with specific dimensions.  If the size is
"auto", select the size that best fits the drawing.

The paper size set by the ''size'' key overrides that one set by the
''paper'' key. Note: setting only one number for the ''size'' key
or using of any unit suffixes will not work.


==== gnetlist group ====
//**Table 2.**// **gnetlist** group parameters
^  Key                 ^  Format                                                   ^  Default              ^
| default-bus-name     | string                                                    |  unnamed_bus          |
| default-net-name     | string                                                    |  unnamed_net          |
| net-naming-priority  | predefined string: "net-attribute" or "netname-attribute" |  net-attribute        |
| traverse-hierarchy   | boolean                                                   |  true                 |

=== default-bus-name ===
Define the default bus name for the buses unnamed in the
schematic.

Buses are still not used by any gnetlist backend, so this
parameter is not useful yet.

=== default-net-name ===
Define the default net name for the nets unnamed in the
schematic.

It is used to create netnames of the form "unnamed_netN"
where ''N'' is a number.

=== net-naming-priority ===
Specify which attribute, ''net'' or ''netname'', has priority if a
net is found with two names.  Any netname conflict will be
resolved using the chosen attribute.

This option is used when both ''net'' and ''netname''
attributes are defined for some nets in your schematic and you want
to specify which one should define the net names that gnetlist will
use for netlisting. See the [[na_howto|net= attribute mini-HOWTO]]
and [[master_attributes_list|Master attributes list]] for more
information on these attributes.

=== traverse-hierarchy ===
Decides if the hierarchy is traversed or not.  If this is disabled
then **gnetlist** will not go down searching for any underlying
sources.

==== gschem group ====
//**Table 3.**// **gschem** group parameters
^  Key              ^  Format  ^  Default   ^
| default-filename  | string   |  untitled  |

=== default-filename ===
Define the default file name for any new schematic files created
in **gschem**.

It is used to create filenames of the form "untitled_N.sch"
where ''N'' is a number.


==== gschem.library group ====
//**Table 4.**// **gschem.library** group parameters
^  Key                    ^  Format                                                   ^  Default              ^
| component-attributes    | comma separated list of attribute names                   |  *                    |
| sort                    | boolean                                                   |  false                |

=== component-attributes ===
Holds a list of attribute names that are displayed in the
component select dialog.

Symbol attributes in the dialog are sorted in the same order as they appear in the
list.  If the first list element is an asterisk "*", all
attributes will be displayed in the alphabetical order.  An empty list
will disable the attribute view in the dialog.

=== sort ===
Sort the component library.

If the value of this attribute is true, the component libraries
are sorted alphabetically. Otherwise they are sorted in the order
opposite to what they were added in.


==== gschem.printing group ====
//**Table 5.**// **gschem.printing** group parameters
^  Key        ^  Format                                                   ^  Default               ^
| layout      | predefined string: "portrait", "landscape", or "auto"     |  auto                  |
| monochrome  | boolean                                                   |  false                 |
| paper       | predefined paper size string                              |  //locale dependent//  |

=== layout ===
When using a paper size, set the orientation of the output.  If
"auto" layout is used, the orientation that best fits the
drawing will be used.

**gschem** page orientation is intended to output pages to a
printer rather than to PDF, so the value "auto" means that if
you output pages to PDF you will get rotated landscape instead of
ordinary. To get readable PDF with pages in landscape use instead
the [[#gaf export]] command, and set to "auto" the ''layout'' key
in the [[#export group]].

Note: as of now, printing using the script //''print.scm''// doesn't
use the ''layout'' key setting.

=== paper ===
Size the output for a particular paper size.

The default ''paper'' value depends on the current locale.
See the notes on the paper size above in the description of the
''paper'' key for the [[#export group]].

=== monochrome ===
Toggle monochrome or color output.

It is intended that unlike the ''monochrome'' value in the
[[#export group]], the key value in this group is ''false''.


==== gschem.dialog-geometry.* groups ====
These groups include:
  * gschem.dialog-geometry.arc-angle
  * gschem.dialog-geometry.autonumber
  * gschem.dialog-geometry.color-edit
  * gschem.dialog-geometry.compselect
  * gschem.dialog-geometry.coord
  * gschem.dialog-geometry.fill-type
  * gschem.dialog-geometry.find-text
  * gschem.dialog-geometry.hide-text
  * gschem.dialog-geometry.hotkeys
  * gschem.dialog-geometry.line-type
  * gschem.dialog-geometry.log
  * gschem.dialog-geometry.multiattrib
  * gschem.dialog-geometry.pin-type-edit
  * gschem.dialog-geometry.show-text
  * gschem.dialog-geometry.singleattrib
  * gschem.dialog-geometry.slot-edit
  * gschem.dialog-geometry.snap-size
  * gschem.dialog-geometry.text-edit
  * gschem.dialog-geometry.text-entry
  * gschem.dialog-geometry.text-size
  * gschem.dialog-geometry.translate

There are two special groups having additional settings:
  * gschem.dialog-geometry.compselect
  * gschem.dialog-geometry.multiattrib

//**Table 5.**// ** gschem.dialog-geometry.* ** groups parameters
^  All dialogs                                                                                              ^^^
^  Key                    ^  Format                                                   ^  Default              ^
| x                       | integer                                                   |  -                    |
| y                       | integer                                                   |  -                    |
| width                   | integer                                                   |  -                    |
| height                  | integer                                                   |  -                    |
^  gschem.dialog-geometry.compselect                                                                        ^^^
^  Key                    ^  Format                                                   ^  Default              ^
| hpaned                  | integer                                                   |  -                    |
| vpaned                  | integer                                                   |  -                    |
| source-tab              | 0 or 1                                                    |  1                    |
^  gschem.dialog-geometry.multiattrib                                                                       ^^^
^  Key                    ^  Format                                                   ^  Default              ^
| show_inherited          | boolean                                                   |  true                 |

Note: all these values are automatically stored in the user
configuration files. You can change them manually, but the values
will be overwritten next time the dialog in question changes its
size or other value mentioned in the table. If you edit the values
when **gschem** is running they will be silently overwritten after
it closes.

=== x ===
X position of the dialog window.

=== y ===
Y position of the dialog window.

=== width ===
Width of the dialog window.

=== height ===
Height of the dialog window.

=== hpaned ===
Width of the horizontal pane where components are selected in the
component select dialog.

=== vpaned ===
Height of the vertical pane containing component preview in the
component select dialog.

=== source-tab ===
This value determines which tab will be opened when you bring up
the component selection dialog. 0 means that the "In use" tab will
be chosen, 1 means that the "Libraries" tab will be chosen.

=== show_inherited ===
Visibility setting for inherited attributes in the multiattrib
dialog.


===== gaf shell =====
**gaf shell** provides a Scheme Read-Eval-Print Loop (REPL) for
automating processing of schematic and symbol files. It is
designed to be used with the gEDA Scheme API. See the //gaf(1)//
manual page for more information on the utility options, and
**info geda-scheme** on which gEDA Scheme procedures you can use.


===== Fonts =====
On Linux, font configuring is handled by **Fontconfig**, and modern
systems (particularly **pango** and **cairo**) rely on its library in
looking up any font specified. You can provide the **gaf** command
with a pattern containing the font name wanted and, optionally,
with some settings for that font.
Fontconfig performs matching of the pattern against all the
fonts available in your system. The closest matching font is
selected. This ensures that a font will always be returned, but
doesn't ensure that it is anything like the requested pattern.

If you want to find out which fonts are available in your system,
you can use the //fc-list(1)// utility from the fontconfig package. To
check whether fontconfig could find an appropriate font by the
specified pattern (or to see which font will correspond to your
pattern), use the //fc-match(1)// utility.

See the
[[http://freedesktop.org/software/fontconfig/fontconfig-user.html|fontconfig
documentation]] for more information on how to specify the font
name you want to use.

In some circumstances, the font system can even embed more than one
font into your document. This occurs, for instance, if the most
appropriate font chosen by fontconfig doesn't contain some glyphs
for one of the languages used in the document. In this case it will
add some other font that does have the glyphs required.

The next table lists possible settings (acquired from the Pango
documentation) which you can use in your font name patterns. See
also the [[#Examples]] section below.

//**Table 6.**// Possible font settings
^ Setting ^ Value ^
| Style   | Normal\\ Oblique\\ Italic |
| Weight  | Thin\\ Ultralight\\ Light\\ Book\\ Normal\\ Medium\\ Semibold\\ Bold\\ Ultrabold\\ Heavy\\ Ultraheavy |
| Variant |Normal\\ SmallCaps |
| Stretch | UltraCondensed\\ ExtraCondensed\\ Condensed\\ SemiCondensed\\ Normal\\ SemiExpanded\\ Expanded\\ ExtraExpanded\\ UltraExpanded |


===== Examples =====
==== Set up exporting ====
Use the "landscape" layout by default for a local project:
  gaf config --project export layout landscape
Use the "letter" paper size by default for all your printouts:
  gaf config --user export paper na_letter
Set paper size to the definite value of 1x2 inch for a local
project:
  gaf config --project export size "72;144"
Set margins as a half of inch for left and right sides and as a
quarter of inch for top and bottom for a local project:
  gaf config --project export margins "18;36;18;36"
This command will align your project's schematics to the right.
  gaf config --project export align "1.0;0.5"
This command is wrong, it doesn't work for you even if your locale
uses comma as a separator for floating point numbers:
  gaf config --project export align "1,0;0,0"
This command, though, works in this case (e.g., in the ru_RU.UTF-8
locale):
  gaf export -a 0,0:1.0 -o file.pdf file.sch
Note, that I use **''gaf export''** here, not **''gaf config''**.

To print all your schematics in color (note: "False" or "FALSE"
will not work):
  gaf config --project export monochrome false
Set up a custom user font:
  gaf config --user export font "OpenGost Type B TT Italic"
Choose another font for a local project:
  gaf config --project export font "Arial Bold"


==== Set up netlisting ====
Use more short net and bus names in all netlists created by the
user:
  gaf config --user gnetlist default-net-name net
  gaf config --user gnetlist default-bus-name bus
Ensure that a local project will use hierarchical net
names despite of settings in //''geda-user.conf''//:
  gaf config --project gnetlist traverse-hierarchy true
Rename nets connecting to //''gnd-1.sym''// (and other symbols
having the ''net'' attribute) if they have the ''netname''
attribute:
  gaf config --project gnetlist net-naming-priority netname-attribute

==== Set up gschem ====
Use shorter names for new files:
  gaf config --user gschem default-filename empty

==== Set up gschem library view ====
This command explicitly tells that you want to always show
all attributes:
  gaf config --project gschem.library component-attributes "*"
Please be careful when using this command in the command line. If
you forget the quotes, your shell will substitute the first file
name in the working directory file list for the
attribute name. This is most likely not what you want.

Display only attributes that are in the filter list:
  gaf config --project gschem.library component-attributes "refdes;device;description"
Don't show any attributes in the component select dialog:
  gaf config --project gschem.library component-attributes ""
The same as before. However, this command will not work because the
specified string separates values with commas instead semicolons,
so the whole string will be considered one attribute name:
  gaf config --project gschem.library component-attributes "refdes,device,description"
Sort the component library in **gschem** alphabetically:
  gaf config --user gschem.library sort true

==== Set up gschem printing ====
Choose ''landscape'' as the default orientation for a local
project when printing from within **gschem**:
  gaf config --project gschem.printing layout landscape
Use the A5 paper size when printing from within **gschem**:
  gaf config --project gschem.printing paper iso_a5
Always use B&W printing output from within **gschem**:
  gaf config --user gschem.printing monochrome true

==== Set up gschem dialogs ====
Don't show any inherited attributes in the multiattrib dialog:
  gaf config --user gschem.dialog-geometry.multiattrib show_inherited false
Note that you cannot use the ''%%--project%%'' (''-p'') key in the
command above. This command works only in the user context and has
no sense for local projects.

==== Using gaf shell ====
Find out the path to the gEDA user configuration directory,
type:
  gaf shell -c "(display (user-config-dir))"
The same for the system configuration directories:
  gaf shell -c "(display (sys-config-dirs))"
