File: X11.html

package info (click to toggle)
brltty 6.8-4
links: PTS, VCS
area: main
in suites: forky, sid
size: 35,776 kB
sloc: ansic: 150,447; java: 13,484; sh: 9,667; xml: 5,702; tcl: 2,634; makefile: 2,328; awk: 713; lisp: 366; python: 321; ml: 301
file content (461 lines) | stat: -rw-r--r-- 13,142 bytes
parent folder | download | duplicates (2)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="Docutils 0.20.1: https://docutils.sourceforge.io/" />
<title>BRLTTY with X11</title>
<style type="text/css">

/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 8954 2022-01-20 10:10:25Z milde $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See https://docutils.sourceforge.io/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

.subscript {
  vertical-align: sub;
  font-size: smaller }

.superscript {
  vertical-align: super;
  font-size: smaller }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
  overflow: hidden;
}

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title, .code .error {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left, .figure.align-left, object.align-left, table.align-left {
  clear: left ;
  float: left ;
  margin-right: 1em }

img.align-right, .figure.align-right, object.align-right, table.align-right {
  clear: right ;
  float: right ;
  margin-left: 1em }

img.align-center, .figure.align-center, object.align-center {
  display: block;
  margin-left: auto;
  margin-right: auto;
}

table.align-center {
  margin-left: auto;
  margin-right: auto;
}

.align-left {
  text-align: left }

.align-center {
  clear: both ;
  text-align: center }

.align-right {
  text-align: right }

/* reset inner alignment in figures */
div.align-right {
  text-align: inherit }

/* div.align-center * { */
/*   text-align: left } */

.align-top    {
  vertical-align: top }

.align-middle {
  vertical-align: middle }

.align-bottom {
  vertical-align: bottom }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font: inherit }

pre.literal-block, pre.doctest-block, pre.math, pre.code {
  margin-left: 2em ;
  margin-right: 2em }

