# Adriane-Manual

Notes on this Wikibook
* Target group: Users of the ADRIANE-Systems as well as people who want to install the system, configure or provide training to.
* Learning: The user should be enabled, to use the system independently and without sighted assistance and to work productively with the installed programs and services. This book is a "reference book" for a user in which he takes aid to individual tasks. The technician will get instructions for the installation and configuration of the system, so that he can configure it to meet the needs of the user. Trainers should be enabled to understand easily and to explain the system to users so that they can learn how to use it in a short time without help.
* Contact: Klaus Knopper
* Are Co authors currently wanted? Yes, in prior consultation with the contact person to coordinate the writing of individual chapters, please.
* Guidelines for co authors: see above. A clear distinction would be desirable between 'technical part' and 'User part'.
* Topic description The user part of the book deals with the use of programs that are included with Adriane, as well as the operation of the screen reader. The technical part explains the installation and configuration of Adriane, especially the connection of Braille lines, set-up of internet access, configuration of the mail program etc.

# Introduction

ADRIANE stands for "audio desktop reference implementation and networking environment" and is an acoustic menu system, which aims to facilitate blind and severely visually impaired people use the computer and the launch of accessible programs (low barrier). Adriane is integral part of the KNOPPIX live GNU/Linux system and can be started running the boot option “Adriane” within the download version. Alternatively, the KNOPPIX versions containing “Adriane” as part of their file name will start running the audio desktop without special boot options. The main menu system by Adriane contains a selection of programs for Internet applications (e.g. E-Mail, WWW), text processing, creating notes, contact management and SMS-functionality for some mobile phones.

# Working with Adriane
## Start and help

If you are using the Adriane version of Knoppix it starts automatically. Otherwise you will have to type "Adriane" when the boot screen is shown. First you will hear the speech output reporting the first menu item "Help with enter key, arrow key down for next menu". By pressing enter you will reach a help window, which explains the basic language output functions. Here you can also select individual functions and components. With the ARROW down key you can reach the other programs and step through the menu.

## Individual menu system

The menu system is designed "flat", which means that programs are located at the first level. In most cases pressing the ENTER key will open the program, in some cases it’s a window with further information or options. This is to keep operation as clear and easily as possible. You can navigate via the ARROW keys and the ENTER key to select an option. The marked menu item will be highlighted and spoken by speech output. The ESCAPE key will always lead you one menu and level higher. Normally this key is located on the upper left corner of the keyboard.
Some controls in Adriane, like for example input dialogs, know also advanced keyboard commands such as CONTROL +U to completely delete the contentsof the input field
Tabelle: Menü-Bedienung
| Key(s) | Effect |
| ARROW down | The next menu item |
| ARROW up | Previous menu item (General) or other functions (special case of file manager) |
| ARROW left/right | Controls in a dialog box, such as "Accept" or "Cancel" enable, or back to a command window by the text - or proceed |
| Enter key | Select menu item or submitting completed dialog box |
| ESCAPE key | Exit the menu or a menu level back |
Note: Using the keyboard shortcut CONTROL C a menu or a function can generally be canceled, and you will be returned directly to the main menu. Some programs however directly handle this key combination differently, which is described in the following chapters.

## Voice output functions

