Bug#509371: installation-guide: Installation guide accessibility sections
Hi Samuel,
On Sunday 21 December 2008, Samuel Thibault wrote:
> Here is a patch that adds to installation-guide two accessibility
> sections: in the supported hardware section, provide urls to lists
> of supported braille displays and speech syntheses, and in the boot
> section, document the boot parameters needed to enable accessibility
> features.
Sorry for not replying to this sooner. It was on my ToDo list for the
manual, but I tend to work on that in batches.
I'm currently planning an update of the manual for stable, and it would be
nice to include this. However, there are a few problems with the proposed
patch. If you can provide an updated version of the patch fairly shortly,
I'll try to include it in the update (even though it means additional work
for translators).
The main issue is that the installation guide is built for 11
architectures, but most of your description is only valid for 2 of them:
amd64 and i386. This is of course not acceptable.
Either you'll need to specifically limit the sections to those 2 arches
(using 'arch="x86"' conditions in relevant tags), or you'll need to adjust
the descriptions where appropriate. There are various options to make text
architecture specific ('arch=' conditions in section/para tags, or the
<phrase> tag).
Note that for arches that do not support an accessibility option at all
(s390 comes to mind), the text should be suppressed anyway.
General spelling error: s/speech syntheses/speech synthesis/
Also, please use:
s/BRLTTY/<classname>brltty</classname>/
s/Speakup/<classname>speakup</classname>/
Some more specific comments below.
Index: en/hardware/accessibility.xml
===================================================================
+Debian's support for braille displays is determined by the underlying
+support found in BRLTTY. Most displays work under BRLTTY, via serial, USB
+or bluetooth. Details on supported braille devices can be found at <ulink
+url="&url-brltty;"></ulink>. Debian &release; ships with BRLTTY version
+&brlttyver;.
[...]
+Debian's support for hardware speech syntheses is determined by the underlying
+support found in Speakup. Speakup only supports integrated boards and external
+devices connected through Serial (no USB or serial-to-USB adapters are
"Serial" should not be capitalized.
Is "through" correct? You use "via" for brltty. Maybe use something like
"connected to a serial port".
+supported). Details on supported hardware speech syntheses can be found at
+<ulink url="&url-speakup;"></ulink>. Debian &release; ships with Speakup version
+&speakupver;.
Are the versions of brltty and speakup really important for users? Please
consider that it's something that will need to be updated and that that's
easily forgotten or skipped if that is done by someone without much personal
interest in accessibility issues.
Index: en/boot-installer/accessibility.xml
===================================================================
--- en/boot-installer/accessibility.xml (r�vision 0)
+++ en/boot-installer/accessibility.xml (r�vision 0)
@@ -0,0 +1,92 @@
+Some people may need particular support due to e.g. visual impairment. USB
s/people/users/
s/due to e.g./because of e.g. some/
+braille displays are automatically detected, but most other accessibility
+features have to be enabled by hand. On machines that support it, the boot
s/by hand/manually/ or "specifically enabled" ?
+menu emits a beep when it is ready to receive keystrokes. Some boot parameters
+can then be appended to enable accessibility features. Note that on most
+architectures the boot loader interprets your keyboard as a QWERTY keyboard.
+
+</para>
+
+<sect2><title>USB Braille Displays</title>
+
+<para>
+
+USB braille displays should be automatically detected. A textual version of
+the installer will then be automatically selected, and support for the braille
+display will be automatically installed on the target system. You can thus just
+press &enterkey; at the boot menu. Once BRLTTY is started,
+you can choose a braille table by entering the preference menu.
Is it obvious to users how this "preference menu" is entered?
+</para>
+
+ </sect2>
+ <sect2><title>Serial Braille Displays</title>
+
+<para>
+
+Serial braille displays can not safely be automatically detected
+(since that may brick some of them). You thus need to append the
+<userinput>brltty=driver,port,table</userinput> boot parameter to tell
The parts that need to be replaced should be tagged <replaceable>.
+BRLTTY which driver it should use. <userinput>driver</userinput>
+should be replaced by the two-letter driver core for your terminal,
s/core/code/
+see <ulink url="&url-brltty-driver-codes;"></ulink> for a list.
Please change this so that the URL itself is not displayed.
+<userinput>device</userinput> should be replaced by the name of the serial
+port the display is connected to, <userinput>ttyS0</userinput> is the default.
+<userinput>table</userinput> is the name of the braille table to be used, see
+<ulink url="&url-brltty-table-codes;"></ulink> for a list, the english table
Again.
+is the default. Note that the table can be changed later by entering the
+preference menu.
+
+</para>
+
+ </sect2>
+
+ <sect2 arch="x86"><title>Hardware Speech Syntheses</title>
+
+<para>
+
+Support for hardware speech syntheses is enabled only along support for
+graphical installer. You thus need to select the <computeroutput>Graphical
+install</computeroutput> entry in the boot menu.
+
+Hardware speech syntheses can not be automatically detected. You thus need
s/can not/cannot/
+to append the <userinput>speakup.synth=driver</userinput> boot parameter
+to tell Speakup which driver it should use. <userinput>driver</userinput>
+should be replaced by the driver code for your device, see <ulink
+url="&url-speakup-driver-codes;"></ulink> for a list. The textual version of
+the installer will then be automatically selected, and support for the speech
+synthesis will be automatically installed on the target system.
+
+</para>
+
+ </sect2>
+ <sect2><title>Board-based Devices</title>
I don't like "board-based".
+<para>
+
+Some accessibility devices are actual boards that are plugged inside
+the machine and that directly read text from the video memory. To get
s/directly read text/read text directly/
+them working the framebuffer support must be disabled by using the
s/working/to work/
s/the framebuffer support/framebuffer support/
+<userinput>fb=false</userinput> boot parameter.
Maybe mention that this limits the number of available languages?
Reply to: