# Guide de l'utilisateur gschem gEDA

by: Ales Hvezda / September 21st, 2003

The latest version of this document may be found at: http://geda.seul.org/wiki/geda:gschem_ug

This document is released under the GNU Free Documentation License (GFDL).

Please report any errors/inconsistencies in this document by commenting in the Discussion area at the bottom of the associated page.

# About this document ...

gEDA gschem Users Guide

This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.70)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds. Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were: latex2html -local_icons gschem

The translation was initiated by Ales Hvezda on 2005-08-20

# Introduction

This document describes the installation, configuration, and operation of the gschem application.
This document does not describe the process of generating schematics. For this, refer to the various tutorials on using the gEDA Tool Suite:

- Bill Wilson's gschem warmup
- Bill Wilson’s gschem and pcb tutorial
- “Optical Proximity Sensor for Robots (Part 1), Simple PCB Design with the gEDA Suite”, by Stuart Brorson (March 2006 Circuit Cellar article)
- Starting with gEDA at the Cambridge University Engineering Department
- "Circuit simulation using gEDA and SPICE -- HOWTO" by Stuart Brorson
- "gEDA Design Suite for Linux" by Stuart Brorson, Ales Hvezda, & Dan McMahill (03 Mar 2005 Circuite Cellar article)
- "Circuit Design on Your Linux Box Using gEDA" by Stuart Brorson (29 November 2005 Linux Journal article)
- Optical Proximity Sensor for Robots (Part 1): Simple PCB Design with the gEDA Suite, by Stuart Brorson, Circuit Cellar magazine, March 2006 (Issue 188), p. 48
- And, of course, Google is your friend.

Ce document suppose que vous comprenez les bases de la capture de schéma. Par exemple: vous comprenez ce qu’un composant représente et que les liaisons et les bus interconnectent ces composants pour former un schéma, etc… For a basic understanding of the various work-flows available in the gEDA Tool Suite, please read the above tutorials. For more detailed understanding of specific tool issues, please refer to How To Ask Questions and to the Resources.

# Overview

gschem is the schematic capture program in the gEDA Tool Suite. Its purpose is to facilitate the graphical input of:

- circuit schematics
- component symbols
- block diagrams

Once gschem has been used to enter the symbols/schematics for your design, several gEDA Tool Suite “utility” programs are used to extract information for other purposes:

- gattrib – gattrib is a gEDA Tool Suite productivity aid. gattrib reads a [hierarchical set of] gschem schematic files and creates a spreadsheet showing all components in rows, with the associated component attributes listed in the columns. It allows the user to add, modify, or delete component attributes outside of gschem, and then save the .sch files.
- gnetlist – A tool that converts a [hierarchical set of] schematic files into an equivalent netlist (a textual representation of a schematic) in various formats. Various gnetlist back-ends are used to create:
  - Bill of Materials (BOM) files.
  - Design Rule Checks (DRCs).
  - Netlist files for use as input to various printed circuit board layout programs (e.g., Allegro, PADS, pcb (part of the gEDA Tool Suite), Protell, Tango, RACAL-REDAC, etc.).
  - Files for input to SPICE simulation programs.
  - VHDL code.
  - Verilog code.
  - etc.
- grenum – grenum is a gEDA Tool Suite productivity aid that will renumber the reference designators (i.e., refdes) in a [hierarchical set of] schematic files.
- gsch2pcb – The prefered method to create a netlist for the pcb printed circuit board layout tool (part of the gEDA Tool Suite).
- gspiceui – GNU Spice GUI (i.e., gspiceui) provides a GUI for freely available Spice electronic cicuit simulation engines (e.g., gnucap and ngspice). It uses gnetlist (to convert schematic files to net list files) and gwave (to display simulation results). gSchem is the preferred schematic capture tool.
- gsymcheck – A checker for symbols created with gEDA Tool Suite (e.g., gschem, tragesym, etc.).
- pcb – A tool for the layout of printed circuit boards.
- refdes_renum – Reads a [hierarchical set of] gschem schematic files and renumbers all reference designators. The reference designators are numbered starting with 1 and the old schematic file is replaced by the modified schematic file.
- tragesym – A python script that creates geda symbols from structured textfiles. The symbols usually need to be “cleaned up” in gschem.

# Resources

The following on-line resources are useful for designers using gschem:

- Bill Wilson's gschem warmup tutorial – If you are new to the gEDA tools, read this before you read Bill’s “Bill Wilson’s gsch2pcb tutorial”.
- Bill Wilson's gschem and pcb tutorial – If you are new to the gEDA tools, this tutorial will bring you up to speed quickly.
- Circuit Cellar Magazine – Practical, hands-on applications and solutions for embedded designers:
  - gEDA Design Suite for Linux, by Stuart Brorson, Ales Hvezda, & Dan McMahill, Circuit Cellar magazine, March 2005 (Issue 176), p. 12
  - Optical Proximity Sensor for Robots (Part 1): Simple PCB Design with the gEDA Suite, by Stuart Brorson, Circuit Cellar magazine, March 2006 (Issue 188), p. 48
  - Optical Proximity Sensor for Robots (Part 2): Open-Source PCB Layout Editor, by Stuart Borson, Circuit Cellar magazine, April 2006 (Issue 189), p. 40
- gEDA Project home page – The homepage for the gEDA Tools Suite. A rather mature site, includes (but not limited to):
  - News – from 2002
  - Screenshots – gschem in action
  - Tools – links to project homepages
  - Download – ISO images, binaries, and sources
  - Lists – e-mail list subscription and archives
  - Docs – current gEDA/gaf documentation (not gEDA Tools Suite documentation), wiki, slide presentations
  - Devel – nonymous CVS access
  - Search – by Google
  - Links – links associated with gEDA, projects developed using gEDA Tools Suite, gEDA-related press
- gEDA Bug Tracker – On SourceForge
- gEDA Project's Wiki – All things related to the gEDA Tools Suite.
- gedasymbols.org – On-line repository of user-developed symbols for gschem, SPICE models, and footprints for pcb.
- John C. Luciani’s proposed Land Pattern Naming Convention – Footprint naming conventions document, used by him, and often used by those submitting to the gedasymbols.org symbols/footprint repository.
- John C. Luciani’s PCB Footprints Library – A rather inclusive collection of non-GPL licensed footprints and the scripts used to create them.
- OpenCollector carries listings and news for free EDA software and circuit designs. Open Collector supports gEDA.
- PCB Design Tutorial; RevA – Document describing the process of taking a schematic to a pcb. Excellent for the beginner.
- PCB Libraries website – Advocates of the IPC standard Land Pattern (a.k.a., footprint) Naming Conventions and Land Pattern Calculators. A useful site if you have the money to subscribe to the services.
  - The free (windows-based) IPC-7351 Land Pattern Viewer is a very useful tool for viewing the latest IPC footprints.
  - CAD Data Files to be used with PCB Libraries' IPC-7351A LP Programs – please note the license restrictions.
- Starting with gEDA at the Cambridge University Engineering Department – The Cambridge University Engineering Department’s tutorial for using gEDA.
- Stuart Brorson's gEDA tools and tips – gEDA related tools and information.

# How To Ask Questions

gschem is an OpenSource, community driven, development. As such, the emphasis has been on developing the gEDA Tools Suite, not on developing commercial-level documentation and support. Much of the burden on learning how to use the gEDA Tools Suite applications is placed on the user, who must understand the basics of electronics, Electronics Design Automation (EDA), and the terminology used in schematic capture, circuit simulation, and printed circuit board design.
As a typical OpenSource development, the gEDA Tools Suite development community provides timely and insightful response to user inquiries, but please perform the following steps before bothering the developers (they need to focus on making gEDA Tools Suite applications better, and you can actually learn to answer your own questions and become independent of the developers):

1. Read Rick Moen’s How To Ask Questions The Smart Way, about how to ask for help. This is a must read for everybody.
2. Read this document. I know, it’s a lot to expect engineers to actually read a user’s guide. The latest version of this document is maintained on the gEDA web-site at TBD. The information should be here. If it isn’t, comment to the fact in one of the on-line document’s “Discussion” areas (at the bottom of each wiki-page). Helpful comments are clear, to the point, and may even contain the wording that should be inserted into the document.
3. Read the gschem Frequently Asked Questions (FAQ) wiki-page. This on-line document is updated often to reflect user and developer experiences with gschem.
4. Read the gEDA/gaf Documentation. This information was installed on your computer if the gEDA Tools Suite was installed from the gEDA Tools Suite CD-ROM.
5. Google is your friend. People that have asked questions that obviously didn’t do any simple Google search will not be treated well when asking for help. This is particularly true if your problem is not unique to the gEDA Tools Suite applications.
6. Ask for a pointer to the right direction. It is considered good “net etiquette” to ask for a pointer to information, so that you can learn where such information can be found, rather than have someone search the information for you.
7. If you are software literate, look at the source code to see what it is doing.
8. Subscribe to the gEDA e-mail lists (i.e., you can only post to the e-mail lists if you are a subscriber). Then:
   1. Start reading recent messages in the geda-user e-mail list archives. Get a feel for the list’s ettiquite so that you learn how to properly ask questions.
   2. Search the archives for issues similar to yours. You may find the question has been asked of the developers and users before, and answered.
   3. In the event that you can find no information concerning your problem, submit a concise description of the problem and a request for the type of help you are requesting.

# Installing gschem

As a mature OpenSource project, the gEDA Tools Suite and its components have been installed on many Linux distributions. The following are by no means the only methods of installing the gEDA Tools Suite and/or its components.

## Latest Stable

gschem is a component of the gEDA/gaf set of tools which tend to integrate together in the development and maintenance of schematics and symbols. The term “gaf” stands for “gEDA and friends”). The gEDA/gaf applications are actually rather stable, and receive significant testing prior to release.
There are multiple methods of installing gschem. The appropriate method depends on your distribution. See the following for some examples.

### "gEDA Tools Suite" CD-ROM

The recommended method is installation from the “gEDA Tools Suite” CD-ROM, gratefully prepared by Stuart Brorson. The latest version of this CD-ROM is available on-line for free download as an ISO image from the gEDA Downloads web-page. Simply burn this ISO image to a CD-ROM using your favorite CD burning software (e.g., K3b, …). Insert the CD-ROM, and if your computer supports autodetection of the CD-ROM, the built-in installation wizzard will launch. This wizzard will first check if your computer has some required software (informing you if you don’t and optionally installing these if you want), then build all of the “gEDA Tool Suite” applications (including gschem) from source. The whole process can take 2 hours on a slower computer.

If the installation wizzard did not launch, enter as follows to install the gEDA Tool Suite for access by all users on this computer (i.e., when prompted for the installation directory, enter something like: “/usr/local/gEDA-20060124”):

    sudo sh /media/cdrecorder/installer –log –verbose

The above command requires superuser permissions configured for the user invoking the command. If you do not have the proper permissions to execute this command, ask your administrator to install the gEDA Tool Suite for you.

If the installation wizzard did not launch, enter as follows to install the gEDA Tool Suite for access by just the user doing the installation(i.e., when prompted for the installation directory, accept the default "/home/{login id}/geda-install”):

    sh /media/cdrecorder/installer –log –verbose

### Debian distributions

For Debian distributions, you may wish to download the latest DEB binaries prepared by Hamish Moffatt. These are not always current with the latest “gEDA Tools Suite” ISO image above, and do not include many of the other tools available on the “gEDA Tools Suite” ISO image.

### Red Hat distributions

For Red Hat distributions (and possibly others) you may wish to download the latest RPM binaries]] prepared by Wojciech Kazubski.

### Mac OSX distributions

For Mac OSX distributions you may wish to download the latest Fink binaries prepared by Charles Lepple.

## CVS Unstable/Testing

For those already familiar with the gEDA/gaf applications on the “gEDA Tools Suite” CD-ROM, access to the CVS repository is available. This is the latest developer source-code version of the application.
Installation from CVS is appropriate for those:

- Seeking a solution to a specific problem that was submitted to the development team, to test the “fix” so that the developers can be informed that the “fix” works.
- With significant working knowledge of the “gEDA Tools Suite” and industry expertise, wishing to test the latest version of the application(s) prior to the next release. This usually requires access to several existing designs known to work in the current stable release of the “gEDA Tools Suite” ISO image, so that comparisons can be made and issues brought to the attention of the developer/user community (via the e-mail lists).

# Configuring gschem