The key CapsLock, located on most keyboards left/middle on the keyboard has no meaning for most programs and is therefore intended for voice output in Adriane, which always work regardless of the active program. All voice output commands follow the basic syntax: CapsLock + ... Note: voice output using CapsLock will not affect the cursor position , therefore the writing position may differ from the spoken text! On a Braille display however, there will be given a tactile output of the actual cursor position. You can imagine the reading of screen text as an invisible window, being moved across the screen and not being realized by the program running. The position of the screen reader text will not be visualized for users, being able to see. In a Braille line is connected to the computer the text being moved to and read will be made tactile.
Table: text-to-speech functions with CapsLock (also advanced options, which are not included in the help)
| Keyboard shortcut | Effect |
| CapsLock SPACEBAR | Read again this line |
| CapsLock arrow high | CapsLock arrow high |
| CapsLock down arrow | Read next line |
| CapsLock arrow key to the right | Read next character (spelling) |
| CapsLock arrow key to the left | Read Last character(spelling) |
| CapsLock Pos1 | Set reading start position to the top and read the first line |
| CapsLock end | Set reading position to the bottom and it read the last line |
| CapsLock page down | Read page from here to end |
| CapsLock page high | Read page from the top to here |
| CapsLock j or l | Read the previous (J) on next (l) word |
| CapsLock k | Read this word again |
| CapsLock F1 or F2 | Decreade reading speed (F1) or increase (F2) |
| CapsLock F3 or F4 | Set tone of the voice set lower or higher |
| CapsLock F5 or F6 | Reduce/increase the volume of the voice |
| CapsLock F7 or F8 | Select previous or next language |
| CapsLock a | The read position as x/y-coordinate and the number of the virtual console, where one is located, acoustically print. Interesting for developers. |
You can also combine the CapsLock codes. For example: if you want the whole text on the screen to be read, type CapsLock Pos1 CapsLock page down
Because the reading position has no influence on the current program, the user must toggle within the respective program to open the next screen to read another page. This works for most programs using the space (without CapsLock) or the "page down" button.
To read English text the German language pronunciation can be switched to the proper English accent by pressing CapsLock F8. To switch back to German pronunciation use CapsLock F7.

## Programs in Adriane

The content of Adriane main menu can be configured using the Adriane configuration system. The menu contains a variety of the most commonly used programs like text editor, email, chat or browser. Some of these (E-Mail, chat, WWW) need third-party information for setup and configuration like access or provider data. Otherwise these services will not be accessable.
By default the main menu contains the following entries. The programs will be explained in detail in following chapters (Version 1.6 (KNOPPIX 7.2.0)):
| Title or name in the menu | Program |
| Return | This brings up the Adriane-help - a help file with overview of the main features of the screen reader and keyboard layout. You can navigate using the arrow keys. |
| KARL | "Keyboard Autonomes Reflexives Lernen" (german) - a keyboard tutorial on finding your way on various keyboards |
| WWW | Use of the World Wide Web with the help of the easy to use browser elinks |
| Email | Read and write emails with the help of the Mailclient "mutt" |
| Chat | Use chat services |
| SMS | Read or send SMS using your own cellphone and the program gnokii, if supported by your cellphone ("modem functions") |
| Multimedia | Play-back audio and Daisy CDs, audio and video DVDs and files using mplayer |
| Address book | A very simple UBB-like address book |
| Notebook | Create, edit, and save texts |
| Calculator | A simple calculator |
| Predictive text | Document reader that can save, edit and convert scans and documents |
| File Manager | copy, rename, edit, delete files quick and easy |
| Shell | Work on the Linux command line (for advanced users) |
| Graphical programs | Working in the graphical user interface with compiz magnification and speech output |
| Settings | Configure volume, Internet and various programs |
| Stop | Shut down the computer after usage |

### KARL - keyboard tutorial

Important note: please use KNOPPIX version 7.2. 0 g or package Adriane karl version 1.6-2 or higher.
By selecting this menu entry and starting the program by the ENTER key the CapsLock key loses its functions for screen navigation and the keyboard switches to "RAW mode" as long as KARL is running. Every time a user hits a button it will be read with its available functions written on it or in combination with function keys like e.g. SHIFT, ALL or CONTROL. So, if you hit for example the “1” key you will hear “one or exclamation mark” because of this button has two meanings: “1” when hit it alone, “!” when hit it in combination with SHIFT. the special keys like SHIFT, ALT, ARROW or CONTROL will be read, but lose their functions as long as KARL is runnig.
After ending running KARL by pressing the ESCAPE key (on most keyboards the easily accessible button top left), the keyboard will be set back into normal mode and the navigation by the CapsLock-Key will be activated again.

### WWW - browser elinks
#### Start elinks

