gammurc

title: gammurc(5)

summary: gammu(1) configuration file

text:
# gammurc(5)

## NAME
gammurc - gammu(1) configuration file

## SYNOPSIS
On Linux, MacOS X, BSD and other Unix-like systems, the config file is searched in following order:

1.

$XDG_CONFIG_HOME/gammu/config

2.

~/.config/gammu/config

3.

~/.gammurc

4.

/etc/gammurc

On Microsoft Windows:

1.

%PROFILE%\Application Data\gammurc

2.

.\gammurc

## DESCRIPTION
Gammu requires configuration to be able to properly talk to your phone. gammu reads configuration from a config file. It's location is determined on runtime, see above for search paths.

You can use gammu-config or gammu-detect to generate configuration file or start from Fully documented example.

For hints about configuring your phone, you can check Gammu Phone Database <https://wammu.eu/phones/> to see what user users experienced.

This file use ini file syntax, see ini.

Configuration file for gammu can contain several sections - [gammu], [gammu1], [gammuN], ... Each section configures one connection setup and in default mode gammu tries all of them in numerical order. You can also specify which configuration section to use by giving it's number ([gammu] has number 0) as a parameter to gammu and it will then use only this section.

[gammu]

This section is read by default unless you specify other on command line.

### Device connection parameters
Connection

Protocol which will be used to talk to your phone. For Nokia cables you want to use one of following:

fbus

serial FBUS connection

dlr3

DLR-3 and compatible cables

dku2

DKU-2 and compatible cables

dku5

DKU-5 and compatible cables

mbus

serial MBUS connection

If you use some non original cable, you might need to append -nodtr (eg. for ARK3116 based cables) or -nopower, but Gammu should be able to detect this automatically.

For non-Nokia phones connected using cable you generally want:

at

generic AT commands based connection

You can optionally specify speed of the connection, eg. at19200, but it is not needed for modern USB cables.

For IrDA connections use one of following:

irdaphonet

Phonet connection for Nokia phones.

irdaat

AT commands connection for most of phones (this is not supported on Linux).

irdaobex

OBEX (IrMC or file transfer) connection for most of phones.

irdagnapbus

GNapplet based connection for Symbian phones, see gnapplet.

For Bluetooth connection use one of following:

bluephonet

Phonet connection for Nokia phones.

bluefbus

FBUS connection for Nokia phones.

blueat

AT commands connection for most of phones.

blueobex

OBEX (IrMC or file transfer) connection for most of phones.

bluerfgnapbus

GNapplet based connection for Symbian phones, see gnapplet.

blues60

Connection to Series60 applet in S60 phones, see s60. New in version 1.29.90.

New in version 1.36.7: Gammu now supports connecting using proxy command.

You can also proxy the connection using shell command, for example to different host. This can be done using proxy connections:

proxyphonet

Phonet connection for Nokia phones.

proxyfbus

FBUS connection for Nokia phones.

proxyat

AT commands connection for most of phones.

proxyobex

OBEX (IrMC or file transfer) connection for most of phones.

proxygnapbus

GNapplet based connection for Symbian phones, see gnapplet.

proxys60

Connection to Series60 applet in S60 phones, see s60.

SEE ALSO:

faq-config

Device

New in version 1.27.95.

Device node or address of phone. It depends on used connection.

For cables or emulated serial ports, you enter device name (for example /dev/ttyS0, /dev/ttyACM0, /dev/ircomm0, /dev/rfcomm0 on Linux, /dev/cuad0 on FreeBSD or COM1: on Windows). The special exception are DKU-2 and DKU-5 cables on Windows, where the device is automatically detected from driver information and this parameters is ignored.

NOTE:

Some USB modems expose several interfaces, in such cases Gammu works best with "User" one, you can find more information on <http://www.dd-wrt.com/wiki/index.php/Mobile_Broadband>.

For USB connections (currently only fbususb and dku2 on Linux), you can specify to which USB device Gammu should connect. You can either provide vendor/product IDs or device address on USB:

```
Device = 0x1234:0x5678  # Match device by vendor and product id
Device = 0x1234:-1      # Match device by vendor id
Device = 1.10           # Match device by usb bus and device address
Device = 10             # Match device by usb device address
Device = serial:123456  # Match device by serial string
```

NOTE:

On Linux systems, you might lack permissions for some device nodes. You might need to be member of some group (eg. plugdev or dialout) or or add special udev rules to enable you access these devices as non-root. For Nokia phones you can put following file (also available in sources as contrib/udev/69-gammu-acl.rules) as /etc/udev/rules.d/69-gammu-acl.rules:

```
#
# udev rule to give users access to USB device to be used by Gammu
#
ACTION!="add|change", GOTO="gammu_acl_rules_end"
KERNEL!="ttyACM[0-9]*", GOTO="gammu_acl_rules_end"
SUBSYSTEM!="tty", GOTO="gammu_acl_rules_end"
# Nokia devices
ATTRS{manufacturer}=="Nokia", TAG+="uaccess"
# Example for Sony Ericsson J108i Cedar
# ATTRS{idVendor}=="0fce", ATTRS{idProduct}=="d14e", TAG+="uaccess"
LABEL="gammu_acl_rules_end"
```

In case your USB device appears as the serial port in the system (eg. /dev/ttyACM0 on Linux or COM5: on Windows), just use same setup as with serial port.

For Bluetooth connection you have to enter Bluetooth address of your phone (you can list Bluetooth devices in range on Linux using hcitool scan command). Optionally you can also force Gammu to use specified channel by including channel number after slash.

Before using Gammu, your device should be paired with computer or you should have set up automatic pairing.

For Proxy connections, you need to specify command which should be executed. It is supposed to pass bidirectional communication from Gammu to the device. This can happen for example over network.

For IrDA connections, this parameters is not used at all.

If IrDA does not work on Linux, you might need to bring up the interface and enable discovery (you need to run these commands as root):

```
ip l s dev irda0 up          # Enables irda0 device
sysctl net.irda.discovery=1  # Enables device discovery on IrDA
```

NOTE:

Native IrDA is not supported on Linux, you need to setup virtual serial port for it (eg. /dev/ircomm0) and use it same way as cable. This can be usually achieved by loading modules ircomm-tty and irtty-sir:

```
modprobe ircomm-tty
modprobe irtty-sir
```

SEE ALSO:

faq-config

Port

Deprecated since version 1.27.95: Please use Device instead.

Alias for Device, kept for backward compatibility.

Model

Do not use this parameter unless really needed! The only use case for this is when Gammu does not know your phone and misdetects it's features. The only special case for using model is to force special type of OBEX connection instead of letting Gammu try the best suited for selected operation:

obexfs

force using of file browsing service (file system support)

obexirmc

force using of IrMC service (contacts, calendar and notes support)

obexnone

none service chosen, this has only limited use for sending file (gammu sendfile command)

mobex

m-obex service for Samsung phones

Use_Locking

On Posix systems, you might want to lock serial device when it is being used using UUCP-style lock files. Enabling this option (setting to yes) will make Gammu honor these locks and create it on startup. On most distributions you need additional privileges to use locking (eg. you need to be member of uucp group). This option has no meaning on Windows.

### Connection options
SynchronizeTime

If you want to set time from computer to phone during starting connection.

StartInfo

This option allows one to set, that you want (setting yes) to see message on the phone screen or phone should enable light for a moment during starting connection. Phone will not beep during starting connection with this option. This works only with some Nokia phones.

### Debugging options
LogFile

Path to file where information about communication will be stored. NOTE:

For most debug levels (excluding errors) the log file is overwritten on each execution.

LogFormat

Determines what all will be logged to LogFile. Possible values are:

nothing

no debug level

text

transmission dump in text format

textall

all possible info in text format

textalldate

all possible info in text format, with time stamp

errors

errors in text format

errorsdate

errors in text format, with time stamp

binary

transmission dump in binary format

For debugging use either textalldate or textall, it contains all needed information to diagnose problems.

Features

Custom features for phone. This can be used as override when values coded in common/gsmphones.c are bad or missing. Consult include/gammu-info.h for possible values (all GSM_Feature values without leading F_ prefix). Please report correct values to Gammu authors.

### Locales and character set options
GammuCoding

Forces using specified codepage (for example 1250 will force CP-1250 or utf8 for UTF-8). This should not be needed, Gammu detects it according to your locales.

GammuLoc

Path to directory with localisation files (the directory should contain LANG/LC_MESSAGES/gammu.mo). If gammu is properly installed it should find these files automatically.

### Advanced options
Advanced options are used to alter default logic, when using these options the user is responsible for ensuring any settings are correct for the target device and that they produce the desired behaviour.

atgen_setCNMI

For configurations using the generic AT command protocol it is possible to override the default indicators used when a new SMS message is received. The value for the setting is a comma delimited list of single digits corresponding to the values for the AT+CNMI modem command. If a digit is not provided, or if the provided digit is outside of the acceptable range for the device the default value is used.

For example setting atgen_setcnmi = ,,2 would set the third parameter of the CNMI command to the value 2, leaving the rest of the parameters at default, and atgen_setcnmi = 1,,,1 would set the first and fourth parameters respectively.

### Other options
DataPath

Additional path where to search for data files. The default path is configured on build time (and defaults to /usr/share/data/gammu on Unix systems). Currently it is used only for searching files to upload to phone using gammu install.

## EXAMPLES
There is more complete example available in Gammu documentation, see gammu.

### Connection examples
Gammu configuration for Nokia phone using DLR-3 cable:

```
[gammu]
device = /dev/ttyACM0
connection = dlr3
```

Gammu configuration for Sony-Ericsson phone (or any other AT compatible phone) connected using USB cable:

```
[gammu]
device = /dev/ttyACM0
connection = at
```

Gammu configuration for Sony-Ericsson (or any other AT compatible phone) connected using bluetooth:

```
[gammu]
device = B0:0B:00:00:FA:CE
connection = blueat
```

Gammu configuration for phone which needs to manually adjust Bluetooth channel to use channel 42:

```
[gammu]
device = B0:0B:00:00:FA:CE/42
connection = blueat
```

### Working with multiple phones
Gammu can be configured for multiple phones (however only one connection is used at one time, you can choose which one to use with gammu -s parameter). Configuration for phones on three serial ports would look like following:

```
[gammu]
device = /dev/ttyS0
connection = at
[gammmu1]
device = /dev/ttyS1
connection = at
[gammmu2]
device = /dev/ttyS2
connection = at
```

### Connecting to remote phone
New in version 1.36.7.

You can connect using Gammu to phone running on different host. This can be achieved using proxy connection, which executes command to forward bi-directional communication with the phone.

```
[gammu]
device = ssh root@my.router /usr/local/bin/myscript /dev/ttyUSB0
connection = proxyat
```

You can find sample script which can be used on the remote side in contrib/proxy/gammu-backend.