pre.code .ln { color: grey; } /* line numbers */
pre.code, code { background-color: #eeeeee }
pre.code .comment, code .comment { color: #5C6576 }
pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
pre.code .literal.string, code .literal.string { color: #0C5404 }
pre.code .name.builtin, code .name.builtin { color: #352B84 }
pre.code .deleted, code .deleted { background-color: #DEB0A1}
pre.code .inserted, code .inserted { background-color: #A3D289}

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

/* "booktabs" style (no vertical lines) */
table.docutils.booktabs {
  border: 0px;
  border-top: 2px solid;
  border-bottom: 2px solid;
  border-collapse: collapse;
}
table.docutils.booktabs * {
  border: 0px;
}
table.docutils.booktabs th {
  border-bottom: thin solid;
  text-align: left;
}

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="brltty-with-x11">
<h1 class="title">BRLTTY with X11</h1>

<div class="contents topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#braille-input" id="toc-entry-1">Braille Input</a><ul>
<li><a class="reference internal" href="#from-the-braille-device" id="toc-entry-2">From the Braille Device</a></li>
<li><a class="reference internal" href="#from-the-pc-keyboard" id="toc-entry-3">From the PC Keyboard</a></li>
</ul>
</li>
<li><a class="reference internal" href="#reading-the-screen" id="toc-entry-4">Reading the Screen</a></li>
</ul>
</div>
<p>BRLTTY provides some support for the X11 graphical environment.</p>
<div class="section" id="braille-input">
<h2><a class="toc-backref" href="#toc-entry-1">Braille Input</a></h2>
<div class="section" id="from-the-braille-device">
<h3><a class="toc-backref" href="#toc-entry-2">From the Braille Device</a></h3>
<p>Some braille devices have an integrated braille keyboard. BRLTTY alone can't
properly simulate keypresses for the X11 server because it doesn't know which
keyboard layout the latter is using.  In order to achieve proper keyboard
simulation, <tt class="docutils literal">xbrlapi</tt> should be started in the background during <tt class="docutils literal">X</tt>
session startup.</p>
<p>By default, <tt class="docutils literal">xbrlapi</tt> also writes the title of the current window to the
braille device. To avoid this (since it could interfere with output from screen
readers like <a class="reference external" href="https://help.gnome.org/users/orca/stable/">Orca</a>), give the <tt class="docutils literal"><span class="pre">-q</span></tt> (quiet) option to <tt class="docutils literal">xbrlapi</tt>.</p>
</div>
<div class="section" id="from-the-pc-keyboard">
<h3><a class="toc-backref" href="#toc-entry-3">From the PC Keyboard</a></h3>
<p>The PC keyboard can be used, when in X11, as a braille keyboard. This
capability can be enabled by using the <tt class="docutils literal">brai</tt> layout. For example:</p>
<pre class="literal-block">
setxkbmap -layout &quot;us,brai&quot; -option &quot;grp:shift_caps_toggle,grp_led:scroll&quot;
</pre>
<p>enables both the <tt class="docutils literal">US</tt> and the <tt class="docutils literal">braille</tt> keyboard layouts in two different
XKB groups), and Shift+CapsLock will switch between them. The scroll LED will
be lit while in <tt class="docutils literal">braille</tt> mode so that sighted users will be alerted as to
why they may be getting unexpected output if they switch groups by accident.
Other shortcuts and LEDs can also be used (see the XKB documentation).</p>
<p>The default keyboard mapping for braille dots is:</p>
<pre class="literal-block">
f j
d k
s l
a ;
</pre>
<p>but other layouts are also available (see the variants in XKB).</p>
<p>Applications then need to be &quot;told&quot; to use the standard X11 Input Module. This
can be done by setting:</p>
<pre class="literal-block">
export GTK_IM_MODULE=xim
export QT_IM_MODULE=xim
export XMODIFIERS=&#64;im=xim
</pre>
<p>This is, however, not enough for recent gnome desktops, which also need to
run:</p>
<pre class="literal-block">
gsettings&nbsp;set&nbsp;org.gnome.settings-daemon.plugins.keyboard&nbsp;active&nbsp;false
</pre>
<p>The <tt class="docutils literal">setxkbmap</tt> command (above) only enables the <tt class="docutils literal">braille</tt> layout for the
current session. For persistent configuration, the two groups must be
configured properly in the system. On Debian, for example, this can be achieved
by setting the following in <tt class="docutils literal">/etc/default/keyboard</tt>:</p>
<pre class="literal-block">
XKBLAYOUT=&quot;us,brai&quot;
XKBOPTIONS=&quot;grp:shift_caps_toggle,grp_led:scroll&quot;
</pre>
<p>By default, the result is Unicode braille patterns because X11 doesn't know
which braille table it should be using. To tell X11 the conversion that should
be performed, use the <tt class="docutils literal"><span class="pre">brltty-ttb</span></tt> tool to convert your BRLTTY text table
into an XCompose table. For example:</p>
<pre class="literal-block">
brltty-ttb -i ttb -o XCompose en_US /tmp/my.XCompose
</pre>
<p>The <tt class="docutils literal">XCompose</tt> table can then be enabled by:</p>
<pre class="literal-block">
cat /tmp/my.XCompose &gt;&gt; ~/.XCompose
</pre>
</div>
</div>
<div class="section" id="reading-the-screen">
<h2><a class="toc-backref" href="#toc-entry-4">Reading the Screen</a></h2>
<p>BRLTTY isn't meant to be able to read a whole graphical environment as it
doesn't have the notion of menus, buttons, etc. The <a class="reference external" href="https://help.gnome.org/users/orca/stable/">Orca</a> screen reader
should be used instead. BRLTTY, however, has a driver that can at least review
the textual elements (edit boxes, terminals). This is particularly useful for
reading terminals since that's what BRLTTY is good at. This can be achieved by
running a second BRLTTY during X11 session startup:</p>
<pre class="literal-block">
brltty -b ba -x as
</pre>
<p>This second BRLTTY connects to the first one via BrlAPI (thanks to the <tt class="docutils literal">ba</tt>
braille driver), and reads the screen via AtSpi (thanks to the <tt class="docutils literal">as</tt> screen
driver). An <tt class="docutils literal">a2</tt> screen driver is also provided for AtSpi2 support.</p>
</div>
</div>
</body>
</html>