Elinks will be started by selecting the menu entry WWW on the Adriane main menu. elinks is a simple text-based JavaScript browser. If you install external plug-ins it can show pictures, play videos. Java applets or Flash content cannot be accessed, like most other browsers do not support.
When started elinks is asking for a web address, e.g. "http://www.wikipedia.de", but you can drop the protocol prefix (www.wikipedia.de will also work).
The text entry fields in elinks are actually marked for the screen reader, in a way that always the complete content of an entry will be read. When entering the text it often sounds like “stutter”, but this mode helps to hear all entries. The additional elements of a web site coming with the text entry or dialog window will not be read at the end of the etxt entry, without to use the screen reader navigation.
Pressing the ENTER key will lead you to the web site entered.

#### Reading web pages using elinks

Screen reader or Braille output of web-pages or single lines will be performed in Adriane by using the above described Caps Lock codes, e.g. CapsLock + arrow up/down to process line by line or CapsLock + page up/page down for the part of a web-page shown on screen. You can use the ARROW up/down key without CapsLock to jump between hyperlinks or use the ARROW left/right keys to follow the hyperlink or jump to the previous page. If the web-site is known, but even it is complex, a user is able to navigate in a fast way through it. Arrow left/right takes you forward (to follow a link) or backwards (to go back to the former page). A page will be scrolled up (using the page up button) or down (using the page down button), without pressing CapsLock. First only the hyperlinks will be read by the screen reader. If the position (number) of a web-site link is known it can be accessed directly adding a prefix number by entering e.g. 10 Arrow Down This will skip the first 9 links and lead you to link no. 10 and the screen will also be focused accordingly.

#### Command and input mode in elinks

When the command or navigation mode is activated each key pressed on keyboard, even the letter keys, will be interpreted as command. They match mainly with the “hot-keys”, listed in the elinks menu. To get access to the hot-keys menu please enter F10 key to show it and to leave the hot-key menu please hit the ESCAPE key. Within this menu navigation is done by the arrow keys without CapsLock.
The next table shows the most important commands within elinks:
Table of commands in elinks :
| Key | stands for | Effect |
| q | Quit | Stop by elinks after consultation. |
| g | Goto | Enter the address of a new Web page |
| . | tags | Type of a form field in the Web page in parentheses show / hide, E.g. [textinput], [submit], etc. |
| a | Add | Save the address of the current page in the bookmark list |
| s | Select | View the bookmark list, select addresses or edit list (Bookmark Manager) |
| / | Search | Search for a word or text in the Web page, and jump there. |
| n | Next | Rescan text with same search term ("find next") |
| F10 | ELinks menu | Open the elinks menu (leaving with escape) |
| o | Options | Options and settings for elinks, very extensive |
| Strg P | Print | Print current page as text by using the Adriane dialog, save to the notebook, or send via mail. |
| v | View | Viewing image graphic |
| Escape | Verlassen | Exit the current dialog, press repeatedly to return to the current Web page in command mode |
Note: To enter a text entry field you must activate the access first using the ENTER key. Unless you do so, every input will be interpreted as a new command instead of an entry!
Input mode: having entered a text entry (one or more lines) by pressing “Enter” the letter or number keys will loose their functionality as command and will work as input for text. For text entries for more than one line there is a special function: you can use the F4 key to open the well-known Nano editor to edit your text in full-screen mode. To store your text and quit the editor press the hotkey CONTROL-X. Dialogue in elinks: forms or commands can trigger additional dialog boxes and activated elements will be read by screen reader. Dialogue boxes may contain a selection or a text input field without any further controls, others may come with functions like e.g. "Edit", "Delete" or "Save". Those will not be read by screen reader, unless they are activated by tab, like for example in the dialog of the Bookmark Manager (button "s") and in the comprehensive settings menu (button "o").
Images and multimedia files: some hyperlinks lead to images or videos. With the ENTER key the content of this link will be shown in case of pictures with the “FBI” image viewer or for audio or video content with the “mplayer” multimedia player. On some websites, however, pictures are shown directly on the page and link pictures not as a link to the picture file, but to another web-page. To visualize the pictures using hyper-links in a terminal (console) open a picture using the key “v” instead of pressing “Enter”. Using “fbi” viewer pictures can be zoomed (key “+” plus) or decreased (key “-” minus). To quit press “q”. When viewing pictures the screen reader is de-activated.

### Managing files - file manager with the Adriane menu system