### Fully documented example
You can find this sample file as docs/config/gammurc in Gammu sources.

```
; This is a sample ~/.gammurc file.
; In Unix/Linux  copy it into your home directory and name it .gammurc
;                or into /etc and name it gammurc
; In Win32       copy it into directory with Gammu.exe and name gammurc
; More about parameters later
; Anything behind ; or # is comment.
; -----------------------------------------------------------------------------
[gammu]
device = com8:
connection = irdaphonet
; Do not use model configuration unless you really need it
;model = 6110
;synchronizetime = yes
;logfile = gammulog
;logformat = textall
;use_locking = yes
;gammuloc = locfile
;startinfo = yes
;gammucoding = utf8
;usephonedb = yes
[gammu1]
device = com8:
;model = 6110
connection = fbusblue
;synchronizetime = yes
;logfile = gammulog
;logformat = textall
;use_locking = yes
;gammuloc = locfile
;startinfo = yes
;gammucoding = utf8
; Step 1. Please find required Connection parameter and look into assigned
; with it device type. With some Connection you must set concrete model
; ================================================================ cables =====
; New Nokia protocol for FBUS/DAU9P
;    Connection "fbus", device type serial
; New Nokia protocol for DLR3/DLR3P
;    Connection "fbusdlr3"/"dlr3", device type serial
; New Nokia protocol for DKU2 (and phone with USB converter on phone mainboard
;                              like 6230)
;    Connection "dku2phonet"/"dku2", device type dku2 on Windows
;    Connection "fbususb" on Linux
; New Nokia protocol for DKU5 (and phone without USB converter on phone
;                              mainboard like 5100)
;    Connection "dku5fbus"/"dku5", device type dku5
; New Nokia protocol for PL2303 USB cable (and phone without USB converter
;                                          on phone mainboard like 5100)
;    Connection "fbuspl2303", device type usb
; Old Nokia protocol for MBUS/DAU9P
;    Connection "mbus", device type serial
; Variants:
; You can modify a bit behaviour of connection using additional flags
; specified just after connection name like connection-variant.
; If you're using ARK3116 cable (or any other which does not like dtr
; handling), you might need -nodtr variant of connection, eg. dlr3-nodtr.
; If cable you use is not powered over DTR/RTS, try using -nopower variant of
; connection, eg. fbus-nopower.
; -----------------------------------------------------------------------------
; AT commands for DLR3, DKU5 or other AT compatible cable (8 bits, None
; parity, no flow control, 1 stop bit). Used with Nokia, Alcatel, Siemens, etc.
;    Connection "at19200"/"at115200"/.., device type serial
; AT commands for DKU2 cable
;    Connection "dku2at", device type dku2
; ============================================================== infrared =====
; Nokia protocol for infrared with Nokia 6110/6130/6150
;    Connection "fbusirda"/"infrared", device type serial
; Nokia protocol for infrared with other Nokia models
;    Connection "irdaphonet"/"irda", device type irda
; -----------------------------------------------------------------------------
; AT commands for infrared. Used with Nokia, Alcatel, Siemens, etc.
;    Connection "irdaat", device type irda
; -----------------------------------------------------------------------------
; OBEX for infrared
;    Connection "irdaobex", device type irda.
; ============================================================= Bluetooth =====
; Nokia protocol with serial device set in BT stack (WidComm, other) from
; adequate service and Nokia 6210
;    Connection "fbusblue", device type serial
; Nokia protocol with serial device set in BT stack (WidComm, other) from
; adequate service and other Nokia models
;    Connection "phonetblue", device type serial
; -----------------------------------------------------------------------------
; Nokia protocol for Bluetooth stack with Nokia 6210
;    Connection "bluerffbus", device type BT
; Nokia protocol for Bluetooth stack with DCT4 Nokia models, which don't inform
; about services correctly (6310, 6310i with firmware lower than 5.50, 8910,..)
;    Connection "bluerfphonet", device type BT
; Nokia protocol for Bluetooth stack with other DCT4 Nokia models
;    Connection "bluephonet", device type BT
; -----------------------------------------------------------------------------
; AT commands for Bluetooth stack and 6210 / DCT4 Nokia models, which don't
; inform about BT services correctly (6310, 6310i with firmware lower
; than 5.50, 8910,..)
;    Connection "bluerfat", device type BT
; AT commands for Bluetooth stack with other phones (Siemens, other Nokia,etc.)
;    Connection "blueat", device type BT
; -----------------------------------------------------------------------------
; OBEX for Bluetooth stack with DCT4 Nokia models, which don't inform about
; BT services correctly (6310, 6310i with firmware lower than 5.50, 8910,...)
;    Connection "bluerfobex", device type BT
; OBEX for Bluetooth stack with other phones (Siemens, other Nokia, etc.)
;    Connection "blueobex", device type BT.
; -----------------------------------------------------------------------------
;    Connection "bluerfgnapbus", device type BT, model "gnap"
;    Connection "irdagnapbus", device type irda, model "gnap"
; Step2. According to device type from Step1 and used OS set Port parameter
; -----------------------------------------------------------------------------
; Port type | "Port" parameter in Windows/DOS | "Port" parameter in Linux/Unix
; ----------|---------------------------------|--------------------------------
; serial    | "com*:"                         | "/dev/ttyS*"
;           | (example "com1:")               | (example "/dev/ttyS1")
;           |                                 | or "/dev/tts/**" (with DevFS)
;           |                                 | virtual serial ports like
;           |                                 | "/dev/ircomm*" or "/dev/rfcomm*"
; ----------|---------------------------------|--------------------------------
; irda      | ignored (can be empty)          | ignored (can be empty)
; ----------|---------------------------------|--------------------------------
; BT        | Bluetooth device address (example "00:11:22:33:44:55").
;           | Optionally you can also include channel after slash
;           | (example "00:11:22:33:44:55/12"). Can be also empty.
; ----------|---------------------------------|--------------------------------
; dku2      | ignored (can be empty)          | /dev/ttyUSB* or /dev/ttyACM*
; ----------|---------------------------------|--------------------------------
; dku5      | ignored (can be empty)          | connection with it not possible
; ----------|---------------------------------|--------------------------------
; usb       | connection with it not possible | "/dev/ttyUSB*"
; Step3. Set other config parameters
; -----------------------------------------------------------------------------
; Parameter name  | Description
; ----------------|------------------------------------------------------------
; Model           | Should not be used unless you have a good reason to do so.
;                 | If Gammu doesn't recognize your phone model, put it here.
;                 | Example values: "6110", "6150", "6210", "8210"
; SynchronizeTime | if you want to set time from computer to phone during
;                 | starting connection. Do not rather use this option when
;                 | when to reset phone during connection (in some phones need
;                 | to set time again after restart)
; GammuLoc        | name of localisation file
; StartInfo       | this option allows one to set, that you want (setting "yes")
;                 | to see message on the phone screen or phone should enable
;                 | light for a moment during starting connection. Phone
;                 | WON'T beep during starting connection with this option.
; GammuCoding     | forces using specified codepage (in win32 - for example
;                 | "1250" will force CP1250) or UTF8 (in Linux - "utf8")
; ----------------|------------------------------------------------------------
; Logfile         | Use, when want to have logfile from communication.
; Logformat       | What debug info and format should be used:
;                 |   "nothing" - no debug level (default)
;                 |   "text"    - transmission dump in text format
;                 |   "textall" - all possible info in text format
;                 |   "errors"  - errors in text format
;                 |   "binary"  - transmission dump in binary format
; ----------------|------------------------------------------------------------
; Features        | Custom features for phone. This can be used as override
;                 | when values coded in common/gsmphones.c are bad or
;                 | missing. Consult include/gammu-info.h for possible values
;                 | (all Feature values without leading F_ prefix).
;                 | Please report correct values to Gammu authors.
; ----------------|------------------------------------------------------------
; Use_Locking     | under Unix/Linux use "yes", if want to lock used device
;                 | to prevent using it by other applications. In win32 ignored
; vim: et ts=4 sw=4 sts=4 tw=78 spell spelllang=en_us
```

## AUTHOR
Michal Čihař <michal@cihar.com>

## COPYRIGHT
2009-2015, Michal Čihař <michal@cihar.com>


gear-changelog-rules

package: gear

title: gear-changelog-rules(5)

summary: rule file for gear\-changelog

text:
# gear-changelog-rules(5)

## NAME
gear-changelog-rules - rule file for gear-changelog

## DESCRIPTION
The rule file specifies actions of gear-changelog(1) required to filter and format got commit messages. There are two types of directives: global and sectional. Global directives should be defined before any sections.

## FORMAT
A rule file consists of lines of the following format:

directive: <value>

Empty lines and lines beginning with “#” are ignored. Directive arguments are delimited by whitespace characters.

## GLOBAL DIRECTIVES
width: <number>

Set width of changelog messages. Default is 70 symbols.

## SECTION DIRECTIVES
group: <TEXT>

This directive begins a new section. It should contain a description for this group. This description will be used as a group message in the changelog.

regexp: <PATTERN>

Specifies the <PATTERN> on which a commit message can be attributed to this group. You can specify more than one directive of this kind.

filter: <SED-COMMAND>

Specify commands for sed(1) utility to transform each commit message before it will be written into changelog. You can specify more than one directive of this kind.

## FILES
.gear/changelog

The gear-changelog(1) expect to find rules, unless another name is specified by the --rules=filename option.

## EXAMPLES

```
[localhost]$ cat .gear/changelog <<EOF
group: gear-changelog utility changes
regexp: ^gear-changelog(-rules.5.in)?:
filter: s/^gear-changelog: //
filter: s/^gear-changelog-rules.5.in: /Documentation: /
group: gear-merge utility changes
regexp: ^gear-merge:
filter: s/^gear-merge: //
EOF
[localhost]$ gear-changelog
* Wed Jun 18 2008 Alexey Gladkov <legion@altlinux.org> 1.4.0-alt1
- gear-changelog utility changes:

  + Replace /bin/ash with /bin/sh.

  + Documentation: Fix typo.

  + Read first commit too.

  + Fix typo.
- gear-merge utility changes:

  + Fix spacing in help message.

  + Update copyrights.

  + More choices in interactive merge mode (thx Alexey I. Froloff).

  + Document --no-interactive option (thx Alexey I. Froloff).

  + Implement --stop option (thx Alexey I. Froloff).
```

## AUTHOR
This manual page written by Alexey Gladkov <legion@altlinux.org>.

Authors and contributors of the programs included in the gear package are listed in the manual pages for these programs.

## SEE ALSO
gear-changelog(1).


gear-import-rules

title: gear-import-rules(5)

summary: rule file for gear\-import

text:
# gear-import-rules(5)

## NAME
gear-import-rules - rule file for gear-import