Assume that you have installed the gEDA Tools Suite from CD-ROM (the most common installation method), and that you are ready to configure gschem to your personal likes. When installing, you were prompted for the path where the gEDA executables would be placed. The default was the /home/{login id}/geda-install directory, where {login id} is the username you logged into your account with, but you may have changed this to another directory on the computer. This directory is referred to below as the {binary-install-path} because this is where the gEDA binary executables are placed. If you forgot where the binaries were installed, simply issue the following command to find where gschem is installed (in this case the {binary-install-path} is /usr/local/gEDA-20060124):

    % which gschem
    /usr/local/gEDA-20060124/bin/gschem
    %

The gEDA Tools Suite applications follow normal Unix/Linux conventions for placement of configuration files; there are usually system-wide, user-wide, and project-specific configuration settings. The system-wide settings are placed in a sub-directory of the {binary-install-path}. The user-wide settings are placed in the user’s home directory, also known as the login directory (referred to in Unix/Linux parlance as the $HOME directory). The project-specific settings are placed in a project-specific directory.

Now that we know the above, we can configure gschem.
gschem is highly configurable. All configuration is handled through the following resource files (written using the GNU Guile programming language, an interpreter for Scheme, a version of Lisp):

- system-gschemrc: The system-wide initialization file for gschem. Installed in the {binary-install-path}/share/gEDA/system-gschemrc file, it is required for gschem to run. Users should not modify this file, but should override the settings in this file by creating their own $HOME/gschemrc file and/or ‘pwd’/gschemrc file and putting the new settings in those files. The {binary-install-path} directory is where your gEDA/gaf executables were installed, including gschem. Depends on your install method. Refer to Installing gschem for more details.
- $HOME/gschemrc: The per-user initialization file for gschem. Created by the user in the user’s home directory. Settings placed in this file will override settings in the system-gschemrc file. Users should put settings in this file they want to apply to all of their sessions, such as (to change the default black background color scheme to a light background color scheme):

    ; Load up a color scheme
    (load (string-append gedadatarc "/gschem-lightbg")) ; light background

- ‘pwd’/gschemrc: The per-project initialization file for gschem. Created by the user in the user’s project directory. Settings placed in this file will override settings in both the system-gschemrc file and the $HOME/gschemrc file. Users should put settings in this file they want to apply to this particular project, such as (to autonumber reference designators when components are placed on the schematic):

    ; Comment in this scheme code if you want automatic numbering when
    ; placing new component and copying components
    ;
    (load (string-append gedadata "/scheme/auto-uref.scm"))
    (add-hook! add-component-hook auto-uref)

- system-gafrc: The system-wide initialization file for gEDA/gaf applications (includes gschem, gnetlist). Installed in the {binary-install-path}/share/gEDA/system-gafrc file, it is required for gschem to run. Users should not modify this file, but should override the settings in this file by creating their own $HOME/gafrc file and/or ‘pwd’/gafrc file and putting the new settings in those files. The {binary-install-path} directory is where your gEDA/gaf executables were installed, including gschem. Depends on your install method. Refer to Installing gschem for more details.
- $HOME/gafrc: The per-user initialization file for gEDA/gaf applications. Created by the user in the user’s home directory. Settings placed in this file will override settings in the system-gafrc file. Users should put settings in this file they want to apply to all of their sessions.
- ‘pwd’/gafrc: The per-project initialization file for the gEDA/gaf applications. Created by the user in the user’s project directory. Settings placed in this file will override settings in both the system-gafrc file and the $HOME/gafrc file. Users should put settings in this file they want to apply to this particular project. Settings such as the component-library or source-library keywords go into this file.
- gschem-gtkrc: Installed in the {binary-install-path}/share/gEDA/gschem-gtkrc file. Used to define the font for all gtk+ widgets in gschem.

A few comments about changing the files:

- Don’t break any guile syntax rules. Doing so will cause the scheme interpreter (guile) to stop interpreting.
- To add a setting to the $HOME/gschemrc file (or to the ‘pwd’/gschemrc file), copy the setting’s text from the {binary-install-directory}/share/gEDA/system-gschemrc file to the $HOME/gschemrc file (or the ‘pwd’/gschemrc file) and make the setting change there.
- To add a setting to the $HOME/gafrc file (or the ‘pwd’/gafrc file), copy the relevant setting’s text from the {binary-install-directory}/share/gEDA/system-gafrc file to the $HOME/gafrc file (or the ‘pwd’/gafrc file) and make the setting change there.
- Keywords/defaults always override what came before, with the exception of cumulative keywords (like component-library).

## gschemrc

The {binary-install-path}/share/gEDA/system-gschemrc file is well commented. Read this file for more details on the settings available.
Some of the settings appropriate for override (by placing in either the user’s $HOME/gschemrc file or the project’s ‘pwd’/gschemrc file) are:

## gafrc

The {binary-install-path}/share/gEDA/system-gafrc file is well commented. Read this file for more details on the settings available.
Some of the settings appropriate for override (by placing in either the user’s $HOME/gafrc file or the project’s ‘pwd’/gafrc file) are:

# Lancer gschem

## Confirming gschem is installed

You should determine if gschem has been correctly installed on your Linux computer.
Log into your Linux account, and launch your favorite interactive shell. The different Linux distributions will usually offer more than one interactive shell such as xterm, gnome-term, konsole, etc.
You will see a shell prompt, which will depend on your Linux distribution and on your selection of interactive shell. It is common practice in Linux documentation to refer to the user’s interactive login shell prompt as “%”, and to refer to the superuser’s (i.e., user “root”) interactive login shell prompt as “#”.
At the shell prompt, enter the following commands to determine if gschem is installed:

    % echo $PATH
    /usr/local/gEDA-20060124/bin:/usr/kerberos/bin:/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin:/home/gEDA/bin
    % which gschem
    /usr/local/gEDA-20060124/bin/gschem
    % ldd /usr/local/gEDA-20060124/bin/gschem
        linux-gate.so.1 =>  (0x00345000)
        libgeda.so.25 => /usr/local/gEDA-20060124/lib/libgeda.so.25 (0x00d7d000)
        libguile.so.12 => /usr/lib/libguile.so.12 (0x00588000)
        libguile-ltdl.so.1 => /usr/lib/libguile-ltdl.so.1 (0x00b62000)
        libqthreads.so.12 => /usr/lib/libqthreads.so.12 (0x009f7000)
        libpthread.so.0 => /lib/libpthread.so.0 (0x006d4000)
        libcrypt.so.1 => /lib/libcrypt.so.1 (0x03266000)
        libgdk-x11-2.0.so.0 => /usr/lib/libgdk-x11-2.0.so.0 (0x00c10000)
        libgdk_pixbuf-2.0.so.0 => /usr/lib/libgdk_pixbuf-2.0.so.0 (0x006ac000)
        libm.so.6 => /lib/libm.so.6 (0x008df000)
        libpangoxft-1.0.so.0 => /usr/lib/libpangoxft-1.0.so.0 (0x003e7000)
        libpangox-1.0.so.0 => /usr/lib/libpangox-1.0.so.0 (0x00a57000)
        libpango-1.0.so.0 => /usr/lib/libpango-1.0.so.0 (0x00bd8000)
        libgobject-2.0.so.0 => /usr/lib/libgobject-2.0.so.0 (0x00a01000)
        libgmodule-2.0.so.0 => /usr/lib/libgmodule-2.0.so.0 (0x009fb000)
        libdl.so.2 => /lib/libdl.so.2 (0x00906000)
        libglib-2.0.so.0 => /usr/lib/libglib-2.0.so.0 (0x0448e000)
        libgtk-x11-2.0.so.0 => /usr/lib/libgtk-x11-2.0.so.0 (0x06a81000)
        libatk-1.0.so.0 => /usr/lib/libatk-1.0.so.0 (0x00c96000)
        libSM.so.6 => /usr/X11R6/lib/libSM.so.6 (0x00d4f000)
        libICE.so.6 => /usr/X11R6/lib/libICE.so.6 (0x00d33000)
        libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00921000)
        libc.so.6 => /lib/libc.so.6 (0x007b4000)
        /lib/ld-linux.so.2 (0x00796000)
        libXrandr.so.2 => /usr/X11R6/lib/libXrandr.so.2 (0x00bac000)
        libXi.so.6 => /usr/X11R6/lib/libXi.so.6 (0x00cca000)
        libXinerama.so.1 => /usr/X11R6/lib/libXinerama.so.1 (0x00bb2000)
        libXft.so.2 => /usr/X11R6/lib/libXft.so.2 (0x00ad1000)
        libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x00af8000)
        libfontconfig.so.1 => /usr/lib/libfontconfig.so.1 (0x00111000)
        libXfixes.so.3 => /usr/X11R6/lib/libXfixes.so.3 (0x00d0d000)
        libXcursor.so.1 => /usr/X11R6/lib/libXcursor.so.1 (0x00bcc000)
        libXrender.so.1 => /usr/X11R6/lib/libXrender.so.1 (0x00ba2000)
        libXext.so.6 => /usr/X11R6/lib/libXext.so.6 (0x00a82000)
        libpangoft2-1.0.so.0 => /usr/lib/libpangoft2-1.0.so.0 (0x05362000)
        libexpat.so.0 => /usr/lib/libexpat.so.0 (0x0068b000)
        libz.so.1 => /usr/lib/libz.so.1 (0x0090c000)

The echo $PATH command displays the user’s current setting for the PATH environment variable. In the above example for a Fedora Core 4 installation, user gEDA executed the command and determined that the PATH included the /usr/local/gEDA-20060124/bin directory (this will differ depending on where you put the gEDA Tools Suite executables). If you installed from the gEDA Tools Suite CD-ROM (the most common method of installing the gEDA tools), as the last step of the installation wizzard you were prompted to:

1. Set your $PATH environment variable to {the directory in which the install wizzard installed gEDA’s executables}
2. Set your $LD_LIBRARY_PATH environment variable to {the directory in which the install wizzard installed gEDA’s libraries}

The which command displays the full path of a command’s executable, searching for the command on the user’s list of directories, as defined in the PATH environment variable. In this case, it will return the full path to the gschem executable if it is on the user’s PATH. If this command does not return the full path to the gschem executable, make sure your PATH environment variable has been properly set.

The ldd command displays shared libraries required by a program. All of the requested libraries must be found for gschem to run. Don’t be intimidated by the long list of libraries, this is common for mature Linux applications. If we had not received this output (or something very similar), we would have to check on our setting for the LD_LIBRARY_PATH environment variable.

And of course, there is always attempting to just run gschem as follows:

    %  gschem -h
    Usage: gschem [OPTIONS] schematic_filename1 ... schematic_filenameN
      -q            Quiet mode
      -v            Verbose mode on
      -r filename   Rc filename
      -s filename   Script (guile) filename
      -o filename   Output filename (for printing)
      -p            Automatically place the window
      -t            Print stroke information
      -h            Help; this message

where we displayed the gschem help.

If these commands do not return the expected results, then most likely the gEDA tools are not installed properly. Please see the appropriate INSTALL docs (which came with the gEDA distribution) for more info on installing the gEDA tools. If you installed from the gEDA Tools Suite CD-ROM, read the INSTALL document on the CD-ROM first.

## The Shell Prompt

Figure 1 – gnome-terminal

You launch gschem from your favorite shell prompt (in this case, gnome-terminal on Fedora Core 4).
There are several command-line switches:

- -q – Quiet mode
  Turns on “quiet mode”. Output (i.e., stdout and stderr) is not generated to the shell. Useful if calling gschem from a script (e.g., bash, sh, csh, etc.) to perform batch operations such as printing a large number of schematics or symbols.
- -v – Verbose mode ON
  Generate verbose information. Not used very much in gschem.
- -r filename – Process additional configuration settings from filename
  filename is a file containing settings of the form found in either system-gschemrc or system-gafrc
  In addition to the following files, gschem will process filename for additional configuration settings:
  * {binary-install-path}/share/gEDA/system-gschemrc
  * $HOME/gschemrc
  * ‘pwd’/gschemrc
  * {binary-install-path}/share/gEDA/system-gafrc
  * $HOME/gafrc
  * ‘pwd’/gafrc