Note: more advanced LINUX users may surely prefer this hell described in the next chapter managing files and directories, because tasks up much quicker to do but it requires a lot of special knowledge.
Advanced Linux users may prefer the shell for all tasks relating to the copying, deleting, moving and renaming files and directories, because with knowledge of some simple commands such tasks can be solved in a fraction of the time it can be done by navigating through menus.
The Adriane File Manager is a simple but very powerful tool which summarizes the most important tasks in the simple menus. However, in many cases several steps have to be taken to e.g. copy a directory with all the files to an USB stick.
When entering the menu item "Manage files" in the Adriane main menu, there will be shown a list of available directories and disc drives. The first menu item is always the own root directory (path /home/knoppix), which contains all your personal files and settings and is always writable for the user. If Adriane runs from CD no files or data will be saved. However, if a USB Flash disk is used you can use an overlay which writes your personal data to district image file or partition on the hard disk. Of cause data can be stored on any device, but first these devices have to be made accessible, you have to “mounted” them. When you want to remove these devices after finishing your work please remember to unmount this disc for safe removal.

#### Disk names and descriptions

In the presented directory list mounted disks and devices are shown with their manufacturer, product names and the device name, which is the name LINUX knows for this location - except the RAM Disk and the root directory. The following table shows a brief summary of usual disk labels and devices, which match with the device list in the directory /dev :
Table of the most common linux disk labels :
| Device name | stands for |
| sda | first (a) SCSI/SATA/USB Disk. |
| sdb | second (a) SCSI/SATA/USB Disk. |
| sda1 | first (1) partition on the first (a) SCSI/SATA/USB Disk. |
| sda2 | second (2) partition on the second (a) SCSI/SATA/USB Disk. |
| sdb1 | first (1) partition on the second (b) SCSI/SATA/USB Disk. |
The first four partitions on a disc are referred as "primary partitions", one of them may be an "extended partition" that contains one or many additional partitions referred as “logical partitions” and are numbered 5 or higher in the device name.
Adriane users don’t need to care for the correct device names, since the numbering follows a logical schema, different to DOS arbitrary assignments ("C", "D",:, "Z:" ) to hard-disk partitions, CDs or DVDs, or network drives.
The content of a mounted partition using Knoppix/Adriane will normally be shown as a subdirectory of “/media”. So for example “/media/SDA 1” refers to the 1st partition on the 1st disc drive.

#### Mounting devices

As part and below the /home directory the recognized devices are listed. If the device is already mounted, it is marked as “mounted”. All others, recognized and referred arelisted with their device name and manufacturer name.
When selecting a unmounted device or disk by pressing the “Enter” key a dialog is opened, proposing to mount this device. To exit the mounting process press ESCAPE (Esc) and you will be lead to the directory you started from.
Knoppix/Adriane automatically detects all standard file systems such as the LINUX based (ext2, ext3, ext4, reiserfs, xfs) or the DOS/Windows types (FAT32, NTFS or ExFAT ). However, some file systems need specific file permissions ("Permissions" and access control lists) and might be difficult to use for inexperienced users. In such a case working with the shell might be the better solution, because you are working with administrator rights and more functions for rights management are available.
Encrypted partitions cannot be mounted with the simple Adriane file manager. But mounting it manually including the needed unlocking mechanism in th Shell will enable access in the file manager. It will appear in the list of mounted devices.
If a selected volume is already mounted, not the mounting dialogue will show up, but another dialogue box will offer to navigate to the selected device or to unmount the drive, close and store all file modifications and to unmount the device. Without unmounting e.g. a CD or DVD drive it will not be possible to open and remove a CD or DVD.

#### Navigate in the file system

Pressing the Enter key after selection of "browse files in…" will directly open the corresponding directory.

##### Enter or leave directories

After entering a directory various options are shown. As a standard and to optimize ergonomy the first file or directory name is read in alphabetical order by the screen reader. Opening a directory various options are offered, but these options are shown above the actual position within the directory and to separate them from the directory listing.
These options can be selected by using the “Arrow Up” key:
Table of actions/options in directories :
| Where? | Caption |
| one higher | a directory higher |
| two higher | create a new directory in the current one |
| three higher | delete this directory with all it's content |
| four higher | ".*" Files |
These option should be self-explanatory beside the last one. Files or directories beginning with a dot “.” will usually be hidden in a listing of a Unix file system (“hidden files”), as they contain e.g. configuration data instead of user data. The option “Show hidden files” will show those files and will allow access, modification or deletion of these hidden files.
Using the “Arrow down” key will move you through the list of the directory, the sub-directories are marked with [DIR].