## DESCRIPTION
The rule file specifies parser patterns for gear-import(1) required to parse archive filename.

## FORMAT
A rule file consists of lines of the following format:

directive: <value>

Empty lines and lines beginning with “#” are ignored.

## DIRECTIVES
pattern: <REGEXP>

Extended posix regexp that applies to archive filename (without path). If pattern matches, name and version are generated using regexp back-reference.

name: \<DIGIT>

Matches the DIGIT-th parenthesized subexpression that match name.

version: \<DIGIT>

Matches the DIGIT-th parenthesized subexpression that match version.

case-sense: yes

Makes `sed' match REGEXP in a case-sensitive manner.

replace-name: <sed-expression>

replace-version: <sed-expression>

Finally, if replace-name or replace-version directives defined, it applied to generated name of version as sed expression.

## EXAMPLES

```
pattern: ^([0-9_-]+[-_])?([a-z0-9.-]+)_([0-9][a-z0-9.-]+)$
name: \2
version: \3
replace-name: s/(-(bin|src)){0,}$//
replace-version: s/([-_](bin|src)){0,}$//
```

## AUTHOR
This manual page written by Alexey Gladkov <legion@altlinux.org>.

Authors and contributors of the programs included in the gear package are listed in the manual pages for these programs.

## SEE ALSO
gear-import(1).


gear-merge-rules

title: gear-merge-rules(5)

summary: rule file for gear\-merge

text:
# gear-merge-rules(5)

## NAME
gear-merge-rules - rule file for gear-merge

## DESCRIPTION
The rule file specifies actions of gear-merge(1) required to merge branches in the package repository.

## FORMAT
A rule file consists of lines of the following format:

directive: <from-branch> <to-branch> [arguments ...]

Empty lines and lines beginning with “#” are ignored. Directive arguments are delimited by whitespace characters.

## COMMON ARGUMENTS
squash

It is the same as git merge --squash. See git-merge(1).

strategy=<STRATEGY>

It is the same as git merge --strategy=<STRATEGY>.

## DIRECTIVES
merge: <from-branch> <to-branch> [options ...]

Call git-merge to merge the retrieved <from-branch> into the <to-branch> branch.

Valid options are:

message=<MESSAGE>

The commit message to be used for the merge commit.

gendiff: <from-branch> <to-branch> name=<FILENAME> [options ...]

Valid options are:

name=<FILENAME>

Write result to file <FILENAME>.

message=<MESSAGE>

The comment is added in the beginning of a diff.

unified=<N>

Generate diffs with <n> lines of context instead of the usual three. See git-diff(1).

## FILES
.gear/merge

The gear-merge(1) expect to find rules, unless another name is specified by the --rules=filename option.

## AUTHOR
This manual page written by Alexey Gladkov <legion@altlinux.org>.

Authors and contributors of the programs included in the gear package are listed in the manual pages for these programs.

## SEE ALSO
gear-merge(1).


gear-rules

title: gear-rules(5)

summary: rule file for gear

text:
# gear-rules(5)

## NAME
gear-rules - rule file for gear

## DESCRIPTION
The rule file specifies actions of gear(1) required to extract source files from the package repository.

## FORMAT
A rule file consists of 0 or more lines of the following format:

directive: arguments...

Empty lines and lines beginning with “#” are ignored. Directive arguments are delimited by whitespace characters. Whitespaces between the directive name and “:” are optional; whitespaces between “:” and the first argument are also optional. Arguments may contain special characters quoted using shell-alike quoting. There is no support for line continuation.

## PATHS
Unless specified otherwise, all paths used in the rule file are relative to the main tree, which is a subtree of the main commit specified by the -t option to gear(1). Paths are not allowed to contain “..”, and therefore can refer only to objects inside the main tree.

However, some directives can accept a tree_path, which can be either a plain path relative to the main tree, or a path with an explicit base tree specification:

base_tree:path_in_tree

The base_tree part can be in one of the following forms:

–

A single period character “.” specifies the main tree. In most cases just omitting the “base_tree:” part gives the same effect; adding “.:” explicitly is required only if the path_in_tree part itself contains the “:” character.

–

A full SHA-1 object name of a commit (40 hex characters) specifies the root tree of that commit. The specified commit must be an ancestor of the main commit.

–

A name of a tag listed in the tag list specifies the root tree of the commit pointed to by the specified tag (directly or indirectly through a chain of tag objects). The specified commit must be an ancestor of the main commit, and all tag objects in the chain must be stored in the tag directory.

The restrictions on references to other commits ensure that a correct git repository which contains the main commit also contains everything which is required to extract source files from the repository.

## KEYWORDS
Arguments of some directives can contain keywords in the @keyword@ format, which are replaced by real values before use. Values for keywords can be obtained from the main spec file or from other arguments of the same directive.

The following keywords are available in all directives which perform keyword replacement:

@name@

Package name extracted from spec file.

@version@

Package version extracted from spec file.

@release@

Package release extracted from spec file.

Other keywords are specific to each directive.

## DIRECTIVES
spec: path_to_file

Specify path of the main spec file within the main tree. This directive may be omitted if the main spec file is the only file in the main tree which matches the *.spec glob pattern; in this case gear(1) can find the spec file automatically.

tags: path_to_directory

Specify another path of the directory with the list of named tags and stored tag objects instead of .gear-tags and .gear/tags.

copy: glob_pattern...

Copy files matching the specified glob patterns to the output directory, except files which match any of glob patterns specified by exclude directives. Every glob_pattern must match at least one file in the main tree.

Glob patterns specified in this directive may contain multiple directory components separated by “/”. Wildcards are interpreted only in the last component of the pattern.

gzip: glob_pattern...

bzip2: glob_pattern...

lzma: glob_pattern...

xz: glob_pattern...

zstd: glob_pattern...

Like copy, but additionally compress the copied files with gzip(1), bzip2(1), lzma(1), xz(1), or zstd(1), and add the appropriate suffix to the copied file name.

compress: type=TYPE [name=NAME] [options] -- glob_pattern...

Like copy, but can additionally compress the copied files with TYPE method.

type=TYPE

Specify compression method. Supported values are: copy, bzip2, gzip, lzma, xz, and zstd.

name=<NAME>

Specify destination file name in output directory. In this case glob_pattern should match only one file.

All methods except copy accept compress options.

copy?: glob_pattern...

gzip?: glob_pattern...

bzip2?: glob_pattern...

lzma?: glob_pattern...

xz?: glob_pattern...

zstd?: glob_pattern...

compress?: type=TYPE [name=NAME] [options] -- glob_pattern...

Like the corresponding directives without “?”, but unmatched patterns are ignored instead of causing errors.

exclude: glob_pattern...

Ignore files matching the specified glob patterns in all copy-like directives. Affects all directives in the rule file irrespective of the order. Specifying a glob pattern which does not match any files in the tree is not an error.

When copying files from subdirectories of the main tree, the whole path including the subdirectory name is matched against exclude patterns. The “/” characters in the path are not treated as special and can be matched by wildcards.

tar: tree_path [options...]

Create a tar(1) archive of the tree specified by tree_path. The specified tree must exist.

Valid options are:

spec=path_to_file

Use another file instead of the main spec file to define keyword values.

name=archive_name

Set name of the tar archive. The .tar suffix is added automatically unless another suffix is specified by the suffix option.

The default value of this option is @dir@-@version@, unless the path part of tree_path is “.”, in which case the default is @name@-@version@.

base=base_name

Add base_name as a leading path to all files in the generated archive. If this option is not specified, by default the archive name without the suffix (set by the name option) is used.

suffix=suffix

Add suffix to the archive file name instead of the default .tar suffix.

exclude=glob_pattern

All files matching the glob_pattern are excluded from the generated tar file. This option can be specified multiple times.

Values of the name and base options and tree_path can contain keywords. In addition to the common keywords, the following keyword is supported:

@dir@

Expands to basename(path(tree_path)). Not allowed when path(tree_path) is “.” and must not be used in the path part of tree_path.

tar.gz: tree_path [options...]

tar.bz2: tree_path [options...]

tar.lzma: tree_path [options...]

tar.xz: tree_path [options...]

tar.zst: tree_path [options...]

Like tar, but additionally compress the generated tar archive with gzip(1), bzip2(1), lzma(1), xz(1), or zstd(1), and add the appropriate suffix to the archive file name (unless the suffix option is specified, which overrides both the .tar part and the suffix for the compression method).

zip: tree_path [options...]

Like tar, but create a zip(1) archive instead of tar(1) and add the .zip suffix to the archive file name instead of .tar.

tar?: tree_path [options...]

tar.gz?: tree_path [options...]

tar.bz2?: tree_path [options...]

tar.lzma?: tree_path [options...]

tar.xz?: tree_path [options...]

tar.zst?: tree_path [options...]

zip?: tree_path [options...]

Like the corresponding directives without “?”, but do not fail if the path specified in tree_path is not present in the tree. However, if tree_path specifies a non-default base tree, this tree still must be valid.

diff: old_tree_path new_tree_path [options...]

Create a diff in the unified format between trees specified by old_tree_path and new_tree_path. Both trees must exist.

Valid options are:

spec=path_to_file

Use another file instead of the main spec file to define keyword values.

name=diff_name

Set name of the generated diff file. The .patch suffix must be specified explicitly if required.

The default name is @new_dir@-@version@-@release@.patch, unless the path part of new_tree_path is “.”, in which case the default is @name@-@version@-@release@.patch.

exclude=glob_pattern

All files matching the glob_pattern are excluded from the generated diff file. This option can be specified multiple times.

Value of the name option and the base tree components of old_tree_path and new_tree_path can contain keywords. In addition to the common keywords, the following keywords are supported:

@old_dir@

Expands to basename(path(old_tree_path)). Not allowed when path(old_tree_path) is “.”.

@new_dir@

Expands to basename(path(new_tree_path)). Not allowed when path(new_tree_path) is “.”.

diff.gz: old_tree_path new_tree_path [options...]

diff.bz2: old_tree_path new_tree_path [options...]

diff.lzma: old_tree_path new_tree_path [options...]

diff.xz: old_tree_path new_tree_path [options...]

diff.zst: old_tree_path new_tree_path [options...]

Like diff, but additionally compress the generated diff file with gzip(1), bzip2(1), lzma(1), xz(1), or zstd(1), and add the appropriate suffix to the diff file name.

diff?: old_tree_path new_tree_path [options...]

diff.gz?: old_tree_path new_tree_path [options...]

diff.bz2?: old_tree_path new_tree_path [options...]

diff.lzma?: old_tree_path new_tree_path [options...]

diff.xz?: old_tree_path new_tree_path [options...]

diff.zst?: old_tree_path new_tree_path [options...]

Like the corresponding directives without “?”, but do not fail if paths specified by old_tree_path or new_tree_path are not present in the tree. However, if old_tree_path or new_tree_path specify non-default base trees, these trees still must be valid.

specsubst: variables...

Specify whitespace-separated list of variables that should be substituted in specfile. Variable names may contain letters, digits and underscore characters. For each variable every occurrence of @variable@ in specfile is substituted with its value. Values for these variables are obtained from the tag object passed to gear(1), therefore a tag object is required when specsubst: directive is used.

## SPECSUBST TAG FORMAT
A tag object may contain definitions for variables to be substituted during specsubst: directive processing. These definitions have the following format:

X-gear-specsubst: variable=value

Values are treated literally, there is no support of quoting or line continuation.

## EXAMPLES

### Archive with modified sources
A simple rule file can contain just a single tar directive to archive everything in the tree:

```
tar: .
```

If the project has a separate upstream, adding @release@ to the archive name is recommended to make the name different from upstream:

```
tar: . name=@name@-@version@-@release@
```

### Archive with unmodified sources and patch with local modifications
If you prefer to create a tar archive with unmodified upstream sources and a separate patch with local modifications, you need to create a tag for the commit with upstream sources (or use the upstream tag if upstream also uses git), specify the tag name in the rule file and store this tag in the repository using gear-store-tags(1). In this case the default archive name used by the tar directive should be correct, unless the package name or version format is different from upstream.

Usually the tag name can be based on the package version:

```
tar: v@version@:.
diff: v@version@:. .
```

(other tag naming conventions may be used, like @name@-@version@ or plain @version@). However, if a prerelease version is packaged, parts like “preN” or “rcN” should not be included in the package version, therefore the rule file will need some modifications for such versions.

You may want to exclude .gear subdirectory and spec file from diff generation:

```
tar: v@version@:.
diff: v@version@:. . exclude=.gear/** exclude=*.spec
```

### Archive with unmodified sources and separate patch files
If you prefer to maintain patch files for local modifications instead of committing modified source files to the git repository, you can store unmodified upstream sources in a subdirectory of the main tree and put patch files directly into the main tree:

```
tar: package_name
copy: *.patch
```

This layout is used by gear-srpmimport(1). The gear-update(1) utility can be used to update sources stored in the git repository to a new upstream release.

If you don't like lots of patch files cluttering the main tree, you can move them into a subdirectory:

```
tar: package_name
copy: patches/*.patch
```

## FILES
.gear-rules, .gear/rules

The list of file names where gear(1), gear-commit(1), gear-create-tag(1), gear-srpmimport(1) and gear-store-tags(1) expect to find rules (first non-empty file from this list is used), unless another name is specified by the --rules=filename option.

## AUTHOR
This manual page written by Sergey Vlasov <vsu@altlinux.org>.

Authors and contributors of the programs included in the gear package are listed in the manual pages for these programs.

## SEE ALSO
gear(1), gear-srpmimport(1), gear-update(1), gear-store-tags(1).


genisoimagerc

package: genisoimage

title: genisoimagerc(5)

text:
# genisoimagerc(5)

## NAME
genisoimagerc - startup configuration file for genisoimage

## DESCRIPTION
genisoimage(1) searches for a configuration file in several places; it uses the first one it is able to open. First, if the GENISOIMAGERC environment variable is set, its value is used as the filename; likewise for the MKISOFSRC environment variable. Next, genisoimage looks for files named .genisoimagerc or .mkisofsrc, first in the current working directory, then in the user's home directory. Next, it looks for /etc/genisoimagerc. Finally, it looks for a .genisoimagerc in the same directory as genisoimage itself is stored.

The .genisoimagerc file contains lines of the form

TAG=value

where TAG is one of the settings defined below. The case of the tag is not significant. All settings have command-line equivalents; if the command-line parameter is specified, it takes priority over the configuration file.

Blank lines and lines beginning with `#' are ignored.

## CONFIGURATION SETTINGS
ABST

The abstract information, typically the name of a file on the disc containing an abstract. There is space for 37 characters. Equivalent to the -abstract command-line option.

APPI

The application identifier should describe the application that will be on the disc. There is space for 128 characters. Equivalent to the -A command-line option.

BIBL

The bibliographic information, often the name of a file on the disc containing a bibliography. There is space for 37 characters. Equivalent to the -biblio command-line option.

COPY

The copyright information, typically the name of a file on the disc containing the copyright notice. There is space for 37 characters. Equivalent to the -copyright command-line option.

HFS_TYPE

The default TYPE for Macintosh files. Must be exactly 4 characters. Equivalent to the -hfs-type command-line option. The default value is TEXT.

HFS_CREATOR

The default CREATOR for Macintosh files. Must be exactly 4 characters. Equivalent to the -hfs-creator command-line option. The default value is Unix.

PREP

This should describe the preparer of the CD-ROM, usually with a mailing address and phone number. There is space for 128 characters. Equivalent to the -p command-line option.

PUBL

This should describe the publisher of the CD-ROM, usually with a mailing address and phone number. There is space for 128 characters. Equivalent to the -publisher command-line option.

SYSI

The System Identifier. There is space for 32 characters. Equivalent to the -sysid command-line option.

VOLI

The Volume Identifier. There is space for 32 characters. Equivalent to the -V command-line option.

VOLS

The Volume Set Name. There is space for 128 characters. Equivalent to the -volset command-line option.

genisoimage can also be configured at compile time with defaults for many of these fields. See the file defaults.h.

## EXAMPLES
The following file

```
COPY=src/COPYING
SYSI=Multics 75
```

is equivalent to the genisoimage command-line parameters

-copyright src/COPYING -sysid "Multics 75"

## SEE ALSO
genisoimage(1).

## AUTHORS
See the genisoimage(1) manual page for credits for the genisoimage program and documentation.


geoclue

title: geoclue(5)

text:
# geoclue(5)

## NAME
geoclue.conf - geoclue configuration parameters

## SYNOPSIS
/etc/geoclue/geoclue.conf

## DESCRIPTION

The geoclue geoclue.conf configuration file specifies parameters that control the operation of geoclue.

All configurations settings below are mandatory and the defaults are what you see before you edit them in geoclue.conf. If you want to keep the default values around, copy and comment out the appropriate line(s) before changing them.

## AGENT CONFIGURATION OPTIONS
[agent] is used to begin the agent configuration.

whitelist

Whitelist of desktop IDs (without .desktop part) of all agents we recognise, separated by a ';'.

whitelist=geoclue-demo-agent;gnome-shell;io.elementary.desktop.agent-geoclue2

[network-nmea]

Network NMEA source configuration options

enable=true

Fetch location from NMEA sources on local network?

[3G]

3G source configuration options

enable=true

Enable 3G source

[cdma]

CDMA source configuration options

enable=true

Enable CDMA source

[modem-gps]

Modem GPS source configuration options

enable=true

Enable Modem-GPS source

[wifi]

WiFi source configuration options

enable=true

Enable WiFi source

url=https://location.services.mozilla.com/v1/geolocate?key=geoclue

URL to the wifi geolocation service. The key can currenty be anything, just needs to be present but that is likely going to change in future.

submit-data=false Submit data to Mozilla Location Service

If set to true, geoclue will automatically submit network data to Mozilla each time it gets a GPS lock.

submission-url=https://location.services.mozilla.com/v1/submit?key=geoclue

URL to submission API of Mozilla Location Service

submission-nick=geoclue

A nickname to submit network data with. A nickname must be 2-32 characters long.

## APPLICATION CONFIGURATION OPTIONS
Having an entry here for an application with allowed=true means that geoclue will not ask agent to authorize the application. This is to ensure that applications with built-in authorization mechanism (e.g web browsers) do not have to be bound to agents.

If your application is denied access to location information and your operating system doesn't provide any mechanism to change that, it is likely a bug in your operation system (or geoclue). The solution is to report the issue with all details, rather than adding your application to this list.

Format:

[random-app]

Desktop ID of application without .desktop part allowed=true|false

Allowed access to location information?

system=true|false

Is application a system component?

users=

List of UIDs of all users for which this application is allowed location info access, separate by ';'. Keep it empty for allowing it for all users.

Examples:

[gnome-datetime-panel]

allowed=true

system=true

users= [gnome-color-panel]

allowed=true

system=true

users=

[org.gnome.Shell]

allowed=true

system=true

users=

[io.elementary.desktop.agent-geoclue2]

allowed=true

system=true

users=

[epiphany]

allowed=true

system=false

users=

[firefox]

allowed=true

system=false

users=

## AUTHOR

```
Sachin Chand
```


discgrp

package: geomview

title: discgrp(5gv)

text:
# discgrp(5gv)

## NAME
discrete group file formats

## SYNOPSIS
An ascii file representation of a discrete geometric group.

## SUMMARY
This file format applies to a wide variety of groups encountered in topology and geometry. At the beginning of the file is the string DISCGRP, in conformity with other OOGL file formats (see oogl(5)). The remainder of the file is a series of parenthesized expressions.

The file format is based on an expandable set of key markers and values. A typical entry would be

```
(group  borromean )
```

where parentheses enclose the expression. The string 'group' is called the key marker. The remaining text contains a value, in this case a character string which is the name of the group. Key markers currently recognized and their values include:

```
group 	A name for this group.
comment An arbitrary comment [maximum length 256 bytes]
	 [must be enclosed in double quotes]
attribute One of a several keyword identifiers including:

        euclidean       is a euclidean group
	hyperbolic      is a hyperbolic group
	spherical       is a spherical group
	transposed      the matrices are transposed
	finite          this is a finite group
model	In the case that 'hyperbolic' is an attribute, and the dimension is
three, this keyword sets the model that is
expected for reading subsequent isometries, i.e., expects elements of
SL(2,C) if the model is upperhalfspace or conformalball and O(3,1,R) if it is
projective.
	projective	default
	upperhalfspace
	conformalball	[not currently implemented]
display These values set characteristics of the the display of the discrete
group.
	centercam	keeps the camera centered in central dirichlet domain.
	zcull		removes tiles which lie behind the camera.
	showcam		if centercam is set, displays camgeom, if provided (see below).
dimn    The dimension of the space.
ngens   Number of generators.
gens    List of generators.
nels    Number of group elements.
els     List of group elements.
wafile	Word acceptor file (in DEAGL format version 2.2)
camgeom An OOGL-format geometry description to represent the observer.
geom	An OOGL-format geometry description. Will replace the default Dirichlet domain computation.
```

String-matching of key markers and attribute values is case-insensitive.

Currently all matrices must be 4x4 real matrices. Hence the only valid dimensions are 2,3, or 4. The typical case is dimension 3 where there are projective models for hyperbolic, euclidean, and spherical geometry. Dimension 2 groups should leave the z-coordinate unchanged.

Matrices are considered transposed if they are considered to act on column vectors as in: M.v = v'. This is the usual mathematical convention convention. So, if you use this convention you must mark your matrices as being transposed.

Group elements are specified by an optional character string followed by a list of 16 real numbers. For the case of generators, the character string represents the name of that generator. Its main use is with the automatic group software: the name used here should match that of the generator in the word acceptor file. It should, for example, be a single character for the software to work reliably. For composite elements, the string is the word in the generators which describes this group element.

OOGL libraries expect discrete group files to use the '.dgp' suffix.

A file which describes the group of the three dimensional torus follows:

```
DISCGRP
(group 3torus )
(comment "  This is a test of the new discrete group library.  " )
(attribute Euclidean )
(display centercam )
(enumdepth 3 )		# look at all words of length 3 or less in generators
(enumdist 10.0 )	# and which don't move the origin more than 10.0
(dimn 3 )
(ngens 3 )
(gens
a

             1             0             0             0

             0             1             0             0

             0             0             1             0

             1             0          -0.1             1
b

             1             0             0             0

             0             1             0             0

             0             0             1             0

           0.1             1             0             1
c

             1             0             0             0

             0             1             0             0

             0             0             1             0

             0           0.2             1             1
)
(cpoint 0.000000 0.000000 0.000000 1.000000 )
(camgeom
{ = OFF
5 2 5
0 0 0
-0.1 0 0.5
0.1 0 0.5
0 -0.1 0.5
0 0.1 0.5
3	 0 1 2	200 200 0 .8
3	 0 3 4	0 200 200 .8
}
)
```

## FILES
Example group files are to be found in the OOGL release in ${GEOM}/data/groups, where e.g., GEOM = /u/gcg/ngrap. See also discgrp(3) and automata(1).

## AUTHORS
Charlie Gunn.

## BUGS
For dimension 2, the code should read and write 3 x 3 matrices.


geomview

title: geomview(5gv)

text:
# geomview(5gv)

Geomview(5gv) Geomview(5gv)

NAME

Geomview - Geomview command language

NOTE

The material in this manual page also appears in the

Geomview manual.

DESCRIPTION

gcl: the Geomview Command Language

**********************************

Gcl has the syntax of lisp -- i.e. an expression of the form (f a b ...) means pass the values of a, b, ... to the function f.

Gcl is very limited and is by no means an implementation of lisp. It

is simply a language for expressing commands to be executed in the order

given, rather than a programming language. It does not support variable

or function definition.

Gcl is the language that Geomview understands for files that it loads

as well as for communication with other programs.

To execute a gcl command interactively, you can bring up the

*Commands* panel which lets you type in a command; Geomview

executes the command when you hit the return key. Output from such

commands is printed to standard output. Alternately, you can invoke

Geomview as `geomview -c -' which causes it to read gcl commands

from standard input.

Gcl functions return a value, and you can nest function calls in ways

which use this returned value. For example (f (g a b))

evaluates `(g a b)' and then evaluates `(f x)' where `x'

is the result returned by `(g a b)'. Geomview maintains these

return values internally but does not normally print them out.

To print out a return value pass it to the `echo' function.

For example the `geomview-version' function returns a string

representing the version of Geomview that is running, and (echo (geomview-version))

prints out this string.

Many functions simply return `t' for success or `nil' for

failure; this is the case if the documentation for the function does not

indicate otherwise. These are the lisp symbols for true and false,

respectively. (They correspond to the C variables `Lt' and

`Lnil' which you are likely to see if you look at the source code

for Geomview or some of the external modules.)

In the descriptions of the commands below several references are made to

"OOGL" formats. OOGL is the data description language that Geomview

uses for describing geometry, cameras, appearances, and other basic

objects. For details of the OOGL formats, *Note OOGL File Formats::.

(Or equivalently, see the oogl(5) manual page, distributed with Geomview

in the file man/cat5/oogl.5.

The gcl commands and argument types are listed below. Most

Geometry Center Thu Dec 12 02:41:23 CST 1996 1

Geomview(5) Geomview(5)

of the documentation in this section of the manual is available within

Geomview via the `?' and `??' commands. The command `(?

COMMAND)' causes Geomview to print out a one-line summary of the

syntax of COMMAND, and `(?? COMMAND)' prints out an

explanation of what COMMAND does. You can include the wild-card

character `*' in COMMAND to print information for a group of

commands matching a pattern. For example, `(?? *emodule*)' will

print all information about all commands containing the string

`emodule'. `(? *)' will print a short list of all commands.

Conventions Used In Describing Argument Types

=============================================

The following symbols are used to describe argument types

in the documentation for gcl functions.

`APPEARANCE' is an OOGL appearance specification.

`CAM-ID' is an ID that refers to a camera.

`CAMERA' is an OOGL camera specification.

`GEOM-ID' is an ID that refers to a geometry.

`GEOMETRY' is an OOGL geometry specification.

`ID' is a string which names a geometry or camera. Besides those you create, valid ones are:

``World, world, worldgeom, g0'' the collection of all geom's

`target' selected target object (cam or geom)

`center' selected center-of-motion object

`targetcam' last selected target camera

`targetgeom' last selected target geom

`focus' camera where cursor is (or most recently was)

Geometry Center Thu Dec 12 02:41:23 CST 1996 2

Geomview(5) Geomview(5)

`allgeoms' all geom objects

`allcams' all cameras

``default, defaultcam, prototype'' future cameras inherit default's settings

The following IDs are used to name coordinate systems, e.g. in `pick' and `write' commands:

``World, world, worldgeom, g0'' the world, within which all other geoms live.

`universe ' the universe, in which the World, lights and cameras live. Cameras' world2cam transforms might better be called universe2cam, etc.

`self' "this Geomview object". Transform from an object to `self' is the identity; writing its geometry gives the object itself with no enclosing transform; picked points appear in the object's coordinates.

`primitive' (for `pick' only) Picked points appear in the coordinate system of the lowest-level OOGL primitive.

A name is also an acceptable id. Given names are made unique by appending numbers if necessary (i.e. `foo<2>'). Every geom is also named g[n] and every camera is also named c[n] (`g0' is always the worldgeom): this name is used as a prefix to keyboard commands and can also be used as a gcl id. Numbers are reused after an object is deleted. Both names are shown in the Object browser.

`STATEMENT' represents a function call. Function calls have the form `(func arg1 arg2 ... )', where `func' is the name of the function and `arg1', `arg2', ... are the arguments.

`TRANSFORM' is an OOGL 4x4 transformation matrix.

`WINDOW' is an OOGL winddow specification.

Gcl Reference Guide

===================

Geometry Center Thu Dec 12 02:41:23 CST 1996 3

Geomview(5) Geomview(5)

`! is a synonym for `shell''

`(< EXPR1 EXPR2)' Returns t if EXPR1 is less than EXPR2. EXPR1 and EXPR2 should be either both integers or floats, or both strings.

`(= EXPR1 EXPR2)' Returns t if EXPR1 is equal to EXPR2. EXPR1 and EXPR2 should be either both integers or floats, or both strings.

`(> EXPR1 EXPR2)' Returns t if EXPR1 is greater than EXPR2. EXPR1 and EXPR2 should be either both integers or floats, or both strings.

`(? [command])' Gives one-line usage summary for `command'. Command may include `*'s as wildcards; see also `??' One-line command help; lists names only if multiple commands match. ? is a synonym for `help'

`(?? command) `command' may include `*' wildcards' Prints more info than `(? command)'. ?? is a synonym for `morehelp'.

`| is a synonym for `emodule-run'.'

`(all geometry) returns a list of names of all geometry objects.' Use e.g. `(echo (all geometry))' to print such a list.

`(all camera) returns a list of names of all cameras.'

`(all emodule defined) returns a list of all defined external modules.'

`(all emodule running) returns a list of all running external modules.'

`(ap-override [on|off])' Selects whether appearance controls should override objects' own settings. On by default. With no arguments, returns current setting.

`(backcolor CAM-ID R G B)' Set the background color of CAM-ID; R G B are numbers between 0 and 1.

`(background-image CAM-ID [FILENAME])' Use the given image as the background of camera CAM-ID (which must be a real camera, not `default' or `allcams'). Centers the image on the window area. Works only with GL and OpenGL graphics. Use "" for filename to remove background. With no filename argument, returns name of that window's current background image, or "". Any file type acceptable as a texture is allowed, e.g. .ppm.gz, .sgi, etc.

`(bbox-color GEOM-ID R G B)' Set the bounding-box color of GEOM-ID; R G B are numbers between 0 and 1.

`(bbox-draw GEOM-ID [yes|no])' Say whether GEOM-ID's bounding-box should be drawn; `yes' if omitted.

Geometry Center Thu Dec 12 02:41:23 CST 1996 4

Geomview(5) Geomview(5)

`(camera CAM-ID [CAMERA])' Specify data for CAM-ID; CAMERA is a string giving an OOGL camera specification. If no camera CAM-ID exists, it is created; in this case, the second argument is optional, and if omitted, a default camera is used. See also: new-camera.

`(camera-draw CAM-ID [yes|no])' Say whether or not cameras should be drawn in CAM-ID; `yes' if omitted.

`(camera-prop { geometry object } [projective])' Specify the object to be shown when drawing other cameras. By default, this object is drawn with its origin at the camera, and with the camera looking toward the object's -Z axis. With the `projective' keyword, the camera's viewing projection is also applied to the object; this places the object's Z=-1 and Z=+1 at near and far clipping planes, with the viewing area -1<={X,Y}<=+1. Example: (camera-prop { < cube } projective)

`(camera-reset CAM-ID)' Reset CAM-ID to its default value.

`(car LIST)' returns the first element of LIST.

`(cdr LIST)' returns the list obtained by removing the first element of LIST.

`(clock)' Returns the current time, in seconds, as shown by this stream's clock. See also set-clock and sleep-until.

`(command INFILE [OUTFILE])' Read commands from INFILE; send corresponding responses (e.g. anything written to filename `-') to OUTFILE, stdout by default.

`(copy [ID] [name])' Copies an object or camera. If ID is not specified, it is assumed to be targetgeom. If name is not specified, it is assumed to be the same as the name of ID.

`(cursor-still [INT])' Sets the number of microseconds for which the cursor must not move to register as holding still. If INT is not specified, the value will be reset to the default.

`(cursor-twitch [INT])' Sets the distance which the cursor must not move (in x or y) to register as holding still. If INT is not specified, the value will be reset to the default.

`(delete ID)' Delete object or camera ID.

Geometry Center Thu Dec 12 02:41:23 CST 1996 5

Geomview(5) Geomview(5)

`(dice GEOM-ID N)' Dice any Bezier patches within GEOM-ID into NxN meshes; default 10. See also the appearance attribute `dice', which makes this command obsolete.

`(dimension [N])' Sets or reads the space dimension for N-dimensional viewing. (Since calculations are done using homogeneous coordinates, this means matrices are (N+1)x(N+1).) With no arguments, returns the current dimension, or 0 if N-dimensional viewing has not been enabled.

`(dither CAM-ID {on|off|toggle})' Turn dithering on or off in that camera.

`(draw CAM-ID)' Draw the view in CAM-ID, if it needs redrawing. See also `redraw'.

`(echo ...)' Write the given data to the special file `-'. Strings are written literally; lisp expressions are evaluated and their values written. If received from an external program, `echo' sends to the program's input. Otherwise writes to geomview's own standard output (typically the terminal).

`(emodule-clear)' Clears the geomview application (external module) browser.

`(emodule-define NAME SHELL-COMMAND ...)' Define an external module called NAME, which then appears in the external-module browser. The SHELL-COMMAND string is a UNIX shell command which invokes the module. See emodule-run for discussion of external modules.

`(emodule-defined `modulename')' If the given external-module name is known, returns the name of the program invoked when it's run as a quoted string; otherwise returns nil. `(echo (emodule-defined `name'))' prints the string.

`(emodule-isrunning NAME)' Returns Lt if the emodule NAME is running, or Lnil if it is not running. NAME is searched for in the names as they appear in the browser and in the shell commands used to execute the external modules (not including arguments).

`(emodule-path)' Returns the current search path for external modules. Note: to actually see the value returned by this function you should wrap it in a call to echo: (echo (emodule-path)). See also set-emodule-path.

`(emodule-run SHELL-COMMAND ARGS...)' Runs the given SHELL-COMMAND (a string containing a UNIX shell command) as an external module. The module's standard output

Geometry Center Thu Dec 12 02:41:23 CST 1996 6

Geomview(5) Geomview(5)

is taken as geomview commands; responses (written to filename `-') are sent to the module's standard input. The shell command is interpreted by /bin/sh, so e.g. I/O redirection may be used; a program which prompts the user for input from the terminal could be run with: (emodule-run yourprogram <&2) If not already set, the environment variable $MACHTYPE is set to the name of the machine type. Input and output connections to geomview are dropped when the shell command terminates. Clicking on a running program's module-browser entry sends the signal SIGHUP to the program. For this to work, programs should avoid running in the background; those using FORMS or GL should call foreground() before the first FORMS or winopen() call. See also emodule-define, emodule-start.

`(emodule-sort)' Sorts the modules in the application browser alphabetically.

`(emodule-start NAME)' Starts the external module NAME, defined by emodule-define. Equivalent to clicking on the corresponding module-browser entry.

`(emodule-transmit NAME LIST)' Places LIST into external module NAME's standard input. NAME is searched for in the names of the modules as they appear in the External Modules browser and then in the shell commands used to execute the external modules. Does nothing if modname is not running.

`(escale GEOM-ID FACTOR)' Same as scale but multiplies by exp(scale). Obsolete.

`(event-keys {on|off})' Turn keyboard events on or off to enable/disable keyboard shortcuts.

`(event-mode MODESTRING)' Set the mouse event (motion) mode; MODESTRING should be one of the following strings:

1. "[r] Rotate"

2. "[t] Translate"

3. "[z] Cam Zoom"

4. "[s] Geom Scale"

5. "[f] Cam Fly"

6. "[o] Cam Orbit"

7. "[le] Edit Lights"

`(event-pick {on|off})' Turn picking on or off.

`(evert GEOM-ID [yes|no])' Set the normal eversion state of GEOM-ID. If the second argument is omitted, toggle the eversion state.

`(exit)' Terminates geomview.

`(ezoom GEOM-ID FACTOR)' Same as zoom but multiplies by exp(zoom). Obsolete.

`(freeze CAM-ID)'

Geometry Center Thu Dec 12 02:41:23 CST 1996 7

Geomview(5) Geomview(5)

Freeze CAM-ID; drawing in this camera's window is turned off until it is explicitly redrawn with `(redraw CAM-ID)', after which time drawing resumes as normal.

`(geometry GEOM-ID [GEOMETRY])' Specify the geometry for GEOM-ID. GEOMETRY is a string giving an OOGL geometry specification. If no object called GEOM-ID exists, it is created; in this case the GEOMETRY argument is optional, and if omitted, the new object GEOM-ID is given an empty geometry.

`(geomview-version)' Returns a string representing the version of geomview that is running.

`(hdefine `geometry'|`camera'|`transform'|`window' name value)' Sets the value of a handle of a given type. (hdefine <type> <name> <value>) is generally equivalent to (read <type> { define <name> <value> }) except that the assignment is done when hdefine is executed, (possibly not at all if inside a conditional statement), while the `read ... define' performs assignment as soon as the text is read.

`(help [command])' Command may include `*'s as wildcards; see also `??' One-line command help; lists names only if multiple commands match.

`(hmodel CAMID {virtual|projective|conformal})' Set the model used to display geometry in this camera; see also `space'.

`(hsphere-draw CAMID [yes|no])' Say whether to draw a unit sphere: the sphere at infinity in hyperbolic space, and a reference sphere in Euclidean and spherical spaces. If the second argument is omitted, `yes' is assumed.

`(if TEST EXPR1 [EXPR2])' Evaluates TEST; if TEST returns a non-nil value, returns the value of EXPR1. If TEST returns nil, returns the value of EXPR2 if EXPR2 is present, otherwise returns nil.

`(inhibit-warning STRING)' Inhibit warning inhbits geomview from displaying a particular warning message determined by STRING. At present there are no warning messages that this applies to, so this command is rather useless.

`(input-translator "#prefix_string" "Bourne-shell-command")' Defines an external translation program for special input types. When asked to read a file which begins with the specified string, geomview invokes that program with standard input coming from the given file.

Geometry Center Thu Dec 12 02:41:23 CST 1996 8

Geomview(5) Geomview(5)

The program is expected to emit OOGL geometric data to its standard output. In this implementation, only prefixes beginning with # are recognized. Useful as in (input-translator "#VRML" "vrml2oogl")

`(interest (COMMAND [args]))'

Allows you to express interest in a command. When geomview executes that command in the future it will echo it to the communication pool from which the interest command came. COMMAND can be any command. Args specify restrictions on the values of the arguments; if args are present in the interest command, geomview will only echo calls to the command in which the arguments match those given in the interest command. Two special argument values may appear in the argument list. `*' matches any value. `nil' matches any value but supresses the reporting of that value; its value is reported as `nil'.

The purpose of the interest command is to allow external modules to find out about things happening inside geomview. For example, a module interested in knowing when a geom called `foo' is deleted could say `(interest (delete foo))' and would receive the string `(delete foo)' when foo is deleted.

Picking is a special case of this. For most modules interested in pick events the command `(interest (pick world))' is sufficient. This causes geomview to send a string of the form `(pick world ...)' every time a pick event (right mouse double click). See the `pick' command for details.

`(lines-closer CAM-ID DIST)' Draw lines (including edges) closer to the camera than polygons by DIST / 10^5 of the Z-buffer range. DIST = 3.0 by default. If DIST is too small, a line lying on a surface may be dotted or invisible, depending on the viewpoint. If DIST is too large, lines may appear in front of surfaces that they actually lie behind. Good values for DIST vary with the scene, viewpoint, and distance between near and far clipping planes. This feature is a kludge, but can be helpful.

`(load filename [command|geometry|camera])' Loads the given file into geomview. The optional second argument specifies the type of data it contains, which may be `command' (geomview commands), `geometry' (OOGL geometric data), or `camera' (OOGL camera definition). If omitted, attempts to guess about the file's contents. Loading geometric data creates a new visible object; loading a camera opens a new window; loading a command file executes those commands.

`(load-path)' Returns the current search path for command, geometry, etc. files. Note: to actually see the value returned by this function you should wrap it in a call to echo: (echo (load-path)).

Geometry Center Thu Dec 12 02:41:23 CST 1996 9

Geomview(5) Geomview(5)

See also set-load-path.

`(look [objectID] [cameraID])' Rotates the named camera to point toward the center of the bounding box of the named object (or the origin in hyperbolic or spherical space). In Euclidean space, moves the camera forward or backward until the object appears as large as possible while still being entirely visible. Equivalent to progn ( (look-toward [objectID] [cameraID] {center | origin}) [(look-encompass [objectID] [cameraID])] ) If objectID is not specified, it is assumed to be World. If cameraID is not specified, it is assumed to be targetcam.

`(look-encompass [objectID] [cameraID])' Moves cameraID backwards or forwards until its field of view surrounds objectID. This routine works only in Euclidean space. If objectID is not specified, it is assumed to be the world. If cameraID is not specified, it is assumed to be the targetcam. See also (look-encompass-size).

`(look-encompass-size [view-fraction clip-ratio near-margin far-margin])' Sets/returns parameters used by (look-encompass). view-fraction is the portion of the camera window filled by the object, clip-ratio is the max allowed ratio of near-to-far clipping planes. The near clipping plane is 1/near-margin times closer than the near edge of the object, and the far clipping plane is far-margin times further away. Returns the list of current values. Defaults: .75 100 0.1 4.0

`(look-recenter [objectID] [cameraID])' Translates and rotates the camera so that it is looking in the -z direction (in objectID's coordinate system) at the center of objectID's bounding box (or the origin of the coordinate system in non-Eudlidean space). In Euclidean space, the camera is also moved as close as possible to the object while allowing the entire object to be visible. Also makes sure that the y-axes of objectID and cameraID are parallel.

`(look-toward [objectID] [cameraID] [origin | center])' Rotates the named camera to point toward the origin of the object's coordinate system, or the center of the object's bounding box (in non-Euclidean space, the origin will be used automatically). Default objectID is the world, default camera is targetcam, default location to point towards is the center of the bounding box.

`(merge {window|camera} CAM-ID { WINDOW or CAMERA ... } )' Modify the given window or camera, changing just those properties specified in the last argument. E.g. (merge camera `Camera' { far 20 }) sets Camera's far clipping plane to 20 while leaving

Geometry Center Thu Dec 12 02:41:23 CST 1996 10

Geomview(5) Geomview(5)

other attributes untouched.

`(merge-ap GEOM-ID APPEARANCE)' Merge in some appearance characteristics to GEOM-ID. Appearance parameters include surface and line color, shading style, line width, and lighting.

`merge-base-ap is a synonym for merge-baseap.'

`(merge-baseap APPEARANCE)' Merge in some appearance characteristics to the base default appearance (applied to every geom before its own apperance). Lighting is typically included in the base appearance.

`(morehelp command)' `command' may include `*' wildcards. Prints more info than `(help command)'.

`(name-object ID NAME)' Assign a new NAME (a string) to ID. A number is appended if that name is in use (for example, `foo' -> `foo<2>'). The new name, possibly with number appended, may be used as object's id thereafter.

`(ND-axes CAMID [CLUSTERNAME [Xindex Yindex Zindex]])' In our model for N-D viewing (enabled by (dimension)), objects in N-space are viewed by N-dimensional *camera clusters*. Each real camera window belongs to some cluster, and shows & manipulates a 3-D axis-aligned projected subspace of the N-space seen by its cluster. Moving one camera in a cluster affects its siblings.

The ND-axes command configures all this. It specifies a camera's cluster membership, and the set of N-space axes which become the 3-D camera's X, Y, and Z axes. Axes are specified by their indices, from 0 to N-1 for an N-dimensional space. Cluster CLUSTERNAME is implicitly created if not previously known. To read a camera's configuration, use `(echo (ND-axes CAMID))'.

`(ND-color CAMID' [ (( [ID] (x0 x1 x2 ... xn) v r g b a v r g b a ... ) ((x0 ... xn) v r g b a v r g b a ...) ...)] ) Specifies a function, applied to each N-D vertex, which determines the colors of N-dimensional objects as shown in camera CAMID. Each coloring function is defined by a vector (in ID's coordinate system) [x0 x1 ... xn] and by a sequence of value (v)/color(r g b a) tuples, ordered by increasing v. The inner product v = P.[x] is linearly interpolated in this table to give a color. If ID is omitted, the (xi) vector is assumed in universe coordinates. The ND-color command specifies a list of such functions; each vertex is colored by their sum (so e.g. green intensity could indicate projection along one axis while red indicated another. An empty list, as in (ND-color CAMID ()), suppresses coloring. With no second argument, (ND-color CAMID) returns that camera's

Geometry Center Thu Dec 12 02:41:23 CST 1996 11

Geomview(5) Geomview(5)

color-function list. Even when coloring is enabled, objects tagged with the `keepcolor' appearance attribute are shown in their natural colors.

`(ND-xform OBJID [ntransform { idim odim ... }])' Sets or returns the N-D transform of the given object. In dimension N, this is an (N+1)x(N+1) matrix. Note that all cameras in a camera-cluster have the same N-D transform.

`(ND-xform-get ID [from-ID])' Returns the N-D transform of the given object in the coordinate system of from-ID (default `universe'), in the sense <point-in-ID-coords> * Transform = <point-in-from-ID-coords>

`(new-alien name [GEOMETRY])' Create a new alien (geom not in the world) with the given name (a string). GEOMETRY is a string giving an OOGL geometry specification. If GEOMETRY is omitted, the new alien is given an empty geometry. If an object with that name already exists, the new alien is given a unique name. The light beams that are used to move around the lights are an example of aliens. They're drawn but are not controllable the way ordinary objects are: they don't appear in the object browser and the user can't move them with the normal motion modes.

`(new-camera name [CAMERA])' Create a new camera with the given name (a string). If a camera with that name already exists, the new object is given a unique name. If CAMERA is omitted a default camera is used.

`(new-center [id])' Stop id, then set id's transform to the identity. Default id is target. Also, if the id is a camera, calls (look-recenter World id). The main function of the call to (look-recenter) is to place the camera so that it is pointing parallel to the z axis toward the center of the world.

`(new-geometry name [GEOMETRY])' Create a new geom with the given name (a string). GEOMETRY is a string giving an OOGL geometry specification. If GEOMETRY is omitted, the new object is given an empty geometry. If an object with that name already exists, the new object is given a unique name.

`(new-reset)' Equivalent to (progn (new-center ALLGEOMS)(new-center ALLCAMS))

`(NeXT)' Returns t if running on a NeXT, nil if not

Geometry Center Thu Dec 12 02:41:23 CST 1996 12

Geomview(5) Geomview(5)

`(normalization GEOM-ID {each|none|all|keep})' Set the normalization status of GEOM-ID. `none' suppresses all normalization. `each' normalizes the object's bounding box to fit into the unit sphere, with the center of its bounding box translated to the origin. The box is scaled such that its long diagonal, sqrt((xmax-xmin)^2 + (ymax-ymin)^2 + (zmax-zmin)^2), is 2. `all' resembles `each', except when an object is changing (e.g. when its geometry is being changed by an external program). Then, `each' tightly fits the bounding box around the object whenever it changes and normalizes accordingly, while `all' normalizes the union of all variants of the object and normalizes accordingly. `keep' leaves the current normalization transform unchanged when the object changes. It may be useful to apply `each' or `all' normalization apply to the first version of a changing object to bring it in view, then switch to `keep'.

`(pick COORDSYS GEOMID G V E F P VI EI FI)' The pick command is executed internally in response to pick events (right mouse double click).

COORDSYS = coordinate system in which coordinates of the following arguments are specified. This can be: world: world coord sys self: coord sys of the picked geom (GEOMID) primitive: coord sys of the actual primitive within the picked geom where the pick occurred. GEOMID = id of picked geom G = picked point (actual intersection of pick ray with object) V = picked vertex, if any E = picked edge, if any F = picked face P = path to picked primitive [0 or more] VI = index of picked vertex in primitive EI = list of indices of endpoints of picked edge, if any FI = index of picked face

External modules can find out about pick events by registering interest in calls to `pick' via the `interest' command.

`(pick-invisible [yes|no])' Selects whether picks should be sensitive to objects whose appearance makes them invisible; default yes. With no arguments, returns current status.

`(pickable GEOM-ID {yes|no})' Say whether or not GEOM-ID is included in the pool of objects that could be returned from the pick command.

Geometry Center Thu Dec 12 02:41:23 CST 1996 13

Geomview(5) Geomview(5)

`(position objectID otherID)' Set the transform of objectID to that of otherID.

`(position-at objectID otherID [center | origin])' Translate objectID to the center of the bounding box or the origin of the coordinate system of otherID (parallel translation). Default is center.

`(position-toward objectID otherID [center | origin])' Rotate objectID so that the center of the bounding box or the origin of the coordinate system of the otherID lies on the positive z-axis of the first object. Default is the center of the bounding box.

`(progn STATEMENT [ ... ])' evaluates each STATEMENT in order and returns the value of the last one. Use progn to group a collection of commands together, forcing them to be treated as a single command.

`quit is a synonym for `exit''

`(quote EXPR)' returns the symbolic lisp expression EXPR without evaluating it.

`(rawevent dev val x y t)' Enter the specified raw event into the event queue. The arguments directly specify the members of the event structure used internally by geomview. This is the lowest level event handler and is not intended for general use.

`(rawpick CAMID X Y)' Process a pick event in camera CAMID at location (X,Y) given in integer pixel coordinates. This is a low-level procedure not intended for external use.

`(read {geometry|camera|transform|command} {GEOMETRY or CAMERA or ...})' Read and interpret the text in ... as containing the given type of data. Useful for defining objects using OOGL reference syntax, e.g.

(geometry thing { INST transform : T geom : fred }) (read geometry { define fred QUAD 1 0 0 0 1 0 0 0 1 1 0 0 }) (read transform { define T <myfile})

`(real-id ID)' Returns a string canonically identifying the given ID, or `nil' if the object does not exist. Examples: (if (real-id fred) (delete fred)) deletes `fred' if it exists but reports no error if it doesn't, and (if (= (real-id targetgeom) (real-id World)) () (delete targetgeom)) deletes `targetgeom' if it is different from the World.

`(redraw CAM-ID)'

Geometry Center Thu Dec 12 02:41:23 CST 1996 14

Geomview(5) Geomview(5)

States that the view in CAM-ID should be redrawn on the next pass through the main loop or the next invocation of `draw'.

`(regtable) --- shows the registry table'

`(rehash-emodule-path)' Rebuilds the application (external module) browser by reading all .geomview-* files in all directories on the emodule-path. Primarily intended for internal use; any applications defined by (emodule-define ...) commands outside of the .geomview-* files on the emodule-path will be lost. Does not sort the entries in the brower; see (emodule-sort) for that.

`(replace-geometry GEOM-ID PART-SPECIFICATION GEOMETRY)' Replace a part of the geometry for GEOM-ID.

`(rib-display [frame|tiff] FILEPREFIX)' Set Renderman display to framebuffer (popup screen window) or a TIFF format disk file. FILEPREFIX is used to construct names of the form `prefixNNNN.suffix'. (i.e. foo0000.rib) The number is incremented on every call to `rib-snapshot' and reset to 0000 when `rib-display' is called. TIFF files are given the same prefix and number as the RIB file (i.e. foo0004.rib generates foo0004.tiff). The default FILEPREFIX is `geom' and the default format is TIFF. (Note that geomview just generates a RIB file, which must then be rendered.)

`(rib-snapshot CAM-ID [filename])' Write Renderman snapshot (in RIB format) of CAM-ID to <filename>. If no filename specified, see `rib-display' for explanation of the filename used.

`(scale GEOM-ID FACTOR [FACTORY FACTORZ])' Scale GEOM-ID, multiplying its size by FACTOR. The factors should be positive numbers. If FACTORY and FACTORZ are present and non-zero, the object is scaled by FACTOR in x, by FACTORY in y, and by FACTORZ in z. If only FACTOR is present, the object is scaled by FACTOR in x, y, and z. Scaling only really makes sense in Euclidean space. Mouse-driven scaling in other spaces is not allowed; the scale command may be issued in other spaces but should be used with caution because it may cause the data to extend beyond the limits of the space.

`(scene CAM-ID [GEOMETRY])' Make CAM-ID look at GEOMETRY instead of at the universe.

`(set-clock TIME)' Adjusts the clock for this command stream to read TIME (in seconds) as of the moment the command is received. See also sleep-until, clock.

`(set-conformal-refine CMX [N [SHOWEDGES]])' Sets the parameters for the refinement algorithm used in drawing in the conformal model. CMX is the cosine of the maximum angle an edge can bend before it is refined. Its value should be between

Geometry Center Thu Dec 12 02:41:23 CST 1996 15

Geomview(5) Geomview(5)

-1 and 1; the default is 0.95; decreasing its value will cause less refinement. N is the maximum number of iterations of refining; the default is 6. SHOWEDGES, which should be `no' or `yes', determines whether interior edges in the refinement are drawn.

`(set-emodule-path (PATH1 ... PATHN))' Sets the search path for external modules. The PATHi should be pathnames of directories containing, for each module, the module's executable file and a .geomview-<modulename> file which contains an (emodule-define ...) command for that module. This command implicitly calls (rehash-emodule-path) to rebuild the application brower from the new path setting. The special directory name `+' is replaced by the existing path, so e.g. (set-emodule-path (mydir +)) prepends mydir to the path.

`(set-load-path (PATH1 ... PATHN))' Sets search path for command, geometry, etc. files. The PATHi are strings giving the pathnames of directories to be searched. The special directory name `+' is replaced by the existing path, so e.g. (set-load-path (mydir +)) prepends mydir to the path.

`(set-motionscale X)' Set the motion scale factor to X (default value 0.5). These commands scale their motion by an amount which depends on the distance from the frame to the center and on the size of the frame. Specifically, they scale by dist + scaleof(frame) * motionscale where dist is the distance from the center to the frame and motionscale is the motion scale factor set by this function. Scaleof(frame) measures the size of the frame object.

`(setenv name string) sets the environment variable `name' to the value'

STRING; the name is visible to geomview (as in pathnames containing `$name') and to processes it creates, e.g. external modules.

`(sgi)' Returns t if running on an sgi machine, nil if not

`(shell SHELL-COMMAND)' Execute the given UNIX SHELL-COMMAND using /bin/sh. Geomview waits for it to complete and will be unresponsive until it does. A synonym is `!'.

`(sleep-for TIME)' Suspend reading commands from this stream for TIME seconds. Commands already read will still be executed; `sleep-for' inside `progn' won't delay execution of the rest of the progn's contents.

`(sleep-until TIME)' Suspend reading commands from this stream until TIME (in seconds). Commands already read will still be executed; `sleep-until' inside `progn' won't delay execution of the rest of the progn's contents.

Geometry Center Thu Dec 12 02:41:23 CST 1996 16

Geomview(5) Geomview(5)

Time is measured according to this stream's clock, as set by `set-clock'; if never set, the first sleep-until sets it to 0 (so initially (sleep-until TIME) is the same as (sleep-for TIME)). Returns the number of seconds until TIME.

`(snapshot CAM-ID FILENAME [FORMAT [XSIZE [YSIZE]]])' Save a snapshot of CAM-ID in the FILENAME (a string). The FORMAT argument is optional; it may be `ppmscreen', `sgi', `ps', or `ppm'. A `ppmscreen' snapshot is created by reading the image directly from the given window; the window is popped above other windows and redrawn first, then its contents are written as a PPM format image. With `ps', dumps a Postscript picture representing the view from that window; hidden-surface removal might be incorrect. With `ppm', dumps a PPM-format image produced by geomview's internal software renderer; this may be of arbitrary size. If the FILENAME argument begins with the vertical bar `|', it's interpreted as a /bin/sh command to which the PPM or PS data should be piped. Optional XSIZE and YSIZE values are relevant only for `ppm' format, and render to a window of that size (or scaled to that size, with aspect fixed, if only XSIZE is given)

`(soft-shader CAM-ID {on|off|toggle})' Select whether to use software or hardware shading in that camera.

`(space {euclidean|hyperbolic|spherical})' Set the space associated with the world.

`(stereowin CAM-ID [no|horizontal|vertical|colored] [gapsize])' Configure CAM-ID as a stereo window. no: entire window is a single pane, stereo disabled horizontal: split left/right: left is stereo eye#0, right is #1. vertical: split top/bottom: bottom is eye#0, top is #1. colored: panes overlap, red is stereo eye#0, cyan is #1.

A gap of `gapsize' pixels is left between subwindows; if omitted, subwindows are adjacent. If both layout and gapsize are omitted, e.g. (stereowin CAM-ID), returns current settings as a `(stereowin ...)' command list. This command doesn't set stereo projection; use `merge camera' or `camera' to set the stereyes transforms, and `merge window' or `window' to set the pixel aspect ratio & window position if needed.

`(time-interests deltatime initial prefix [suffix])' Indicates that all interest-related messages, when separated by at least `deltatime' seconds of real time, should be preceded by the string `prefix' and followed by `suffix'; the first message is preceded by `initial'. All three are printf format strings, whose argument is the current clock time (in seconds) on that stream. A `deltatime' of zero timestamps every message. Typical usage: (time-interests .1 `(set-clock %g)' `(sleep-until %g)') or (time-interests .1 `(set-clock %g)' "(sleep-until %g) (progn (set-clock %g)" ")") or (time-interests .1 "(set-clock %g)" "(if (> 0 (sleep-until %g)) (" "))".

Geometry Center Thu Dec 12 02:41:23 CST 1996 17

Geomview(5) Geomview(5)

`(transform objectID centerID frameID [rotate|translate|translate-scaled|scale] x y z [dt] [`smooth'])' Apply a motion (rotation, translation, scaling) to object `objectID'; that is, construct and concatenate a transformation matrix with objectID's transform The 3 IDs involved are the object that moves, the center of motion, and the frame of reference in which to apply the motion. The center is easiest understood for rotations: if centerID is the same as objectID then it will spin around its own axes; otherwise the moving object will orbit the center object. Normally frameID, in whose coordinate system the (mouse) motions are interpreted, is `focus', the current camera. Translations can be scaled proportional to the distance between the target and the center. Support for spherical and hyperbolic as well as Euclidean space is built-in: use the `space' command to change spaces. With type `rotate' x, y, and z are floats specifying angles in RADIANS. For types `translate' and `translate-scaled' x, y, and z are floats specifying distances in the coordinate system of the center object. The optional `dt' field allows a simple form of animation; if present, the object moves by just that amount during approximately `dt' seconds, then stops. If present and followed by the `smooth' keyword, the motion is animated with a 3t^2-2t^3 function, so as to start and stop smoothly. If absent, the motion is applied immediately.

`(transform-incr objectID centerID frameID [rotate|translate|translate-scaled|scale] x y z [dt])' Apply continuing motion: construct a transformation matrix and concatenate it with the current transform of objectID every refresh (sets objectID's incremental transform). Same syntax as transform. If optional `dt' argument is present, the object is moved at each time step such that its average motion equals one instance of the motion per `dt' seconds. E.g. (transform-incr World World World rotate 6.28318 0 0 10.0) rotates the World about its X axis at 1 turn (2pi radians) per 10 seconds.

`(transform-set objectID centerID frameID [rotate|translate|translate-scaled|scale] x y z)' Set objectID's transform to the constructed transform. Same syntax as transform.

`(ui-center ID)' Set the center for user interface (i.e. mouse) controlled motions to object ID.

`ui-emotion-program is an obsolete command.' Use its new eqivalent `emodule-define' instead.

`ui-emotion-run is an obsolete command.' Use its new eqivalent `emodule_start' instead.

`(ui-freeze [on|off])' Toggle updating user interface panels. Off by default.

`(ui-panel PANELNAME {on|off} [ WINDOW ] )' Do or don't display the given user-interface panel.

Geometry Center Thu Dec 12 02:41:23 CST 1996 18

Geomview(5) Geomview(5)

Case is ignored in panel names. Current PANELNAMEs are: geomview main panel tools motion controls appearance appearance controls cameras camera controls lighting lighting controls obscure obscure controls materials material properties controls command command entry box credits geomview credits By default, the `geomview' and `tools' panels appear when geomview starts. If the optional Window is supplied, a `position' clause (e.g. (ui-panel obscure on { position xmin xmax ymin ymax }) sets the panel's default position. (Only xmin and ymin values are actually used.) A present but empty Window, e.g. `(ui-panel obscure on {})' causes interactive positioning.

`(ui-target ID [yes|no])' Set the target of user actions (the selected line of the target object browser) to ID. The second argument specifies whether to make ID the current object regardless of its type. If `no', then ID becomes the current object of its type (geom or camera). The default is `yes'. This command may result in a change of motion modes based on target choice.

`(uninterest (COMMAND [args]))' Undoes the effect of an `interest' command. (COMMAND [args]) must be identical to those used in the `interest' command.

`(update [timestep_in_seconds])' Apply each incremental motion once. Uses timestep if it's present and nonzero; otherwise motions are proportional to elapsed real time.

`(update-draw CAM-ID [timestep_in_seconds])' Apply each incremental motion once and then draw CAM-ID. Applies `timestep' seconds' worth of motion, or uses elapsed real time if `timestep' is absent or zero.

`(window CAM-ID WINDOW)' Specify attributes for the window of CAM-ID, e.g. its size or initial position, in the OOGL Window syntax. The special CAM-ID `default' specifies properties of future windows (created by `camera' or `new-camera').

`(winenter CAM-ID)' Tell geomview that the mouse cursor is in the window of CAM-ID. This function is for development purposes and is not intended for general use.

`(write {command,geometry,camera,transform,window} FILENAME [ID|(ID ...)] [self|world|universe|otherID])' write description of ID in given format to FILENAME. Last parameter chooses coordinate system for geometry & transform:

Geometry Center Thu Dec 12 02:41:23 CST 1996 19

Geomview(5) Geomview(5)

self: just the object, no transformation or appearance (geometry only) world: the object as positioned within the World. universe: object's position in universal coordinates; includes Worldtransform other ID: the object transformed to otherID's coordinate system.

A filename of `-' is a special case: data are written to the stream from which the 'write' command was read. For external modules, the data are sent to the module's standard input. For commands not read from an external program, `-' means geomview's standard output. (See also the `command' command.)

The ID can either be a single id or a parenthesized list of ids, like `g0' or `(g2 g1 dodec.off)'.

`(write-comments FILENAME GEOMID PICKPATH)' write OOGL COMMENT objects in the GEOMID hierarchy at the level of the pick path to FILENAME. Specifically, COMMENTS at level (a b c ... f g) will match pick paths of the form (a b c ... f *) where * includes any value of g, and also any values of possible further indices h,i,j, etc. The pick path (returned in the `pick' command) is a list of integer counters specifying a subpart of a hierarchical OOGL object. Descent into a complex object (LIST or INST) adds a new integer to the path. Traversal of simple objects increments the counter at the current level. Individual COMMENTS are enclosed by curly braces, and the entire string of zero, one, or more COMMENTS (written in the order in which they are encountered during hierarchy traversal) is enclosed by parentheses.

Note that arbitrary data can only be passed through the OOGL libraries as full-fledged OOGL COMMENT objects, which can be attached to other OOGL objects via the LIST type as described above. Ordinary comments in OOGL files (i.e. everything after '#' on a line) are ignored at when the file is loaded and cannot be returned.

`(write-sexpr FILENAME LISPOBJECT)' Writes the given LISPOBJECT to FILENAME. This function is intended for internal debugging use only.

`(xform ID TRANSFORM)' Concatenate TRANSFORM with the current transform of the object (apply TRANSFORM to object ID).

`(xform-incr ID TRANSFORM)' Apply continual motion: concatenate TRANSFORM with the current transform of the object every refresh (set object ID's incremental transform to TRANSFORM).

`(xform-set ID TRANSFORM)' Overwrite the current object transform with TRANSFORM (set

Geometry Center Thu Dec 12 02:41:23 CST 1996 20

Geomview(5) Geomview(5)

object ID's transform to TRANSFORM).

`(zoom CAM-ID FACTOR)' Zoom CAM-ID, multiplying its field of view by FACTOR. FACTOR should be a positive number.

Info file: geomview, -*-Text-*-

produced by texinfo-format-buffer

from file: geomview.tex

Geometry Center Thu Dec 12 02:41:23 CST 1996 21