//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))"