##### Enter or leave directories

Another option menu appears when you select a file with the input button:
Table of file options :
* Caption
* Edit (or play-back) file file name
* Copy file file name to...
* Move file file name to...
* Rename file file name
* Delete file file name
The menu points shown with three dots at the end will need a target directory for their execution, therefore selecting them will start again a navigation at the starting point of the file manager (i.e. "Browse user's home directory" and the list of attached disks). Open the desired target directory and select in the offered options the option “Copy (or move) file to this directory”. The success (or failure) is acknowledged with an appropriate message, then the initial file Manager menu appears again.

##### To be done

The recursive copy (directory with content) is not yet supported in Adriane file manager in the Knoppix version 7.2.0. It is however recommended for frequent working with files to learn about and use these commands in the shell.
Directories being part to mounted disks get the same device name as the disc name in the file manager (e.g. /media/sda1 etc.).

### Shell - using the command line (for advanced Linux users)

The menu item “Shell” from the main menu will start the popular “Born again Shell” (Bash). Bash-Shell will enable users to enter and execute commands but also to do some minor programming and skripting in a kind of a programming language.
First you will see the prompt like username@hostname: current directory $. When you use Knoppix you will usually see: knoppix@Microknoppix: followed by the working directory (the tilde ~ is an abbreviation for the home directory/home/knoppix).
The result or the output generated by a program is always listed follwing the last command line input and the following lines generated by the execution after "Send" command and the new command prompt. To get there and to get these read by screen reader you have to press the CapsLock-arrow up key (maybe several times if necessary). In case the output of a command should exceed a side of the screen this part of the screen on the previous page can be toggled with SHIFT-key PAGE up (without CapsLock) (also if necessary repeat this). The screen content can be accessed, read by screen reader or Braille line using the CapsLock screen readers function as described in the section "navigation by keyboard".
Beside the direct access the Shell offers comfortable usage of the operating system and programs:
Table of "Hot keys" in bash :
| Keyboard shortcut | Effect |
| Keyboard shortcut | Edit the current command line |
| Arrow up/down | Move through the "command history", repeat the old commands |
| Enter key | Submit/run the current command |
| Tab key | complete a partially typed command, or show all commands which start like this |
| Control-C | cancel the command running in the foreground. |
For a fast navigation in the file system and file management in the shell the following table maybe helpful, as it shows some of the most important commands, being used by any Unix based systems:
Table of file system commands in the shell :
| Command | Effect |
| mount /media/sdb1 | Mount 1 partition of 2 hard disk (E.g. USB stick) as the directory /media/sdb1. |
| umount /media/sdb1 | Unregister disk ("safely remove"). Previously, all accesses to the disk from the shell must be stopped (E.g. use cd to go to the home directory). |
| pwd | Show the current path ("where am I?") |
| cd directory | Changes to the specified directory. The directory name .. (two points) refer to the parent directory or one directory higher. If no directory is specified (i.e. cd without arguments), the home directory will be opened (/home/knoppix). |
| ls-l directory | Shows contents of a directory with date, file sizes, file owner, and file permissions. If the directory as an argument is omitted, the contents of the current directory are listed. With additional option -a "hidden" files and directories starting with dot in the name are displayed. |
| mkdir directory | Creating a subdirectory |
| cp-a old new | Copying a file or directory with complete content (ALT) in a new file or a new directory (new). All file attributes, such as time, file permissions, and so on will be copied (-a). |
| mv -a old new | Moving a file or directory with complete content (ALT) in a new file or a new directory (new). Equivalent to rename, if new is not yet available. |
| rmdir directory | Delete empty subdirectory (harmless) |
| rm -rf directory or File | Delete file or directory with all it contained without question (be careful!) |
| cat filename | Spend the specified text file on screen (caution: do not use with binary files, programs, videos, images, etc.) |
| nano filename | Load text file into the nano text editor. |
Paths within a UNIX file system always have the same syntax, a slash “/” between file and directory names, e.g. directory/subdirectory/file.txt. "Absolute" paths begin with the root directory /, relative paths with the actual directory . (dot), what can also be omitted.
Here is an example to copy a directory and its content from an USB disc drive /media/sdb1 to the current directory (entering cd without any further data) you are in your home directory /home/knoppix:
There is a special aspect in this example: the name of the music folder contains a blank space. To let the cp command know that not two different folders are meant, but that it is the folder’s name with a blank space, the folder’s name it set into “ “ (quotation marks). Otherwise the cp command understands that "My Music" are two different folders (My and Music).
After the copy operation completes the media player (menu "Multimedia") is ablte to open the directory, where the files were copied to, using "Browse files".
By the way, the mount or unmount command in this example is only required, if the USB stick was not previously mounted by the file manager.
The shell can be exited using the exit command.

