Import brltty

grub-core/braille/brltty/Documents/brltty.1.in

@@ -0,0 +1,776 @@
+.TH "BRLTTY" "1" "Oct 2011" "brltty 4.3" "The BRLTTY Project"
+.SH NAME
+brltty \- refreshable braille display driver for Linux/Unix
+.SH SYNOPSIS
+\fBbrltty \fR[\fIoption\fR ...]
+.SH DESCRIPTION
+.B brltty
+is a background process (daemon)
+which provides access to the console screen (when in text mode)
+for a blind person using a refreshable braille display.
+It drives the braille display,
+and provides complete screen review functionality.
+Some speech capability has also been incorporated.
+.SH OPTIONS
+Options can be passed to
+.B brltty
+in a number of ways.
+From most to least influential, these are:
+.IP 1. 4
+Command Line Options
+.IP 2. 4
+Boot Parameters
+.IP 3. 4
+Environment Variables
+(if the
+.B -E
+.RB "(" "--environment-variables" ")"
+option is in effect)
+.IP 4. 4
+The Configuration File
+.IP 5. 4
+Built-in Defaults
+.SS "Command Line Options"
+The options are processed sequentially from left to right.
+If an option is specified more than once,
+or in case of a conflict,
+the rightmost specification takes precedence.
+.PP
+The following options are supported:
+.TP
+\fB-a \fItable\fR (\fB--attributes-table=\fR)
+The path to the attributes table.
+Relative paths are anchored at
+.BR "@TABLES_DIRECTORY@" "."
+The
+.B ".atb"
+extension is optional.
+The built-in default is
+.BR "attributes.atb" "."
+.TP
+\fB-b \fIdriver\fB,\fR...|\fBauto\fR (\fB--braille-driver=\fR)
+The driver for the braille display
+(see Driver Specification).
+The built-in default is \fBauto\fR.
+.TP
+\fB-c \fItable\fR (\fB--contraction-table=\fR)
+The path to the contraction table.
+Relative paths are anchored at
+.BR "@TABLES_DIRECTORY@" "."
+The
+.B ".ctb"
+extension is optional.
+.TP
+\fB-d \fIdevice\fB,\fR... (\fB--braille-device=\fR)
+The device to which the braille display is connected.
+The built-in default is \fB@braille_device@\fR.
+.RS
+.PP
+The general form of a braille device specification is
+\fIqualifier\fB:\fIdata\fR.
+For backward compatibility with earlier releases,
+if the qualifier is omitted then
+.B serial:
+is assumed.
+The following device types are supported:
+.TP
+.B Bluetooth
+For a bluetooth device, specify \fBbluez:\fIaddress\fR.
+The address must be six two-digit hexadecimal numbers separated by colons, e.g.
+.BR "01:23:45:67:89:AB" "."
+.TP
+.B Serial
+For a serial device, specify \fBserial:\fI/path/to/device\fR.
+The
+.B serial:
+qualifier is optional (for backward compatibility).
+If a relative path is given then it's anchored at
+.B /dev/
+(the usual location where devices are defined on a Unix-like system).
+The following device specifications all refer
+to the primary serial device:
+.BR "serial:/dev/@first_serial_device@" ","
+.BR "serial:@first_serial_device@" ","
+.BR "/dev/@first_serial_device@" ","
+.BR "@first_serial_device@" "."
+.TP
+.B USB
+For a USB device, specify \fBusb:\fR.
+.B brltty
+will search for the first USB device which
+matches the braille display driver being used.
+If this is inadequate,
+e.g. if you have more than one USB braille display which requires the same driver,
+then you can refine the device specification
+by appending the serial number of the display to it, e.g.
+.BR "usb:12345" "."
+N.B.:
+The "identification by serial number" feature doesn't work for some models
+because some manufacturers
+either don't set the USB serial number descriptor at all
+or do set it but not to a unique value.
+.PP
+A comma-delimited list of braille devices may be specified.
+If this is done then autodetection is performed on each listed device in sequence.
+This feature is particularly useful if you have
+a braille display with more than one interrface,
+e.g. both a serial and a USB port.
+.RE
+.TP
+\fB-e\fR (\fB--standard-error\fR)
+Write logs to standard error rather than to the system log (useful for debugging).
+.TP
+\fB-f \fIfile\fR (\fB--configuration-file=\fR)
+The path to the configuration file.
+Relative paths are anchored at the current working directory.
+The built-in default is
+.BR "@CONFIGURATION_DIRECTORY@/@CONFIGURATION_FILE@" "."
+.TP
+\fB-h\fR (\fB--help\fR)
+Print a command line usage summary and then exit.
+.TP
+\fB-i \fIname\fR (\fB--speech-input=\fR)
+The file system object
+(FIFO, named pipe, named socket, etc)
+which gives other applications access to
+.BR brltty 's
+speech driver for text-to-speech conversion.
+It's created at start-up and removed at termination.
+Relative paths are anchored at the current working directory.
+The built-in default is
+that the file system object is not created.
+.TP
+\fB-l \fIlevel\fR (\fB--log-level=\fR)
+The minimum severity level for messages written to the log.
+Any of the following numbers,
+or any abbreviation of their corresponding names,
+may be specified:
+.RS
+.TP 4
+.B 0
+.B emergency
+.TP 4
+.B 1
+.B alert
+.TP 4
+.B 2
+.B critical
+.TP 4
+.B 3
+.B error
+.TP 4
+.B 4
+.B warning
+.TP 4
+.B 5
+.B notice
+.TP 4
+.B 6
+.B information
+.TP 4
+.B 7
+.B debug
+.RE
+.PP
+The built-in default is
+.BR "notice" "."
+.TP
+\fB-m \fIdevice\fR (\fB--midi-device=\fR)
+The device to use for the Musical Instrument Digital Interface.
+For ALSA it's \fIclient\fB:\fIport\fR,
+where each may be either a number or a case-sensitive substring of its name.
+For other interfaces it's the full path to an appropriate system device.
+The built-in default is:
+.RS
+.IP Linux/ALSA 12
+the first available MIDI output port
+.IP Linux/OSS 12
+.B /dev/sequencer
+.RE
+.TP
+\fB-n\fR (\fB--no-daemon\fR)
+Remain in the foreground (useful for debugging).
+.TP
+\fB-p \fIdevice\fR (\fB--pcm-device=\fR)
+The device to use for digital audio.
+For ALSA it's \fIname\fR[\fB:\fIargument\fB,\fR...].
+For other interfaces it's the full path to an appropriate system device.
+The built-in default is:
+.RS
+.IP FreeBSD 12
+.B /dev/dsp
+.IP Linux/ALSA 12
+.B hw:0,0
+.IP Linux/OSS 12
+.B /dev/dsp
+.IP NetBSD 12
+.B /dev/audio
+.IP OpenBSD 12
+.B /dev/audio
+.IP Qnx 12
+the preferred PCM output device
+.IP Solaris 12
+.B /dev/audio
+.RE
+.TP
+\fB-q\fR (\fB--quiet\fR)
+Suppress the start-up messages.
+This is done by reducing the default log level
+(see the
+.B -l
+.RB "(" "--log-level=" ")"
+option)
+to
+.B warning
+.RB "(" "information"
+if either
+.B -v
+.RB "(" "--verify" ")"
+or
+.B -V
+.RB "(" "--version" ")"
+is also specified).
+.TP
+\fB-r\fR (\fB--release-device\fR)
+Release the device to which the braille display is connected
+when the current screen or window can't be read.
+.TP
+\fB-s \fIdriver\fB,\fR...|\fBauto\fR (\fB--speech-driver=\fR)
+The driver for the speech synthesizer
+(see Driver Specification).
+The built-in default is \fBauto\fR.
+.TP
+\fB-t \fItable\fR (\fB--text-table=\fR)
+The path to the text table.
+Relative paths are anchored at
+.BR "@TABLES_DIRECTORY@" "."
+The
+.B ".ttb"
+extension is optional.
+The built-in default is
+.B "nabcc.ttb"
+(the North American Braille Computer Code).
+.TP
+\fB-v\fR (\fB--verify\fR)
+Print the start-up messages and then exit.
+This always includes the versions of
+.B brltty
+itself,
+the server side of its application programming interface,
+and each of the selected braille and speech drivers.
+If the
+.B -q
+.RB "(" "--quiet" ")"
+option isn't also specified
+then it also includes the values of the options after all sources have been considered.
+If more than one braille driver and/or more than one braille device
+has been specified then braille display autodetection is performed.
+If more than one speech driver
+has been specified then speech synthesizer autodetection is performed.
+.TP
+\fB-x \fIdriver\fR (\fB--screen-driver=\fR)
+The screen driver.
+The built-in default is operating system appropriate.
+.TP
+\fB-A \fIname\fB=\fIvalue\fB,\fR... (\fB--api-parameters=\fR)
+Parameters for the application programming interface.
+If the same parameter is specified more than once
+then the rightmost specification is used.
+Parameter names may be abbreviated.
+.TP
+\fB-B \fR[\fIdriver\fB:\fR]\fIname\fB=\fIvalue\fB,\fR... (\fB--braille-parameters=\fR)
+Parameters for the braille display driver.
+If the same parameter is specified more than once
+then the rightmost specification is used.
+Parameter names may be abbreviated.
+If a parameter assignment is qualified with a driver identification code
+then it's only processed if that braille display driver is being used.
+.TP
+\fB-E\fR (\fB--environment-variables\fR)
+Recognize environment variables.
+.TP
+\fB-F \fIfile\fR (\fB--preferences-file=\fR)
+The path to the preferences file.
+Relative paths are anchored at
+.BR "@STATE_DIRECTORY@" "."
+The built-in default is
+.BR "@PREFERENCES_FILE@" "."
+.TP
+\fB-I\fR (\fB--install-service\fR)
+(Windows only)
+Install
+.B brltty
+as the
+.B BrlAPI
+service so that it will be automatically started when the system is booted
+and so that applications can know that a
+.B BrlAPI
+server is running.
+.TP
+\fB-L \fIfile\fR (\fB--log-file=\fR)
+The file to which log messages are written.
+Relative paths are anchored at the current working directory.
+The default is to send log messages to the system log.
+.TP
+\fB-M \fIcsecs\fR (\fB--message-delay=\fR)
+The message hold time in hundredths of a second.
+The built-in default is
+.B 400
+(4 seconds).
+.TP
+\fB-N\fR (\fB--no-api\fR)
+Don't start the application programming interface.
+.TP
+\fB-P \fIfile\fR (\fB--pid-file=\fR)
+The full path to the process identifier file.
+If this option is supplied,
+.B brltty
+writes its process identifier (pid) into the specified file at start-up.
+The file is removed when
+.B brltty
+terminates.
+.TP
+\fB-R\fR (\fB--remove-service\fR)
+(Windows only)
+Remove the
+.B BrlAPI
+service so that
+.B brltty
+will not be automatically started when the system is booted
+and so that applications can know that no
+.B BrlAPI
+server is running.
+.TP
+\fB-S \fR[\fIdriver\fB:\fR]\fIname\fB=\fIvalue\fB,\fR... (\fB--speech-parameters=\fR)
+Parameters for the speech synthesizer driver.
+If the same parameter is specified more than once
+then the rightmost specification is used.
+Parameter names may be abbreviated.
+If a parameter assignment is qualified with a driver identification code
+then it's only processed if that speech synthesizer driver is being used.
+.TP
+\fB-U \fIcsecs\fR (\fB--update-interval=\fR)
+The braille window update interval in hundredths of a second.
+The built-in default is
+.B 4
+(25 times per second).
+.TP
+\fB-V\fR (\fB--version\fR)
+Print the versions of
+.B brltty
+itself,
+the server side of its application programming interface,
+and those drivers which were configured in at build-time,
+and then exit.
+If the
+.B -q
+.RB "(" "--quiet" ")"
+option isn't also specified
+then also print copyright information.
+.TP
+\fB-X \fIname\fB=\fIvalue\fB,\fR... (\fB--screen-parameters=\fR)
+Parameters for the screen driver.
+If the same parameter is specified more than once
+then the rightmost specification is used.
+Parameter names may be abbreviated.
+.SS "Environment Variables"
+The following environment variables are recognized if the
+.B -E
+.RB "(" "--environment-variables" ")"
+option is specified:
+.TP
+\fBBRLTTY_API_PARAMETERS=\fIname\fB=\fIvalue\fB,\fR...
+Parameters for the application programming interface.
+See the
+.B -A
+.RB "(" "--api-parameters=" ")"
+option for details.
+.TP
+\fBBRLTTY_ATTRIBUTES_TABLE=\fItable\fR
+The attributes table.
+See the
+.B -a
+.RB "(" "--attributes-table=" ")"
+option for details.
+.TP
+\fBBRLTTY_BRAILLE_DEVICE=\fIdevice\fB,\fR...
+The device to which the braille display is connected.
+See the
+.B -d
+.RB "(" "--braille-device=" ")"
+option for details.
+.TP
+\fBBRLTTY_BRAILLE_DRIVER=\fIdriver\fB,\fR...|\fBauto\fR
+The driver for the braille display.
+See the
+.B -b
+.RB "(" "--braille-driver=" ")"
+option for details.
+.TP
+\fBBRLTTY_BRAILLE_PARAMETERS=\fR[\fIdriver\fB:\fR]\fIname\fB=\fIvalue\fB,\fR...
+Parameters for the braille display driver.
+See the
+.B -B
+.RB "(" "--braille-parameters=" ")"
+option for details.
+.TP
+\fBBRLTTY_CONFIGURATION_FILE=\fIfile\fR
+The configuration file.
+See the
+.B -f
+.RB "(" "--configuration-file=" ")"
+option for details.
+.TP
+\fBBRLTTY_CONTRACTION_TABLE=\fItable\fR
+The contraction table.
+See the
+.B -c
+.RB "(" "--contraction-table=" ")"
+option for details.
+.TP
+\fBBRLTTY_MIDI_DEVICE=\fIdevice\fR
+The device to use for the Musical Instrument Digital Interface.
+See the
+.B -m
+.RB "(" "--midi-device=" ")"
+option for details.
+.TP
+\fBBRLTTY_PCM_DEVICE=\fIdevice\fR
+The device to use for digital audio.
+See the
+.B -p
+.RB "(" "--pcm-device=" ")"
+option for details.
+.TP
+\fBBRLTTY_PREFERENCES_FILE=\fIfile\fR
+The preferences file.
+See the
+.B -F
+.RB "(" "--preferences-file=" ")"
+option for details.
+.TP
+\fBBRLTTY_RELEASE_DEVICE=on\fR|\fBoff\fR
+Release the device to which the braille display is connected
+when the current screen or window can't be read.
+See the
+.B -r
+.RB "(" "--release-device" ")"
+option for details.
+.TP
+\fBBRLTTY_SCREEN_DRIVER=\fIdriver\fR
+The screen driver.
+See the
+.B -x
+.RB "(" "--screen-driver=" ")"
+option for details.
+.TP
+\fBBRLTTY_SCREEN_PARAMETERS=\fIname\fB=\fIvalue\fB,\fR...
+Parameters for the screen driver.
+See the
+.B -X
+.RB "(" "--screen-parameters=" ")"
+option for details.
+.TP
+\fBBRLTTY_SPEECH_DRIVER=\fIdriver\fB,\fR...|\fBauto\fR
+The driver for the speech synthesizer.
+See the
+.B -s
+.RB "(" "--speech-driver=" ")"
+option for details.
+.TP
+\fBBRLTTY_SPEECH_INPUT=\fIname\fR
+The file system object which gives other applications access to
+.BR brltty 's
+speech driver for text-to-speech conversion.
+See the
+.B -i
+.RB "(" "--speech-input=" ")"
+option for details.
+.TP
+\fBBRLTTY_SPEECH_PARAMETERS=\fR[\fIdriver\fB:\fR]\fIname\fB=\fIvalue\fB,\fR...
+Parameters for the speech synthesizer driver.
+See the
+.B -S
+.RB "(" "--speech-parameters=" ")"
+option for details.
+.TP
+\fBBRLTTY_TEXT_TABLE=\fItable\fR
+The text table.
+See the
+.B -t
+.RB "(" "--text-table=" ")"
+option for details.
+.SS "The Configuration File"
+Blank lines are ignored.
+If the character
+.B "#"
+occurs on any line then
+all characters from it to the end of that line are treated as a comment.
+.PP
+The following configuration directives are supported:
+.TP
+\fBapi-parameters \fIname\fB=\fIvalue\fB,\fR...
+Parameters for the application programming interface.
+See the
+.B -A
+.RB "(" "--api-parameters=" ")"
+option for details.
+.TP
+\fBattributes-table \fItable\fR
+The attributes table.
+See the
+.B -a
+.RB "(" "--attributes-table=" ")"
+option for details.
+.TP
+\fBbraille-device \fIdevice\fB,\fR...
+The device to which the braille display is connected.
+See the
+.B -d
+.RB "(" "--braille-device=" ")"
+option for details.
+.TP
+\fBbraille-driver \fIdriver\fB,\fR...|\fBauto\fR
+The driver for the braille display.
+See the
+.B -b
+.RB "(" "--braille-driver=" ")"
+option for details.
+.TP
+\fBbraille-parameters \fR[\fIdriver\fB:\fR]\fIname\fB=\fIvalue\fB,\fR...
+Parameters for the braille display driver.
+See the
+.B -B
+.RB "(" "--braille-parameters=" ")"
+option for details.
+.TP
+\fBcontraction-table \fItable\fR
+The contraction table.
+See the
+.B -c
+.RB "(" "--contraction-table=" ")"
+option for details.
+.TP
+\fBmidi-device \fIdevice\fR
+The device to use for the Musical Instrument Digital Interface.
+See the
+.B -m
+.RB "(" "--midi-device=" ")"
+option for details.
+.TP
+\fBpcm-device \fIdevice\fR
+The device to use for digital audio.
+See the
+.B -p
+.RB "(" "--pcm-device=" ")"
+option for details.
+.TP
+The preferences file.
+See the
+.B -F
+.RB "(" "--preferences-file=" ")"
+option for details.
+.TP
+\fBrelease-device on\fR|\fBoff\fR
+Release the device to which the braille display is connected
+when the current screen or window can't be read.
+See the
+.B -r
+.RB "(" "--release-device" ")"
+option for details.
+.TP
+\fBscreen-driver \fIdriver\fR
+The screen driver.
+See the
+.B -x
+.RB "(" "--screen-driver=" ")"
+option for details.
+.TP
+\fBscreen-parameters \fIname\fB=\fIvalue\fB,\fR...
+Parameters for the screen driver.
+See the
+.B -X
+.RB "(" "--screen-parameters=" ")"
+option for details.
+.TP
+\fBspeech-driver \fIdriver\fB,\fR...|\fBauto\fR
+The driver for the speech synthesizer.
+See the
+.B -s
+.RB "(" "--speech-driver=" ")"
+option for details.
+.TP
+\fBspeech-input \name\fR
+The file system object which gives other applications access to
+.BR brltty 's
+speech driver for text-to-speech conversion.
+See the
+.B -i
+.RB "(" "--speech-input=" ")"
+option for details.
+.TP
+\fBspeech-parameters \fR[\fIdriver\fB:\fR]\fIname\fB=\fIvalue\fB,\fR...
+Parameters for the speech synthesizer driver.
+See the
+.B -S
+.RB "(" "--speech-parameters=" ")"
+option for details.
+.TP
+\fBtext-table \fItable\fR
+The text table.
+See the
+.B -t
+.RB "(" "--text-table=" ")"
+option for details.
+.SS "Driver Specification"
+A braille display or speech synthesizer driver
+must be specified via its identification code:
+.RS
+.TP 4
+.B al
+Alva
+.TP 4
+.B at
+Albatross
+.TP 4
+.B ba
+BrlAPI
+.TP 4
+.B bc
+BrailComm
+.TP 4
+.B bd
+Braudi
+.TP 4
+.B bl
+BrailleLite
+.TP 4
+.B bm
+Baum
+.TP 4
+.B bn
+BrailleNote
+.TP 4
+.B cb
+CombiBraille
+.TP 4
+.B ec
+EcoBraille
+.TP 4
+.B es
+eSpeak
+.TP 4
+.B eu
+EuroBraille
+.TP 4
+.B fl
+FestivalLite
+.TP 4
+.B fs
+FreedomScientific
+.TP 4
+.B fv
+Festival
+.TP 4
+.B gs
+GenericSay
+.TP 4
+.B hm
+HIMS
+.TP 4
+.B ht
+HandyTech
+.TP 4
+.B hw
+HumanWare
+.TP 4
+.B il
+IrisLinux
+.TP 4
+.B lb
+Libbraille
+.TP 4
+.B lt
+LogText
+.TP 4
+.B mb
+MultiBraille
+.TP 4
+.B md
+MDV
+.TP 4
+.B mn
+MiniBraille
+.TP 4
+.B mp
+Mikropuhe
+.TP 4
+.B mt
+Metec
+.TP 4
+.B no
+no driver
+.TP 4
+.B pg
+Pegasus
+.TP 4
+.B pm
+Papenmeier
+.TP 4
+.B sd
+SpeechDispatcher
+.TP 4
+.B sk
+Seika
+.TP 4
+.B sw
+Swift
+.TP 4
+.B th
+Theta
+.TP 4
+.B tn
+TechniBraille Systems Inc.
+.TP 4
+.B ts
+Telesensory Systems Inc.
+.TP 4
+.B tt
+TTY
+.TP 4
+.B vd
+VideoBraille
+.TP 4
+.B vo
+Voyager, Part232 (serial adapter), BraillePen/EasyLink
+.TP 4
+.B vr
+Virtual
+.TP 4
+.B vs
+VisioBraille
+.TP 4
+.B vv
+ViaVoice
+.TP 4
+.B xs
+ExternalSpeech
+.TP 4
+.B xw
+XWindow
+.PP
+A comma-delimited list of drivers may be specified.
+If this is done then autodetection is performed using each listed driver in sequence.
+You may need to experiment in order to determine the most reliable order
+since some drivers autodetect better than others.
+.PP
+If the single word
+.B auto
+is specified then autodetection is performed
+using only those drivers which are known to be reliable for this purpose.
+.RE
+.SH "SEE ALSO"
+For full documentation, see
+.BR brltty 's
+on-line manual at
+.RB "[" "http://mielke.cc/brltty/doc/Manual-HTML/Manual.html" "]."