- -s filename – Process filename as a guile script
  The name of a script file (written in guile) for gschem to process.
  Refer to Appendix B -- Printing Schematics and Symbols and Appendix C -- Writing guile Scripts for more details.
  For example, in your $HOME/geda-sources/gedagaf/{gEDA Tools Suite version}/scripts/ directory is the print.scm file, a template script file directing gschem to generate a PostScript file of a schematic appropriate for printing. This print.scm file works as is, but you may want to customize it for your own needs. To print the schematic_1.sch schematic to the schematic_1.ps PostScript file from within a bash script, you would enter: `gschem -q -p -o schematic_1.ps -s print.scm schematic_1.sch`
  Then, simply use your favorite printing solution to print the file, such as: `lp schematic_1.ps`
  to a PostScript printer.
- -o filename – Output filename (e.g., for printing)
  Specify the output filename. For example, as used to specify the Postscript filename in the example above.
- -p – Automatically place the window
  Don’t wait for the windowmanager to place the window.
  When a new window is opened, some window managers display the bounding box of the window and wait for the user to place the window manually. The "-p” option avoids that, letting the window manager decide where to put the new window.
- -t – Print stroke information
- -h – Help
  Generate a short usage printout.

Running gschem is straightforward once you have installed it on your GNU/Linux system.
Although gschem is a GUI application, gschem is meant to be launched from the command-line, as it takes command-line arguements (see Figure 1 above).
To open an empty schematic, run: `% gschem`

To open a specific schematic, run: `% gschem schematic_name.sch`

To open a list of schematics, run: `% gschem schematic_1.sch schematic_2.sch, schematic_3.sch …`
or use wildcards to specify multiple filenames: `% gschem schematic_*.sch`

As operations are performed in the gschem Main Window the gschem Status Window continues to output information, and the shell prompt’s window continues to output information, consisting of:

- …

## Backups

There are two basic mechanisms in gschem for backing up schematics and symbols, classic Linux backups and incremental backups.

### Classic Linux backups

While creating and/or editing schematic file(s) or symbol file(s), snapshots are triggered by the autosave interval setting in the {binary-install-path}/share/gEDA/system-gschemrc file (see Relevant configuration settings below). If the file has not been manually saved, and the interval expires (current default 2 minutes), the snapshot is saved the next time a change is made in the gschem main window (to either a schematic or to a symbol). The interval timer starts again as soon as the snapshot file(s) have been written, and once the timer expires the next change to the main window will trigger the snapshot to be written.
This snapshot includes all work up to, but not including, the last operation performed in the gschem main window. This is to allow for easier recovery from a crash that may have been caused by the last operation.
When gschem exits normally, the snapshot file(s) are deleted. So, if gschem were to crash, or not terminate normally for some reason (e.g., power failure, soda → keyboard, etc.), the shapshot file(s) would be found the next time gschem opened the file(s). gschem will display the following warning message when it finds a snapshot file associated with the schematic file(s) or symbol file(s) it opens:

    WARNING: Found and autosave backup file:
      {full path to autosave file}

    The backup copy is newer than the schematic, so it seems you
    should load it instead of the original fil.
    Gschem usually makes backup copies automatically, and this
    situation happens when it crashed or it was forced to exit
    abruptely.

    If you load the original file, the backup file will be overwritten in
    the next autosave timeout and it will be lost.

    Do you want to load the backup file?

The snapshots are saved to a file whose filename is constructed from the original filename (schematic or symbol) as follows:

- add a "#" to the beginning of the original filename
- add a "#" to the end

so that:

- “schematic_1.sch” becomes "#schematic_1.sch#"
- “symbol.sym” becomes "#symbol.sym#"

And yes, the "#" at the front and back of the filename are part of the filename.