# Installation and configuration of Adriane

The technology part describes the installation on hard disk or USB flash drive, the configuration of the system and gives guidance on technical issues.

## Installation from CD or DVD to USB flash drive

Adriane originally is a life solution that runs from CD or DVD. Nevertheless the integrated program flash-knoppix offers a comfortable way to install Adriane on an USB flash drive and, in case there is enough storage capacity left, to create an overlay file or a separate partition to store own files and individual settings.
Installing the system to an USB drive the compression of the basic file system and the boot procedure wil stay the same as booting from a CD, but the on a USB stick installed version runs up to 5-times faster than from a CD and offers the opportunity to keep and store own data and files, even to crypt them.
Within Adriane please select the menu item “settings” and then the point “save to Flash disk” to start the installation.
From (Adriane-) Knoppix version 7.2 and higher, there are two variants to set-up the writable overlay: 1. Creating a “virtual hard drive" as an image file in the folder "KNOPPIX" on the disk. The maximum file size for the overlay will be 4 GB, due to the FAT32 formatting. This option is recommended, if the disk should not newly be partitioned and formatted, but only Knoppix data should be transmitted and a master boot record should be created. 2. Creating a dedicated Linux partition: This option normally requires a repartitioning of the disk with previously existing data will be deleted or overwritten. The advantage of this method is the possibility to use the complete disk for Linux and so to be able to save even more than 4 GB own data.
Due to the many explanations given in many text boxes, the text output from flash-Knoppix, it is difficult to understand and not so easy to use as other parts of Adriane. First you are asked to determine the destination disk, on which the data should be stored. Please be very careful to choose the correct location, which is not used for other purposes, because all data on this drive could be destroyed! Never select your internal hard disc!
The next step is to define the desired form of overlay (in case there is space left on the USB device): image file in FAT32 or an additional partition (which deletes and partition this part of the disc). Selecting the second option two security questions (both have to be answered “yes”) will be asked to prevent accidental loss of data loss and to continue the installation. One question is to define the size of the writable overlay container in Mega-Byte (MB). Next question is if or if not to encrypt your personal data and to define the individual password.
The (optional) partitioning, the formating of and data transfer to the USB drive will last a while, depending on type, disk speed and amount of data that is transferred. On screen you will see and hear a roughly estimated percentage of progress. The end of the process will be acknowledged with a corresponding success (or error) message.

## Set up and save the volume settings

The "Settings" menu item "Volume" starts the mixer tool rexima, offering various controllers to set all input and output channels of the sound card. Using Arrow right or left keys will change the value of the selected controller. Arrow up or down key will move to the next or previous control. If you hit ESCAPE or the key Q the current settings of the controllers will be saved in the file /etc/aumixrc and – in case you are running the system using an USB drive - will be active after a reboot.
Advanced users can also edit this file directly through the shell. The corresponding command is:
The aumixrc file is not complicated, here an example:
The "84" is in this example for the percentage volume (0-100), which "P" means that the output is switched on ("play"). After the values were changed as needed the file can be stored as usual using the nano editor, press control-X (Ctl + X). The new settings will automatically be activated at the next reboot.