//На других языках:// [[gaf_utility|English]]

====== gaf - утилита командной строки gEDA/gaf ======

Программа **gaf** предоставляет в распоряжение пользователя несколько маленьких утилит
командной строки для работы с файлами схем и символов. Её назначение ---
пакетная обработка данных проектов, созданных с помощью редактора схем
[[gEDA:gschem_ug.ru|gschem]]. В настоящее время программа поддерживает три
встроенных команды:
  * [[#gaf export]] используется для конвертации файлов схем и символов в форматы SVG, PDF, PNG, PS и EPS с целью распечатки или внедрения в другую документацию.
  * [[#gaf config]] предназначена для чтения текущих и записи новых параметров настройки в файлы настроек проектов, пользовательские и системные файлы настроек gEDA.
  * [[#gaf shell ]] предоставляет интерфейс командной строки с «циклом чтения-вычисления-вывода» Scheme (REPL) для пакетной обработки данных принципиальных схем.

Подробное описание опций утилиты см. в справочной странице //gaf(1)//.

===== gaf export =====
Подробное описание команды **gaf export** можно найти в справочной странице
//gaf(1)//.

===== gaf config =====
В данном разделе приводится описание настройки **gschem** и **gnetlist** с
помощью команды **gaf config**.

Подробное описание опций утилиты см. в справочной странице //gaf(1)//.

==== Файлы настроек ====
Параметры настройки записываются в файлы настроек
gEDA.
Это следующие файлы:
  * //''geda-system.conf''// для системных настроек. Файл системных настроек последовательно ищется в трёх местах:
    * в //''${XDG_CONFIG_DIRS}/gEDA''//, подробности об этой переменной окружения см. в [[http://standards.freedesktop.org/basedir-spec/latest/|XDG Base Directory Specification]];
    * если системных настроек там не найдено, то в традиционном местоположении rc-файлов gEDA, то есть в каталоге //''${PREFIX}/share/gEDA''//, где ''${PREFIX}'' является скомпилированным умолчанием, обычно //''/usr''// или //''/usr/local''// (но в дистрибутивах на основе Debian вместо этого используется каталог //''/etc/gEDA''//),
    * и наконец, если файл настроек так и не был пока найден, в каталоге по умолчанию XDG или, если таковой не определён, в каталоге //''/etc/xdg/gEDA''//.
  * //''$HOME/.gEDA/geda-user.conf''// для пользовательских настроек.
  * //''путь/к/проекту/geda.conf''// для локальных настроек проекта.


Примечание: эти файлы можно также редактировать вручную в текстовом
редакторе.

Формат файла настроек приводится в этом
[[http://standards.freedesktop.org/desktop-entry-spec/1.0/|стандарте
freedesktop.org]].

Все файлы настроек состоят из разделов, называемых группами, содержащих пары
ключ-значение.

Значениями ключей в файлах настроек gEDA могут быть отдельные числа или списки.
Обратите внимание, что в отличие от команды [[#gaf export]], для которой
можно использовать несколько разделителей списка, единственным разделителем между значениями
списка в файлах настроек является точка с запятой ';'. Другое отличие заключается
в том, что при использовании команды **gaf config** всегда необходимо указывать
все параметры используемого списка. Таким образом, например, следующая
команда не будет работать должным образом:
  gaf config --project export size 1000
Правильная команда будет выглядеть так:
  gaf config --project export size "1000;1000"

Все размеры должны задаваться в пунктах Adobe (72 пункта = 1 дюйму).
Суффиксы, такие как "pt", "mm" и другие, которые могут использоваться с
командой [[#gaf export]], в файлах настроек не работают.

В следующих разделах приводятся все существующие группы.

==== Группа export ====
//**Таблица 1.**// Параметры группы **export**
^  Ключ       ^ Формат                                                                ^  По умолчанию          ^
| align       | строка «auto» или список из двух целых вида ''ГОРИЗ_ВЫРАВНИВАНИЕ;ВЕРТ_ВЫРАВНИВАНИЕ''  |  auto  |
| dpi         | целое                                                                 |  96                    |
| font        | строка                                                                |  Arial                 |
| layout      | предопределённая строка: «portrait», «landscape» или «auto»     |  auto                  |
| margins     | список из четырёх целых вида ''TOP;LEFT;BOTTOM;RIGHT''                |  18;18;18;18           |
| monochrome  | логическое значение                                                   |  true                  |
| paper       | строка, определяющая предопределённый формат                 |  //зависит от текущей локали//  |
| size        | строка «auto» или список из двух целых вида ''ВЫСОТА;ШИРИНА''         |  auto                  |

=== align ===
Настройка выравнивания изображения на странице. ''ГОРИЗ_ВЫРАВНИВАНИЕ''
управляет горизонтальным выравниванием, а ''ВЕРТ_ВЫРАВНИВАНИЕ'' ---
вертикальным.  Оба значения должны быть в диапазоне 0.0 --- 1.0. Значение
выравнивания ''auto'' эквивалентно значению ''0.5:0.5'', т. е. изображение
будет центрировано.

Для команды [[#gaf export]] при отсутствии кавычек можно использовать
разделитель своей локали. В этом случае числа будут интерпретироваться вашей
оболочкой. Для **gaf config** так делать нельзя, поскольку значение ключа
''align'' является строкой. При записи в файл настроек чисел с плавающей
запятой в качестве разделителя используется точка, и точка также должна
использоваться для чисел, содержащихся в строках. См. [[#примеры]] ниже.

=== dpi ===
Количество пикселов на дюйм для вывода в формате PNG.

=== font ===
Настройка шрифта для вывода текста.

Подробную информацию о выборе шрифтов см. ниже в разделе [[#Шрифты]].

=== layout ===
Настройка ориентации вывода при задании размера бумаги. При задании «auto»
используется та ориентация, которая лучше соответствует размерам
изображения.

=== margins ===
Установка ширины полей.

Фактические размеры полей могут быть больше значений, записанных в файлах
настроек, так как эти значения определяют только минимальные расстояния от
краёв листа, а размеры выбранной бумаги могут не соответствовать размерам
печатаемой схемы с полями. Если значение не определено, размер полей по
умолчанию составляет 18pt для каждого поля.

Примечание: задание менее четырёх чисел для данного ключа или использование
каких-либо суффиксов для указания единиц измерения работать не будет.

=== monochrome ===
Переключение монохромного/цветного вывода.

=== paper ===
Задание размера вывода в виде конкретного формата листа.

Легальные размеры бумаги описаны в стандарте
[[ftp://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn10-20020226-5101.1.pdf
| PWG 5101.1-2002]] (''iso_a4'', ''iso_a3'',
''na_letter'', ''na_legal'' и т. д.).
Формат бумаги по умолчанию зависит от текущей локали. Например,
это ''A4'', когда используется ''ru_RU.UTF-8'', в то время как
для локали ''en_US.UTF-8'' это ''letter''.

=== size ===
Задание определённых размеров для вывода изображения. При задании «auto»,
выбирается тот размер, при котором изображение размещается наилучшим
образом.

Размер бумаги, заданный ключом ''size'', переопределит размер, заданный
ключом ''paper''. Примечание: задание только одного числа для данного ключа
или использование каких-либо суффиксов для указания единиц измерения
работать не будет.


==== Группа gnetlist ====
//**Таблица 2.**// Параметры группы **gnetlist**
^  Ключ                ^  Формат                                                   ^  По умолчанию         ^
| default-bus-name     | строка                                                    |  unnamed_bus          |
| default-net-name     | строка                                                    |  unnamed_net          |
| net-naming-priority  | предопределённая строка: «net-attribute» или «netname-attribute» |  net-attribute  |
| traverse-hierarchy   | логическое значение                                       |  true                 |

=== default-bus-name ===
Имя шины по умолчанию для именования шин, не имеющих имён в схеме.

Шины пока ещё не используются ни в одном из низкоуровневых драйверов
**gnetlist**, поэтому данный параметр пока бесполезен.

=== default-net-name ===
Имя соединения по умолчанию для именования соединений, не имеющих имён в
схеме.

Оно используется для создания имён соединений вида «unnamed_netN», где ''N''
является числом.

=== net-naming-priority ===
Настройка приоритета одного из атрибутов ''net'' или ''netname'' для
случаев, когда обнаруживаются соединения с двумя именами. Все конфликты имён
соединений будут разрешаться с использованием указанного атрибута.

Этот параметр используется, когда какие-нибудь соединения схемы имеют и
атрибут ''net'', и атрибут ''netname'', и нужно указать, какой из них должен
определять имена соединений, которые **gnetlist** будет использовать для
создания списка соединений. Подробности использования этих атрибутов см. в
[[na_howto.ru|Мини-HOWTO по атрибуту net= ]] и в
[[master_attributes_list.ru|Перечне основных атрибутов]].

=== traverse-hierarchy ===
Настройка разрешения обхода иерархии. При отключении **gnetlist** не будет
спускаться вниз по иерархии для поиска низлежащих источников данных.

==== Группа gschem ====
//**Таблица 3.**// Параметры группы **gschem**
^  Ключ             ^  Формат  ^  По умолчанию ^
| default-filename  | строка   |  untitled     |

=== default-filename ===
Имя файла по умолчанию для новых файлов схем, создаваемых в **gschem**.

Оно используется для создания имён файлов вида «untitled_N.sch», где ''N''
является числом.


==== Группа gschem.library ====
//**Таблица 4.**// Параметры группы **gschem.library**
^  Ключ                   ^  Формат                                                   ^  По умолчанию         ^
| component-attributes    | список имён атрибутов, разделённых запятыми               |  *                    |
| sort                    | логическое значение                                       |  false                |

=== component-attributes ===
Список имён атрибутов, отображаемых в диалоговом окне выбора компонентов.

Атрибуты символов в диалоговом окне сортируются в том же порядке, в каком
они появляются в списке. Если первым элементом списка будет звёздочка "*",
все атрибуты будут отображаться в алфавитном порядке. При задании пустого
списка показ атрибутов в диалоговом окне будет отключен.

=== sort ===
Настройка сортировки библиотеки компонентов.

Если значение этого параметра равно «true», библиотеки компонентов
сортируются в алфавитном порядке. В противном случае они сортируются в
порядке, обратном порядку их добавления.


==== Группа gschem.printing ====
//**Таблица 5.**// Параметры группы **gschem.printing**
^  Ключ       ^  Формат                                                         ^  По умолчанию           ^
| layout      | предопределённая строка: «portrait», «landscape» или «auto»     |  auto                   |
| monochrome  | логическое значение                                             |  false                  |
| paper       | предопределённая строка размера                                 |  //зависит от локали//  |

=== layout ===
Настройка ориентации вывода при задании размера бумаги. При задании «auto»
используется та ориентация, которая лучше соответствует размерам
изображения.

Ориентация страницы в **gschem** рассчитана на вывод страниц на принтер, а не в
PDF, поэтому значение «auto» означает, что если
вы выводите страницы в PDF, вы получите перевёрнутую пейзажную ориентацию вместо
обычной. Для получения пригодного для чтения PDF со страницами в пейзажной ориентации
используйте вместо этого команду [[#gaf export]] и задайте значение «auto» для ключа ''layout''
в группе [[#Группа export|export]].

Примечание: в настоящее время при печати с помощью скрипта //''print.scm''//
настройка ключа ''layout'' не используется.

=== paper ===
Задание размера вывода в виде конкретного формата листа.

Значение по умолчанию ключа ''paper'' зависит от текущей
локали. См. примечания о размере бумаги выше в описании ключа ''paper'' для
группы [[#Группа export|export]].

=== monochrome ===
Переключение монохромного/цветного вывода.

Значение по умолчанию ключа ''monochrome'' в данной группе в отличие от
значения этого ключа в группе [[#Группа export|export]] задано равным
''false'' умышленно.


==== Группы gschem.dialog-geometry.* ====
Сюда входят группы:
  * 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

Есть две особые группы, имеющие дополнительные настройки:
  * gschem.dialog-geometry.compselect
  * gschem.dialog-geometry.multiattrib

//**Таблица 5.**// Параметры группы ** gschem.dialog-geometry.* **
^  Все диалоговые окна                                                                                      ^^^
^  Ключ                   ^  Формат                                                   ^  По умолчанию         ^
| x                       | целое                                                     |  -                    |
| y                       | целое                                                     |  -                    |
| width                   | целое                                                     |  -                    |
| height                  | целое                                                     |  -                    |
^  gschem.dialog-geometry.compselect                                                                        ^^^
^  Ключ                   ^  Формат                                                   ^  По умолчанию         ^
| hpaned                  | целое                                                     |  -                    |
| vpaned                  | целое                                                     |  -                    |
| source-tab              | 0 или 1                                                   |  1                    |
^  gschem.dialog-geometry.multiattrib                                                                       ^^^
^  Ключ                   ^  Формат                                                   ^  По умолчанию         ^
| show_inherited          | логическое значение                                       |  true                 |

Примечание: все указанные значения автоматически сохраняются в файлах
настроек пользователя. Их можно изменить вручную, но значения будут
перезаписаны в следующий раз, когда изменится размер или другая упомянутая в
этой таблице величина соответствующего диалогового окна. Если вы
отредактируете эти значения в то время, когда программа **gschem** запущена,
они будут молча перезаписаны при завершении её работы.

=== x ===
Позиция диалогового окна по оси X.

=== y ===
Позиция диалогового окна по оси Y.

=== width ===
Ширина диалогового окна.

=== height ===
Высота диалогового окна.

=== hpaned ===
Ширина горизонтального фрейма, где выбираются компоненты в диалоговом окне
выбора компонентов.

=== vpaned ===
Высота вертикального фрейма для предварительного просмотра компонента в
диалоговом окне выбора компонентов.

=== source-tab ===
Значение, определяющее то, какая вкладка будет открываться при открытии
диалогового окна выбора компонента. 0 означает, что будет выбрана вкладка
«Используемые» («In use»), 1 означает, что будет выбрана вкладка
«Библиотечные» («Libraries»).

=== show_inherited ===
Настройка видимости унаследованных атрибутов в диалоговом окне
редактирования атрибутов.


===== gaf shell =====
**gaf shell** предоставляет цикл чтения-вычисления-вывода Scheme («Read-Eval-Print Loop» --- REPL) для
автоматической обработки файлов схем и символов. Эта утилита разработана
для поддержки работы с API языка Scheme в gEDA. Информацию об опциях утилиты см. в справочной странице //gaf(1)//, а
для информации о поддерживаемых Scheme-процедурах gEDA см. **info geda-scheme**.


===== Шрифты =====
В Linux за настройку шрифтов отвечает пакет **Fontconfig**, и современные
системы (в частности **pango** и **cairo**) полагаются на его библиотеку в
поиске любого заданного шрифта. Вы можете задать команде **gaf** шаблон,
содержащий имя нужного шрифта и, при желании, некоторые настройки для этого
шрифта. Fontconfig ищет соответствие шаблону среди всех шрифтов, доступных в
вашей системе, и выбирает самое близкое соответствие. Это обеспечивает то,
что библиотека всегда возвращает какой-то шрифт, но не гарантирует, что он
будет похож на запрошенный в шаблоне.

Если вы хотите узнать, какие шрифты доступны в вашей системе, вы можете
использовать утилиту //fc-list(1)// из пакета fontconfig. Для проверки, смог
ли fontconfig найти подходящий шрифт по указанному шаблону (или посмотреть
какой шрифт будет соответствовать вашему шаблону), используйте утилиту
//fc-match(1)//.

Больше информации о том, как задать имя шрифта, который хотелось бы
использовать, см. в
[[http://freedesktop.org/software/fontconfig/fontconfig-user.html|документации
пакета fontconfig]].

В некоторых случаях система шрифтов может даже внедрить в ваш документ более
одного шрифта. Это может произойти, например, тогда, когда наиболее
подходящий шрифт, выбранный библиотекой fontconfig не содержит некоторых
глифов для одного из языков, используемых в документе. В этом случае она
добавит какой-то другой шрифт, в котором есть необходимые глифы.

В следующей таблице приводится список возможных значений настроек
(полученный из документации по Pango), которые вы можете использовать в
своих шаблонах имён шрифтов. См. также раздел [[#Примеры]] ниже.

//**Table 6.**// Возможные параметры настройки шрифта
^ Параметр ^ Значение ^
| 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 |


===== Примеры =====
==== Настройка экспорта ====
Использовать пейзажную ориентацию («landscape») по умолчанию для локального проекта:
  gaf config --project export layout landscape
Использовать размер бумаги «letter» по умолчанию для печати чего-угодно:
  gaf config --user export paper na_letter
Задать для локального проекта определённое значение размера бумаги, равное 1x2 дюйма:
  gaf config --project export size "72;144"
Задать поля как полдюйма для левой и правой сторон и как четверть
дюйма для верха и низа для локального проекта:
  gaf config --project export margins "18;36;18;36"
Следующая команда выровняет схемы вашего проекта вправо:
  gaf config --project export align "1.0;0.5"
Следующая команда --- неправильная, она не будет работать, даже если
в вашей локали в качестве разделителя в числах с плавающей запятой используется запятая, а не точка:
  gaf config --project export align "1,0;0,0"
Эта команда, однако, работает в данном случае (например, в локали ru_RU.UTF-8):
  gaf export -a 0,0:1.0 -o file.pdf file.sch
Обратите внимание, что здесь я использую **''gaf export''**, а не **''gaf config''**.

Чтобы печатать все свои схемы в цвете (обратите внимание: "False" или "FALSE"
работать не будут):
  gaf config --project export monochrome false
Настроить нестандартный пользовательский шрифт:
  gaf config --user export font "OpenGost Type B TT Italic"
Выбрать другой шрифт для локального проекта:
  gaf config --project export font "Arial Bold"


==== Настройка создания списков соединений ====
Использовать более короткие имена соединений и шин во всех списках соединений
созданных пользователем:
  gaf config --user gnetlist default-net-name net
  gaf config --user gnetlist default-bus-name bus
Обеспечить, что в локальном проекте будут использоваться иерархические
имена соединений, несмотря на настройки в //''geda-user.conf''//:
  gaf config --project gnetlist traverse-hierarchy true
Переименовывать соединения, подключенные к //''gnd-1.sym''// (и другим символам
имеющим атрибут ''net''), если они имеют атрибут ''netname'':
  gaf config --project gnetlist net-naming-priority netname-attribute

==== Настройка gschem ====
Использовать более короткие имена для новых файлов:
  gaf config --user gschem default-filename empty

==== Настройка вида библиотеки gschem ====
Эта команда явно говорит, что вы хотите, чтобы всегда показывались все
атрибуты:
  gaf config --project gschem.library component-attributes "*"
Будьте осторожны при использовании этой команды в командной строке.
Если вы забудете кавычки, командная оболочка подставит вместо имени атрибута
первое имя файла в рабочем каталоге. Скорее всего, это не то, что вам надо.

Ограничить список отображаемых атрибутов указанным фильтром:
  gaf config --project gschem.library component-attributes "refdes;device;description"
Не показывать никаких атрибутов в диалоговом окне выбора атрибутов:
  gaf config --project gschem.library component-attributes ""
То же самое, что и выше, но эта команда работать не будет, потому что
в указанной строке значения разделены запятыми, а не точками с запятыми,
поэтому строка целиком будет считаться именем одного атрибута:
  gaf config --project gschem.library component-attributes "refdes,device,description"
Сортировать библиотеку компонентов в **gschem** в алфавитном порядке:
  gaf config --user gschem.library sort true

==== Настройка печати из gschem ====
Выбрать пейзажную ориентацию (''landscape'') как ориентацию по умолчанию для локального проекта
при печати из **gschem**:
  gaf config --project gschem.printing layout landscape
Использовать формат A5 при печати из **gschem**:
  gaf config --project gschem.printing paper iso_a5
Всегда использовать чёрно-белую печать в **gschem**:
  gaf config --user gschem.printing monochrome true

==== Настройка диалоговых окон gschem ====
Не отображать никаких унаследованных атрибутов в диалоговом окне редактирования атрибутов:
  gaf config --user gschem.dialog-geometry.multiattrib show_inherited false
Учтите, что в команде выше нельзя использовать ключ ''%%--project%%'' (''-p'').
Эта команда работает только в пользовательском контексте и не имеет смысла
для локальных проектов.

==== Использование оболочки gaf (gaf shell) ====
Для определения имени каталога пользовательских настроек gEDA,
наберите:
  gaf shell -c "(display (user-config-dir))"
То же самое для каталогов системных настроек:
  gaf shell -c "(display (sys-config-dirs))"