When the user does finally manually save the file, the original file (i.e., the file that was opened) is renamed to "{filename~}" and the latest snapshot file (i.e., "#{filename}#") gets copied as "{filename}". Note that this new "{filename}" file may not contain the latest information as displayed on the gschem main window, as the autosave interval timer may not have expired since the last change to the schematic/symbol.
When the user finally decides to close gschem, the latest snapshot file (i.e., "#{filename}#") is saved to the original file (i.e., "{filename}".
When you exit gschem and are prompted to save any unsaved schematic file(s) or symbol file(s), this constitutes a manual save.

### Incremental backups

### Relevant configuration settings

There are the following configuration settings in the {binary-install-path}/share/gEDA/system-gschemrc file that effect backups:

- undo-control : Controls if the undo feature is enabled or not.
- undo-levels : Determines the number of levels of undo. Basically this number decides how many backup schematics are saved.
- undo-type : Controls which kind of undo is used, disk or memory. The default is to use the disk as the storage medium (i.e., after every action the undo information is stored to a new file on disk). The disk mechanism is nice because you get that many backups of the schematic, written to disk as backups, so you should never lose a schematic due to a crash.
- autosave : Controls if a backup copy is made every “interval” seconds. Note that a backup copy is only made when you make some change to the schematic, and there were more than “interval” seconds from the last autosave. Autosaving will not be allowed if the “interval” setting is set to zero.

## On-line documentation

For a listing of the various command line flags run “gschem -h”:

    % gschem -h
    Usage: gschem [OPTIONS] schematic_filename1 ... schematic_filenameN
      -q            Quiet mode
      -v            Verbose mode on
      -r filename   Rc filename
      -s filename   Script (guile) filename
      -o filename   Output filename (for printing)
      -p            Automatically place the window
      -t            Print stroke information
      -h            Help; this message

For a detailed explanation of the command line flags look at the gschem man page:

    % man gschem
    gschem(1)			   20031231			     gschem(1)

    NAME
           gschem - gEDA/gaf Schematic Capture

    SYNOPSIS
           gschem  [-q]  [-v] [-t] [-r rcfilename] [-s scriptfilename] [-o output-
           filename] [-p] [schematic1 ... schematicN]

    DESCRIPTION
           gschem is the schematic capture program which is part gEDA  (GPL	 Elec-
           tronic  Design Automation) toolset.  This program is used to draw elec-
           tronic schematics.  Schematics consist of standard symbols  (which  are
           either  part of a standard library or created by the user) which repre-
           sent the various gates  and  components.	  These	 components  are  then
           interconnected  by  nets	 (wires).   Schematics	may  be	 printed  to a
           PostScript file for printing or further conversion to other output for-
           mats.

           gschem is also the symbol creation editor.  All the standard methods of
           creating schematics are used in the creation of symbols.	 There	are  a
           few  special  rules when creating symbols, so please refer to the (non-
           existant as of now) symbol creation document.

           Please read the official documentation (very minimal at this point)  on
           how  to use gschem, since this man page just describes the command line
           arguments and a few examples on how to run gschem.

    OPTIONS
           gschem accepts the following options:

           -q      Quiet mode on.  This mode  turns	 off  all  warnings/notes/mes-
    	       sages. (optional)

           -v      Verbose	mode on.  This mode gives as much feedback to the user
    	       as possible. (optional)

           -t      Print out more information when using mouse strokes.  With this
    	       command	line  flag  and the middle button configured for mouse
    	       strokes, gschem will output the stroke sequence numbers as  the
    	       user executes strokes.  These numbers can be used to define new
    	       strokes in the system-gschemrc file.

           -r filename
    	       Specify a rc filename.  Normally gschem searches for  the  sys-
    	       tem-gschemrc, then ~/.gEDA/gschemrc, and finally for a gschemrc
    	       in the current directory.  This	options	 allows	 the  user  to
    	       specify an additional rc file which is read after all the other
    	       rc files are read. (optional)

           -s filename
    	       Specify a guile script to be executed at startup. (optional)

           -o filename
    	       Specify a filename for postscript output.   This	 command  line
    	       argument	 is useful when running gschem from a shell script and
    	       with a guile script.  The filename can be changed  through  the
    	       print dialog box.

           -p      Automatically  place  the  window, especially useful if running
    	       gschem from the command line and generating output.

           schematic1 [... schematicN]
    	       Schematic file to be loaded.  Specifing	a  schematic  file  is
    	       optional.   If  multiple schematic files are specified they are
    	       read in sequentially and put on seperate pages.	It  is	impor-
    	       tant that the schematic(s) follow all the options (ie last).

    EXAMPLES
           These  examples	assume that you have a schematic called stack_1.sch in
           the current directory

           To run gschem and then interact with the program:

    	    ./gschem

           To run gschem in interactive mode but load a sample schematic:

    	    ./gschem adders_1.sch

           To run gschem and load up all schematics in the current subdirectory:

    	    ./gschem *.sch

    ENVIRONMENT
           No environment variables are used.

    AUTHOR
           Ales Hvezda and many others

    SEE ALSO
           gnetlist(1), gsymcheck(1)

    COPYRIGHT
           Copyright ©  1999-2004 Ales Hvezda

           This document can be freely redistributed according to the terms of the
           GNU General Public License version 2.0

    Version			      December 31st, 2003		     gschem(1)

# Electrical Connectivity

As you draw schematics you need be aware of what is considered to be electrically connected by the gEDA programs.
Nets which are visually connected to other nets are electrically connected. This connection may be endpoint to endpoint or endpoint to midpoint. When a single endpoint to endpoint (net or pin endpoint) connection is drawn, the visual dangling net cue disappears. When an endpoint ends in the middle of another net (or multiple endpoints coming together at a single point) then a circular filled connectivity cue is drawn. You cannot connect a net to the middle of a pin. Nets can only be connected to the endpoints of pins. You cannot connect to a net if that net is not orthogonal (horizontal or vertical). The visual cues are the primary way of telling if nets/pins are connected.
Bus are similar to nets with the exception that you cannot connect a net to the endpoint of a bus (only to the middle). If you do try to connect a net to the end of a bus you will see a big red X at the invalid endpoint connection. Buses are still very new so there are still many quirks.
You can label nets by using the `label=` attribute. Do not attach more than one `label=` to a net. You only need to attach the `label=` attribute to one net segment. Different nets (i.e. multiple net segments which aren’t connected together) which have the same attribute `label=` attached to them are also considered electrically connected. You will not get any indication of this connection by gschem, but the netlister (gnetlist) considers nets with the same `label=` attribute electrically connected. The naming convention for buses has not been formalized yet.

# Components & Symbols & Objects & Attributes

There is a hierarchical association between components, symbols, objects, and attributes.

## Components

A component is the instantiation of a specific symbol, as placed on the schematic. When discussing a schematic you refer to components on the schematic, not symbols on the schematic. Think of symbols as being conceptual, and components as being concrete.
The component consists of a graphic representation and the attributes describing the component’s features.
The component inherits all of the attributes defined in the symbol. Certain attributes in the symbol:

- those explicitly defined as visible unattached attributes (see Attributes)
- specific attributes such as `symversion` and `refdes`

are promoted to the component level for manipulation by the circuit designer. These attributes may optionally be exposed (made viewable) with the component’s graphic, and their values may be changed.
Any attribute not defined in the symbol may be defined in the component. For example, if the symbol does not define the `comment` attribute, this attribute may be added to the component, perhaps to add a comment for the Bill of Material or Assembly Instructions.
Unfortunately, it is difficult to determine a component’s attributes from gschem while entering the schematic. You have to place a symbol on the schematic, select the resulting component, and select Hierarchy | Down Symbol from the pull-down menus. Then, you have to unhide all attributes with Edit | Make Inv Text Vis from the pull-down menus. Then you have to expand your view of the symbol with View | Extents. Then, you have to go back to the schematic by selecting Hierarchy | Up from the pull-down menus. Then, you have to select Edit | Edit… to bring up the “Edit Attributes” dialog box to determine if any attributes have been added at the component level.

## Symbols

Symbols are just a collection of objects and attributes.
The objects have positional significance in the symbol, and define the graphic that is viewed.
Attributes may be attached to objects, or they may be attached to the symbol itself (termed as “unattached” attributes, because they are not attached to an object).

## Objects

The following are objects:

- Line
- Box
- Circle
- Arc
- Pin
- Picture
- Text

## Attributes

An attribute is text which is in the form `name=value` (there are no spaces to the left or right of the name,value pair). An attribute can be either attached to an object or unattached. Attributes are used extensively in the gEDA project to convey information (e.g., device name, pin numbers, hidden nets, and unit reference numbers). Check gEDA/gaf Master Attribute Document for a complete list of attributes.
There are three kinds of attributes:

Attached attributes
  These are attributes which take on the standard form and are attached to some object (pin, net, component, or box etc…) to associate a value with the attribute. For example: a pin number associated with a pin. These attributes are usually yellow in color.
Unattached attributes
  These are attributes which take on the standard form, but are not attached to any object and usually convey some information which is global in nature. For example: a `device=` attribute (which lives inside symbols) and specifies what device the entire symbol represents. These attributes are also known as floating or toplevel attributes.
Promoted attributes
  These are unattached attributes in the symbol’s definition that get turned into attached attributes in the component’s definition when the symbol is instantiated as a component when placed in the schematic. If you place an unattached visible attribute inside a symbol and then instantiate that symbol, then that unattached attribute gets “promoted”; that is, it becomes an attached attribute. This mechanism of attribute reattachement (from within a symbol) is known as attribute promotion.

There are some gotchas about attribute promotion:

- Promotion only happens when the symbol is first placed. That means that if you place a symbol (e.g., sym1) and then change it on disk (by adding or removing new unattached attributes), existing sym1’s will not reflect these new unattached attributes (i.e., they won’t get promoted) in any schematic.
- The `device=` attribute is not promoted.
- Invisible attributes are not promoted by default. If you add an unattached attribute (e.g., numslots=#) and make it invisible, it will not be promoted.

Now, in order to make everybody happy, this attribute promotion behavior is configurable.
The system-gschemrc file defines:

    (attribute-promotion "enabled")

which enables attribute promotion.
If you override the system-gschemrc’s default promote-invisible setting by adding:

    (promote-invisible "enabled")

to either your user’s ~/gschemrc or local ‘pwd’/gschemrc file, invisible unattached attributes will also be promoted (and in memory removed).

However, if you do this, component slotting will break because gschem expects certain unattached attributes inside the symbol (in memory even though they are invisible).
So you can add:

    (keep-invisible "enabled")

to either your user’s ~/gschemrc or local ‘pwd’/gschemrc file. This is enabled by default, but has no effect unless promote-invisible is enabled.

So, to summarize, attribute promotion takes unattached attributes inside symbols and attaches them to the outside of a placed symbol. Three *rc keywords control this behavior: attribute-promotion, promote-invisible, and keep-invisible.

# The Main Window

There are several ways to interact with gschem. gschem requires a keyboard and mouse. There are three ways to initiate an operation or command:

- Using the mouse to select the operation off a menu
- Typing the keyboard shortcut(s).
- Draw the appropriate stroke (if stroke support is enabled)

To make usage matters more confusing, selecting an operation off of the menus behaves slightly differently than typing the keyboard shortcut. Most of the operations operate on the currently selected object(s), hence you need to select the object first before manipulating them. The menu selected operations usually require some more input (usually a mouse click) after they are picked off of the menu. The keyboard shortcut operations take that required input as the current mouse position. This saves an extra click since you can position the mouse at the right place, type in the shortcut(s), and the command then executes. Note, you can change this so that both menu and shortcut behavior is exactly the same. See the section on the resource file for more info on how to configure this.
Most of the interaction with gschem is fairly mode oriented (similar to the great text editor vi). If you select operations off of the menu, then you are placed into the corresponding mode (like copy or move mode). You must then select an anchor point (or whatever the appropriate point is) to continue the operation. Most of the commands off of the menu expect the objects to be already selected. Some of the modes persist after being execute while other immediately return you into select mode (the default mode).
The shortcuts are also mode like in nature. Most of the default shortcuts are for the various commands are not single keystrokes. There are a few which are single keystrokes (like zoom in: `z’ or pan: `x’), but most are typically two keystrokes long. As examples, to execute File/Save you would type `f’ and `s’ (without the quotes) or Add/Line is `a’ and `l’. You can get a listing of the shortcuts by picking Help/Hotkeys. You can also see the hotkey assignments in the pulldown menus as well. The shortcuts are defined in the resource files (system-gschemrc, /.gEDA/gschemrc, or `pwd`/gschemrc). See the section on the resource file for more info.
The mouse button actions in gschem are mostly configurable. The first mouse button is always used to select objects or pick points. This button is not configurable. The second mouse button is either a copy/move action (when held down over an object), a repeat last command or used to draw a stroke to execute a command. The third mouse button is either a mouse pan (when held down as the mouse is moved) or a popup menu. The behavior of the second and third mouse buttons is controlled through the resource file (see the section below for more info).

# The Status Window

Add some details about what gets displayed in the status window.

# The Schematic File

Schematic files. These files contain components, nets, text, and sometimes primitive objects (like lines, circles, box etc…) Schematics do not contain pins. Schematic filenames should follow this convention: name_#.sch where:

- name is a text string which describes what this schematic contains.
- _# is an underscore and a number (like _1, _2, _7, _13, etc…) This number is used to sequence schematic pages in a multiple page schematic.
- .sch is the schematic extension/suffix. It is important the schematic pages have this extension.

Schematic files are pure ASCII and will always be pure ASCII. gEDA does not support any binary file formats. The file format for schematics is described in the gEDA file formats document.

# The Symbol File

Symbol files. The schematic and symbol file formats are identical. gschem (or a text editor) is used to create symbol files as well as schematics. Symbol files contain lines, circles, boxes, arcs, pins, text, and attributes.
The naming convention for symbol files is: name-#.sym where:

- name is a text string which describes what the symbol represents.
- -# is a dash and a number (like -1, -2 etc…) The number is used to allow for a symbols to have the same name yet different contents. There might be multiple representations for resistors so these symbols should be called: resistor-1.sym, resistor-2.sym, and resistor-3.sym.
- .sym is the symbol extension/suffix. It is important the symbols have this extension.

The way of specifying hierarchy is by using the source= attribute. Please see the master attribute document for info on this mechanism.
The hierarchy mechanism is still in heavy flux, so there might be some more changes.

# Symbol Libraries

Components are searched for by specifying (component-library "…”) inside one of the *rc files. See below for more info.

# The Log File

Log file. This file contains informative, error, warnings etc… messages when gschem was run. This file is created in the working directory that gschem was started in. This allows the user to preserve log files between independent projects.

# Grips

Grips are a mechanism used in gschem to provide an easy way of modifying objects inside schematics. When you select an object, little squares are placed in strategic locations (line end points or circle radius point or corners of a box) which allow you to change the object quickly. Grip support currently exists for lines, nets, pins, buses, circles, and boxes. Arcs do not yet have grips, but will eventually have them.

Using grips is easy:

- Select the object you want to change. The grips (the little boxes) will appear.
- Click and hold the first mouse button inside the box.
- Move the mouse around till you have the object where you want it
- Release the mouse button.

# Menu Operations

## File

The gschem application is primarily used for the creation of schematic files (i.e., filename.sch) and symbol files (filename.sym).
The following operations are related to the manipulation of these files.
Note that gschem automatically maintains backups of open schematic/symbol files, in the /tmp directory, for the purpose of Undo/Redo. gschem cleans up these files when it exits gracefully. If gschem does not exit gracefully, the next time you launch gschem you will be prompted with a dialog similar to:

    WARNING: Found an autosave backup file:
            {filename}

          The backup copy is newer than the schematic, so it seems you
          load it instead of the original file.
          gschem usually makes backup copies automatically, and this
          situation happens when it crashed or it was forced to exit
          abruptly.

          If you load the original file, the backup file will be overwritten in
          the next autosave timeout and it will be lost.

          Do you want to load the backup file?

The following are available from the gschem main window’s menu-bar when you expand File:

### New Window (fw)

File | New Window Ouvre une nouvelle fenêtre. Chaque fenêtre est totalement séparée des autres fenêtres.

### New Page (fn)

File | New Page Ouvre une nouvelle page en plus de toute page ouverte existante. Cette page sera habituellement appelée «·untitled_N.sch·» où N est un nombre incrémenté.

### Open Page... (fo)

File | Open Page… Ouvre une page depuis le disque.
The “Open…” dialog box pops up providing:

- Directory navigation aids
- Filters for restricting the displayed files:
  - Schematics
  - Symbols
  - Schematics and Symbols
  - All files

### Close Page (pc)

File | Close Page Fermer la page actuellement affichée. Il vous sera demandé de faire une sauvegarde si vous avez fait des modifications sur la page.

### Revert Page (pr)

File | Revert Page Ferme et réouvre la page actuellement affichée. Il ne vous sera pas demandé de sauvegarder la page courante et effacera toutes les changements que vous avez fait en réouvrant le schéma sauvegardé dans le disque. A utiliser avec précaution.

### Save Page (fs)

File | Save Page Sauve la page courante. The current filename is displayed in the gschem status-bar.
Si la page est appelée untitled_N.sch (o N est un entier) alors une boîte de dialogue avec Save As… apparaîtra demandant un nouveau nom de fichier.
If the page’s filename is NOT “untitled_N.sch” (where N is a integer), then the Save As… dialog box will NOT be displayed, and:

- the backup file will be created for the previous version, named {filename}~ That is, the "~" (tilde character) is appended to the filename. Any previous backup file is lost.
- the file will be saved to the current filename.

### Save Page As... (fa)

File | Save Page As… Ouvre la boîte de dialogue Save As.
If the current filename is “untitled_N.sch”, the Save As… dialog box prompts for a new filename.
If the current filename is NOT “untitled_N.sch”, the Save As… dialog box prompts for a new filename, filling in the current filename as a default.
In either case the filename may be changed, and a new file created when the Save As button is clicked.

### Save All (fl) (fl)

File | Save All Sauvegarde inconditionnelle de tous les schémas chargés dans la mémoire.

### Print... (fp)

File | Print… Affiche la boîte de dialogue Print.
The following may be selected:

- Filename (if gschem has multiple pages loaded, this filename defaults to the page currently displayed).
- Paper size (that is loaded into your printer).
- The print type:
  - Extents with margins – the current page, with margins where the printer doesn’t output.
  - Extents no margins – the current page, but without margins where the printer doesn’t output. The printer output may be scaled larger than when using “Entents with margins”, but at the loss along the borders of the schematic.
  - Current window – Scaled to fit the page size, but not optimally.
- Orientation:
  - Landscape
  - Portrait

Pressing Print will generate a PostScript file with the filname format of the form {filename}.ps (e.g., printing schematic file First_1.sch would generate First_1.ps).
Printing the PostScript file to your printer is distribution dependent:

Fedora Core (from the command-line):
  `lp First_1.ps`

### Write PNG... (fi)

File | Write PNG… Affiche la boîte de dialogue Write PNG. Note you must have libgdgeda installed (and any required dependencies) if you want to output images.
The dialog box allows you to select:

- Width x Height:
  - 320 x 240
  - 640 x 480
  - 800 x 600
  - 1024 x 768
  - 1280 x 960
  - 1600 x 1200
  - 3200 x 2400
- Filename (if gschem has multiple pages loaded, the currently displayed page’s filname is given)

When the OK button is clicked, a PNG graphic file with a filename of the form {filename}.png is created (e.g., writing a PNG for schematic file First_1.sch will generate a First_1.png file).
This file may be used any way a PNG file is used (e.g., web-page, document insertion, image manipulation with the GIMP, etc.).

### Execute Script... (ft)

File | Execute Script… …..TBD

### Close Window (fc)

File | Close Window Ferme la fenêtre actuelle. S’il y a des schémas modifiés, une boîte de dialogue “There are unsaved schematics” apparaîtra. Cliquer sur OK fera perdre tous les schémas non sauvegardés.

### Quit (Alt-q)

File | Quit closes all opened windows and exits gschem. A “There are unsaved schematics” dialog box will appear for each window that has unsaved schematics.

## Edit

The following are available from the gschem main window’s menu-bar when you expand Edit:

### Undo (shift-u)

Edit | Undo does exactly that, it undos the last action which changed the schematic.
The depth of undo (how many undo steps can be performed) is set in the system-gschemrc file. The default is 10. Simply override this setting by placing the following lines in either your ~/.gEDA/gschemrc file or your local gschemrc file:

    ; undo-levels number
    ;
    ; Determines the number of levels of undo.  Basically this number decides
    ; how many backup schematics are saved on disk.
    ;
    (undo-levels 10)

After every action (including zooming and panning) the schematic is saved to disk (in /tmp). The undo-levels setting determines how many of these temporary files are maintained in the /tmp directory. gschem does clean-up after itself when you exit.
Should gschem crash, the saved files remain in /tmp for disaster recovery. You will be prompted the next time the schematic is opened to recover from the backup.

### Redo (shift-r)

Edit | Redo only applies after you have done an Edit | Undo. You can undo something and then immediately redo it. However if you do anything in between you will lose the undo info. You can undo and redo to your hearts desire up and down till you reach the max undo levels.

### Select Mode (s)

Edit | Select Mode is the initial mode in which gschem starts.
When in Select Mode, an unlocked object (i.e., component, line, box, circle, …) may be selected by placing the mouse pointer within the outline of the object and single-clicking, or by dragging a box (i.e., holding down the first mouse-button) around the object. Selecting an already selected object will leave the object selected (i.e., you can not unselect an object by single-clicking it). Multiple unlocked objects may be selected by dragging a box around the objects.
A locked object may be selected by dragging a box around the object.
To de-select all objects, single-click anywhere on the schematic where there is no object.
A visible attribute for an unlocked component may be selected by placing the mouse pointer over the component’s visible attribute and single-clicking. Placing the mouse pointer over the unlocked component’s visible attribute and double-clicking will open the edit dialog box appropriate for the attribute.
Objects will change color when selected.
You stay in Select Mode until you select one of the other Modes (e.g., Line, Copy, Move, etc.).
Your current Mode is displayed on the status-bar, in the lower-right corner of the gschem window.
If multiple objects overlap, single-clicking where they overlap will cycle through the objects.
If you hold down the SHIFT key and single-click, you can select and deselect multiple objects. Doing this with multiple overlapping objects will cause the selection to cycle among the possible object selections.
If you hold down the CONTROL key and single-click, you will toggle the object in and out of the current selection list.
If you hold down the SHIFT key while drawing a selection box you will add to the currently selected objects. Objects cannot be removed using the selection box and holding down the SHIFT key.
If you hold down the CONTROL key while drawing a selection box then you will toggle any encompassed objects. If an object was selected then it will be unselected and vice versa.
If you pick a component, its visible and invisible attributes are selected as well. If you just want to select the object, you must deselect the attributes.
The selection mechanisms are not obvious and do require some practice. There are some quirks so please report them as you come across them.

### Edit... (ee)

First, select the object to be edited (i.e., in Select Mode).
If the object is a component, Edit | Edit… then pops up a dialog box that allows you to edit the component’s attributes:

- Existing attributes (e.g., refdes) are displayed.
- A drop-down list of pre-defined attributes permits selection, and a edit-box provides association of a value to the attribute.
- The attribute’ name and/or value may be made visible or invisible,

If the ojbect is a text string, Edit… then pops up a dialog box that allows you to modify the text string’s attributes:

- The text string may be modified. Multiple lines of text may be entered by inserting carriage-returns.
- The text color may be modified.
- The text size may be modified.
- The text alignment:
  - Lower/middle/upper left
  - Lower/middle/upper middle
  - Lower/middle/upper right

Apply the changes by pressing OK.

Notes:
If you need to change the attributes to more than just a few components, consider saving your schematics, closing gschem, and using the gattrib application, the grenum application, or the refdes_renum application to make the changes.

### Edit Text... (ex)

First, select the text object to be edited (i.e., in Select Mode).
Edit | Edit Text… allows you to edit just text.
Edit | Edit Text… then pops up a dialog box that allows you to modify the text string’s attributes:

- The text string may be modified. Multiple lines of text may be entered by inserting carriage-returns.
- The text color may be modified.
- The text size may be modified.
- The text alignment:
  - Lower/middle/upper left
  - Lower/middle/upper middle
  - Lower/middle/upper right

Apply the changes by pressing OK.

Notes:
If you need to change the attributes to more than just a few text strings, consider saving your schematics, closing gschem, and using the gattrib application, the grenum application, or the refdes_renum application to make the changes.

### Copy Mode (ec)

Edit | Copy Mode allows you to copy (i.e., duplicate) the currently selected objects.
To copy the object(s):

- Select the objects to be copied (i.e., in Select Mode)
- Select Edit | Copy Mode
- Observe the status-bar now indicates Copy Mode
- Click on the selected component(s) to establish an origin of reference
- Observe a shadow/outline appears for the selected components that moves with the mouse
- Place the components where you want them
- Click to anchor the copied components in place.

After finishing the copy, you automatically return to Select Mode.
Holding down the CONTROL key as you move the outline around will constrain the movement to be either horizontal or vertical.
To copy objects using the shortcut keys is almost the same as above except that the origin point is selected automatically for you once you hit the copy mode shortcut.

### Move Mode (em)

Edit | Move Mode allows you to move the currently selected objects.
To move the object(s):

- Select the objects to be moved (i.e., in Select Mode)
- Select Edit | Move Mode
- Observe the status-bar now indicates Move Mode
- Click on the selected component(s) to establish an origin of reference
- Observe a shadow/outline appears for the selected components that moves with the mouse
- Place the components where you want them
- Click to anchor the moved components in place.

After finishing the move, you automatically return to Select Mode.
Holding down the CONTROL key as you move the outline around will constrain the movement to be either horizontal or vertical.
To move objects using the shortcut keys is almost the same as above except that the origin point is selected automatically for you once you hit the copy mode shortcut.

Since version 20060906, there is another way to move object(s):

- Select the objects to be moved (i.e., in Select Mode).
- Put the mouse pointer on one of the selected objects, then drag the objects and drop them where you want them.

### Delete (Delete-key)

Edit | Delete allows you to remove objects off of the page.
To delete objects:

- Select the desired object(s) (i.e., in Select Mode)
- Select Edit | Delete

The object(s) will be deleted immediately. If you inadvertantly delete a component, you can use Undo to recover.

### Rotate 90 Mode (er)

Edit | Rotate 90 Mode allows you to rotate objects 90 degrees around a pivot/center point.
To rotate objects:

- Select the desired object(s) (i.e., in Select Mode)
- Select Edit | Rotate 90 Mode
- Click on the pivot (or center) point of the rotate

The object(s) will be rotated 90º counter-clockwise immediately. If you inadvertantly rotate a component, you can use Undo to recover.
Rotating objects using the shortcut keys is similar to above except that the center point is the last mouse position at which you typed the shortcut.

### Mirror Mode (ei)

Edit | Mirror Mode allows you to mirror objects horizontally around a pivot point.
To mirror objects:

- Select the desired object(s) (i.e., in Select Mode)
- Select Edit | Mirror Mode
- Click on the pivot (or center) point of the mirror

Mirroring objects using the shortcut keys is similar to above except that the pivot point is the last mouse position at which you typed the shortcut.
Objects are mirrored horizontally about the pivot point. If you want to get a vertical mirror then rotate and mirror the object(s) till you get the desired position.
Mirroring of embedded components is not supported.

### Slot... (e shift-s)

Some physical packages (e.g., the classic 7400 Quad NAND gate) contain more than one logical component (e.g., one of the NAND gates). In gchem terminology, each of these logical components is termed a “slot” (e.g., there would be 4 slots in the 7400 Quad NAND gate). Each slot is associated with specific pins on the physical package.
Edit | Slot… allows you to change the slot number of a multiple-slot package. The package must support slotting. Refer to the gEDA/gaf Symbol Creation Document for more details.
To change the slot number (i.e., select which package pins are associated with a logical component):

- Select the desired logical component (i.e., in Select Mode)
- Select Edit | Slot…
- Change the “slot=n” value in the “Edit slot number” dialog box
- Press OK

Note that selecting the slot on a package often effects the layout of the printed circuit board, as the slot may be on the wrong side of the package for effecient routing of nets. Don’t worry, you can always come back and change the slot selection once you start laying out your board and know which slots route best.

### Color... (eo)

Edit | Color… allows you to change the color of any selected object (with the exception of components).
To change the color of the currently selected objects:

- Select the desired object(s) (i.e., in Select Mode)
- Select Edit | Color…
- The “Edit | Color Edit” dialog box, with a drop down list for colors, will appear:
  - 1 | pin | black
  - 2 | net endpoint | red
  - 3 | graphic | green4
  - 4 | net | blue2
  - 5 | attribute | black
  - 6 | logic bubble | DarkCyan
  - 8 | detached attribute | red
  - 9 | text | green4
  - 10 | bus | green2
  - 11 | select | firebrick
  - 12 | bounding box | orange
  - 13 | zoom box | DarkCyan
  - 14 | stroke | grey90
  - 15 | lock | grey40
- Pick the new color
- Press Apply

The color change will take effect once you press Apply.
You can leave this dialog box up and select other objects and change their color by pressing Apply.

### Lock (el) / Unlock (e shift-l)

Edit | Lock and Edit | Unlock allow you to lock/unlock components in a schematic. A locked component cannot be selected by a single click. To select locked component(s), drag a box around the component(s).
Locking a component is useful for components such as title blocks, which should not be selectable because there are other objects inside its boundaries. If the titleblock was not locked, and you missed selecting a component by clicking it with the mouse, you would end up selecting the titleblock instead.
Locking a component is also useful just to prevent it from being inadvertantly selected.
To lock/unlock components:

- Select the desired object(s) (i.e., in Select Mode)
- Select Edit | Lock or Edit | Unlock

The locked/unlocked state of components is preserved when gschem exits, so components which were locked remain locked the next time the schematic is opened.
You can lock and unlock regular objects (e.g., lines, pins, boxes…). This is nice when you are drawing something and an object is in the way. Just lock it, and you will not have to think about it when you click to select other objects. Locking an object is not preserved in the file format, so once you quit gschem any locked objects will be unlocked the next time the schematic is opened.
Note that if a component is locked, you can not single-click to select a visible attribute, or double-click to select and edit a visible component. First unlock such locked components.

### Line Width & Type... (ew)

The Edit | Line Width & Type… dialog box lets you control the width and type of lines, boxes, circles, and arcs on the schematic/symbol.
To change the Line Width & Type…:

- Select the desired object(s) (i.e., in Select Mode)
- Select Edit | Line Width & Type…
- The “Edit Line Width * Type” dialog box displays
- Change the following as suites the object:
  - Line Width
  - Line Type
  - Line Dash Length
  - Line Dash Space
- Press OK to apply the changes

Note that if the line width doesn’t seem to change, just pick a larger value.

### Fill Type... (ef)

Edit | Fill Type… is used to fill boxes and circles.
To fill a box or circle:

- Select the box or circle.
- Select Edit | Fill Type…. The “Edit FIll Type” dialog box is displayed.
- Enter:
  - Fill Type
  - Line Width
  - Angle 1
  - Pitch 1
  - Angle 2
  - Pitch 2
- Press OK.

### Symbol Translate... (et)

Edit | Symbol Translate… is used when creating a symbol, to translate the symbol to an origin for subsequent placement. The symbol may take an optional offset (in mils), as appropriate to the symbol.
To translate the symbol:

- Open a file for the symbol
- Set the grid snap spacing to 100 mils (Options | Snap Grid Spacing…).
- Toggle the grid ON (Options | Toggle Grid On/Off)
- Toggle the grid snap ON (Options | Toggle Snap On/Off)
- Zoom as appropriate for the symbol’s dimensions
- Draw the symbol, according to the recommendations in the gEDA/gaf Symbol Creation Document
- Select Edit | Symbol Translate…
- The “Translate” dialog box is displayed.
- Enter 0 to translate to the origin, or enter a value (in mils), positive or negative, to offset the symbol from the origin.
- Press OK to apply
- Save the symbol to the file

If you enter a 0, then all the objects will be translated to the origin.
If you enter a non-zero offset, this will be applied equally in both the X and the Y directions.

### Embed Component/Picture (eb)

gschem supports the concept of embedded components and graphics, where all the information necessary to display a component/graphic is placed in the schematic file. Edit | Embed Component/Picture causes schematic files to be significantly larger, but it makes it easy to share schematics with other people or archive schematics. You should only embed components when absolutely necessary.
To Embed Component/Picture:

- Select the component/picture (in Select Mode)
- Select Edit | Embed Component/Picture

Save the schematic. The schematic file will now contain the text strings for the embedded component or embedded graphic.
The Add Component… dialog box allows you to optionally embed the component.
The Add Picture… dialog box does NOT allow you to optionally embed the component.
You can only embed and unembed components. Also, you cannot embed and then mirror a component (this is a limitation of gschem and will eventually be fixed).

### Unembed Component/Picture (eu)

Edit | Unembed Component/Picture will move the component’s or graphic’s information from the schematic file’s contents and output it to the original file’s path/filename (i.e., the schematic file includes the path/filename information). To Unembed Component/Picture:

- Select the component/picture (in Select Mode)
- Select Edit | Unembed Component/Picture

Save the schematic. The schematic file will now NOT contain the text strings for the embedded component or embedded graphic.
You can only embed and unembed components.

### Update Component (ep)

Edit | Update Component updates a component’s definition.
A symbol can be modified from within gschem using the following sequence:

- Select the component for which the symbol should be changed.
- Select Hierarchy | Down Symbol. This takes you to the symbol editor
- Modify the symbol. This includes modifying the symbol’s graphic objects, adding/changing/deleting attributes, and moving objects with respect to the origin
- Don’t forget to Edit | Symbol Translate
- Select File | Save Page to save the symbol to it’s file
- Select Hierarchy | Up Symbol. This returns you to the schematic editor
- With the component still selected, select Edit | Update Component to update the componet’s description from the modified symbol’s definition
- Select each component on the schematic(s) made from this symbol, and select Edit | Update Component

New components placed on the schematic from this updated symbol will use the new symbol definition.
Components placed on the schematic from this symbol will be updated the next time this schematic is opened.
The symbol’s `symversion` attribute will automatically be incremented for non-trivial changes when the symbol is saved. When a schematic is opened by gschem, all symbols used by the schematic are read from their libraries. The `symversion` attribute of the symbol read from the library is compared to the `symversion` attribute of the components in the schematic. If the `symversion` attributes are different, the `symversion` attribute is exposed on the schematic for those symbols effected. Note that:

- This is a “hint” to the designer to check the symbol.
- You need to actually open a schematic file with gschem for the components to be updated.

### Show/Hide Inv Text (en)

Edit | Show/Hide Inv Text is most appropriate when creating or editing symbols, to view or hide the text for all of the symbol’s invisible attributes.
Make Inv Text Vis is most appropriate when adding symbols to schematics, to view the text for the symbol’s modifiable invisible attributes.
Edit | Show/Hide Inv Text toggles between making all invisible text visible and hiding all invisible text. When selected, all objects in the symbol are effected.
Visible text always remains visible.
A symbol has the following potential attributes :

- netname
- refdes
- slot
- value
- net
- device
- pinnumber
- pinseq
- pintype
- pinlabel
- source
- numslots
- slotdef
- graphical
- footprint
- description
- documentation
- symversion
- comment
- file
- model-name

Not all attributes need to be used to define a symbol (see the discussion of Appendix A -- Heavy vs Light Symbol Libraries). The gschem default is to define symbols as “light”, indicating that the symbol includes as few attributes as necessary to describe the symbol. “light” symbols depend on the designer attaching additional descriptive attributes to the symbol when the symbol is placed on the schematic. For example: a “light” symbol for a resistor might include just the graphic for a resistor, its pin attributes, and the “refdes” attribute. This describes a resistor. It would be the designer’s responsibility, after the resistor has been placed on the schematic, to add the “value” and “footprint” attributes appropriate for the specific resistor in the circuit. A “heavy” symbol includes more descriptive attributes. Using “light” vs. “heavy” symbols is up to the designer.
A symbol’s attributes may be flagged as either visible or invisible. Attributes are flagged as invisible to reduce the clutter around a symbol on the schematic.
When creating or editing the symbol, and changing a visible attribute to an invisible attribute, the attribute can not be viewed during further editing of the symbol. It becomes difficult to place attribute text. To view both the visible and invisible text, select Edit | Show/Hide Inv Text.
When a symbol is instantiated on a schematic as a component, only the symbol’s visible attributes are promoted to the component. For example: if a resistor’s symbol defines “refdes” as the only visible attribute defined in the symbol, the only attribute that the component contains is the “refdes” attribute). Those attributes not included in the symbol definition may be added at the schematic level, component-by-component.
This operation is useful when drawing/debugging symbols.
When hidden text is visible, “Show Hidden” will appear on the status-bar in the lower right.

### Make Inv Text Vis (ev)

Edit | Make Inv Text Vis is a quick method of making all of a component’s invisible attributes visible. The same effect can be accomplished by double-clicking on the component and marking all of the entries in the Attributes listbox as “Vis?" (i.e., visible).
To Make Inv Text Vis for a component:

- Select the component(s) in Select Mode
- Select Edit | Make Inv Text Vis

The attributes that had been hidden are displayed.
To hide the attributes again, you need to double-click the component to bring up it’s “Edit Attributes” dialog box, and explicitly place a check for each attribute you want hidden.

## Buffer

gschem supports 5 copy/cut/paste buffers which are visible across all opened pages and windows.

### Copy into 1/2/3/4/5 (yc)

To copy something into a buffer:

1. Select the objects you want to copy.
2. Select Buffer/Copy/Copy into buffer #.

### Cut into 1/2/3/4/5 (yu)

Cut is like copy in that it removes the objects from the schematic

### Paste from 1/2/3/4/5 (yp)

To paste a buffer into the current schematic:

1. Fill the buffer using the above Copy or Cut.
2. Go to the new schematic page/window.
3. Select Buffer/Paste/Paste from buffer #.
4. Click the first mouse button to pick an anchor point.
5. Move the mouse to the final spot.
6. Click the first mouse button again.

## View

### Redraw (vr)

View | Redraw re-paints the current window.
This is useful when you have mouse/component/line/text etc… droppings left over from a previous action. It is also useful when you want to update all visual connectivity cues.

### Pan (x)

View | Pan lets you change the focus of the display.
To pan the display:

- Select View | Pan
- Click the first mouse button at the new center of the display.

To pan the display using the shortcut is much simpler, simply place the mouse pointer where you want the display centered and type “x”. The display will jump to the mouse’s location.
Pan behavior is configurable. The system-gschemrc file defines:

    (third-button "popup")

If you override the system-gschemrc’s default, of popping up a menu when the third mouse button is clicked, by adding:

    (third-button "mousepan")

to either your user’s ~/gschemrc file or local ‘pwd’/gschemrc file, the third mouse button (i.e., the right mouse button on scroll-wheel mice) will allow you to pan the schematic by holding down the third mouse button and dragging.
The system-gschemrc file also defines:

    (fast-mousepan "enabled")

If you override the system-gschemrc’s default by adding:

    (fast-mousepan "disabled")

to either your user’s ~/gschemrc file or local ‘pwd’/gschemrc file, text will be displayed properly when the third mouse button is held down while dragging. The `(third-button “mousepan”)` setting must also be applied for this to work. Disabling `fast-mousepan` adversely effects rendering speed while panning on large “complicated” schematics.
The system-gschemrc file also defines:

    (zoom-with-pan "enabled")

If you override the system-gschemrc’s default by adding:

    (zoom-with-pan "disabled")

to either your user’s ~/gschemrc file or local ‘pwd’/gschemrc file, whenever you zoom in/out, the zoom will NOT center on the mouse pointer, effectively removing the pan feature of the zoom in/out operations.

### Zoom Box (w)

View | Zoom Box allows you to draw a box around a part of the gschem window and zoom in.
To use View | Zoom Box:

- Select View | Zoom Box
- Position the mouse pointer at one corner of the box you want to draw
- Click and hold down the first mouse button
- Drag the mouse, drawing the zoom box around the area to which you want to zoom
- Release the mouse button and the display will zoom

To use View | Zoom Box by typing the equivalent shortcut (i.e., “w”) is more convenient. Simply position the mouse pointer at one corner of the zoom box, then type “w”. The zoom box will start immediately using the current mouse location as the first corner of the box.
View | Zoom Box will attempt to zoom to the requested area, but some boxes are not legal and gschem will do it’s best to zoom the requested area.

### Zoom Extents (ve)

View | Extents will zoom the display to fit all of the placed objects into the current window.
To view all of the current window’s objects:

- Select View | Extents

Typing the View | Extents shortcut (i.e., “ve”) is particularly convenient for those that have learned to navigate the schematics using the shortcuts.

### Zoom In (z)

View | Zoom In zooms the display in. The current center of the window is the center of the new window. This command zooms in by a factor.
To zoom in:

- Select View | Zoom In

The (zoom-with-pan “enabled”) configuration setting in the gschemrc files effects the operation of the zoom in shortcut (i.e., “z”). The default system-gschemrc setting for:

    (zoom-with-pan "enabled")

enables zooming in, using the mouse pointer’s location as the new center of the window. If this changed to:

    (zoom-with-pan "disabled")

in either your user’s ~/gschemrc file or local ‘pwd’/gschemrc file, whenever you zoom in, the zoom will NOT center on the mouse pointer but will center on the current center of the window, effectively removing the pan feature of the zoom in operation.
To zoom in using the shortcut:

- If the default (zoom-with-pan “enabled”) is configured in one of the gschemrc files, position the mouse pointer in the window where you want the new center
- Type “z”

Typing “z” is particularly convenient for those that have learned to navigate the schematics using the shortcuts.

### Zoom Out (Z)

View | Zoom Out zooms the display out. The current center of the window is the center of the new window. This command zooms out by a factor.
To zoom out:

- Select View | Zoom Out

The (zoom-with-pan “enabled”) configuration setting in the gschemrc files effects the operation of the zoom out shortcut (i.e., “z”). The default system-gschemrc setting for:

    (zoom-with-pan "enabled")

enables zooming out, using the mouse pointer’s location as the new center of the window. If this changed to:

    (zoom-with-pan "disabled")

in either your user’s ~/gschemrc file or local ‘pwd’/gschemrc file, whenever you zoom out, the zoom will NOT center on the mouse pointer but will center on the current center of the window, effectively removing the pan feature of the zoom out operation.
To zoom out using the shortcut:

- If the default (zoom-with-pan “enabled”) is configured in one of the gschemrc files, position the mouse pointer in the window where you want the new center
- Type “Z” (i.e., shift-z)

Typing “Z” is particularly convenient for those that have learned to navigate the schematics using the shortcuts.

### Zoom Full (vf)

View | Zoom Full will zoom the display to the maximum possible displayable view.

To view the maximum displayable area:

- Select View | Zoom Full

The window contents will immediately change to show the maximum possible displayable view.

To view the maximum displayable area using the keyboard shortcut (i.e., “vf”):

- Type “vf”

The window contents will immediately change to show the maximum possible displayable view.

View | Zoom Full is useful if you like to put your working notes outside the titleblock for you schematic, for example. Just remember, these notes would now be considered part of the windows extents, so if you were to View | Extents, the display would show the titleblock and your working notes.

## Page

### Manager... (pm)

### Next (>)

### Previous (<)

### New (pe)

### Revert (pr)

### Close (pc)

### Discard (pd)

## Add

### Component... (i)

Add | Component… Ouvre une boîte de dialogue qui vous

    permet de placer les composants depuis les bibliothèques de composants.\\

Pour placer un composant:

- Select Add |Component…
- Select a component Library from the left list-box
- Sélectionnez un Composant dans la liste de droite
- Confirm the symbol is correct by reviewing the image in the Preview window
- Move the mouse into the main drawing window (you should see an outline follow the mouse pointer).
- Press the first mouse button to anchor the component
- Position the mouse pointer, and keep pressing the first mouse button to anchor additional instances of the component
- When finished anchoring components, press the last mouse button or the ESC key

Si un nom de composant est déjà sélectionné, taper Appliquer et déplacer la souris dans la fenêtre principale vous permettra placer à nouveau ce composant.
Vous pouvez effectuer une rotation avant le placement du composant en cliquant sur le bouton du milieu. Pour chaque clic de bouton, le composant effectuera une rotation de 90 degrésdans le sens inverse des aiguilles.
Care has been taken to give components descriptive names in the libraries, though it is sometimes difficult to determine what the component really represents from its name.
For example: in the analog library there are four capacitor entries:

- capacitor-1.sym
- capacitor-2.sym
- capacitor-3.sym
- capacitor-4.sym

It helps to preview the symbol in the “Select Component” dialog box before selecting and placing the symbol.

### Net (n)

Net Dessine un nouveau segment de liaison.
A net is typically a contiguous set of line segments between two pins, though it is possible to draw nets between a pin and a point on another net, or between two nets.
For example, the following diagram shows 3 net segments:

- Between R1 and R2
- Between R3 and R4
- Between the two nets

Note the small red segment at the end of the resistor’s pins. All pins in gschem have this red segment. This is the connectivity cue for the pin. It is sometimes difficult to “grab” this attachment point when drawing nets, you may need to zoom in on the pin. To zoom in, press the “z” key. To zoom out, press the “Z” (i.e., shift-z) key.
To begin drawing a net using the menu:

- Select Add | Net
- Zoom in on the component where the net is to start, so that you can easily grab the pin’s attachment point
- Position the mouse pointer over the pin’s connectivity cue
- Press the first mouse button to start the net

To begin drawing the net using the shortcut:

- Zoom in on the component where the net is to start, so that you can easily grab the pin’s attachment point
- Position the mouse pointer over the pin’s connectivity cue
- Press the “n” key

To continue drawing the net segment(s):

- Drag the mouse pointer in the direction of the end-point
- For any necessary 90º turns, single-click the mouse, and continue dragging the mouse pointer toward the end-point
- For any necessary non-orthogonal net segments (e.g., 45º angle), hold down the CONTROL button, single-click the mouse, and continue dragging the mouse pointer to the end-point
- When you reach the end-point, press the first mouse button to end the net segment
- Another net segment will start at the last end-point
  - If this second pin is to be connected to a third pin, continue as above
  - If this is the end of the connections, press the last mouse button (or ESC) to end the net

Appuyez sur le dernier bouton de souris ou sur ESC pour effacer toute liaison en cours.
If the net is cancelled you are automatically placed in Select Mode. You must pick Add | Net again or type the shortcut to add more nets.
You cannot connect a net segment to the middle of a non-orthogonal net.
The boxes at the end of the nets are connectivity cues. Red boxes signify a dangling net (not connected to anything).
Filled circles are midpoint connections/junctions. These cues are drawn automatically and are an indicator of electrical connectivity.
See Electrical Connectivity for more information.

### Bus (u)

Add | Bus est basiquement la même chose que Add | Net, except that it draws buses.
Buses are very new and there are many aspects which are not defined yet, so keep that in mind as you uses buses. More to be added here eventually.

### Attribute... (aa)

Add | Attribute… is appropriate when creating or editing symbols, to add a new attribute.
Add | Attribute… brings up the “Single Attribute Editor” dialog box. This dialog box is ONLY used to add attributes. It does not display or manipulate already placed attributes.
Un attribut n’est rien de plus qu’un objet texte qui est de la forme name=value (Il ne peut y avoir d’espace à gauche et à droite de la paire name,value). Il peut soit être attaché à un objet ou détaché.
Pour attacher un attribut détaché (e.g., “comment”, “documentation”, etc.) au symbole:

- Select Add | Attribute…
- Select an attribute name off of the pulldown list, or type the attribute name into the name entry
- Saisissez la valeur pour l’attribut
- Pick any of the attribute options
- Cliquez sur OK et l’attribut sera placé.

Si vous voulez attacher un attribut à un objet, sélectionnez d’abord l’objet souhaité et pressez ensuite Add | Attribute… depuis le menu déroulant. Si vous cliquez sur un objet qui possède des attributs attachés, ils doivent être aussi sélectionnés.
Si vous sélectionnez Add | Attribute… en dehors des menus déroulants alors vous n’avez pas beaucoup de contrôle sur le placement de l’attribut (il prend place soit en bas à gauche de l’extension de l’objet soit à l’origine de tout objet sélectionné). Si vous exécutez néanmoins Add/Attribute (i.e., “aa”) en utilisant la touche de raccourci alors la position courante de la souris est utilisé comme point d’encrage pour l’objet attribut.
Vous ne pouvez pas placer un attribut incomplet (un attribut sans nom et sans valeur).
Please see Components/Symbols/Objects/Attributes for more info on how to use attributes.

### Text... (at)

Add | Text… displays the “Text Entry…” dialog box. To place text:

- Select Options | Text Size… and select the size for the text
- Select Add | Text…
- Type the text in the entry field (multiple lines may be entered by pressing Enter)
- Press Apply or type Enter
- Déplacez la souris dans la fenêtre principale (un soulignement de texte devrait apparaître et suivre

la souris)

- Pressez le premier bouton de souris pour ancrer le texte
- Close the “Text Entry…” dialog box

Si vous laissez la boîte de dialogue d’ajout de texte (Add | Text…) ouverte, vous pouvez replacer le même objet texte encore et encore en cliquant simplement sur apply (ou en pressant enter) et en déplaçant la souris dans la fenêtre principale.
The following settings in the system-gschemrc file, the user’s ~/gschemrc file, or the local ‘pwd’/gschemrc file control how text is displayed:

text-origin-marker
  Controls if the text origin markers are displayed.
text-size
  Sets the default text size.
text-caps-style
  Sets the default caps style used for the display of text
output-text
  Controls how text is rendered to postscript

Le texte placé débutera automatiquement avec une majuscule. Veuillez voir la section Fichiers Ressource ci-dessous sur comment contrôler ce comportement.
Pour effacer un emplacement de texte, pressez le dernier bouton de souris ou sur la touche ESC.
Si vous créez du texte dans la forme name=value alors vous êtes en cours de création d’attributs. gEDA permet aux attributs généraux de flotter librement (ou détachés). C’est une bonne idée de changer la couleur de ces attributs flottants à la couleur des attributs courants (qui est aussi appelée couleur d’attribut attaché) pour indiquer que le l’objet texte est un attribut.
Vous pouvez faire pivoter le texte avant de le placer en cliquant sur le bouton milieu. Pour chaque clic de bouton, le texte fera une rotation de 90 degrés.

### Line (l)

Add | Line draws a single line segment.
To draw a line:

- If you want to snap the line to the grid, set the grid spacing by selecting Options | Snap Grid Spacing… and entering the grid spacing, and then selecting Options | Toggle Snap On/Off until you don’t see “Snap Off” on the status-bar
- Select Add | Line
- If you want to constrain the line to 90º movements, hold the CONTROL key down while moving the mouse
- Position the mouse pointer to the start-point
- Press the first mouse button
- Move the mouse in the intended direction
- When positioned at the end-point, press the first mouse button
- Continue placing lines, until you either press the second mouse button or type the Escape key

Add | Line dessine une ligne de la même manière qu’en dessinant les réseaux avec les exceptions suivantes:

- Une ligne n’a pas de signification électrique
- Seule un segment de ligne est dessiné
- Vous gardez les lignes dessinées tant que vous êtes dans le mode de dessin de lignes (Line Mode).

Pour effacer une ligne directe en cours, pressez le dernier bouton de souris ou la touche ESC.

### Box (b)

Add | Box draws a box. To draw a box:

- If you want to snap the box to the grid, set the grid spacing by selecting Options | Snap Grid Spacing… and entering the grid spacing, and then selecting Options | Toggle Snap On/Off until you don’t see “Snap Off” on the status-bar
- Select Add | Box
- Position the mouse pointer to the start-point
- Press the first mouse button
- Move the mouse in the intended direction
- When positioned at the end-point, press the first mouse button again
- Continue placing boxes, until you either press the second mouse button or type the ESC key

To cancel a box in progress, press the last mouse button or type the ESC key.
A box has no electrical significance.

### Circle (ai)

Add | Circle creates a circle.
To draw a circle:

- If you want to snap the box to the grid, set the grid spacing by selecting Options | Snap Grid Spacing… and entering the grid spacing, and then selecting Options | Toggle Snap On/Off until you don’t see “Snap Off” on the status-bar
- Select Add | Circle
- Placez le centre du cercle
- Pressez le premier bouton
- Déplacez la souris pour voir un surlignement du cercle
- Pressez le premier bouton de souris pour terminer le cercle
- Continue placing circles, until you either press the second mouse button or type the ESC key

Pour dessiner un cercle (en utilisant le raccourci clavier), identique à au-dessus excepté que ce centre du cercle est pris sur la dernière position de souris lorsque vous saisissez le raccourci.
Pour effacer un dessin de cercle en cours, pressez sur le dernier bouton de souris ou sur la touche ESC.

### Arc (ar)

Add | Arc draws an arc. Pour dessiner un arc:

- If you want to snap the box to the grid, set the grid spacing by selecting Options | Snap Grid Spacing… and entering the grid spacing, and then selecting Options | Toggle Snap On/Off until you don’t see “Snap Off” on the status-bar
- Select Add | Arc
- Place the mouse pointer at the center-point for the arc
- Press the first mouse button
- Move the mouse to the right, to define the radius of the arc
- Press the first mouse button again
- Enter the Start Angle (in degrees) – 0º is the “x” axis
- Enter the Degrees of Sweep (for counter-clockwise sweep)
- Press OK
- Continue placing arcs, until you either press the second mouse button or type the ESC key

L’angle de démarrage peut être positif ou négatif. Les degrés sont spécifiés en utilisant le système des coordonnées Cartésiennes standard. Les degrés de sweep peuvent être positifs ou négatifs.
Pour effacer un arc en cours de dessin (lorsqu’il y a le rayon) pressez le dernier bouton de souris ou la touche ESC ou pressez le bouton Cancel dans la boîte de dialogue arc.

### Pin (ap)

Add | Pin adds a pin.
Though you can Add | Pin while entering a schematic, it only makes sense to create pins while creating or editing symbol files.
To draw a pin:

- Set the grid spacing by selecting Options | Snap Grid Spacing… and entering the grid spacing, and then selecting Options | Toggle Snap On/Off until you don’t see “Snap Off” on the status-bar. The gEDA/gaf Symbol Creation Document specifies grid settings for pin placement in gEDA/gaf compliant symbols files.
- Select Add | Pin
- Pins are constrained to 90º movements
- Position the mouse pointer to the start-point
- Press the first mouse button
- Move the mouse in the intended direction. The gEDA/gaf Symbol Creation Document specifies the length of pins in gEDA/gaf compliant symbol files.
- When positioned at the end-point, press the first mouse button
- Continue placing pins, until you either press the second mouse button or type the Escape key

To cancel a pin in progress, press the last mouse button or the ESC key.

### Picture... (ag)

Add | Picture places a graphic in the schematic. To draw a picture:

- If you want to snap the picture to the grid, set the grid spacing by selecting Options | Snap Grid Spacing… and entering the grid spacing, and then selecting Options | Toggle Snap On/Off until you don’t see “Snap Off” on the status-bar
- Select Add | Picture
- Select the graphic file from the “Please select a picture file” dialog box
- Press OK
- Position the mouse pointer to the start-point
- Press the first mouse button
- Move the mouse in the intended direction. The outline of the picture will appear, retaining the aspect ratio of the original picture.
- When positioned at the end-point, press the first mouse button again.
- Continue placing pictures, until you either press the second mouse button or type the ESC key

To cancel a picture in progress, press the last mouse button or type the ESC key.
A picture has no electrical significance.

## Hierarchy

### Down Schematic (Hd)

Hierarchy | Down Schematic shifts the focus from the current schematic to a sub-schematic.
Descend dans un symbole, en ouvrant tous les schémas sous-jacents. Cela ouvrira typiquement un schéma sous-jacent du composant sélectionné s’il existe dans le chemin de recherche de la bibliothèque source. Voyez la section des Fichiers Ressource sur la manière de définir ce chemin.
Il y a actuellement deux manières de spécifier qu’un symbole possède un schéma sous-jacent ou des schémas:

1. Le schéma sous-jacent doit avoir le même nom que le symbole mais avec une extension .sch et doit suivre la convention de nommage de suffixe _#. Voyez la section Fichiers au-dessus à propos de cette convention.
2. Attacher un attribut au symbole appelé source=filename.sch filename.sch n’est pas un chemin vers le symbole mais plutôt un nom de base (le dernier fichier dans le spécificateur de chemin) du chemin de symbole. Le schéma sous-jacent sera encore recherché dans le chemin de bibliothèque source. Vous pouvez spécifier des attributs source= multiples. Les schémas sous-jacents seront ouverts dans l’ordre de découverte de l’attribut source= .

S’il a des schémas sous-jacents multiples, ils seront chargés. Le mouvement entre les pages de schéma est limité (au niveau du même jeu des schémas sous-jacent) à moins que le mot-clé rc enforce-hierarchy ne soit modifié pour permettre un mode de libre circulation transversal. Veuillez voir la section des Fichiers de Ressource pour plus d’informations.
Il est aussi recommandé que vous mainteniez des noms uniques pour les divers niveaux (lorsque vous utilisez l’attribut source pour éviter des possibles confusions. Les mécanismes hiérarchiques sont assez nouveaux et vous pouvez craindre quelques anomalies (et veuillez les rapporter s’il vous plaît).

### Down Symbol (Hs)

Cette option ouvrira le symbole du composant sélectionné.
Une fois que le symbole est ouvert, l’utilisateur peut l’éditer et le sauvegarder.
A ce moment, le schéma principal ne verra pas les changements du symbole à moins que le schéma principal ne soit rechargé ou que File/Revert ne soit exécuté. Cela sera modifié un jour.

### Up (Hu)

Cette option permettra de remonter dans la hiérarchie (s’il y a des pages au-dessus de la page actuellement affichée).

### Documentation (Ho)

Open any documentation available for the selected symbol/component.
The job is handed over to “gschemdoc”, which makes a best-effort attempt of finding relevant documentation.
The documention would normally be in PDF, HTML, text or image format, but gschemdoc tries to be as transparent as possible on this account.
First and foremost, the attribute “documentation=" is assumed to point to the documentation. This attribute should either be the filename (basename) of the document, or it should be a complete URL.
If it is a filename, and the file is found locally (in /usr/share/gEDA/documentation or otherwise), the relevant viewer will be initiated. Otherwise, a Google search for the document will be initiated.
If there is no documentation attribute, the attributes “device” and possibly “value” will be consulted in much the same way as for “documentation”. File searches will be made in forms of filenames like “device-value.pdf” and “device.pdf”.
Failing that, the file name for the symbol itself will be used as basis for the search.

## Attributes

### Attach (ta)

The Attach command allows you to take a text item (in the proper form; `name=value`) and attach it to another object.
To use Attributes/Attach:

1. Select the object which will receive the attributes
2. Select the text object(s) which will be attached to the above object
3. Pick or type the shortcut for Attributes/Attach

The order of the sequence of selecting the object and then the text items is important; gschem will not allow you to select the text items first and then the object. After going through the above sequence the text item will turn yellow (or the current attached attribute color) signifying that the text item is an attached attribute.
You cannot attach a single attribute to several different objects. You cannot attach non-text items as attributes.

### Detach (td)

Detach allows you to deassociate attributes from objects.
To deselect an object of all attributes:

1. Select the object of interest
2. Pick or type the shortcut for Attributes/Detach

All the attached attributes (even if they are not selected) will be detached from the object. This behavior is probably broken and will eventually be fixed (so that only selected attributes are detached).
When you detach attributes then they turn red (or the current detached attribute color). This color changes allows you to spot text which was an attribute and is now dangling (unattached).

### Show Value (tv)

These operations allow you to control which part of the attribute string is visible. Usually you are just interested in seeing the `value` of the attribute, but there are circumstances where seeing the `name` and `value` (or maybe just the `name`) would be useful.
To use the options:

1. Select the attribute(s) of interest
2. Pick or type the shortcut for Attributes/Show *

The text item(s) should immediately change.
These operations only work on text items which are in the form `name=value`

### Show Name (tn)

These operations allow you to control which part of the attribute string is visible. Usually you are just interested in seeing the `value` of the attribute, but there are circumstances where seeing the `name` and `value` (or maybe just the `name`) would be useful.
To use the options:

1. Select the attribute(s) of interest
2. Pick or type the shortcut for Attributes/Show *

The text item(s) should immediately change.
These operations only work on text items which are in the form `name=value`

### Show Both (tb)

These operations allow you to control which part of the attribute string is visible. Usually you are just interested in seeing the `value` of the attribute, but there are circumstances where seeing the `name` and `value` (or maybe just the `name`) would be useful.
To use the options:

1. Select the attribute(s) of interest
2. Pick or type the shortcut for Attributes/Show *

The text item(s) should immediately change.
These operations only work on text items which are in the form `name=value`

### Toggle Visibility (tt)

This operation allows you to toggle the visibility of attributes.
To use this option:

1. Select the text item(s) of interest
2. Pick or type the shortcut for Attributes/Toggle Vis

The text item(s) should change their visibility immediately.
If you make an attached attribute invisible, then you can simply select the parent object and select Toggle Vis and the attribute will be come visible (likewise any visible attributes attached to that object will become invisible).
If you make a free floating (unattached) attribute invisible, then the only way to make it visible (and all other invisible attributes) is to use the Edit/Show Hidden Text option.

### Find Specific Text... (t shift-f)

### Hide Specific Text... (th)

### Show Specific Text... (t shift-h)

### Autonumber Text... (tu)

## Options

### Text Size... (ot)

Options | Text Size… pops up a dialog box which allows you to specify the text size of all text (including attributes placed with the Add/Attribute… dialog box).
The text size is in points (1/72”). The default text size is 10 point text. The smallest text size is 2 points.

### Toggle Grid On/Off (og)

Options | Toggle Grid On/Off toggles the visible grid.

### Toggle Snap On/Off (os)

Options | Toggle Snap On/Off toggles the snap. Be very careful using this. Connections between pins and nets (and nets to nets) depends on being exactly connected. Turning of the grid will almost guarantee that nets/pins do not connect.
Before you translate a symbol using Edit/Symbol Translate, make sure the snap is on.
When snap mode is off, the text “Snap Off” will appear in the lower, righthand corner.

### Snap Grid Spacing... (oS)

Options | Snap Grid Spacing… brings up a dialog box which allows you to change the snap grid spacing (not the grid spacing). The units for this spacing are mils.
Before you translate a symbol using Edit/Symbol Translate, make sure this spacing is set to 100.

### Toggle Outline/Box (oa)

Options | Toggle Outline/Box toggles between drawing the outline of the current selection or just drawing a box when doing moves/copies/component and text places. The outline mode looks better, but tends to be significantly slower than using the box (bounding box) mode.

### Toggle Net/Rubberband (or)

Options | Toggle Net/Rubberband …..????

### Show Log Window (ol)

Options | Show Log Window displays the log window if it has been closed or disabled from being displayed when you start up gschem.

### Show Coord Window... (oc)

Options | Show Coord Window… displays a pop-up window that displays the coordinates of the mouse pointer on the schematic. Useful for accurately placing objects.

## Help

### About... (ha)

Every GUI application needs an Help | About… feature, to display:

- The application’s name.
- The version of the software.
- The author’s name(s) and how to contact.

### Manual... (hm)

Help | Manual… brings up the “gEDA/gaf Documention” web-page installed on this computer. Very useful for accessing the various documentation available for the gEDA/gaf applications.

### Hotkeys... (hh)

Help | Hotkeys… lists the current hotkeys (a.k.a., shortcuts, a.k.a., keyboard accellerators).

### Component... (Ho)

If you select a component on the schematic, and select Help | Component…, gschem uses the gschemdoc script to do its best job finding some documentation appropriate for the component:

- If the component’s symbol included the `documentation=documentation_locator` attribute, this URI is used to retreive the documentation. If the full URI is given, the URI on the internet is retrieved. If the URI is not fully qualified, it is considered to be local to this computer, and is searched for and displayed.
- If the component’s symbol does not include the `documentation=documentation_locator` attribute, a Google search is performed for PDF documents, based on the `device=` attribute, the `value=` attribute, and the symbol basename.

# Appendix A -- Heavy vs Light Symbol Libraries

A short discussion of Light Symbol Libraries as the default for gschem, and the option to build your own Heavy Symbol Libraries.

# Appendix B -- Printing Schematics and Symbols

To be supplied…

# Appendix C -- Writing guile Scripts

To be supplied…

# Appendix D -- I Want To Build A Printed Circuit Board

gschem is used for two primary design workflows:

- Circuit design intended for production of Printed Circuit Boards (PCBs).
- Circuit design intended for simulation.

The following guidelines will assist you in developing quality designs intended for use by applications that support the creation of Printed Circuit Boards:

- To be supplied…

The following on-line tutorials are an excellent method for the beginner to learn the gEDA Tools Suite design workflow resulting in a PCB:

- Bill Wilson's gschem warmup
- Bill Wilson's gsch2pcb tutorial

# Appendix E -- I Want To Simulate My Design

gschem is used for two primary design workflows:

- Circuit design intended for production of Printed Circuit Boards.
- Circuit design intended for simulation.

The following guidelines will assist you in developing quality designs intended for simulation:

- Discuss attributes appropriate for a SPICE model, and how these differ from attributes appropriate for a PCB.
- To be supplied…

The following on-line tutorials are an excellent method for the beginner to learn the gEDA Tools Suite design workflow resulting in a SPICE simulation:

- "Circuit simulation using gEDA and SPICE -- HOWTO" by Stuart Brorson
- Starting with gEDA at the Cambridge University Engineering Department

# Appendix F -- Change gschemdoc User-Defined Preferences

As installed, the gschemdoc utility script is used by gschem to:

- Display the “gEDA/gaf Documentation” (i.e., Help | Manual…)
- Display component documentation (i.e., Help | Component…)

The list of application launchers that gschemdoc uses are defined in the {binary-install-path}/bin/gschemdoc file:

    #
    # these may be changed to suit local preferences
    #
    CANDIDATE_BROWSER="galeon mozilla phoenix netscape netscape-navigator opera firefox konqueror"
    CANDIDATE_PDFREADER="xpdf acroread ggv gv"
    CANDIDATE_LOCATE="slocate locate"

To select a different application launcher, simply edit the {binary-install-path}/bin/gschemdoc file, find the above lines, and move your favorite application to the beginning of the list. For example, to use firefox as your preferred browser, move it to the beginning of the CANDIDATE_BROWSER= list, to use acroread (Adobe’s Acrobat Reader) as your preferred PDF reader, move it to the beginning of the CANDIDATE_PDFREADER= list, and to use locate as your preferred filesystem search utility, move it to the beginning of the CANDIDATE_LOCATE= list.

# Appendix G -- Breaking a Large Symbol Into Smaller Symbols

To be supplied…

# Appendix H -- Definition of Terms

Some terms used in the art of schematic capture:

attribute
  A text item which is in the form `name=value`. It can be either unattached or attached.
buffer
  …
component
  Also know as part. The equivalent of an [electronics] device, as one may place on a printed circuit board. Components are instances of a symbol placed on a schematic.
device
  Also known as “package”. The equivalent of an [electronics] device, as one may place on a printed circuit board.
dialog box
  …
embedded component
  A component whose definition is saved as part of the schematic’s file.
footprint
  Also known as a land pattern. The surface space occupied by a component/package/part.
gEDA/gaf
  gschem is a component of the gEDA/gaf set of tools, which tend to integrate together in the development and maintenance of schematics and symbols. The term “gaf” stands for “gEDA and friends”).
grip
  …
guile
  GNU Guile is an interpreter for Scheme, a version of Lisp.
HDL
  Hardware Description Language (e.g., VHDL, Verilog, etc.). Used to simulate or document a device.
hierarchical
  The concept that designs can contain nested levels of schematics, so that all the circuit doesn’t need to be placed on a single sheet.
land pattern
  Also known as a footprint. The surface space occupied by a structure or device.
library
  A collection of symbols.
line
  A straight drawing element, connecting two points. On the schematic it has no electrical significance. In a symbol, a line is part of the symbol’s graphic elements.
model
  A description of how a device behaves. Most often this is a SPICE model. The model is defined in gschem, but used in subsequent applications such as ngspice, gnucap, etc.
net
  A net connects two or more pins on a schematic, and is made up of segments. The net’s equivalent is a “wire” or “trace” on the printed circuit board.
object
  A line, circle, pin, net, box, bus, text/attribute, or picture.
package
  Also known as device. The equivalent of an [electronics] device, as one may place on a printed circuit board.
page
  Also known as a schematic’s sheet.
part
  Also know as component. The equivalent of an [electronics] device, as one may place on a printed circuit board.
project
  A collection of schematics, custom symbols, models, documentation, etc.
segment
  Part of a net. A segment has two end-points, or “grips”.
schematic
  A page/sheet with electronics symbols, text, and drawing elements (i.e., lines, circles, boxes, etc.) representing a diagram of an electrical or mechanical system.
series
  A collection of schematics which share a common basename (e.g., schematic_1.sch, schematic_2.sch, schematic_3.sch, etc.). The series basename ties schematics together.
slotted device
  Also known as a slotted package. A physical [electronics] device consisting of multiple identical components (e.g., the 7400 quad NAND device consists of 4 identical NAND gates).
source
  A schematic, HDL code, or model which implements, describes, or documents some aspect of the project.
symbol
  A collection of objects. The objects may have attributes attatched (i.e., associated) with them. There may also be attributes attached (i.e., associated) to the symbol itself (i.e., not specifically associated with an object).
sheet
  Also known as a schematic’s page.
trace
  The equivalent of a wire on a printed circuit board.
window
  …
workflow
  The process of designing. Usually includes continuous review and re-design, until it works. In the gEDA Tools Suite design workflow, multiple applications are used. One application typically is followed by another. The flow of data collected and how this data effects the design is considered the workflow.

~~DISCUSSION~~