Ticket #520: 520.patch

File 520.patch, 184.6 KB (added by orcauser, 2 years ago)

  • user_docs/en/user 

    # Bazaar merge directive format 2 (Bazaar 0.90)
# revision_id: mhameed@src.gnome.org-20100104112839-xv7kapec589qgbqk
# target_branch: http://bzr.nvaccess.org/nvda/main/
# testament_sha1: bcb171f823d6ead0ea2cfea41682eb847e95b8f2
# timestamp: 2010-01-04 12:00:27 +0000
# base_revision_id: mick@kulgan.net-20100104044910-whkeupxu2j1us5fn
# 
# Begin patch
=== added file 'user_docs/en/user guide-fromWiki.html'
     
     1<html> 
     2<head> 
     3<META http-equiv=Content-Type content="text/html; charset=utf-8"> 
     4<title>NVDA 2009.1 User Guide</title> 
     5</head> 
     6<body lang="en"> 
     7<h1>NVDA 2009.1 User Guide</h1> 
     8<p> 
     9Last updated September 13, 2009 
     10</p> 
     11<h2>Table of Contents</h2> 
     12<ul> 
     13<li><a href="#1">1. Introduction</a></li> 
     14<ul> 
     15<li><a href="#1.1">1.1. General features</a></li> 
     16<li><a href="#1.2">1.2. Internationalization</a></li> 
     17<li><a href="#1.3">1.3. Speech synthesizer support</a></li> 
     18<li><a href="#1.4">1.4. Braille support</a></li> 
     19<li><a href="#1.5">1.5. License and copyright</a></li> 
     20</ul> 
     21<li><a href="#2">2. System Requirements</a></li> 
     22<li><a href="#3">3. Getting NVDA</a></li> 
     23<li><a href="#4">4. Installing NVDA</a></li> 
     24<ul> 
     25<li><a href="#4.1">4.1. The NVDA Installer</a></li> 
     26<li><a href="#4.2">4.2. NVDA Portable</a></li> 
     27</ul> 
     28<li><a href="#5">5. Getting started with NVDA</a></li> 
     29<ul> 
     30<li><a href="#5.1">5.1. Launching NVDA</a></li> 
     31<li><a href="#5.2">5.2. About NVDA keyboard commands</a></li> 
     32</ul> 
     33<li><a href="#6">6. The NVDA menu</a></li> 
     34<ul> 
     35<li><a href="#6.1">6.1. Accessing the NVDA menu</a></li> 
     36<li><a href="#6.2">6.2. Configuring NVDA</a></li> 
     37<ul> 
     38<li><a href="#6.2.1">6.2.1 The Preferences Menu</a></li> 
     39<ul> 
     40<li><a href="#6.2.1.1">6.2.1.1. General Settings</a></li> 
     41<li><a href="#6.2.1.2">6.2.1.2. Synthesizer Selection</a></li> 
     42<li><a href="#6.2.1.3">6.2.1.3. Voice Settings</a></li> 
     43<li><a href="#6.2.1.4">6.2.1.4. Braille Settings</a></li> 
     44<li><a href="#6.2.1.5">6.2.1.5. Keyboard Settings</a></li> 
     45<li><a href="#6.2.1.6">6.2.1.6. Mouse Settings</a></li> 
     46<li><a href="#6.2.1.7">6.2.1.7. Object Presentation Settings</a></li> 
     47<li><a href="#6.2.1.8">6.2.1.8. Virtual Buffer Settings</a></li> 
     48<li><a href="#6.2.1.9">6.2.1.9. Document Formatting Settings</a></li> 
     49<li><a href="#6.2.1.10">6.2.1.10. Speech dictionaries</a></li> 
     50</ul> 
     51<li><a href="#6.2.2">6.2.2: Saving and Reverting Configuration</a></li> 
     52</ul> 
     53</ul> 
     54<li><a href="#7">7. Navigating with NVDA</a></li> 
     55<ul> 
     56<li><a href="#7.1">7.1. Navigating by Focus</a></li> 
     57<li><a href="#7.2">7.2. Navigating with the System Caret</a></li> 
     58<li><a href="#7.3">7.3. Object Navigation</a></li> 
     59<li><a href="#7.4">7.4. Reviewing Text in the Current Object</a></li> 
     60<li><a href="#7.5">7.5. Navigating with the Mouse</a></li> 
     61</ul> 
     62<li><a href="#8">8. Virtual Buffers</a></li> 
     63<ul> 
     64<li><a href="#8.1">8.1. Single Letter Navigation</a></li> 
     65<li><a href="#8.2">8.2. Forms and Focus Mode</a></li> 
     66<li><a href="#8.3">8.3. The Elements list</a></li> 
     67<li><a href="#8.4">8.4. Embedded Objects</a></li> 
     68</ul> 
     69<li><a href="#9">9. Troubleshooting NVDA</a></li> 
     70</ul> 
     71<h2 id="1">1. Introduction</h2> 
     72<h3 id="1.1">1.1. General Features</h3> 
     73<p> 
     74Providing feedback by synthetic speech, Nonvisual Desktop Access allows blind and vision impaired people to access and interact with the Windows operating system and many third party applications. 
     75</p> 
     76<p> 
     77Major highlights include: 
     78</p> 
     79<ul> 
     80<li>Ability to run entirely from a USB stick or other portable media without the need for installation</li> 
     81<li>Easy to use talking installer </li> 
     82<li>Browsing the web with <a href="http://www.getfirefox.com/">Mozilla Firefox 3</a></li> 
     83<li>Working with email using <a href="http://www.mozillamessaging.com/en-US/thunderbird/early_releases/">Mozilla Thunderbird 3</a></li> 
     84<li>Support for Microsoft Internet Explorer</li> 
     85<li>Basic support for Microsoft Outlook Express / Windows Mail</li> 
     86<li>support for Microsoft Word and Excel</li> 
     87<li>Support for accessible Java applications</li> 
     88<li>Support for Adobe Reader</li> 
     89<li>Early support for IBM Lotus Symphony</li> 
     90<li>support for Windows Command Prompt and console applications</li> 
     91<li>Automatic announcement of text under the mouse and optional audible indication of the mouse position</li> 
     92<li>Support for many refreshable Braille displays</li> 
     93</ul> 
     94<h3 id="1.2">1.2. Internationalization</h3> 
     95<p> 
     96It is important that people anywhere in the world, no matter what language they speak, get equal access to technology. NVDA currently has been translated into over 20 languages besides the English language including: Arabic, Brazilian Portuguese, Croatian, Czech, Finnish, French, Galician, German, Hungarian, Italian, Japanese, Portuguese, Russian, Slovak, Spanish, Thai, Traditional Chinese, Ukrainian, Afrikaans, Polish and Vietnamese. 
     97</p> 
     98<h3 id="1.3">1.3. Speech Synthesizer Support</h3> 
     99<p> 
     100Apart from providing its messages and interface in several languages, NVDA can also enable the user to read content in any language, as long as they have a speech synthesizer that can speak that particular language. 
     101</p> 
     102<p> 
     103NVDA is bundled with <a href="http://espeak.sourceforge.net/">eSpeak</a>, a free, open-source, multi-lingual speech synthesizer. Additionally, NVDA can use both SAPI4 and SAPI5 speech engines to provide speech output, as well as the Audiologic and NewFon speech synthesizers. 
     104</p> 
     105<h3 id="1.4">1.4. Braille support</h3> 
     106<p> 
     107For users that own a refreshable braille display, NVDA can output its information in braille. NVDA supports Freedom Scientific Pacmate and Focus displays, Handy Tech displays, ALVA BC640/680 displays, plus many others supported by the BRLTTY package if it is available. 
     108</p> 
     109<p> 
     110NVDA supports many braille codes covering a large set of languages. In many cases grade 1 and 2 versions of the codes are available. For English readers both U.S. English braille and Unified English braille (UEB) codes are included. 
     111</p> 
     112<h3 id="1.5">1.5. Licence and Copyright</h3> 
     113<p> 
     114NVDA is copyright 2006-2009 NVDA contributors. 
     115</p> 
     116<p> 
     117NVDA is covered by the GNU General Public License (Version 2). You are free to share or change this software in any way you like as long as you distribute the licence along with the software, and make all source code available to anyone who wants it. This applies to both original and modified copies of the software, plus any software that uses code taken from this software. For further details, you can <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">view the full licence.</a> 
     118</p> 
     119<h2 id="2">2. System Requirements</h2> 
     120<ul> 
     121<li>Operating Systems: all 32-bit and 64-bit versions of Windows XP, Windows Vista and Windows 7 (including Server operating Systems), may partially work on Windows 2000.</li> 
     122<li>Memory: 256 mb or more of RAM</li> 
     123<li>Processor speed: 1.0 ghz or above</li> 
     124<li>About 50 MB of storage space.</li> 
     125</ul> 
     126<h2 id="3">3. Getting NVDA</h2> 
     127<p> 
     128If you have not yet got a copy of NVDA, you can download it <a href="http://www.nvda-project.org/">here</a>. 
     129</p> 
     130<p> 
     131Go to the download section and you will find a link to download the latest version of NVDA. 
     132</p> 
     133<p> 
     134There are currently two ways NVDA is packaged. One is an Installer which will talk you through installing NVDA so that you can then run it at any time from the Start Menu. The other is a self-extracting archive file that contains a fully portable version of NVDA, which you can run from anywhere, including a USB thumb drive or CD. 
     135</p> 
     136<h2 id="4">4. Installing NVDA</h2> 
     137<h3 id="4.1">4.1. The NVDA Installer</h3> 
     138<p> 
     139If you already have the NVDA installer, simply press enter or double click on the file and the installer will start. 
     140</p> 
     141<p> 
     142As the installer loads, you will hear the NVDA installation music. Once loaded, a temporary copy of NVDA will allow you to follow the prompts of the installer and install NVDA. Note that if you were running another copy of NVDA at the time you started the installer, a message will appear telling you that your previous copy of NVDA will be closed. When you press enter on this message, the installer will close your previous copy and start its own one. This is necessary so that the installer can properly update any changed files. At this point, if you have another copy of NVDA already installed, the NVDA installer will uninstall it for you, and then it will commence to install NVDA. 
     143</p> 
     144<p> 
     145Once you have successfully completed the installation, the installer will alert you that the install of NVDA has finished. If reinstalling NVDA, It may ask you to reboot the system at this point. It is very important that you reboot the system as failing to do so will have undesirable consequences. If it did not ask you to reboot, pressing Finnish will close the installer and start the newly installed version of NVDA. 
     146</p> 
     147<h3 id="4.2">4.2. NVDA portable</h3> 
     148<p> 
     149If you have the portable version of NVDA, then all you have to do is to press enter or double click on the file, and follow the prompts. It will ask you where on your system you wish to place the files. 
     150</p> 
     151<h2 id="5">5. Getting started with NVDA</h2> 
     152<h3 id="5.1">5.1. Launching NVDA</h3> 
     153<p> 
     154If you have installed NVDA with the installer, then starting NVDA is as simple as either pressing control+alt+n, or choosing NVDA from the NVDA menu under Programs on the Start Menu. Additionally you can type NVDA into the Run dialog and press Enter. 
     155</p> 
     156<p> 
     157To start the portable version, go to the directory you unpacked NVDA to, and press enter or double click on nvda.exe. 
     158</p> 
     159<p> 
     160As NVDA starts, you will first hear an ascending set of tones (telling you that NVDA is loading). Depending on how fast your computer is, or if you are running NVDA off a USB key or other slower medium, it may take a little while to start. If it is taking an extra long time, NVDA should say &quot;Loading subsystems. Please wait...&quot; 
     161</p> 
     162<p> 
     163If you don't hear any of this, or you hear the Windows error sound, or a descending set of tones, then this means that NVDA has an error, and you will need to possibly report a bug to the developers. Please check out the NVDA website for how to do this. 
     164</p> 
     165<p> 
     166When NVDA starts for the first time, you will be greeted by a dialog box which provides you with some basic information about the NVDA modifier key and the NVDA menu. (Please see further sections about these topics). The dialog box also contains two checkboxes. The first lets you control if NVDA should use the capslock as an NVDA modifier key, and the second lets you control if this Welcome dialog should appear each time NVDA starts. 
     167</p> 
     168<h3 id="5.2">5.2. About NVDA keyboard commands</h3> 
     169<p> 
     170Most NVDA-specific keyboard commands usually consist of pressing the NVDA modifier key, in conjunction with one or more other keys. An exception to this are the text review commands which just use the numpad keys by themselves. 
     171</p> 
     172<p> 
     173By default both numpad insert and extended insert can be used as the NVDA modifier key. However, you can also configure NVDA so that the capslock key also becomes an NVDA modifier key. When configured this way, pressing or holding down capslock acts as an NVDA modifier key, but pressing it twice in quick succession causes it to act as the normal capslock key. 
     174</p> 
     175<p> 
     176Many key commands are mentioned through out the rest of this user guide, but an easy way to explore all the different key commands is to turn on keyboard help. 
     177</p> 
     178<p> 
     179To turn on keyboard help, press NVDA+1. To turn it off again, press NVDA+1 again. While in keyboard help, pressing any key will announce what it does (if in deed it does do something). The keys will not actually perform their function while in keyboard help mode, so you can press what ever keys you like. 
     180</p> 
     181<h2 id="6">6. The NVDA menu</h2> 
     182<p> 
     183The NVDA menu allows you to control NVDA's settings, access help, save/revert your configuration, Modify speech dictionaries, read the log file, and exit NVDA. 
     184</p> 
     185<h3 id="6.1">6.1. Accessing the NVDA menu</h3> 
     186<p> 
     187To get to the NVDA menu from anywhere in Windows while NVDA is running, press NVDA+n. You can also get to the NVDA menu via the windows system tray. Either right-click on the nvda icon located in the system tray, or access the system tray by pressing the windows logo key+B, DownArrow to the NVDA icon and press the applications key located next to the right control key on most keyboards. When the menu comes up, You can use the arrow keys to navigate the menu, and the enter key to activate an item. The Preferences menu allows you to configure NVDA how you like, the tools menu contains useful tools such as the NVDA log viewer and the NVDA Python console for developers, the help menu allows you to access the user guide, a quick key reference, and much more. The NVDA menu also contains items that allow you to save or revert your current configuration. There is also an option that allows you to exit NVDA, although this can be accomplished more efficiently by pressing NVDA+Q. 
     188</p> 
     189<p> 
     190The options under the preferences menu can also be accessed via keyboard shortcut commands, as well as the NVDA Python Console, save and revert configuration options discussed in this section. For more information about this, please visit the quick reference guide for a list of shortcut commands.  
     191</p> 
     192<h3 id="6.2">6.2. Configuring NVDA</h3> 
     193<h4 id="6.2.1">6.2.1 Preferences</h4> 
     194<h5 id="6.2.1.1">6.2.1.1. General Settings</h5> 
     195<p> 
     196The General settings dialog box is found in the Preferences menu. It is also accessed by pressing NVDA+Control+G. To save the options after modifying settings, press the OK button. To cancel, press the cancel button or the escape key. It contains the following options: 
     197</p> 
     198<h6>Language</h6> 
     199<p> 
     200A combo box which allows you to select the language that NVDA's user interface and messages should be shown in. There are many languages, however the default option is &quot;User Default, Windows&quot;. This option tells NVDA to use the language that Windows is currently set to. Please note that NVDA must be restarted when changing the language. NVDA will ask you if you wish to restart if you do change the selection. Press OK, and NVDA will restart. 
     201</p> 
     202<h6>Save Configuration on Exit</h6> 
     203<p> 
     204This option is a checkbox that, when checked, tells NVDA to automatically save the current configuration when you exit NVDA. 
     205</p> 
     206<h6>Warn before exiting NVDA</h6> 
     207<p> 
     208This option is a checkbox that allows you to choose whether or not a dialog appears when you exit NVDA that asks whether or not you would like to exit. When checked, a dialog will appear when you attempt to exit NVDA asking whether or not you want to exit. 
     209</p> 
     210<h6>Logging level</h6> 
     211<p> 
     212This is a combo box that permits you to choose how much NVDA wil log as it's running. Generally users should not need to touch this as not too much is logged. However if you are wanting to provide information in a bug report, then it may be a useful option. 
     213</p> 
     214<h6>Automatically start nvda after I log on to windows</h6> 
     215<p> 
     216If this option is enabled, NVDA will start automatically as soon as you log on to Windows. 
     217</p> 
     218<h6>Use nvda on the windows log on screen (requires administrative privileges)</h6> 
     219<p> 
     220If you log on to Windows by providing a user name and password, then enabling this option will make NVDA start automatically at the logon screen when Windows starts. 
     221</p> 
     222<h5 id="6.2.1.2">6.2.1.2. Synthesizer Selection</h5> 
     223<p> 
     224The Synthesizer dialog, which is found under &quot;Synthesizer...&quot; in the Preferences menu or by pressing NVDA+Control+S, allows you to select which Synthesizer NVDA should use to speak with. 
     225</p> 
     226<p> 
     227The dialog contains a simple combo box, which lists all the available synthesizers. Choose the synthesizer you want using the arrow keys, and then press ok. If there is an error loading the synthesizer, a message box will alert you, and NVDA will keep the old synthesizer loaded. 
     228</p> 
     229<p> 
     230The current list of synthesizers NVDA supports is: eSpeak, SAPI4, SAPI5, Audiologic, Display, and Silence. 
     231</p> 
     232<p> 
     233The eSpeak synthesizer is built directly in to NVDA, and does not depend on any other special drivers or SAPI runtime to be installed. NVDA starts using eSpeak by default. This synthesizer should work on any system that NVDA works on, so it will definitely work when running NVDA off a USB thumb drive or CD, on anyone else's system. 
     234</p> 
     235<p> 
     236The Sapi4 option allows you to use the Sapi synthesizer. Voices that are included under Ssapi4 include eloquence voices, as well as other Ssapi4 voices that you may have installed on your system. 
     237</p> 
     238<p> 
     239The Sapi5 synthesizer allows you to use the microsoft voices that are iincluded on your machine. In XP, the default Ssapi5 voice is Microsoft Sam. In Vista, the default voice is Microsoft Anna. Depending on what voices you have installed, others may show up under Ssapi5. 
     240</p> 
     241<p> 
     242The Display synthesizer is useful for sighted developers who wish to read what NVDA is speaking, as they test NVDA with their applications. 
     243</p> 
     244<p> 
     245The Silence synthesizer driver is not that useful, unless you want to not have any speech at all while running NVDA. 
     246</p> 
     247<p> 
     248Please note that no matter how many different SAPI4 or SAPI5 voices (or engines) you have installed on your system, only the actual SAPI4 and SAPI5 synthesizers will show up in the Synthesizers dialog. To actually select one of the engines (voices), select either SAPI4 or SAPI5, and then in the Voice settings dialog, you can choose the voice you want. 
     249</p> 
     250<h5 id="6.2.1.3">6.2.1.3. Voice Settings</h5> 
     251<p> 
     252The Voice Settings dialog, found in the Preferences menu or accessed by pressing NVDA+Control+V, contains options that let you change the sound of the speech. You can also configure many of the options from anywhere by pressing NVDA+Control along with one of the arrow keys. The left and right arrow keys move through the various settings, the up and down arrows increase or decrease that setting respectively. 
     253</p> 
     254<p> 
     255The Voice Settings dialog box contains the following options: 
     256</p> 
     257<h6>Voice</h6> 
     258<p> 
     259The first option that you land on in this dialog is a combo box listing all the voices of the current synthesizer that you have installed. You can use the arrow keys to listen to all the various choices. Left and Up arrow take you up in the list, while right and down arrow moves you down in the list. 
     260</p> 
     261<h6>Variant</h6> 
     262<p> 
     263If you are using the Espeak synthesizer that is packaged with NVDA, this is a combo box that lets you select the Variant the synthesizer should speak with. ESpeak's Variants are rather like voices, as they provide slightly different attributes to the eSpeak voice. Some variants will sound like a male, some like a female, and some even like a frog. 
     264</p> 
     265<h6>Rate</h6> 
     266<p> 
     267This option allows you to change the rate of your voice. This is a slider that goes from 0 to 100, (0 being the slowest, 100 being the fastest). 
     268</p> 
     269<h6>Pitch</h6> 
     270<p> 
     271This option allows you to change the pitch of the current voice. It is a slider which goes from 0 to 100, (0 being the lowest pitch and 100 being the highest). 
     272</p> 
     273<h6>Volume</h6> 
     274<p> 
     275This option is a slider which goes from 0 to 100, (0 being the lowest volume and 100 being the highest). 
     276</p> 
     277<h6>Inflection</h6> 
     278<p> 
     279This option is a slider that lets you choose how much inflection (rise and fall in pitch) the synthesizer should use to speak with. (The only synthesizer that provides this option at the present time is eSpeak). 
     280</p> 
     281<h6>Speak All Punctuation</h6> 
     282<p> 
     283This setting is a checkbox, that when checked, tells NVDA to speak all punctuation symbols as words (very useful for proof reading). When unchecked, NVDA leaves the punctuation unchanged, so the synthesizer will still read sentences with the right inflection, however the symbols won't be spoken aloud. 
     284</p> 
     285<h6>Raise pitch for capitals</h6> 
     286<p> 
     287This setting, if checked, will raise the pitch for capitals. 
     288</p> 
     289<h6>Say &quot;CAP&quot; before capitals</h6> 
     290<p> 
     291This setting is a checkbox, that when checked, tells NVDA to say the word &quot;cap;&quot; before any capital letter, when arrowing over it or speaking it when its being typed. Usually, NVDA raises the pitch slightly for any capital letter, but some synthesizers may not support this well, so perhaps this option may be of use. 
     292</p> 
     293<h6>Beep for capitals</h6> 
     294<p> 
     295If this checkbox is checked, NVDA will make a small beep each time it encounters a capitalized character by itself. Like the 'say cap for capitals' checkbox, this is useful for Synthesizers that can't change their pitch for capital letters. 
     296</p> 
     297<h5 id="6.2.1.4">6.2.1.4. Braille Settings</h5> 
     298<p> 
     299The braille settings dialog box can be invoked by going to the preferences menu and then to the braille settings option. 
     300</p> 
     301<h6>Braille Display</h6> 
     302<p> 
     303The first option you will come upon in the braille settings dialog is a combo box that says &quot;braille display&quot;. You will be presented with three options. Move between these options with the arrow keys. 
     304</p> 
     305<p> 
     306No braille means that you are not using braille. 
     307</p> 
     308<p> 
     309Freedom Scientific is for Freedom Scientific Focus/Pacmate displays. Note that this option only appears if you have the braille driver from Freedom Scientific installed, see <a href="http://www.freedomscientific.com/PACMATE-HQ/FS_Braille_Display_Driver.asp">Official Freedom Scientific braille drivers page</a> for more info on how to obtain and install the drivers. 
     310</p> 
     311<p> 
     312Handy Tech is for the Handy Tech displays. Note that this option will only exist if you have installed the <a href="ftp://ftp.handytech.de/public/Software/BrailleDriver/bsd1111a.exe">Handy Tech Universal Driver</a> 
     313</p> 
     314<p> 
     315BRLTTY allows you to use a wide list of braille displays. Please install the <a href="http://brl.thefreecat.org/brltty/">BRLTTY Windows installer</a> in order to get support for these displays. 
     316</p> 
     317<h6>Translation Table</h6> 
     318<p> 
     319The next option you will come to in this dialog is the braille table combo box. In this combo box, you will find braille tables for different languages. You can move from braille table to braille table in the list by using the arrow keys. 
     320</p> 
     321<h6>Expand to computer braille for the word at the cursor</h6> 
     322<p> 
     323This option allows the word that is under the cursor to be displayed in non-contracted computer braille. 
     324</p> 
     325<h6>Cursor Blink Rate</h6> 
     326<p> 
     327This option is a numerical field that allows you to change the blink rate of the cursor in milliseconds. 
     328</p> 
     329<h6>Message Timeout (sec)</h6> 
     330<p> 
     331This option is a numerical field that controls how long system messages are displayed on the braille display. 
     332</p> 
     333<h6>Miscellaneous</h6> 
     334<p> 
     335When pressing NVDA+Control+T, you can control what is being displayed on the braille display. The two options are focus and review. Focus displays what is being accessed via the arrow keys, the tab key, in short, focus navigation. Review allows you to review what is on the screen, I.E object navigation. You can cycle between these options by pressing control+NVDA+T. 
     336</p> 
     337<h5 id="6.2.1.5">6.2.1.5. Keyboard settings</h5> 
     338<p> 
     339This dialog box is found in the Preferences menu, under &quot;Keyboard settings...&quot;. Alternatively, it can be accessed by pressing NVDA+Control+K. It contains the following options: 
     340</p> 
     341<h6>Keyboard layout</h6> 
     342<p> 
     343This combo box lets you choose what type of keyboard layout NVDA should use. Currently the two that come with NVDA are Desktop and Laptop. 
     344</p> 
     345<h6>Use capslock as an NVDA modifier key</h6> 
     346<p> 
     347If this checkbox is checked, capslock can be used as an NVDA modifier key. 
     348</p> 
     349<h6>Use extended insert as an NVDA modifier key</h6> 
     350<p> 
     351If this checkbox is checked, the extended insert key (usually found above the arrow keys, near home and end) can be used as an NVDA modifier key. 
     352</p> 
     353<h6>Use numpad insert as an NVDA modifier key</h6> 
     354<p> 
     355If this checkbox is checked, the insert key on the number pad can be used as an NVDA modifier key. 
     356</p> 
     357<h6>Speak Typed Characters</h6> 
     358<p> 
     359A checkbox that when checked means that NVDA will announce all characters you type on the keyboard. You can also configure this option from anywhere by pressing NVDA+2. 
     360</p> 
     361<h6>Speak Typed Words</h6> 
     362<p> 
     363A checkbox that when checked means that NVDA will announce all words you type on the keyboard. You can also configure this option from anywhere by pressing NVDA+3. 
     364</p> 
     365<h6>Speak Command Keys</h6> 
     366<p> 
     367A checkbox that when checked means that NVDA will announce all non-character keys you type on the keyboard. This includes key combinations such as control plus another letter. You can also configure this option from anywhere by pressing NVDA+4. 
     368</p> 
     369<h5 id="6.2.1.6">6.2.1.6. Mouse Settings</h5> 
     370<p> 
     371The Mouse Settings dialog is found in the Preferences Menu, under &quot;Mouse settings...&quot;. Alternatively, it can be accessed by pressing NVDA+Control+M. It contains the following options: 
     372</p> 
     373<h6>Report Mouse Shape Changes</h6> 
     374<p> 
     375A checkbox, that when checked means that NVDA will announce the shape of the mouse pointer each time it changes. The mouse pointer in Windows changes shape to convey certain information such as when something is editable, or when something is loading etc. 
     376</p> 
     377<h6>Report text Under Mouse</h6> 
     378<p> 
     379A checkbox that when checked means that NVDA will announce the text currently under the mouse pointer, as you move it around the screen. This allows you to find things on the screen, by physically moving the mouse, rather than trying to find them through object navigation. 
     380</p> 
     381<h6>Text unit resolution</h6> 
     382<p> 
     383If NVDA is set to announce the text under the mouse as you move it, this option allows you to choose exactly how much text will be spoken. The options are character, word, line and paragraph. 
     384</p> 
     385<h6>Report role when mouse enters object</h6> 
     386<p> 
     387If this checkbox is checked, NVDA will announce the role (type) of object as the mouse moves in side it. 
     388</p> 
     389<h6>Play audio coordinates when mouse moves</h6> 
     390<p> 
     391Checking this checkbox makes NVDA play beeps as the mouse moves, so that the user can work out where the mouse is in regards to the dimentions of the screen. 
     392</p> 
     393<h6>Brightness controls audio coordinates volume</h6> 
     394<p> 
     395If the 'play audio coordinates when mouse moves' checkbox is checked, then checking this checkbox means that the volume of the audio coordinates beeps is controled by how bright the screen is under the mouse. This may cause some performence issues on Windows Vista, so it is unchecked by default. 
     396</p> 
     397<h5 id="6.2.1.7">6.2.1.7. Object Presentation Settings</h5> 
     398<p> 
     399Found in the Preferences menu under &quot;Object Presentation...&quot; or by pressing NVDA+Control+O. This dialog box contains the following options: 
     400</p> 
     401<h6>Report Tool Tips</h6> 
     402<p> 
     403A checkbox that when checked tells NVDA to announce tool tips as they appear. Many Windows and controls show a small message (or tool tip) when you move the mouse pointer over them, or sometimes when you move the focus to them. 
     404</p> 
     405<h6>Report Help Balloons</h6> 
     406<p> 
     407This checkbox when checked tells NVDA to announce help balloons as they appear. Help Balloons are like tool tips, but are usually larger in size, and are associated with system events such as a network cable being unplugged, or perhaps to alert you about Windows security issues. 
     408</p> 
     409<h6>Report Object Shortcut Keys</h6> 
     410<p> 
     411When this checkbox is checked, NVDA will include the shortcut key that is associated with a certain object or control when it is announced. For example the File menu on a menu bar may have a shortcut key of alt+f. 
     412</p> 
     413<h6>Report object position information</h6> 
     414<p> 
     415This option lets you choose whether you wish to have an object's position (e.g. 1 of 4) reported when moving to the object with the focus or object navigation. 
     416</p> 
     417<h6>Report Object descriptions</h6> 
     418<p> 
     419Uncheck this checkbox if you feel you don't need to hear the description announced along with objects. 
     420</p> 
     421<h6>Progress bar output</h6> 
     422<p> 
     423A progress bar is a control which looks a bit like a ruler. As a task is slowly being completed, more of the bar gets highlighted. It also shows a percentage value, to numerically tell you how far along it is. Progress bars are shown for things like loading a web page, checking your email, or processing a sound file etc. 
     424</p> 
     425<p> 
     426This option presents you with a combo box which controls how nvda reports progress bar updates to you. It has the following options: 
     427</p> 
     428<ul> 
     429<li>Off: Progress bars will not be reported as they change.</li> 
     430<li>Speak: This option tells nvda to speak the progress bar in percentages. Each time the progress bar changes, nvda will speak the new value.</li> 
     431<li>Beep: This tells nvda to beep each time the progress bar changes. The higher the beep, the closer the progress bar is to completion.</li> 
     432<li>Beep and speak: This option tells nvda to both beep and speak when a progress bar updates.</li> 
     433</ul> 
     434<h6>Report background progress bars</h6> 
     435<p> 
     436This is an option that, when checked, tells nvda to keep reporting a progress bar, even if it is not physically in the foreground. If you minimize or switch away from a window that contains a progress bar, nvda will keep track of it, allowing you to do other things while nvda tracks the progress bar. 
     437</p> 
     438<h5 id="6.2.1.8">6.2.1.8. Virtual Buffer Settings</h5> 
     439<p> 
     440The Virtual Buffer settings dialog can be found in the Preferences menu, under &quot;Virtual Buffers...&quot;. Alternatively, it can be accessed by pressing NVDA+Control+B. 
     441</p> 
     442<p> 
     443The dialog contains the following options: 
     444</p> 
     445<h6>Maximum Number of Characters on One Line</h6> 
     446<p> 
     447This field sets the maximum length of a line of a virtual buffer (in characters). 
     448</p> 
     449<h6>Maximum Lines Per Page</h6> 
     450<p> 
     451Although virtual buffers don't really have pages, this field sets the amount of lines you will move by when pressing page up or page down while in a virtual buffer. 
     452</p> 
     453<h6>Use screen layout</h6> 
     454<p> 
     455This option allows you to specify whether content in the virtual Buffer should place content such as links and other fields on their own line, or if it should keep them in the flow of text as it is visually shown. If the option is enabled then things will stay as they are visually shown, but if it is disabled then fields will be placed on their own line. 
     456</p> 
     457<h6>Report layout tables</h6> 
     458<p> 
     459When disabled this option makes NVDA only report tables that contain tabular data (where it makes sense to know that this is a table). But if enabled, NVDA will also report tables used purely for visual presentation. 
     460</p> 
     461<h6>Configuring announcement of fields such as links and headings</h6> 
     462<p> 
     463Previous versions of NVDA allowed you to use the Virtual Buffer settings dialog to configure whether NVDA should announce the type of field that you entered while reading through web content. Examples of field types are links, headings, tables, and lists. To configure these, please find new options in the <a href="#6.2.1.9">Document Formatting Settings dialog</a>. These options now not only affect virtual Buffers, but any documents that may cause these types of fields to be announced. 
     464</p> 
     465<h6>Automatic focus mode for focus changes</h6> 
     466<p> 
     467This option allows focus mode to be invoked if focus changes. For example, when on a web page, if you press tab and you land on a form, if this option is checked, focus mode will automatically be invoked. 
     468</p> 
     469<h6>Automatic focus mode for carret movement</h6> 
     470<p> 
     471This option, when checked, allows NVDA to enter and leave focus mode when using arrow keys. For example, if arrowing down a webpage and you land on an edit box, NVDA will automatically bring you into focus mode. If you arrow out of the edit box, NVDA will put you back in browse mode. 
     472</p> 
     473<h6>Audio indication of Focus and Browse modes</h6> 
     474<p> 
     475If this option is enabled, NVDA will play special sounds when it switches between browse mode and focus mode in a virtual Buffer, rather than speaking the change. 
     476</p> 
     477<h5 id="6.2.1.9">6.2.1.9. Document Formatting Settings</h5> 
     478<p> 
     479This dialog box is found in the Preferences menu, under &quot;Document Formatting...&quot;. Alternatively, this dialog box can be invoked by pressing NVDA+Control+D. All the checkboxes in this dialog are for configuring what type of formatting you wish to hear automatically as you move the cursor around microsoft word or wordpad documents. For example, if you check the report font name checkbox, each time you arrow onto text with a different font, the name of the font will be announced. 
     480</p> 
     481<p> 
     482You can configure announcement of font name, font size, font attributes, style, text alignment, text style, tables, page numbers, line numbers, spelling errors, links, headings, lists and blockquotes. 
     483</p> 
     484<h5 id="6.2.1.10">6.2.1.10. Speech dictionaries</h5> 
     485<p> 
     486The speech dictionaries menu (found in the Preferences menu) contains dialogs that allow you to manage the way NVDA pronounces particular words or phrases. There are currently three different types of speech dictionaries. They are: 
     487</p> 
     488<ul> 
     489<li>Default: rules in this dictionary affect all speech in NVDA.</li> 
     490<li>Voice: rules in this dictionary affect speech for the synthesizer voice currently being used.</li> 
     491<li>Temporary: rules in this dictionary affect all speech in NVDA, but only for the current session. These rules are temporary and will be lost if NVDA is restarted.</li> 
     492</ul> 
     493<p> 
     494All dictionary dialogs contain a list of rules which will be used for processing the speech. The dialog also contains Add, Edit and remove buttons. 
     495</p> 
     496<p> 
     497To add a new rule to the dictionary, press the Add button, and fill in the fields in the dialog box that appears and then press Ok. You will then see your new rule in the list of rules. However to make sure your rule is actually saved, make sure to press Ok to exit the dictionary dialog all together once you have finished adding/editing rules. 
     498</p> 
     499<p> 
     500The rules for NVDA's speech dictionaries allow you to change one string of characters in to another.  A simple example would be that you want to have NVDA say the word frog each time it is supposed to say the word bird. In the Add rule dialog, the easiest way to do this is to type the word bird in the Pattern field, and the word frog in the Replacement field. You may also want to type a description of the rule in the Comment field (something like: changes bird to frog). 
     501</p> 
     502<p> 
     503NVDA's speech dictionaries however are much more powerful than simple word replacement. The Add rule dialog also contains a checkbox to say whether or not you want the rule to be case sensitive (meaning that NVDA should care whether the characters are uppercase or lowercase. NVDA ignores case by default). Another chekbox allows you to state whether your pattern is a &quot;Regular expression&quot;. A regular expression is a pattern containing special symbols that allow you to match on more than one character at a time, or match on just numbers, or just letters, as a few examples. Regular expressions are not covered in this user guide, but there are many tutorials on the web which can provide you with more information. 
     504</p> 
     505<h4 id="6.2.2.">6.2.2. Saving and Reloading the configuration</h4> 
     506<p> 
     507NVDA stores its settings in a file called nvda.ini in its directory. You will probably never have to touch this file, but for advanced users, this file does allow you to change some extra settings which don't yet have dialog boxes to do so. 
     508</p> 
     509<p> 
     510NVDA does not automatically save your settings, so if you exit NVDA, and then restart it, the settings will go back to the original values. Note, however, that this default option can be changed under the general options in the preferences menu. To save the settings, you can either choose the Save configuration item in the NVDA menu, or press NVDA+Control+c from anywhere. 
     511</p> 
     512<p> 
     513If NVDA is on a read-only file system, such as a CD, it will not be able to save your settings, and it will tell you so. 
     514</p> 
     515<p> 
     516If you ever make a mistake with your settings and need to revert back to the saved settings, you can either choose the &quot;revert to saved configuration&quot; item in the NVDA menu, or you can press NVDA+Control+r from anywhere.  
     517</p> 
     518<h2 id="7">7. Navigating with NVDA</h2> 
     519<h3 id="7.1">7.1. Navigating with the Focus</h3> 
     520<p> 
     521The Most common way of navigating around Windows with NVDA, is to just move around with normal keyboard commands, such as tab and shift tab to move forward and back between controls, pressing alt to get to the menu bar and then using the arrows to navigate menus, using alt+tab to move between running applications. As you do this, NVDA will announce what has focus. 
     522</p> 
     523<p> 
     524When NVDA announces an object (e.g. when it receives focus), it will usually say the object's name, type, state, value, description, keyboard shortcut, and positional information. This is quite similar to other screen readers; however the types of objects may be a little different. 
     525</p> 
     526<p> 
     527There are some key commands that are useful when moving with focus: 
     528</p> 
     529<ul> 
     530<li>NVDA+tab - reports the current focus</li> 
     531<li>NVDA+b - reads the entire foreground window (useful for reading a dialog box)</li> 
     532<li>NVDA+t - Announces the title of the current foreground window</li> 
     533</ul> 
     534<h3 id="7.2">7.2. Navigating with the System Caret</h3> 
     535<p> 
     536When the focus is on an object that has an edit cursor (system caret), you can arrow around and edit like you normally would. NVDA will announce as you move by character, word, line, and will also announce selecting and unselecting text. 
     537</p> 
     538<p> 
     539When you move with the system caret, the position of the review cursor will also be updated to match the system caret. 
     540</p> 
     541<p> 
     542You can also read the entire text (say all) with NVDA+down Arrow. Note though that this is different to numpad Plus which only moves the review cursor, this moves the system caret as it goes. 
     543</p> 
     544<h3 id="7.3">7.3. Object Navigation</h3> 
     545<p> 
     546If you wish to navigate around the current application or the Operating System a bit, but with out moving the focus, you can use NVDA's object navigation. This allows you to move from object to object in a tree like structure. 
     547</p> 
     548<p> 
     549The tree structure of objects starts at the desktop window, the root of the tree. The first branches of the tree are the currently running applications, and of course these applications have their own branches (objects), representing various parts of the application. 
     550</p> 
     551<p> 
     552The tree structure can get quite large, but it does allow you to navigate in a logical order, so that you can quickly find the information you need. 
     553</p> 
     554<p> 
     555This structure has nothing to do with how the objects are laid out on the screen, but how they are related logically. This may take a little bit of time to get used to, but once you grasp this, you should be able to move around quite easily. 
     556</p> 
     557<p> 
     558NVDA currently can not navigate the objects in a screen-based layout due to not having a video intercept driver or display hooks. NVDA chooses not to interact with the screen, more so because over all it should allow a much clearer, and more logical perception of an application and the operating system, rather than trying to picture a flat screen layout. 
     559</p> 
     560<p> 
     561Not all applications have a perfect tree structure, but this is up to the developer of that particular application. Most seem to be ok; certainly most Dialog boxes and highly structured applications seem to have gotten it right. 
     562</p> 
     563<p> 
     564To navigate by object, use the following keys: 
     565</p> 
     566<ul> 
     567<li>NVDA+numpad5: Speak current object</li> 
     568<li>NVDA+numpad8: Move to parent object (moving towards the root of the tree)</li> 
     569<li>NVDA+numpad4: Move to previous object (the object directly before this one on the same level)</li> 
     570<li>NVDA+numpad6: Move to Next object (the object directly after this one on the same level)</li> 
     571<li>NVDA+numpad2: Move to first child object (The first branch coming out of this one)</li> 
     572<li>NVDA+shift+numpad4: Move to previous object in flow (crosses parent child object boundaries automatically until it can go previous)</li> 
     573<li>NVDA+shift+numpad6: Move to next object in flow (crosses parent child object boundaries automatically until it can go next)</li> 
     574<li>NVDA+numpadMinus: Move to focus</li> 
     575<li>NVDA+numpadEnter: Activate current object (e.g. press enter / click / double click)</li> 
     576<li>NVDA+numpadDivide: Move the mouse to the current object</li> 
     577<li>NVDA+numpadMultiply: Move to the mouse</li> 
     578<li>NVDA+numpadDelete: announce current object's dimentions in regards to the screen</li> 
     579<li>NVDA+numpadPlus: say all objects - starts reading from the current object, traveling next in flow</li> 
     580</ul> 
     581<p> 
     582note: numpad keys require numlock key to be turned off to work properly 
     583</p> 
     584<p> 
     585When you move with the focus, the current navigator object changes along with it. However, if you wish to lock the object navigation to one specific object, so it doesn't change with the focus, you can turn off focus Moves Navigator Object with NVDA+7. 
     586</p> 
     587<h3 id="7.4">7.4. Reviewing the Text in the Current Object</h3> 
     588<p> 
     589NVDA allows you to read the contents of the current navigator object, by character, word or line. This is mostly useful in Dos console windows, and other places where there is a limited or non-existant system caret. 
     590</p> 
     591<ul> 
     592<li>Shift+numpad7: Top line</li> 
     593<li>numpad7: Previous line</li> 
     594<li>numpad8: Current line</li> 
     595<li>numpad9: Next line</li> 
     596<li>shift+numpad9: Bottom line</li> 
     597<li>numpad4: Previous word</li> 
     598<li>numpad5: Current word</li> 
     599<li>numpad6: Next word</li> 
     600<li>shift+numpad1: Start of line</li> 
     601<li>numpad1: Previous character</li> 
     602<li>numpad2: Current character</li> 
     603<li>numpad3: Next character</li> 
     604<li>shift+numpad3: End of line</li> 
     605<li>numpad Plus: Say all text</li> 
     606</ul> 
     607<p> 
     608note: numpad keys require numlock key to be turned off to work properly 
     609</p> 
     610<p> 
     611When an object contains an edit cursor (system caret), and it moves, the review cursor is also updated to that position. If you want the review cursor to stay where it is, and not move with the caret, you can turn off caret Moves Review Cursor by pressing NVDA+6. 
     612</p> 
     613<p> 
     614It is possible to copy parts of the text you are reviewing. For example, you may wish to copy an internet address someone has sent you in a text chat program. To copy text, Start by moving the review cursor to the first character of the text you wish to copy, and press NVDA+f9. Then move to the end of the text, and press NVDA+f10. The text will now be copied to the clipboard so that you can paste it somewhere else. Note that if the program you are using already allows you to move through the text using the system caret, and copy using the normal control+c command, then you will always get better results using this. 
     615</p> 
     616<h3 id="7.5">7.5. Navigating with the Mouse</h3> 
     617<p> 
     618When you move the Mouse, NVDA by default reports the text that is directly under the mouse pointer, as it moves over it. Where supported, NVDA will read a paragraph's worth of text, though some controls may only read by line. 
     619</p> 
     620<p> 
     621NVDA can also be configured to also announce the type of control or object the mouse is currently over as it moves (e.g. list, button etc), which may be useful for totally blind users as sometimes the text isn't enough. 
     622</p> 
     623<p> 
     624NVDA provides a way for users to understand where the mouse is in regards to the dimentions of the screen, by playing the current mouse coordinates as audio beeps. The higher the mouse is on the screen, the higher the pitch of the beeps. The more left or right the mouse is on the screen, the more left or right the sound will seem to come from (assuming the user has stereo speakers). 
     625</p> 
     626<p> 
     627These extra mouse features are not turned on by default in NVDA, but if you wish to take advantage of them, you can configure them from the Mouse settings dialog, found in the Preferences menu on the NVDA menu. 
     628</p> 
     629<h2 id="8">8. Virtual Buffers</h2> 
     630<p> 
     631Complex read-only documents, such as web pages, are represented in NVDA with in a Virtual Buffer. 
     632</p> 
     633<p> 
     634A virtual buffer is a flat representation of content such as a web page, that can be moved around in with the arrow keys. Information such as whether text is a link, heading etc is announced along with the text as you move. 
     635</p> 
     636<p> 
     637While in a virtual buffer, there are two modes of interaction. Browse mode is where you can move around all the text using a virtual cursor. Focus mode is where you can directly interact with the control (edit field, combo box, radio buttons) using what ever keys you would normally use. When in Browse mode, NVDA will automatically switch to focus mode if you tab to or click on a particular control that requires it. Note that pressing enter or space on controls that require it will also switch to focus mode. You can also manually change to focus mode with NVDA+space. If NVDA automatically changed to focus mode because of a tab, click or enter/space key press, it will change back to browse mode once you tab or click on to something that doesn't require it, or if you press escape. However, if you changed to focus mode with NVDA+space, it will stay in focus mode until you manually go back to browse mode. At any time when you are in focus mode, you can manually switch back to browse mode by pressing escape, or NVDA+space. The virtual buffer settings dialog in the preferences menu in the NVDA menu allows you to disable automatic switching of browse mode and focus mode. 
     638</p> 
     639<p> 
     640Currently NVDA uses Virtual Buffers for reading documents in Mozilla Firefox, Microsoft Internet Explorer, and Adobe Reader. 
     641</p> 
     642<h3 id="8.1">8.1. Single Letter Navigation</h3> 
     643<p> 
     644While in browse mode, For quicker navigation NVDA also provides single character keys to jump to certain fields in a virtual buffer. 
     645</p> 
     646<p> 
     647By themselves they jump to the next field, with the shift key they jump to the previous field. 
     648</p> 
     649<p> 
     650Available keys: 
     651</p> 
     652<ul> 
     653<li>h: heading</li> 
     654<li>l: list</li> 
     655<li>i: list item</li> 
     656<li>t: table</li> 
     657<li>k: link</li> 
     658<li>n: nonLinked text</li> 
     659<li>f: form field</li> 
     660<li>u: unvisited link</li> 
     661<li>v: visited link</li> 
     662<li>e: edit field</li> 
     663<li>b: button</li> 
     664<li>x: checkbox</li> 
     665<li>c: combo box</li> 
     666<li>r: radio button</li> 
     667<li>q: block quote</li> 
     668<li>s: separator</li> 
     669<li>m: frame</li> 
     670<li>g: graphic</li> 
     671<li>d: ARIA landmark</li> 
     672<li>o: embedded object</li> 
     673<li>1 to 6: headings 1 to 6 respectively</li> 
     674</ul> 
     675<h3 id="8.2">8.2. Forms and Focus Mode</h3> 
     676<p> 
     677Sometimes you may wish to interact with form fields with out the virtual buffer keys getting in the way. Focus mode is created for this purpose, and can be toggled on and off with NVDA+space. 
     678</p> 
     679<h3 id="8.3">8.3. The Elements List</h3> 
     680<p> 
     681The elements list (available by pressing NVDA+f7 while in a virtual buffer) provides access to a list of either links, headings or ARIA landmarks on the page. Radio buttons allow you to switch between these three types of information. An edit field is also provided in the dialog which allows you to filter the list to help you search for a particular item on the page. Once you have chosen an item, you can use the provided buttons in the dialog to move to, or activate, that item. 
     682</p> 
     683<h3 id="8.4">8.4. Embedded Objects</h3> 
     684<p> 
     685Pages can include rich content using technologies such as Adobe Flash and Sun Java. Where these are encountered in a virtual buffer, NVDA will announce &quot;embedded object&quot;. You can press enter on these objects to interact with them. If it is accessible, you can then tab around it and interact with it like any other application. To return to the page, press NVDA+space. 
     686</p> 
     687<h2 id="9">9. Troubleshooting NVDA</h2> 
     688<p> 
     689As NVDA is constantly being updated, there is no guarantee that all commands provided here in this user guide will still apply. If you have any problems with any of the commands presented in this user guide, please visit: <a href="http://www.nvda-project.org/">http://www.nvda-project.org/</a> for more assistance. 
     690</p> 
     691 
     692</body> 
     693</html> 

  • user_docs/en/user 

    === added file 'user_docs/en/user guide.txt'
     
     1%%title: NVDA 2009.1 User Guide 
     2%%lang:en 
     3 
     4 
     5=NVDA 2009.1 User Guide= 
     6 
     7 
     8Last updated September 13, 2009 
     9 
     10==Table of Contents== 
     11 
     12* [[#1 | 1. Introduction]] 
     13** [[#1.1 | 1.1. General features]] 
     14** [[#1.2 | 1.2. Internationalization]] 
     15** [[#1.3 | 1.3. Speech synthesizer support]] 
     16** [[#1.4 | 1.4. Braille support]] 
     17** [[#1.5 | 1.5. License and copyright]] 
     18* [[#2 | 2. System Requirements]] 
     19* [[#3 | 3. Getting NVDA]] 
     20* [[#4 | 4. Installing NVDA]] 
     21** [[#4.1 | 4.1. The NVDA Installer]] 
     22** [[#4.2 | 4.2. NVDA Portable]] 
     23* [[#5 | 5. Getting started with NVDA]] 
     24** [[#5.1 | 5.1. Launching NVDA]] 
     25** [[#5.2 | 5.2. About NVDA keyboard commands]] 
     26* [[#6 | 6. The NVDA menu]] 
     27** [[#6.1 | 6.1. Accessing the NVDA menu]] 
     28** [[#6.2 | 6.2. Configuring NVDA]] 
     29*** [[#6.2.1 | 6.2.1 The Preferences Menu]] 
     30**** [[#6.2.1.1 | 6.2.1.1. General Settings]] 
     31**** [[#6.2.1.2 | 6.2.1.2. Synthesizer Selection]] 
     32**** [[#6.2.1.3 | 6.2.1.3. Voice Settings]] 
     33**** [[#6.2.1.4 | 6.2.1.4. Braille Settings]] 
     34**** [[#6.2.1.5 | 6.2.1.5. Keyboard Settings]] 
     35**** [[#6.2.1.6 | 6.2.1.6. Mouse Settings]] 
     36**** [[#6.2.1.7 | 6.2.1.7. Object Presentation Settings]] 
     37**** [[#6.2.1.8 | 6.2.1.8. Virtual Buffer Settings]] 
     38**** [[#6.2.1.9 | 6.2.1.9. Document Formatting Settings]] 
     39**** [[#6.2.1.10 | 6.2.1.10. Speech dictionaries]] 
     40*** [[#6.2.2 | 6.2.2: Saving and Reverting Configuration]] 
     41* [[#7 | 7. Navigating with NVDA]] 
     42** [[#7.1 | 7.1. Navigating by Focus]] 
     43** [[#7.2 | 7.2. Navigating with the System Caret]] 
     44** [[#7.3 | 7.3. Object Navigation]] 
     45** [[#7.4 | 7.4. Reviewing Text in the Current Object]] 
     46** [[#7.5 | 7.5. Navigating with the Mouse]] 
     47* [[#8 | 8. Virtual Buffers]] 
     48** [[#8.1 | 8.1. Single Letter Navigation]] 
     49** [[#8.2 | 8.2. Forms and Focus Mode]] 
     50** [[#8.3 | 8.3. The Elements list]] 
     51** [[#8.4 | 8.4. Embedded Objects]] 
     52* [[#9 | 9. Troubleshooting NVDA]] 
     53 
     54==%id:1 1. Introduction== 
     55 
     56 
     57===%id:1.1 1.1. General Features=== 
     58 
     59 
     60 
     61Providing feedback by synthetic speech, Nonvisual Desktop Access allows blind and vision impaired people to access and interact with the Windows operating system and many third party applications. 
     62 
     63 
     64 
     65Major highlights include: 
     66 
     67* Ability to run entirely from a USB stick or other portable media without the need for installation 
     68* Easy to use talking installer  
     69* Browsing the web with [[http://www.getfirefox.com/ 
    070| Mozilla Firefox 3]] 
     71* Working with email using [[http://www.mozillamessaging.com/en-US/thunderbird/early_releases/ | Mozilla Thunderbird 3]] 
     72* Support for Microsoft Internet Explorer 
     73* Basic support for Microsoft Outlook Express / Windows Mail 
     74* support for Microsoft Word and Excel 
     75* Support for accessible Java applications 
     76* Support for Adobe Reader 
     77* Early support for IBM Lotus Symphony 
     78* support for Windows Command Prompt and console applications 
     79* Automatic announcement of text under the mouse and optional audible indication of the mouse position 
     80* Support for many refreshable Braille displays 
     81 
     82===%id:1.2 1.2. Internationalization=== 
     83 
     84 
     85 
     86It is important that people anywhere in the world, no matter what language they speak, get equal access to technology. NVDA currently has been translated into over 20 languages besides the English language including: Arabic, Brazilian Portuguese, Croatian, Czech, Finnish, French, Galician, German, Hungarian, Italian, Japanese, Portuguese, Russian, Slovak, Spanish, Thai, Traditional Chinese, Ukrainian, Afrikaans, Polish and Vietnamese. 
     87 
     88===%id:1.3 1.3. Speech Synthesizer Support=== 
     89 
     90 
     91 
     92Apart from providing its messages and interface in several languages, NVDA can also enable the user to read content in any language, as long as they have a speech synthesizer that can speak that particular language. 
     93 
     94 
     95 
     96NVDA is bundled with [[http://espeak.sourceforge.net/ | eSpeak]], a free, open-source, multi-lingual speech synthesizer. Additionally, NVDA can use both SAPI4 and SAPI5 speech engines to provide speech output, as well as the Audiologic and NewFon speech synthesizers. 
     97 
     98 
     99===%id:1.4 1.4. Braille support=== 
     100 
     101 
     102 
     103For users that own a refreshable braille display, NVDA can output its information in braille. NVDA supports Freedom Scientific Pacmate and Focus displays, Handy Tech displays, ALVA BC640/680 displays, plus many others supported by the BRLTTY package if it is available. 
     104 
     105 
     106 
     107NVDA supports many braille codes covering a large set of languages. In many cases grade 1 and 2 versions of the codes are available. For English readers both U.S. English braille and Unified English braille (UEB) codes are included. 
     108 
     109 
     110===%id:1.5 1.5. Licence and Copyright=== 
     111 
     112 
     113 
     114NVDA is copyright 2006-2009 NVDA contributors. 
     115 
     116 
     117 
     118NVDA is covered by the GNU General Public License (Version 2). You are free to share or change this software in any way you like as long as you distribute the licence along with the software, and make all source code available to anyone who wants it. This applies to both original and modified copies of the software, plus any software that uses code taken from this software. 
     119For further details, you can [[http://www.gnu.org/licenses/old-licenses/gpl-2.0.html | view the full licence.]] 
     120 
     121==%id:2 2. System Requirements== 
     122 
     123* Operating Systems: all 32-bit and 64-bit versions of Windows XP, Windows Vista and Windows 7 (including Server operating Systems), may partially work on Windows 2000. 
     124* Memory: 256 mb or more of RAM 
     125* Processor speed: 1.0 ghz or above 
     126* About 50 MB of storage space. 
     127 
     128==%id:3 3. Getting NVDA== 
     129 
     130 
     131 
     132If you have not yet got a copy of NVDA, you can download it [[http://www.nvda-project.org/ | here]]. 
     133 
     134 
     135 
     136Go to the download section and you will find a link to download the latest version of NVDA. 
     137 
     138 
     139 
     140There are currently two ways NVDA is packaged. One is an Installer which will talk you through installing NVDA so that you can then run it at any time from the Start Menu. The other is a self-extracting archive file that contains a fully portable version of NVDA, which you can run from anywhere, including a USB thumb drive or CD. 
     141 
     142 
     143==%id:4 4. Installing NVDA== 
     144 
     145 
     146===%id:4.1 4.1. The NVDA Installer=== 
     147 
     148 
     149 
     150If you already have the NVDA installer, simply press enter or double click on the file and the installer will start. 
     151 
     152 
     153 
     154As the installer loads, you will hear the NVDA installation music. Once loaded, a temporary copy of NVDA will allow you to follow the prompts of the installer and install NVDA. Note that if you were running another copy of NVDA at the time you started the installer, a message will appear telling you that your previous copy of NVDA will be closed. When you press enter on this message, the installer will close your previous copy and start its own one. This is necessary so that the installer can properly update any changed files. At this point, if you have another copy of NVDA already installed, the NVDA installer will uninstall it for you, and then it will commence to install NVDA. 
     155 
     156 
     157 
     158Once you have successfully completed the installation, the installer will alert you that the install of NVDA has finished. If reinstalling NVDA, It may ask you to reboot the system at this point. It is very important that you reboot the system as failing to do so will have undesirable consequences. If it did not ask you to reboot, pressing Finnish will close the installer and start the newly installed version of NVDA. 
     159 
     160 
     161===%id:4.2 4.2. NVDA portable=== 
     162 
     163 
     164 
     165If you have the portable version of NVDA, then all you have to do is to press enter or double click on the file, and follow the prompts. It will ask you where on your system you wish to place the files. 
     166 
     167 
     168==%id:5 5. Getting started with NVDA== 
     169 
     170 
     171===%id:5.1 5.1. Launching NVDA=== 
     172 
     173 
     174 
     175If you have installed NVDA with the installer, then starting NVDA is as simple as either pressing control+alt+n, or choosing NVDA from the NVDA menu under Programs on the Start Menu. Additionally you can type NVDA into the Run dialog and press Enter. 
     176 
     177 
     178 
     179To start the portable version, go to the directory you unpacked NVDA to, and press enter or double click on nvda.exe. 
     180 
     181 
     182 
     183As NVDA starts, you will first hear an ascending set of tones (telling you that NVDA is loading). Depending on how fast your computer is, or if you are running NVDA off a USB key or other slower medium, it may take a little while to start. If it is taking an extra long time, NVDA should say "Loading subsystems. Please wait..." 
     184 
     185 
     186If you don't hear any of this, or you hear the Windows error sound, or a descending set of tones, then this means that NVDA has an error, and you will need to possibly report a bug to the developers. Please check out the NVDA website for how to do this. 
     187 
     188 
     189 
     190When NVDA starts for the first time, you will be greeted by a dialog box which provides you with some basic information about the NVDA modifier key and the NVDA menu. (Please see further sections about these topics). The dialog box also contains two checkboxes. The first lets you control if NVDA should use the capslock as an NVDA modifier key, and the second lets you control if this Welcome dialog should appear each time NVDA starts. 
     191 
     192 
     193===%id:5.2 5.2. About NVDA keyboard commands=== 
     194 
     195 
     196 
     197Most NVDA-specific keyboard commands usually consist of pressing the NVDA modifier key, in conjunction with one or more other keys. An exception to this are the text review commands which just use the numpad keys by themselves. 
     198 
     199 
     200 
     201By default both numpad insert and extended insert can be used as the NVDA modifier key. However, you can also configure NVDA so that the capslock key also becomes an NVDA modifier key. When configured this way, pressing or holding down capslock acts as an NVDA modifier key, but pressing it twice in quick succession causes it to act as the normal capslock key. 
     202 
     203 
     204 
     205Many key commands are mentioned through out the rest of this user guide, but an easy way to explore all the different key commands is to turn on keyboard help. 
     206 
     207 
     208 
     209To turn on keyboard help, press NVDA+1. To turn it off again, press NVDA+1 again. While in keyboard help, pressing any key will announce what it does (if in deed it does do something). The keys will not actually perform their function while in keyboard help mode, so you can press what ever keys you like. 
     210 
     211 
     212==%id:6 6. The NVDA menu== 
     213 
     214 
     215 
     216The NVDA menu allows you to control NVDA's settings, access help, save/revert your configuration, Modify speech dictionaries, read the log file, and exit NVDA. 
     217 
     218 
     219===%id:6.1 6.1. Accessing the NVDA menu=== 
     220 
     221 
     222 
     223To get to the NVDA menu from anywhere in Windows while NVDA is running, press NVDA+n. You can also get to the NVDA menu via the windows system tray. Either right-click on the nvda icon located in the system tray, or access the system tray by pressing the windows logo key+B, DownArrow to the NVDA icon and press the applications key located next to the right control key on most keyboards. When the menu comes up, You can use the arrow keys to navigate the menu, and the enter key to activate an item. The Preferences menu allows you to configure NVDA how you like, the tools menu contains useful tools such as the NVDA log viewer and the NVDA Python console for developers, the help menu allows you to access the user guide, a quick key reference, and much more. The NVDA menu also contains items that allow you to save or revert your current configuration. There is also an option that allows you to exit NVDA, although this can be accomplished more efficiently by pressing NVDA+Q. 
     224 
     225 
     226 
     227The options under the preferences menu can also be accessed via keyboard shortcut commands, as well as the NVDA Python Console, save and revert configuration options discussed in this section. For more information about this, please visit the quick reference guide for a list of shortcut commands.  
     228 
     229 
     230===%id:6.2 6.2. Configuring NVDA=== 
     231 
     232 
     233====%id:6.2.1 6.2.1 Preferences==== 
     234 
     235 
     236=====%id:6.2.1.1 6.2.1.1. General Settings===== 
     237 
     238 
     239 
     240The General settings dialog box is found in the Preferences menu. It is also accessed by pressing NVDA+Control+G. To save the options after modifying settings, press the OK button. To cancel, press the cancel button or the escape key. It contains the following options: 
     241 
     242 
     243======Language====== 
     244 
     245 
     246 
     247A combo box which allows you to select the language that NVDA's user interface and messages should be shown in. There are many languages, however the default option is "User Default, Windows". This option tells NVDA to use the language that Windows is currently set to. 
     248Please note that NVDA must be restarted when changing the language. NVDA will ask you if you wish to restart if you do change the selection. Press OK, and NVDA will restart. 
     249 
     250 
     251======Save Configuration on Exit====== 
     252 
     253 
     254 
     255This option is a checkbox that, when checked, tells NVDA to automatically save the current configuration when you exit NVDA. 
     256 
     257 
     258======Warn before exiting NVDA====== 
     259 
     260 
     261 
     262This option is a checkbox that allows you to choose whether or not a dialog appears when you exit NVDA that asks whether or not you would like to exit. When checked, a dialog will appear when you attempt to exit NVDA asking whether or not you want to exit. 
     263 
     264 
     265======Logging level====== 
     266 
     267 
     268 
     269This is a combo box that permits you to choose how much NVDA wil log as it's running. Generally users should not need to touch this as not too much is logged. However if you are wanting to provide information in a bug report, then it may be a useful option. 
     270 
     271 
     272======Automatically start nvda after I log on to windows====== 
     273 
     274 
     275 
     276If this option is enabled, NVDA will start automatically as soon as you log on to Windows. 
     277 
     278 
     279======Use nvda on the windows log on screen (requires administrative privileges)====== 
     280 
     281 
     282 
     283If you log on to Windows by providing a user name and password, then enabling this option will make NVDA start automatically at the logon screen when Windows starts. 
     284 
     285 
     286=====%id:6.2.1.2 6.2.1.2. Synthesizer Selection===== 
     287 
     288 
     289 
     290The Synthesizer dialog, which is found under "Synthesizer..." in the Preferences menu or by pressing NVDA+Control+S, allows you to select which Synthesizer NVDA should use to speak with. 
     291 
     292 
     293 
     294The dialog contains a simple combo box, which lists all the available synthesizers. Choose the synthesizer you want using the arrow keys, and then press ok. If there is an error loading the synthesizer, a message box will alert you, and NVDA will keep the old synthesizer loaded. 
     295 
     296 
     297 
     298The current list of synthesizers NVDA supports is: 
     299eSpeak, SAPI4, SAPI5, Audiologic, Display, and Silence. 
     300 
     301 
     302 
     303The eSpeak synthesizer is built directly in to NVDA, and does not depend on any other special drivers or SAPI runtime to be installed. NVDA starts using eSpeak by default. This synthesizer should work on any system that NVDA works on, so it will definitely work when running NVDA off a USB thumb drive or CD, on anyone else's system. 
     304 
     305 
     306 
     307The Sapi4 option allows you to use the Sapi synthesizer. Voices that are included under Ssapi4 include eloquence voices, as well as other Ssapi4 voices that you may have installed on your system. 
     308 
     309 
     310 
     311The Sapi5 synthesizer allows you to use the microsoft voices that are iincluded on your machine. In XP, the default Ssapi5 voice is Microsoft Sam. In Vista, the default voice is Microsoft Anna. Depending on what voices you have installed, others may show up under Ssapi5. 
     312 
     313 
     314 
     315The Display synthesizer is useful for sighted developers who wish to read what NVDA is speaking, as they test NVDA with their applications. 
     316 
     317 
     318 
     319The Silence synthesizer driver is not that useful, unless you want to not have any speech at all while running NVDA. 
     320 
     321 
     322 
     323Please note that no matter how many different SAPI4 or SAPI5 voices (or engines) you have installed on your system, only the actual SAPI4 and SAPI5 synthesizers will show up in the Synthesizers dialog. To actually select one of the engines (voices), select either SAPI4 or SAPI5, and then in the Voice settings dialog, you can choose the voice you want. 
     324 
     325 
     326=====%id:6.2.1.3 6.2.1.3. Voice Settings===== 
     327 
     328 
     329 
     330The Voice Settings dialog, found in the Preferences menu or accessed by pressing NVDA+Control+V, contains options that let you change the sound of the speech. You can also configure many of the options from anywhere by pressing NVDA+Control along with one of the arrow keys. The left and right arrow keys move through the various settings, the up and down arrows increase or decrease that setting respectively. 
     331 
     332 
     333 
     334The Voice Settings dialog box contains the following options: 
     335 
     336 
     337======Voice====== 
     338 
     339 
     340 
     341The first option that you land on in this dialog is a combo box listing all the voices of the current synthesizer that you have installed. You can use the arrow keys to listen to all the various choices. Left and Up arrow take you up in the list, while right and down arrow moves you down in the list. 
     342 
     343 
     344======Variant====== 
     345 
     346 
     347 
     348If you are using the Espeak synthesizer that is packaged with NVDA, this is a combo box that lets you select the Variant the synthesizer should speak with. ESpeak's Variants are rather like voices, as they provide slightly different attributes to the eSpeak voice. Some variants will sound like a male, some like a female, and some even like a frog. 
     349 
     350 
     351======Rate====== 
     352 
     353 
     354 
     355This option allows you to change the rate of your voice. This is a slider that goes from 0 to 100, (0 being the slowest, 100 being the fastest). 
     356 
     357 
     358======Pitch====== 
     359 
     360 
     361 
     362This option allows you to change the pitch of the current voice. It is a slider which goes from 0 to 100, (0 being the lowest pitch and 100 being the highest). 
     363 
     364 
     365======Volume====== 
     366 
     367 
     368 
     369This option is a slider which goes from 0 to 100, (0 being the lowest volume and 100 being the highest). 
     370 
     371 
     372======Inflection====== 
     373 
     374 
     375 
     376This option is a slider that lets you choose how much inflection (rise and fall in pitch) the synthesizer should use to speak with. (The only synthesizer that provides this option at the present time is eSpeak). 
     377 
     378 
     379======Speak All Punctuation====== 
     380 
     381 
     382 
     383This setting is a checkbox, that when checked, tells NVDA to speak all punctuation symbols as words (very useful for proof reading). When unchecked, NVDA leaves the punctuation unchanged, so the synthesizer will still read sentences with the right inflection, however the symbols won't be spoken aloud. 
     384 
     385 
     386======Raise pitch for capitals====== 
     387 
     388 
     389 
     390This setting, if checked, will raise the pitch for capitals. 
     391 
     392 
     393======Say "CAP" before capitals====== 
     394 
     395 
     396 
     397This setting is a checkbox, that when checked, tells NVDA to say the word "cap;" before any capital letter, when arrowing over it or speaking it when its being typed. Usually, NVDA raises the pitch slightly for any capital letter, but some synthesizers may not support this well, so perhaps this option may be of use. 
     398 
     399 
     400======Beep for capitals====== 
     401 
     402 
     403 
     404If this checkbox is checked, NVDA will make a small beep each time it encounters a capitalized character by itself. Like the 'say cap for capitals' checkbox, this is useful for Synthesizers that can't change their pitch for capital letters. 
     405 
     406 
     407=====%id:6.2.1.4 6.2.1.4. Braille Settings===== 
     408 
     409 
     410 
     411The braille settings dialog box can be invoked by going to the preferences menu and then to the braille settings option. 
     412 
     413 
     414======Braille Display====== 
     415 
     416 
     417 
     418The first option you will come upon in the braille settings dialog is a combo box that says "braille display". You will be presented with three options. Move between these options with the arrow keys. 
     419 
     420 
     421 
     422No braille means that you are not using braille. 
     423 
     424 
     425 
     426Freedom Scientific is for Freedom Scientific Focus/Pacmate displays. Note that this option only appears if you have the braille driver from Freedom Scientific installed, see [[http://www.freedomscientific.com/PACMATE-HQ/FS_Braille_Display_Driver.asp | Official Freedom Scientific braille drivers page]] for more info on how to obtain and install the drivers. 
     427 
     428 
     429 
     430Handy Tech is for the Handy Tech displays. Note that this option will only exist if you have installed the [[ftp://ftp.handytech.de/public/Software/BrailleDriver/bsd1111a.exe | Handy Tech Universal Driver]] 
     431 
     432 
     433BRLTTY allows you to use a wide list of braille displays. Please install the [[http://brl.thefreecat.org/brltty/ | BRLTTY Windows installer]] in order to get support for these displays. 
     434 
     435 
     436======Translation Table====== 
     437 
     438 
     439 
     440The next option you will come to in this dialog is the braille table combo box. In this combo box, you will find braille tables for different languages. You can move from braille table to braille table in the list by using the arrow keys. 
     441 
     442 
     443======Expand to computer braille for the word at the cursor====== 
     444 
     445 
     446 
     447This option allows the word that is under the cursor to be displayed in non-contracted computer braille. 
     448 
     449 
     450======Cursor Blink Rate====== 
     451 
     452 
     453 
     454This option is a numerical field that allows you to change the blink rate of the cursor in milliseconds. 
     455 
     456 
     457======Message Timeout (sec)====== 
     458 
     459 
     460 
     461This option is a numerical field that controls how long system messages are displayed on the braille display. 
     462 
     463 
     464======Miscellaneous====== 
     465 
     466 
     467 
     468When pressing NVDA+Control+T, you can control what is being displayed on the braille display. The two options are focus and review. Focus displays what is being accessed via the arrow keys, the tab key, in short, focus navigation. Review allows you to review what is on the screen, I.E object navigation. You can cycle between these options by pressing control+NVDA+T. 
     469 
     470 
     471=====%id:6.2.1.5 6.2.1.5. Keyboard settings===== 
     472 
     473 
     474 
     475This dialog box is found in the Preferences menu, under "Keyboard settings...". Alternatively, it can be accessed by pressing NVDA+Control+K. It contains the following options: 
     476 
     477 
     478======Keyboard layout====== 
     479 
     480 
     481 
     482This combo box lets you choose what type of keyboard layout NVDA should use. Currently the two that come with NVDA are Desktop and Laptop. 
     483 
     484 
     485======Use capslock as an NVDA modifier key====== 
     486 
     487 
     488 
     489If this checkbox is checked, capslock can be used as an NVDA modifier key. 
     490 
     491 
     492======Use extended insert as an NVDA modifier key====== 
     493 
     494 
     495 
     496If this checkbox is checked, the extended insert key (usually found above the arrow keys, near home and end) can be used as an NVDA modifier key. 
     497 
     498 
     499======Use numpad insert as an NVDA modifier key====== 
     500 
     501 
     502 
     503If this checkbox is checked, the insert key on the number pad can be used as an NVDA modifier key. 
     504 
     505 
     506======Speak Typed Characters====== 
     507 
     508 
     509 
     510A checkbox that when checked means that NVDA will announce all characters you type on the keyboard. You can also configure this option from anywhere by pressing NVDA+2. 
     511 
     512 
     513======Speak Typed Words====== 
     514 
     515 
     516 
     517A checkbox that when checked means that NVDA will announce all words you type on the keyboard. You can also configure this option from anywhere by pressing NVDA+3. 
     518 
     519 
     520======Speak Command Keys====== 
     521 
     522 
     523 
     524A checkbox that when checked means that NVDA will announce all non-character keys you type on the keyboard. This includes key combinations such as control plus another letter. You can also configure this option from anywhere by pressing NVDA+4. 
     525 
     526 
     527=====%id:6.2.1.6 6.2.1.6. Mouse Settings===== 
     528 
     529 
     530 
     531The Mouse Settings dialog is found in the Preferences Menu, under "Mouse settings...". Alternatively, it can be accessed by pressing NVDA+Control+M. It contains the following options: 
     532 
     533 
     534======Report Mouse Shape Changes====== 
     535 
     536 
     537 
     538A checkbox, that when checked means that NVDA will announce the shape of the mouse pointer each time it changes. The mouse pointer in Windows changes shape to convey certain information such as when something is editable, or when something is loading etc. 
     539 
     540 
     541======Report text Under Mouse====== 
     542 
     543 
     544 
     545A checkbox that when checked means that NVDA will announce the text currently under the mouse pointer, as you move it around the screen. This allows you to find things on the screen, by physically moving the mouse, rather than trying to find them through object navigation. 
     546 
     547 
     548======Text unit resolution====== 
     549 
     550 
     551 
     552If NVDA is set to announce the text under the mouse as you move it, this option allows you to choose exactly how much text will be spoken. The options are character, word, line and paragraph. 
     553 
     554 
     555======Report role when mouse enters object====== 
     556 
     557 
     558 
     559If this checkbox is checked, NVDA will announce the role (type) of object as the mouse moves in side it. 
     560 
     561 
     562======Play audio coordinates when mouse moves====== 
     563 
     564 
     565 
     566Checking this checkbox makes NVDA play beeps as the mouse moves, so that the user can work out where the mouse is in regards to the dimentions of the screen. 
     567 
     568 
     569======Brightness controls audio coordinates volume====== 
     570 
     571 
     572 
     573If the 'play audio coordinates when mouse moves' checkbox is checked, then checking this checkbox means that the volume of the audio coordinates beeps is controled by how bright the screen is under the mouse. This may cause some performence issues on Windows Vista, so it is unchecked by default. 
     574 
     575 
     576=====%id:6.2.1.7 6.2.1.7. Object Presentation Settings===== 
     577 
     578 
     579 
     580Found in the Preferences menu under "Object Presentation..." or by pressing NVDA+Control+O. This dialog box contains the following options: 
     581 
     582 
     583======Report Tool Tips====== 
     584 
     585 
     586 
     587A checkbox that when checked tells NVDA to announce tool tips as they appear. Many Windows and controls show a small message (or tool tip) when you move the mouse pointer over them, or sometimes when you move the focus to them. 
     588 
     589 
     590======Report Help Balloons====== 
     591 
     592 
     593 
     594This checkbox when checked tells NVDA to announce help balloons as they appear. Help Balloons are like tool tips, but are usually larger in size, and are associated with system events such as a network cable being unplugged, or perhaps to alert you about Windows security issues. 
     595 
     596 
     597======Report Object Shortcut Keys====== 
     598 
     599 
     600 
     601When this checkbox is checked, NVDA will include the shortcut key that is associated with a certain object or control when it is announced. For example the File menu on a menu bar may have a shortcut key of alt+f. 
     602 
     603 
     604======Report object position information====== 
     605 
     606 
     607 
     608This option lets you choose whether you wish to have an object's position (e.g. 1 of 4) reported when moving to the object with the focus or object navigation. 
     609 
     610 
     611======Report Object descriptions====== 
     612 
     613 
     614 
     615Uncheck this checkbox if you feel you don't need to hear the description announced along with objects. 
     616 
     617 
     618======Progress bar output====== 
     619 
     620 
     621 
     622A progress bar is a control which looks a bit like a ruler. As a task is slowly being completed, more of the bar gets highlighted. It also shows a percentage value, to numerically tell you how far along it is. Progress bars are shown for things like loading a web page, checking your email, or processing a sound file etc. 
     623 
     624 
     625 
     626This option presents you with a combo box which controls how nvda reports progress bar updates to you. It has the following options: 
     627 
     628* Off: Progress bars will not be reported as they change. 
     629* Speak: This option tells nvda to speak the progress bar in percentages. Each time the progress bar changes, nvda will speak the new value. 
     630* Beep: This tells nvda to beep each time the progress bar changes. The higher the beep, the closer the progress bar is to completion. 
     631* Beep and speak: This option tells nvda to both beep and speak when a progress bar updates. 
     632 
     633======Report background progress bars====== 
     634 
     635 
     636 
     637This is an option that, when checked, tells nvda to keep reporting a progress bar, even if it is not physically in the foreground. If you minimize or switch away from a window that contains a progress bar, nvda will keep track of it, allowing you to do other things while nvda tracks the progress bar. 
     638 
     639 
     640=====%id:6.2.1.8 6.2.1.8. Virtual Buffer Settings===== 
     641 
     642 
     643 
     644The Virtual Buffer settings dialog can be found in the Preferences menu, under "Virtual Buffers...". Alternatively, it can be accessed by pressing NVDA+Control+B. 
     645 
     646 
     647 
     648The dialog contains the following options: 
     649 
     650 
     651======Maximum Number of Characters on One Line====== 
     652 
     653 
     654 
     655This field sets the maximum length of a line of a virtual buffer (in characters). 
     656 
     657 
     658======Maximum Lines Per Page====== 
     659 
     660 
     661 
     662Although virtual buffers don't really have pages, this field sets the amount of lines you will move by when pressing page up or page down while in a virtual buffer. 
     663 
     664 
     665======Use screen layout====== 
     666 
     667 
     668 
     669This option allows you to specify whether content in the virtual Buffer should place content such as links and other fields on their own line, or if it should keep them in the flow of text as it is visually shown. If the option is enabled then things will stay as they are visually shown, but if it is disabled then fields will be placed on their own line. 
     670 
     671 
     672======Report layout tables====== 
     673 
     674 
     675 
     676When disabled this option makes NVDA only report tables that contain tabular data (where it makes sense to know that this is a table). But if enabled, NVDA will also report tables used purely for visual presentation. 
     677 
     678 
     679======Configuring announcement of fields such as links and headings====== 
     680 
     681 
     682 
     683Previous versions of NVDA allowed you to use the Virtual Buffer settings dialog to configure whether NVDA should announce the type of field that you entered while reading through web content. Examples of field types are links, headings, tables, and lists. To configure these, please find new options in the [[#6.2.1.9 | Document Formatting Settings dialog]]. These options now not only affect virtual Buffers, but any documents that may cause these types of fields to be announced. 
     684 
     685 
     686======Automatic focus mode for focus changes====== 
     687 
     688 
     689 
     690This option allows focus mode to be invoked if focus changes. For example, when on a web page, if you press tab and you land on a form, if this option is checked, focus mode will automatically be invoked. 
     691 
     692 
     693======Automatic focus mode for carret movement====== 
     694 
     695 
     696 
     697This option, when checked, allows NVDA to enter and leave focus mode when using arrow keys. For example, if arrowing down a webpage and you land on an edit box, NVDA will automatically bring you into focus mode. If you arrow out of the edit box, NVDA will put you back in browse mode. 
     698 
     699 
     700======Audio indication of Focus and Browse modes====== 
     701 
     702 
     703 
     704If this option is enabled, NVDA will play special sounds when it switches between browse mode and focus mode in a virtual Buffer, rather than speaking the change. 
     705 
     706 
     707=====%id:6.2.1.9 6.2.1.9. Document Formatting Settings===== 
     708 
     709 
     710 
     711This dialog box is found in the Preferences menu, under "Document Formatting...". Alternatively, this dialog box can be invoked by pressing NVDA+Control+D. All the checkboxes in this dialog are for configuring what type of formatting you wish to hear automatically as you move the cursor around microsoft word or wordpad documents. For example, if you check the report font name checkbox, each time you arrow onto text with a different font, the name of the font will be announced. 
     712 
     713 
     714 
     715You can configure announcement of font name, font size, font attributes, style, text alignment, text style, tables, page numbers, line numbers, spelling errors, links, headings, lists and blockquotes. 
     716 
     717 
     718=====%id:6.2.1.10 6.2.1.10. Speech dictionaries===== 
     719 
     720 
     721 
     722The speech dictionaries menu (found in the Preferences menu) contains dialogs that allow you to manage the way NVDA pronounces particular words or phrases. There are currently three different types of speech dictionaries. They are: 
     723 * Default: rules in this dictionary affect all speech in NVDA. 
     724* Voice: rules in this dictionary affect speech for the synthesizer voice currently being used. 
     725* Temporary: rules in this dictionary affect all speech in NVDA, but only for the current session. These rules are temporary and will be lost if NVDA is restarted. 
     726 
     727 
     728All dictionary dialogs contain a list of rules which will be used for processing the speech. The dialog also contains Add, Edit and remove buttons. 
     729 
     730 
     731 
     732To add a new rule to the dictionary, press the Add button, and fill in the fields in the dialog box that appears and then press Ok. You will then see your new rule in the list of rules. However to make sure your rule is actually saved, make sure to press Ok to exit the dictionary dialog all together once you have finished adding/editing rules. 
     733 
     734 
     735 
     736The rules for NVDA's speech dictionaries allow you to change one string of characters in to another.  A simple example would be that you want to have NVDA say the word frog each time it is supposed to say the word bird. In the Add rule dialog, the easiest way to do this is to type the word bird in the Pattern field, and the word frog in the Replacement field. You may also want to type a description of the rule in the Comment field (something like: changes bird to frog). 
     737 
     738 
     739 
     740NVDA's speech dictionaries however are much more powerful than simple word replacement. The Add rule dialog also contains a checkbox to say whether or not you want the rule to be case sensitive (meaning that NVDA should care whether the characters are uppercase or lowercase. NVDA ignores case by default). Another chekbox allows you to state whether your pattern is a "Regular expression". A regular expression is a pattern containing special symbols that allow you to match on more than one character at a time, or match on just numbers, or just letters, as a few examples. Regular expressions are not covered in this user guide, but there are many tutorials on the web which can provide you with more information. 
     741 
     742 
     743====%id:6.2.2. 6.2.2. Saving and Reloading the configuration=== 
     744 
     745 
     746 
     747NVDA stores its settings in a file called nvda.ini in its directory. You will probably never have to touch this file, but for advanced users, this file does allow you to change some extra settings which don't yet have dialog boxes to do so. 
     748 
     749 
     750 
     751NVDA does not automatically save your settings, so if you exit NVDA, and then restart it, the settings will go back to the original values. Note, however, that this default option can be changed under the general options in the preferences menu. To save the settings, you can either choose the Save configuration item in the NVDA menu, or press NVDA+Control+c from anywhere. 
     752 
     753 
     754 
     755If NVDA is on a read-only file system, such as a CD, it will not be able to save your settings, and it will tell you so. 
     756 
     757 
     758 
     759If you ever make a mistake with your settings and need to revert back to the saved settings, you can either choose the "revert to saved configuration" item in the NVDA menu, or you can press NVDA+Control+r from anywhere.  
     760 
     761 
     762==%id:7 7. Navigating with NVDA== 
     763 
     764 
     765===%id:7.1 7.1. Navigating with the Focus=== 
     766 
     767 
     768 
     769The Most common way of navigating around Windows with NVDA, is to just move around with normal keyboard commands, such as tab and shift tab to move forward and back between controls, pressing alt to get to the menu bar and then using the arrows to navigate menus, using alt+tab to move between running applications. As you do this, NVDA will announce what has focus. 
     770 
     771 
     772 
     773When NVDA announces an object (e.g. when it receives focus), it will usually say the object's name, type, state, value, description, keyboard shortcut, and positional information. This is quite similar to other screen readers; however the types of objects may be a little different. 
     774 
     775 
     776 
     777There are some key commands that are useful when moving with focus: 
     778 
     779* NVDA+tab - reports the current focus 
     780* NVDA+b - reads the entire foreground window (useful for reading a dialog box) 
     781* NVDA+t - Announces the title of the current foreground window 
     782 
     783===%id:7.2 7.2. Navigating with the System Caret=== 
     784 
     785 
     786 
     787When the focus is on an object that has an edit cursor (system caret), you can arrow around and edit like you normally would. NVDA will announce as you move by character, word, line, and will also announce selecting and unselecting text. 
     788 
     789 
     790 
     791When you move with the system caret, the position of the review cursor will also be updated to match the system caret. 
     792 
     793 
     794 
     795You can also read the entire text (say all) with NVDA+down Arrow. Note though that this is different to numpad Plus which only moves the review cursor, this moves the system caret as it goes. 
     796 
     797 
     798===%id:7.3 7.3. Object Navigation=== 
     799 
     800 
     801 
     802If you wish to navigate around the current application or the Operating System a bit, but with out moving the focus, you can use NVDA's object navigation. This allows you to move from object to object in a tree like structure. 
     803 
     804 
     805 
     806The tree structure of objects starts at the desktop window, the root of the tree. The first branches of the tree are the currently running applications, and of course these applications have their own branches (objects), representing various parts of the application. 
     807 
     808 
     809 
     810The tree structure can get quite large, but it does allow you to navigate in a logical order, so that you can quickly find the information you need. 
     811 
     812 
     813 
     814This structure has nothing to do with how the objects are laid out on the screen, but how they are related logically. This may take a little bit of time to get used to, but once you grasp this, you should be able to move around quite easily. 
     815 
     816 
     817 
     818NVDA currently can not navigate the objects in a screen-based layout due to not having a video intercept driver or display hooks. NVDA chooses not to interact with the screen, more so because over all it should allow a much clearer, and more logical perception of an application and the operating system, rather than trying to picture a flat screen layout. 
     819 
     820 
     821 
     822Not all applications have a perfect tree structure, but this is up to the developer of that particular application. Most seem to be ok; certainly most Dialog boxes and highly structured applications seem to have gotten it right. 
     823 
     824 
     825 
     826To navigate by object, use the following keys: 
     827 
     828* NVDA+numpad5: Speak current object 
     829* NVDA+numpad8: Move to parent object (moving towards the root of the tree) 
     830* NVDA+numpad4: Move to previous object (the object directly before this one on the same level) 
     831* NVDA+numpad6: Move to Next object (the object directly after this one on the same level) 
     832* NVDA+numpad2: Move to first child object (The first branch coming out of this one) 
     833* NVDA+shift+numpad4: Move to previous object in flow (crosses parent child object boundaries automatically until it can go previous) 
     834* NVDA+shift+numpad6: Move to next object in flow (crosses parent child object boundaries automatically until it can go next) 
     835* NVDA+numpadMinus: Move to focus 
     836* NVDA+numpadEnter: Activate current object (e.g. press enter / click / double click) 
     837* NVDA+numpadDivide: Move the mouse to the current object 
     838* NVDA+numpadMultiply: Move to the mouse 
     839* NVDA+numpadDelete: announce current object's dimentions in regards to the screen 
     840* NVDA+numpadPlus: say all objects - starts reading from the current object, traveling next in flow 
     841 
     842 
     843note: numpad keys require numlock key to be turned off to work properly 
     844 
     845 
     846 
     847When you move with the focus, the current navigator object changes along with it. However, if you wish to lock the object navigation to one specific object, so it doesn't change with the focus, you can turn off focus Moves Navigator Object with NVDA+7. 
     848 
     849 
     850===%id:7.4 7.4. Reviewing the Text in the Current Object=== 
     851 
     852 
     853 
     854NVDA allows you to read the contents of the current navigator object, by character, word or line. This is mostly useful in Dos console windows, and other places where there is a limited or non-existant system caret. 
     855 
     856* Shift+numpad7: Top line 
     857* numpad7: Previous line 
     858* numpad8: Current line 
     859* numpad9: Next line 
     860* shift+numpad9: Bottom line 
     861* numpad4: Previous word 
     862* numpad5: Current word 
     863* numpad6: Next word 
     864* shift+numpad1: Start of line 
     865* numpad1: Previous character 
     866* numpad2: Current character 
     867* numpad3: Next character 
     868* shift+numpad3: End of line 
     869* numpad Plus: Say all text 
     870 
     871 
     872note: numpad keys require numlock key to be turned off to work properly 
     873 
     874 
     875 
     876When an object contains an edit cursor (system caret), and it moves, the review cursor is also updated to that position. If you want the review cursor to stay where it is, and not move with the caret, you can turn off caret Moves Review Cursor by pressing NVDA+6. 
     877 
     878 
     879 
     880It is possible to copy parts of the text you are reviewing. For example, you may wish to copy an internet address someone has sent you in a text chat program. To copy text, Start by moving the review cursor to the first character of the text you wish to copy, and press NVDA+f9. Then move to the end of the text, and press NVDA+f10. The text will now be copied to the clipboard so that you can paste it somewhere else. Note that if the program you are using already allows you to move through the text using the system caret, and copy using the normal control+c command, then you will always get better results using this. 
     881 
     882 
     883===%id:7.5 7.5. Navigating with the Mouse=== 
     884 
     885 
     886 
     887When you move the Mouse, NVDA by default reports the text that is directly under the mouse pointer, as it moves over it. Where supported, NVDA will read a paragraph's worth of text, though some controls may only read by line. 
     888 
     889 
     890 
     891NVDA can also be configured to also announce the type of control or object the mouse is currently over as it moves (e.g. list, button etc), which may be useful for totally blind users as sometimes the text isn't enough. 
     892 
     893 
     894 
     895NVDA provides a way for users to understand where the mouse is in regards to the dimentions of the screen, by playing the current mouse coordinates as audio beeps. The higher the mouse is on the screen, the higher the pitch of the beeps. The more left or right the mouse is on the screen, the more left or right the sound will seem to come from (assuming the user has stereo speakers). 
     896 
     897 
     898 
     899These extra mouse features are not turned on by default in NVDA, but if you wish to take advantage of them, you can configure them from the Mouse settings dialog, found in the Preferences menu on the NVDA menu. 
     900 
     901 
     902==%id:8 8. Virtual Buffers== 
     903 
     904 
     905 
     906Complex read-only documents, such as web pages, are represented in NVDA with in a Virtual Buffer. 
     907 
     908 
     909 
     910A virtual buffer is a flat representation of content such as a web page, that can be moved around in with the arrow keys. Information such as whether text is a link, heading etc is announced along with the text as you move. 
     911 
     912 
     913 
     914While in a virtual buffer, there are two modes of interaction. Browse mode is where you can move around all the text using a virtual cursor. Focus mode is where you can directly interact with the control (edit field, combo box, radio buttons) using what ever keys you would normally use. When in Browse mode, NVDA will automatically switch to focus mode if you tab to or click on a particular control that requires it. Note that pressing enter or space on controls that require it will also switch to focus mode. You can also manually change to focus mode with NVDA+space. If NVDA automatically changed to focus mode because of a tab, click or enter/space key press, it will change back to browse mode once you tab or click on to something that doesn't require it, or if you press escape. However, if you changed to focus mode with NVDA+space, it will stay in focus mode until you manually go back to browse mode. At any time when you are in focus mode, you can manually switch back to browse mode by pressing escape, or NVDA+space. The virtual buffer settings dialog in the preferences menu in the NVDA menu allows you to disable automatic switching of browse mode and focus mode. 
     915 
     916 
     917 
     918Currently NVDA uses Virtual Buffers for reading documents in Mozilla Firefox, Microsoft Internet Explorer, and Adobe Reader. 
     919 
     920 
     921===%id:8.1 8.1. Single Letter Navigation=== 
     922 
     923 
     924 
     925While in browse mode, For quicker navigation NVDA also provides single character keys to jump to certain fields in a virtual buffer. 
     926 
     927 
     928 
     929By themselves they jump to the next field, with the shift key they jump to the previous field. 
     930 
     931 
     932 
     933Available keys: 
     934 
     935* h: heading 
     936* l: list 
     937* i: list item 
     938* t: table 
     939* k: link 
     940* n: nonLinked text 
     941* f: form field 
     942* u: unvisited link 
     943* v: visited link 
     944* e: edit field 
     945* b: button 
     946* x: checkbox 
     947* c: combo box 
     948* r: radio button 
     949* q: block quote 
     950* s: separator 
     951* m: frame 
     952* g: graphic 
     953* d: ARIA landmark 
     954* o: embedded object 
     955* 1 to 6: headings 1 to 6 respectively 
     956 
     957===%id:8.2 8.2. Forms and Focus Mode=== 
     958 
     959 
     960 
     961Sometimes you may wish to interact with form fields with out the virtual buffer keys getting in the way. Focus mode is created for this purpose, and can be toggled on and off with NVDA+space. 
     962 
     963 
     964===%id:8.3 8.3. The Elements List=== 
     965 
     966 
     967 
     968The elements list (available by pressing NVDA+f7 while in a virtual buffer) provides access to a list of either links, headings or ARIA landmarks on the page. Radio buttons allow you to switch between these three types of information. An edit field is also provided in the dialog which allows you to filter the list to help you search for a particular item on the page. Once you have chosen an item, you can use the provided buttons in the dialog to move to, or activate, that item. 
     969 
     970 
     971===%id:8.4 8.4. Embedded Objects=== 
     972 
     973 
     974 
     975Pages can include rich content using technologies such as Adobe Flash and Sun Java. Where these are encountered in a virtual buffer, NVDA will announce "embedded object". You can press enter on these objects to interact with them. If it is accessible, you can then tab around it and interact with it like any other application. To return to the page, press NVDA+space. 
     976 
     977 
     978==%id:9 9. Troubleshooting NVDA=== 
     979 
     980 
     981 
     982As NVDA is constantly being updated, there is no guarantee that all commands provided here in this user guide will still apply. If you have any problems with any of the commands presented in this user guide, please visit: 
     983[[http://www.nvda-project.org/ | http://www.nvda-project.org/]] 
     984for more assistance. 

  • user_docs/sconstruct 

    +

=== added file 'user_docs/sconstruct'
     
     1#import os 
     2#import os.path 
     3 
     4 
     5env = Environment() 
     6 
     7## wiki2html Builder: 
     8wiki2htmlBuilder = Builder(action='python wikiTools/creole2html.py < $SOURCE > $TARGET', 
     9                     src_suffix='.txt' ,suffix='.html' ) 
     10env.Append(BUILDERS={'Wiki2html': wiki2htmlBuilder}) 
     11 
     12for i in Glob('*/user guide.txt'): 
     13    env.Wiki2html(i) 
     14 
     15#for i in Glob('*/whats new.txt'): 
     16#    env.Wiki2html(i) 

  • user_docs/wikiTools/COPYING 

    === added directory 'user_docs/wikiTools'
=== added file 'user_docs/wikiTools/COPYING'
     
     1This software is doubly-licensed. You can use it under the terms and 
     2conditions of any of the two licenses provided here. 
     3 
     4 
     5                           BSD LICENSE 
     6 
     7Copyright (c) 2007, Radomir Dopieralski, Thomas Waldmann. 
     8All rights reserved.  
     9 
     10Redistribution and use in source and binary forms, with or without 
     11modification, are permitted provided that the following conditions 
     12are met: 
     13 
     14 * Redistributions of source code must retain the above copyright 
     15   notice, this list of conditions and the following disclaimer. 
     16 
     17 * Redistributions in binary form must reproduce the above copyright 
     18   notice, this list of conditions and the following disclaimer in 
     19   the documentation and/or other materials provided with the 
     20   distribution. 
     21 
     22THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
     23"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
     24LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
     25FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
     26OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
     27SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 
     28TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
     29PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
     30LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
     31NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
     32SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
     33 
     34 
     35                    GNU GENERAL PUBLIC LICENSE 
     36                       Version 2, June 1991 
     37 
     38 Copyright (C) 1989, 1991 Free Software Foundation, Inc. 
     39     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
     40 Everyone is permitted to copy and distribute verbatim copies 
     41 of this license document, but changing it is not allowed. 
     42 
     43                            Preamble 
     44 
     45  The licenses for most software are designed to take away your 
     46freedom to share and change it.  By contrast, the GNU General Public 
     47License is intended to guarantee your freedom to share and change free 
     48software--to make sure the software is free for all its users.  This 
     49General Public License applies to most of the Free Software 
     50Foundation's software and to any other program whose authors commit to 
     51using it.  (Some other Free Software Foundation software is covered by 
     52the GNU Library General Public License instead.)  You can apply it to 
     53your programs, too. 
     54 
     55  When we speak of free software, we are referring to freedom, not 
     56price.  Our General Public Licenses are designed to make sure that you 
     57have the freedom to distribute copies of free software (and charge for 
     58this service if you wish), that you receive source code or can get it 
     59if you want it, that you can change the software or use pieces of it 
     60in new free programs; and that you know you can do these things. 
     61 
     62  To protect your rights, we need to make restrictions that forbid 
     63anyone to deny you these rights or to ask you to surrender the rights. 
     64These restrictions translate to certain responsibilities for you if you 
     65distribute copies of the software, or if you modify it. 
     66 
     67  For example, if you distribute copies of such a program, whether 
     68gratis or for a fee, you must give the recipients all the rights that 
     69you have.  You must make sure that they, too, receive or can get the 
     70source code.  And you must show them these terms so they know their 
     71rights. 
     72 
     73  We protect your rights with two steps: (1) copyright the software, and 
     74(2) offer you this license which gives you legal permission to copy, 
     75distribute and/or modify the software. 
     76 
     77  Also, for each author's protection and ours, we want to make certain 
     78that everyone understands that there is no warranty for this free 
     79software.  If the software is modified by someone else and passed on, we 
     80want its recipients to know that what they have is not the original, so 
     81that any problems introduced by others will not reflect on the original 
     82authors' reputations. 
     83 
     84  Finally, any free program is threatened constantly by software 
     85patents.  We wish to avoid the danger that redistributors of a free 
     86program will individually obtain patent licenses, in effect making the 
     87program proprietary.  To prevent this, we have made it clear that any 
     88patent must be licensed for everyone's free use or not licensed at all. 
     89 
     90  The precise terms and conditions for copying, distribution and 
     91modification follow. 
     92 
    093 
     94                    GNU GENERAL PUBLIC LICENSE 
     95   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 
     96 
     97  0. This License applies to any program or other work which contains 
     98a notice placed by the copyright holder saying it may be distributed 
     99under the terms of this General Public License.  The "Program", below, 
     100refers to any such program or work, and a "work based on the Program" 
     101means either the Program or any derivative work under copyright law: 
     102that is to say, a work containing the Program or a portion of it, 
     103either verbatim or with modifications and/or translated into another 
     104language.  (Hereinafter, translation is included without limitation in 
     105the term "modification".)  Each licensee is addressed as "you". 
     106 
     107Activities other than copying, distribution and modification are not 
     108covered by this License; they are outside its scope.  The act of 
     109running the Program is not restricted, and the output from the Program 
     110is covered only if its contents constitute a work based on the 
     111Program (independent of having been made by running the Program). 
     112Whether that is true depends on what the Program does. 
     113 
     114  1. You may copy and distribute verbatim copies of the Program's 
     115source code as you receive it, in any medium, provided that you 
     116conspicuously and appropriately publish on each copy an appropriate 
     117copyright notice and disclaimer of warranty; keep intact all the 
     118notices that refer to this License and to the absence of any warranty; 
     119and give any other recipients of the Program a copy of this License 
     120along with the Program. 
     121 
     122You may charge a fee for the physical act of transferring a copy, and 
     123you may at your option offer warranty protection in exchange for a fee. 
     124 
     125  2. You may modify your copy or copies of the Program or any portion 
     126of it, thus forming a work based on the Program, and copy and 
     127distribute such modifications or work under the terms of Section 1 
     128above, provided that you also meet all of these conditions: 
     129 
     130    a) You must cause the modified files to carry prominent notices 
     131    stating that you changed the files and the date of any change. 
     132 
     133    b) You must cause any work that you distribute or publish, that in 
     134    whole or in part contains or is derived from the Program or any 
     135    part thereof, to be licensed as a whole at no charge to all third 
     136    parties under the terms of this License. 
     137 
     138    c) If the modified program normally reads commands interactively 
     139    when run, you must cause it, when started running for such 
     140    interactive use in the most ordinary way, to print or display an 
     141    announcement including an appropriate copyright notice and a 
     142    notice that there is no warranty (or else, saying that you provide 
     143    a warranty) and that users may redistribute the program under 
     144    these conditions, and telling the user how to view a copy of this 
     145    License.  (Exception: if the Program itself is interactive but 
     146    does not normally print such an announcement, your work based on 
     147    the Program is not required to print an announcement.) 
     148 
    1149 
     150These requirements apply to the modified work as a whole.  If 
     151identifiable sections of that work are not derived from the Program, 
     152and can be reasonably considered independent and separate works in 
     153themselves, then this License, and its terms, do not apply to those 
     154sections when you distribute them as separate works.  But when you 
     155distribute the same sections as part of a whole which is a work based 
     156on the Program, the distribution of the whole must be on the terms of 
     157this License, whose permissions for other licensees extend to the 
     158entire whole, and thus to each and every part regardless of who wrote it. 
     159 
     160Thus, it is not the intent of this section to claim rights or contest 
     161your rights to work written entirely by you; rather, the intent is to 
     162exercise the right to control the distribution of derivative or 
     163collective works based on the Program. 
     164 
     165In addition, mere aggregation of another work not based on the Program 
     166with the Program (or with a work based on the Program) on a volume of 
     167a storage or distribution medium does not bring the other work under 
     168the scope of this License. 
     169 
     170  3. You may copy and distribute the Program (or a work based on it, 
     171under Section 2) in object code or executable form under the terms of 
     172Sections 1 and 2 above provided that you also do one of the following: 
     173 
     174    a) Accompany it with the complete corresponding machine-readable 
     175    source code, which must be distributed under the terms of Sections 
     176    1 and 2 above on a medium customarily used for software interchange; or, 
     177 
     178    b) Accompany it with a written offer, valid for at least three 
     179    years, to give any third party, for a charge no more than your 
     180    cost of physically performing source distribution, a complete 
     181    machine-readable copy of the corresponding source code, to be 
     182    distributed under the terms of Sections 1 and 2 above on a medium 
     183    customarily used for software interchange; or, 
     184 
     185    c) Accompany it with the information you received as to the offer 
     186    to distribute corresponding source code.  (This alternative is 
     187    allowed only for noncommercial distribution and only if you 
     188    received the program in object code or executable form with such 
     189    an offer, in accord with Subsection b above.) 
     190 
     191The source code for a work means the preferred form of the work for 
     192making modifications to it.  For an executable work, complete source 
     193code means all the source code for all modules it contains, plus any 
     194associated interface definition files, plus the scripts used to 
     195control compilation and installation of the executable.  However, as a 
     196special exception, the source code distributed need not include 
     197anything that is normally distributed (in either source or binary 
     198form) with the major components (compiler, kernel, and so on) of the 
     199operating system on which the executable runs, unless that component 
     200itself accompanies the executable. 
     201 
     202If distribution of executable or object code is made by offering 
     203access to copy from a designated place, then offering equivalent 
     204access to copy the source code from the same place counts as 
     205distribution of the source code, even though third parties are not 
     206compelled to copy the source along with the object code. 
     207 
    2208 
     209  4. You may not copy, modify, sublicense, or distribute the Program 
     210except as expressly provided under this License.  Any attempt 
     211otherwise to copy, modify, sublicense or distribute the Program is 
     212void, and will automatically terminate your rights under this License. 
     213However, parties who have received copies, or rights, from you under 
     214this License will not have their licenses terminated so long as such 
     215parties remain in full compliance. 
     216 
     217  5. You are not required to accept this License, since you have not 
     218signed it.  However, nothing else grants you permission to modify or 
     219distribute the Program or its derivative works.  These actions are 
     220prohibited by law if you do not accept this License.  Therefore, by 
     221modifying or distributing the Program (or any work based on the 
     222Program), you indicate your acceptance of this License to do so, and 
     223all its terms and conditions for copying, distributing or modifying 
     224the Program or works based on it. 
     225 
     226  6. Each time you redistribute the Program (or any work based on the 
     227Program), the recipient automatically receives a license from the 
     228original licensor to copy, distribute or modify the Program subject to 
     229these terms and conditions.  You may not impose any further 
     230restrictions on the recipients' exercise of the rights granted herein. 
     231You are not responsible for enforcing compliance by third parties to 
     232this License. 
     233 
     234  7. If, as a consequence of a court judgment or allegation of patent 
     235infringement or for any other reason (not limited to patent issues), 
     236conditions are imposed on you (whether by court order, agreement or 
     237otherwise) that contradict the conditions of this License, they do not 
     238excuse you from the conditions of this License.  If you cannot 
     239distribute so as to satisfy simultaneously your obligations under this 
     240License and any other pertinent obligations, then as a consequence you 
     241may not distribute the Program at all.  For example, if a patent 
     242license would not permit royalty-free redistribution of the Program by 
     243all those who receive copies directly or indirectly through you, then 
     244the only way you could satisfy both it and this License would be to 
     245refrain entirely from distribution of the Program. 
     246 
     247If any portion of this section is held invalid or unenforceable under 
     248any particular circumstance, the balance of the section is intended to 
     249apply and the section as a whole is intended to apply in other 
     250circumstances. 
     251 
     252It is not the purpose of this section to induce you to infringe any 
     253patents or other property right claims or to contest validity of any 
     254such claims; this section has the sole purpose of protecting the 
     255integrity of the free software distribution system, which is 
     256implemented by public license practices.  Many people have made 
     257generous contributions to the wide range of software distributed 
     258through that system in reliance on consistent application of that 
     259system; it is up to the author/donor to decide if he or she is willing 
     260to distribute software through any other system and a licensee cannot 
     261impose that choice. 
     262 
     263This section is intended to make thoroughly clear what is believed to 
     264be a consequence of the rest of this License. 
     265 
    3266 
     267  8. If the distribution and/or use of the Program is restricted in 
     268certain countries either by patents or by copyrighted interfaces, the 
     269original copyright holder who places the Program under this License 
     270may add an explicit geographical distribution limitation excluding 
     271those countries, so that distribution is permitted only in or among 
     272countries not thus excluded.  In such case, this License incorporates 
     273the limitation as if written in the body of this License. 
     274 
     275  9. The Free Software Foundation may publish revised and/or new versions 
     276of the General Public License from time to time.  Such new versions will 
     277be similar in spirit to the present version, but may differ in detail to 
     278address new problems or concerns. 
     279 
     280Each version is given a distinguishing version number.  If the Program 
     281specifies a version number of this License which applies to it and "any 
     282later version", you have the option of following the terms and conditions 
     283either of that version or of any later version published by the Free 
     284Software Foundation.  If the Program does not specify a version number of 
     285this License, you may choose any version ever published by the Free Software 
     286Foundation. 
     287 
     288  10. If you wish to incorporate parts of the Program into other free 
     289programs whose distribution conditions are different, write to the author 
     290to ask for permission.  For software which is copyrighted by the Free 
     291Software Foundation, write to the Free Software Foundation; we sometimes 
     292make exceptions for this.  Our decision will be guided by the two goals 
     293of preserving the free status of all derivatives of our free software and 
     294of promoting the sharing and reuse of software generally. 
     295 
     296                            NO WARRANTY 
     297 
     298  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY 
     299FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN 
     300OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES 
     301PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED 
     302OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
     303MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS 
     304TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE 
     305PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, 
     306REPAIR OR CORRECTION. 
     307 
     308  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 
     309WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR 
     310REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, 
     311INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING 
     312OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED 
     313TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY 
     314YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER 
     315PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE 
     316POSSIBILITY OF SUCH DAMAGES. 
     317 
     318                     END OF TERMS AND CONDITIONS 
     319 
    4320 
     321            How to Apply These Terms to Your New Programs 
     322 
     323  If you develop a new program, and you want it to be of the greatest 
     324possible use to the public, the best way to achieve this is to make it 
     325free software which everyone can redistribute and change under these terms. 
     326 
     327  To do so, attach the following notices to the program.  It is safest 
     328to attach them to the start of each source file to most effectively 
     329convey the exclusion of warranty; and each file should have at least 
     330the "copyright" line and a pointer to where the full notice is found. 
     331 
     332    <one line to give the program's name and a brief idea of what it does.> 
     333    Copyright (C) <year>  <name of author> 
     334 
     335    This program is free software; you can redistribute it and/or modify 
     336    it under the terms of the GNU General Public License as published by 
     337    the Free Software Foundation; either version 2 of the License, or 
     338    (at your option) any later version. 
     339 
     340    This program is distributed in the hope that it will be useful, 
     341    but WITHOUT ANY WARRANTY; without even the implied warranty of 
     342    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
     343    GNU General Public License for more details. 
     344 
     345    You should have received a copy of the GNU General Public License 
     346    along with this program; if not, write to the Free Software 
     347    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
     348 
     349 
     350Also add information on how to contact you by electronic and paper mail. 
     351 
     352If the program is interactive, make it output a short notice like this 
     353when it starts in an interactive mode: 
     354 
     355    Gnomovision version 69, Copyright (C) year  name of author 
     356    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 
     357    This is free software, and you are welcome to redistribute it 
     358    under certain conditions; type `show c' for details. 
     359 
     360The hypothetical commands `show w' and `show c' should show the appropriate 
     361parts of the General Public License.  Of course, the commands you use may 
     362be called something other than `show w' and `show c'; they could even be 
     363mouse-clicks or menu items--whatever suits your program. 
     364 
     365You should also get your employer (if you work as a programmer) or your 
     366school, if any, to sign a "copyright disclaimer" for the program, if 
     367necessary.  Here is a sample; alter the names: 
     368 
     369  Yoyodyne, Inc., hereby disclaims all copyright interest in the program 
     370  `Gnomovision' (which makes passes at compilers) written by James Hacker. 
     371 
     372  <signature of Ty Coon>, 1 April 1989 
     373  Ty Coon, President of Vice 
     374 

  • user_docs/wikiTools/creole.py 

    +This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Library General
+Public License instead of this License.

=== added file 'user_docs/wikiTools/creole.py'
     
     1# -*- coding: iso-8859-1 -*- 
     2""" 
     3    Creole wiki markup parser 
     4 
     5    See http://wikicreole.org/ for latest specs. 
     6 
     7    Notes: 
     8    * No markup allowed in table headings. 
     9      Creole 1.0 does not require us to support this. 
     10    * No (non-bracketed) generic url recognition: this is "mission impossible" 
     11      except if you want to risk lots of false positives. Only known protocols 
     12      are recognized. 
     13    * We do not allow ":" before "//" italic markup to avoid urls with 
     14      unrecognized schemes (like wtf://server/path) triggering italic rendering 
     15      for the rest of the paragraph. 
     16 
     17    @copyright: 2007 MoinMoin:RadomirDopieralski (creole 0.5 implementation), 
     18                2007 MoinMoin:ThomasWaldmann (updates) 
     19                2009 Mesar Hameed <mhameed at src dot gnome dot org> (modified to suit NVDA) 
     20                 
     21    @license: GNU GPL, see COPYING for details. 
     22    @license: BSD, see COPYING for details. 
     23""" 
     24 
     25import re 
     26 
     27__version__ = '1.0' 
     28 
     29 
     30# Whether the parser should convert \n into <br>. 
     31bloglike_lines = False 
     32 
     33class Rules: 
     34    """Hold all the rules for generating regular expressions.""" 
     35 
     36    # For the inline elements: 
     37    proto = r'http|https|ftp|nntp|news|mailto|telnet|file|irc' 
     38    url =  r'''(?P<url> 
     39            (^ | (?<=\s | [.,:;!?()/=])) 
     40            (?P<escaped_url>~)? 
     41            (?P<url_target> (?P<url_proto> %s ):\S+? ) 
     42            ($ | (?=\s | [,.:;!?()] (\s | $))) 
     43        )''' % proto 
     44    link = r'''(?P<link> 
     45            \[\[ 
     46            (?P<link_target>.+?) \s* 
     47            ([|] \s* (?P<link_text>.+?) \s*)? 
     48            ]] 
     49        )''' 
     50    image = r'''(?P<image> 
     51            {{ 
     52            (?P<image_target>.+?) \s* 
     53            ([|] \s* (?P<image_text>.+?) \s*)? 
     54            }} 
     55        )''' 
     56    macro = r'''(?P<macro> 
     57            << 
     58            (?P<macro_name> \w+) 
     59            (\( (?P<macro_args> .*?) \))? \s* 
     60            ([|] \s* (?P<macro_text> .+?) \s* )? 
     61            >> 
     62        )''' 
     63    code = r'(?P<code> {{{ (?P<code_text>.*?) }}} )' 
     64    emph = r'(?P<emph> (?<!:)// )' # there must be no : in front of the // 
     65                                   # avoids italic rendering in urls with 
     66                                   # unknown protocols 
     67    strong = r'(?P<strong> \*\* )' 
     68    prop = r'''(?P<prop> %(?P<prop_key>[a-zA-Z]+):(?P<prop_val>[a-zA-Z0-9_\.]+) \s+ )''' 
     69    title = r'''(?P<title> ^ %%title: \s+ (?P<title_text> .*?) \s* $ )''' 
     70    gprop = r'''(?P<gprop> %%(?P<gprop_key>[a-zA-Z]+):(?P<gprop_val>[a-zA-Z0-9_\.]+) \s+ )''' 
     71    linebreak = r'(?P<break> \\\\ )' 
     72    escape = r'(?P<escape> ~ (?P<escaped_char>\S) )' 
     73    char =  r'(?P<char> . )' 
     74    quot = r'''(?P<quot> " )''' 
     75 
     76    # For the block elements: 
     77    separator = r'(?P<separator> ^ \s* ---- \s* $ )' # horizontal line 
     78    line = r'(?P<line> ^ \s* $ )' # empty line that separates paragraphs 
     79    head = r'''(?P<head> 
     80            ^ \s* 
     81            (?P<head_head>=+) \s* 
     82            (?P<head_text> .*? ) \s* 
     83            (?P<head_tail>=*) \s* 
     84            $ 
     85        )''' 
     86    if bloglike_lines: 
     87        text = r'(?P<text> .+ ) (?P<break> (?<!\\)$\n(?!\s*$) )?' 
     88    else: 
     89        text = r'(?P<text> .+ )' 
     90    list = r'''(?P<list> 
     91            ^ [ \t]* ([*][^*\#]|[\#][^\#*]).* $ 
     92            ( \n[ \t]* [*\#]+.* $ )* 
     93        )''' # Matches the whole list, separate items are parsed later. The 
     94             # list *must* start with a single bullet. 
     95    item = r'''(?P<item> 
     96            ^ \s* 
     97            (?P<item_head> [\#*]+) \s* 
     98            (?P<item_text> .*?) 
     99            $ 
     100        )''' # Matches single list items 
     101    pre = r'''(?P<pre> 
     102            ^{{{ \s* $ 
     103            (\n)? 
     104            (?P<pre_text> 
     105                ([\#]!(?P<pre_kind>\w*?)(\s+.*)?$)? 
     106                (.|\n)+? 
     107            ) 
     108            (\n)? 
     109            ^}}} \s*$ 
     110        )''' 
     111    pre_escape = r' ^(?P<indent>\s*) ~ (?P<rest> \}\}\} \s*) $' 
     112    table = r'''(?P<table> 
     113            ^ \s* 
     114            [|].*? \s* 
     115            [|]? \s* 
     116            $ 
     117        )''' 
     118 
     119    # For splitting table cells: 
     120    cell = r''' 
     121            \| \s* 
     122            ( 
     123                (?P<head> [=][^|]+ ) | 
     124                (?P<cell> (  %s | [^|])+ ) 
     125            ) \s* 
     126        ''' % '|'.join([link, macro, image, code]) 
     127 
     128class Parser: 
     129    """ 
     130    Parse the raw text and create a document object 
     131    that can be converted into output using Emitter. 
     132    """ 
     133 
     134    # For pre escaping, in creole 1.0 done with ~: 
     135    pre_escape_re = re.compile(Rules.pre_escape, re.M | re.X) 
     136    link_re = re.compile('|'.join([Rules.image, Rules.linebreak, Rules.char]), re.X | re.U) # for link descriptions 
     137    item_re = re.compile(Rules.item, re.X | re.U | re.M) # for list items 
     138    cell_re = re.compile(Rules.cell, re.X | re.U) # for table cells 
     139    # For block elements: 
     140    block_re = re.compile('|'.join([Rules.line, Rules.head, Rules.separator, 
     141        Rules.pre, Rules.list, Rules.title, Rules.gprop, Rules.table, Rules.text]), re.X | re.U | re.M) 
     142    # For inline elements: 
     143    inline_re = re.compile('|'.join([Rules.link, Rules.url, Rules.macro, 
     144        Rules.code, Rules.prop, Rules.quot, Rules.image, Rules.strong, Rules.emph, Rules.linebreak, 
     145        Rules.escape, Rules.char]), re.X | re.U) 
     146 
     147    def __init__(self, raw): 
     148        self.raw = raw 
     149        self.root = DocNode('document', None) 
     150        self.cur = self.root        # The most recent document node 
     151        self.text = None            # The node to add inline characters to 
     152 
     153    def _upto(self, node, kinds): 
     154        """ 
     155        Look up the tree to the first occurence 
     156        of one of the listed kinds of nodes or root. 
     157        Start at the node node. 
     158        """ 
     159        while node.parent is not None and not node.kind in kinds: 
     160            node = node.parent 
     161        return node 
     162 
     163    # The _*_repl methods called for matches in regexps. Sometimes the 
     164    # same method needs several names, because of group names in regexps. 
     165 
     166    def _url_repl(self, groups): 
     167        """Handle raw urls in text.""" 
     168 
     169        if not groups.get('escaped_url'): 
     170            # this url is NOT escaped 
     171            target = groups.get('url_target', '') 
     172            node = DocNode('link', self.cur) 
     173            node.content = target 
     174            DocNode('text', node, node.content) 
     175            self.text = None 
     176        else: 
     177            # this url is escaped, we render it as text 
     178            if self.text is None: 
     179                self.text = DocNode('text', self.cur, u'') 
     180            self.text.content += groups.get('url_target') 
     181    _url_target_repl = _url_repl 
     182    _url_proto_repl = _url_repl 
     183    _escaped_url = _url_repl 
     184 
     185    def _link_repl(self, groups): 
     186        """Handle all kinds of links.""" 
     187 
     188        target = groups.get('link_target', '') 
     189        text = (groups.get('link_text', '') or '').strip() 
     190        parent = self.cur 
     191        self.cur = DocNode('link', self.cur) 
     192        self.cur.content = target 
     193        self.text = None 
     194        re.sub(self.link_re, self._replace, text) 
     195        self.cur = parent 
     196        self.text = None 
     197    _link_target_repl = _link_repl 
     198    _link_text_repl = _link_repl 
     199 
     200    def _macro_repl(self, groups): 
     201        """Handles macros using the placeholder syntax.""" 
     202 
     203        name = groups.get('macro_name', '') 
     204        text = (groups.get('macro_text', '') or '').strip() 
     205        node = DocNode('macro', self.cur, name) 
     206        node.args = groups.get('macro_args', '') or '' 
     207        DocNode('text', node, text or name) 
     208        self.text = None 
     209    _macro_name_repl = _macro_repl 
     210    _macro_args_repl = _macro_repl 
     211    _macro_text_repl = _macro_repl 
     212 
     213    def _image_repl(self, groups): 
     214        """Handles images and attachemnts included in the page.""" 
     215 
     216        target = groups.get('image_target', '').strip() 
     217        text = (groups.get('image_text', '') or '').strip() 
     218        node = DocNode("image", self.cur, target) 
     219        DocNode('text', node, text or node.content) 
     220        self.text = None 
     221    _image_target_repl = _image_repl 
     222    _image_text_repl = _image_repl 
     223 
     224    def _separator_repl(self, groups): 
     225        self.cur = self._upto(self.cur, ('document', 'section', 'blockquote')) 
     226        DocNode('separator', self.cur) 
     227 
     228    def _item_repl(self, groups): 
     229        bullet = groups.get('item_head', u'') 
     230        text = groups.get('item_text', u'') 
     231        if bullet[-1] == '#': 
     232            kind = 'number_list' 
     233        else: 
     234            kind = 'bullet_list' 
     235        level = len(bullet) 
     236        lst = self.cur 
     237        # Find a list of the same kind and level up the tree 
     238        while (lst and 
     239                   not (lst.kind in ('number_list', 'bullet_list') and 
     240                        lst.level == level) and 
     241                    not lst.kind in ('document', 'section', 'blockquote')): 
     242            lst = lst.parent 
     243        if lst and lst.kind == kind: 
     244            self.cur = lst 
     245        else: 
     246            # Create a new level of list 
     247            self.cur = self._upto(self.cur, 
     248                (kind, 'document', 'section', 'blockquote')) 
     249            self.cur = DocNode(kind, self.cur) 
     250            self.cur.level = level 
     251        self.cur = DocNode('list_item', self.cur) 
     252        self.parse_inline(text) 
     253        self.text = None 
     254    _item_text_repl = _item_repl 
     255    _item_head_repl = _item_repl 
     256 
     257    def _list_repl(self, groups): 
     258        text = groups.get('list', u'') 
     259        self.item_re.sub(self._replace, text) 
     260 
     261    def _head_repl(self, groups): 
     262        self.cur = self._upto(self.cur, ('document', 'section', 'blockquote')) 
     263        text = groups.get('head_text', '').strip() 
     264        self.cur = DocNode('header', self.cur) 
     265        self.cur.level = len(groups.get('head_head', ' ')) 
     266        self.parse_inline(text) 
     267        self.text = None 
     268    _head_head_repl = _head_repl 
     269    _head_text_repl = _head_repl 
     270 
     271    def _text_repl(self, groups): 
     272        text = groups.get('text', '') 
     273        if self.cur.kind in ('table', 'table_row', 'bullet_list', 
     274            'number_list', 'header'): 
     275            self.cur = self._upto(self.cur, 
     276                ('document', 'section', 'blockquote')) 
     277        if self.cur.kind in ('document', 'section', 'blockquote'): 
     278            self.cur = DocNode('paragraph', self.cur) 
     279        else: 
     280            text = u' ' + text 
     281        self.parse_inline(text) 
     282        if groups.get('break') and self.cur.kind in ('paragraph', 
     283            'emphasis', 'strong', 'code'): 
     284            DocNode('break', self.cur, '') 
     285        self.text = None 
     286    _break_repl = _text_repl 
     287 
     288    def _table_repl(self, groups): 
     289        row = groups.get('table', '|').strip() 
     290        self.cur = self._upto(self.cur, ( 
     291            'table', 'document', 'section', 'blockquote')) 
     292        if self.cur.kind != 'table': 
     293            self.cur = DocNode('table', self.cur) 
     294        tb = self.cur 
     295        tr = DocNode('table_row', tb) 
     296 
     297        text = '' 
     298        for m in self.cell_re.finditer(row): 
     299            cell = m.group('cell') 
     300            if cell: 
     301                self.cur = DocNode('table_cell', tr) 
     302                self.text = None 
     303                self.parse_inline(cell) 
     304            else: 
     305                cell = m.group('head') 
     306                self.cur = DocNode('table_head', tr) 
     307                self.text = DocNode('text', self.cur, u'') 
     308                self.text.content = cell.strip('=') 
     309        self.cur = tb 
     310        self.text = None 
     311 
     312    def _pre_repl(self, groups): 
     313        self.cur = self._upto(self.cur, ('document', 'section', 'blockquote')) 
     314        kind = groups.get('pre_kind', None) 
     315        text = groups.get('pre_text', u'') 
     316        def remove_tilde(m): 
     317            return m.group('indent') + m.group('rest') 
     318        text = self.pre_escape_re.sub(remove_tilde, text) 
     319        node = DocNode('preformatted', self.cur, text) 
     320        node.sect = kind or '' 
     321        self.text = None 
     322    _pre_text_repl = _pre_repl 
     323    _pre_head_repl = _pre_repl 
     324    _pre_kind_repl = _pre_repl 
     325 
     326    def _line_repl(self, groups): 
     327        self.cur = self._upto(self.cur, ('document', 'section', 'blockquote')) 
     328 
     329    def _code_repl(self, groups): 
     330        DocNode('code', self.cur, groups.get('code_text', u'').strip()) 
     331        self.text = None 
     332    _code_text_repl = _code_repl 
     333    _code_head_repl = _code_repl 
     334 
     335    def _emph_repl(self, groups): 
     336        if self.cur.kind != 'emphasis': 
     337            self.cur = DocNode('emphasis', self.cur) 
     338        else: 
     339            self.cur = self._upto(self.cur, ('emphasis', )).parent 
     340        self.text = None 
     341 
     342    def _strong_repl(self, groups): 
     343        if self.cur.kind != 'strong': 
     344            self.cur = DocNode('strong', self.cur) 
     345        else: 
     346            self.cur = self._upto(self.cur, ('strong', )).parent 
     347        self.text = None 
     348 
     349    def _prop_repl(self, groups): 
     350        key = groups.get('prop_key', '') 
     351        value = groups.get('prop_val', '') 
     352        self.cur.properties.append( NodeProperty(key, value) ) 
     353    _prop_key_repl = _prop_repl 
     354    _prop_val_repl = _prop_repl 
     355 
     356    def _title_repl(self, groups): 
     357        text = groups.get('title_text', '') 
     358        self.root.headProperties.append( NodeProperty('title', text) ) 
     359    _title_text_repl = _title_repl 
     360 
     361    def _gprop_repl(self, groups): 
     362        key = groups.get('gprop_key', '') 
     363        value = groups.get('gprop_val', '') 
     364        self.root.properties.append( NodeProperty(key, value) ) 
     365    _gprop_key_repl = _gprop_repl 
     366    _gprop_val_repl = _gprop_repl 
     367 
     368    def _break_repl(self, groups): 
     369        DocNode('break', self.cur, None) 
     370        self.text = None 
     371 
     372    def _quot_repl(self, groups): 
     373        DocNode('quot', self.cur, None) 
     374        self.text = None 
     375 
     376    def _escape_repl(self, groups): 
     377        if self.text is None: 
     378            self.text = DocNode('text', self.cur, u'') 
     379        self.text.content += groups.get('escaped_char', u'') 
     380 
     381    def _char_repl(self, groups): 
     382        if self.text is None: 
     383            self.text = DocNode('text', self.cur, u'') 
     384        self.text.content += groups.get('char', u'') 
     385 
     386    def _replace(self, match): 
     387        """Invoke appropriate _*_repl method. Called for every matched group.""" 
     388 
     389        groups = match.groupdict() 
     390        for name, text in groups.iteritems(): 
     391            if text is not None: 
     392                replace = getattr(self, '_%s_repl' % name) 
     393                replace(groups) 
     394                return 
     395 
     396    def parse_inline(self, raw): 
     397        """Recognize inline elements inside blocks.""" 
     398 
     399        re.sub(self.inline_re, self._replace, raw) 
     400 
     401    def parse_block(self, raw): 
     402        """Recognize block elements.""" 
     403 
     404        re.sub(self.block_re, self._replace, raw) 
     405 
     406    def parse(self): 
     407        """Parse the text given as self.raw and return DOM tree.""" 
     408 
     409        self.parse_block(self.raw) 
     410        return self.root 
     411 
     412#################### Helper classes 
     413 
     414### The document model and emitter follow 
     415 
     416class DocNode: 
     417    """ 
     418    A node in the document. 
     419    """ 
     420 
     421    def __init__(self, kind='', parent=None, content=None): 
     422        self.children = [] 
     423        self.parent = parent 
     424        self.kind = kind 
     425        self.content = content 
     426        self.properties = [] 
     427        self.headProperties = [] 
     428        if self.parent is not None: 
     429            self.parent.children.append(self) 
     430 
     431 
     432class NodeProperty: 
     433    """"A particular property for a node.""" 
     434   
     435    def __init__(self, key,value): 
     436        self.key =  key 
     437        self.value = value 
     438 
     439    def __str__(self): 
     440        return self.key + '="' + self.value +'"' 
     441         

  • user_docs/wikiTools/creole2html.py 

    === added file 'user_docs/wikiTools/creole2html.py'
     
     1# -*- coding: utf-8 -*- 
     2 
     3ur""" 
     4WikiCreole to HTML converter 
     5This program is an example of how the creole.py WikiCreole parser 
     6can be used. 
     7 
     8@copyright: 2007 MoinMoin:RadomirDopieralski 
     9@license: GNU GPL, see COPYING for details. 
     10@license: BSD, see COPYING for details. 
     11 
     12Test cases contributed by Jan Klopper (janklopper@underdark.nl), 
     13modified by Radomir Dopieralski (MoinMoin:RadomirDopieralski). 
     14Modified for NVDA by Mesar Hameed <mhameed at src dot gnome dot org> 
     15""" 
     16 
     17import re 
     18from creole import Parser 
     19 
     20class Rules: 
     21    # For the link targets: 
     22    proto = r'http|https|ftp|nntp|news|mailto|telnet|file|irc' 
     23    extern = r'(?P<extern_addr>(?P<extern_proto>%s):.*)' % proto 
     24    interwiki = r''' 
     25            (?P<inter_wiki> [A-Z][a-zA-Z]+ ) : 
     26            (?P<inter_page> .* ) 
     27        ''' 
     28 
     29class HtmlEmitter: 
     30    """ 
     31    Generate HTML output for the document 
     32    tree consisting of DocNodes. 
     33    """ 
     34 
     35    addr_re = re.compile('|'.join([ 
     36            Rules.extern, 
     37            Rules.interwiki, 
     38        ]), re.X | re.U) # for addresses 
     39 
     40    def __init__(self, root): 
     41        self.root = root 
     42 
     43    def get_text(self, node): 
     44        """Try to emit whatever text is in the node.""" 
     45 
     46        try: 
     47            return node.children[0].content or '' 
     48        except: 
     49            return node.content or '' 
     50 
     51    def html_escape(self, text): 
     52        return text.replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;') 
     53 
     54    def attr_escape(self, text): 
     55        return self.html_escape(text).replace('"', '&quot') 
     56 
     57    # *_emit methods for emitting nodes of the document: 
     58 
     59    def document_emit(self, node): 
     60        string = '<html>\n<head>\n<META http-equiv=Content-Type content="text/html; charset=utf-8">\n' + \ 
     61            self.listHeadProperties(node) + \ 
     62            '</head>\n<body' + \ 
     63            self.listProperties(node) + \ 
     64            '>\n' + \ 
     65            self.emit_children(node)  + \ 
     66            "\n</body>\n</html>\n" 
     67        return string 
     68 
     69    def text_emit(self, node): 
     70        return self.html_escape(node.content) 
     71 
     72    def separator_emit(self, node): 
     73        return u'<hr>'; 
     74 
     75    def listHeadProperties(self, node): 
     76        string = u"" 
     77        for a in node.headProperties: 
     78            string += "<" + a.key + ">" + a.value +"</" + a.key + ">\n" 
     79        return string 
     80 
     81 
     82    def listProperties(self, node): 
     83        string = u"" 
     84        for a in node.properties: 
     85            string += " " + a.__str__() 
     86        return string 
     87 
     88    def paragraph_emit(self, node): 
     89        string = U"<p" + self.listProperties(node) 
     90        string += u'>\n%s\n</p>\n' % self.emit_children(node) 
     91        return string 
     92 
     93    def bullet_list_emit(self, node): 
     94        return u'<ul>\n%s</ul>\n' % self.emit_children(node) 
     95 
     96    def number_list_emit(self, node): 
     97        return u'<ol>\n%s</ol>\n' % self.emit_children(node) 
     98 
     99    def list_item_emit(self, node): 
     100        return u'<li>%s</li>\n' % self.emit_children(node) 
     101 
     102    def table_emit(self, node): 
     103        return u'<table>\n%s</table>\n' % self.emit_children(node) 
     104 
     105    def table_row_emit(self, node): 
     106        return u'<tr>%s</tr>\n' % self.emit_children(node) 
     107 
     108    def table_cell_emit(self, node): 
     109        return u'<td>%s</td>' % self.emit_children(node) 
     110 
     111    def table_head_emit(self, node): 
     112        return u'<th>%s</th>' % self.emit_children(node) 
     113 
     114    def emphasis_emit(self, node): 
     115        return u'<i>%s</i>' % self.emit_children(node) 
     116 
     117    def strong_emit(self, node): 
     118        return u'<b>%s</b>' % self.emit_children(node) 
     119 
     120    def header_emit(self, node): 
     121        string = u'<h%d%s' % (node.level, self.listProperties(node)) 
     122        string += u'>%s</h%d>\n' % (self.emit_children(node), node.level) 
     123        #print "i am a heading, i have %d properties and %d children" % (len(node.properties), len(node.children)) 
     124        return string 
     125 
     126    def code_emit(self, node): 
     127        return u'<tt>%s</tt>' % self.html_escape(node.content) 
     128 
     129    def link_emit(self, node): 
     130        target = node.content 
     131        if node.children: 
     132            inside = self.emit_children(node) 
     133        else: 
     134            inside = self.html_escape(target) 
     135        m = self.addr_re.match(target) 
     136        if m: 
     137            if m.group('extern_addr'): 
     138                return u'<a href="%s">%s</a>' % ( 
     139                    self.attr_escape(target), inside) 
     140            elif m.group('inter_wiki'): 
     141                raise NotImplementedError 
     142        return u'<a href="%s">%s</a>' % ( 
     143            self.attr_escape(target), inside) 
     144 
     145    def image_emit(self, node): 
     146        target = node.content 
     147        text = self.get_text(node) 
     148        m = self.addr_re.match(target) 
     149        if m: 
     150            if m.group('extern_addr'): 
     151                return u'<img src="%s" alt="%s">' % ( 
     152                    self.attr_escape(target), self.attr_escape(text)) 
     153            elif m.group('inter_wiki'): 
     154                raise NotImplementedError 
     155        return u'<img src="%s" alt="%s">' % ( 
     156            self.attr_escape(target), self.attr_escape(text)) 
     157 
     158    def macro_emit(self, node): 
     159        raise NotImplementedError 
     160 
     161    def break_emit(self, node): 
     162        return u"<br>" 
     163 
     164    def quot_emit(self, node): 
     165        return u"&quot;" 
     166 
     167    def preformatted_emit(self, node): 
     168        return u"<pre>%s</pre>" % self.html_escape(node.content) 
     169 
     170    def default_emit(self, node): 
     171        """Fallback function for emitting unknown nodes.""" 
     172 
     173        raise TypeError 
     174 
     175    def emit_children(self, node): 
     176        """Emit all the children of a node.""" 
     177 
     178        return u''.join([self.emit_node(child) for child in node.children]) 
     179 
     180    def emit_node(self, node): 
     181        """Emit a single node.""" 
     182 
     183        #print "emiting node of type " + node.kind 
     184        emit = getattr(self, '%s_emit' % node.kind, self.default_emit) 
     185        return emit(node) 
     186 
     187    def emit(self): 
     188        """Emit the document represented by self.root DOM tree.""" 
     189 
     190        return self.emit_node(self.root) 
     191 
     192if __name__=="__main__": 
     193    import sys 
     194    document = Parser(unicode(sys.stdin.read(), 'utf-8', 'ignore')).parse() 
     195    sys.stdout.write(HtmlEmitter(document).emit().encode('utf-8', 'ignore')) 
     196 
     197 

  • user_docs/wikiTools/html2wiki.py 

    === added file 'user_docs/wikiTools/html2wiki.py'
     
     1#html2wiki.py 
     2#included in NVDA to make the transition from existing html documentation  
     3# to wiki markupped files. 
     4#Copyright (C) 2010 NVDA Contributors <http://www.nvda-project.org/> 
     5#This file is covered by the GNU General Public License. 
     6#See the file COPYING for more details. 
     7 
     8import sys 
     9from HTMLParser import HTMLParser 
     10 
     11class MyHTMLParser(HTMLParser): 
     12 
     13    def __init__(self): 
     14        HTMLParser.__init__(self) 
     15        self.listDepth = [] 
     16        
     17        self.etags = {  
     18        'h1':'=\n\n', 'h2':'==\n\n', 'h3':'===\n\n',  
     19        'h4':'====\n\n', 'h5':'=====\n\n', 'h6':'======\n\n',  
     20        'p':'\n', 'b':'**', 'strong':'**',  
     21        'em':'//', 'a':']]', 'li': '\n', 'title': '\n', 
     22        }         
     23 
     24        self.stags = { \ 
     25        'h1':'\n=', 'h2':'\n==', 'h3':'\n===', \ 
     26        'h4':'\n====', 'h5':'\n=====', 'h6':'\n======', \ 
     27        'p':'\n', 'b':'**', 'strong':'**', \ 
     28        'em':'//', 
     29        } 
     30 
     31    def handle_entityref(self, name): 
     32        #print("i got %s" %name) 
     33        if name == 'quot': 
     34            sys.stdout.write('"') 
     35 
     36 
     37    def handle_data(self, data): 
     38        if data.strip(): 
     39            sys.stdout.write("%s" %data) 
     40         
     41    def unwanted(self, tag): 
     42        if tag in ['html','meta','head', 'body']: 
     43            return True 
     44        return False 
     45 
     46    def handle_starttag(self, tag, attrs): 
     47 
     48        if self.unwanted(tag): 
     49            return 
     50        if tag in self.stags: 
     51            sys.stdout.write("%s" % self.stags[tag] + self.getAttrib(attrs, 'id')) 
     52        elif tag == 'title': 
     53            sys.stdout.write("%%title:") 
     54        elif tag == 'a': 
     55            sys.stdout.write("[[" + self.getAttrib(attrs, 'href') +" | ") 
     56        elif tag == 'ul': 
     57            self.listDepth.append("*") 
     58        elif tag == 'ol': 
     59            self.listDepth.append("#") 
     60        elif tag == 'li': 
     61            sys.stdout.write("".join(self.listDepth) + " ") 
     62        else: 
     63            #print "Encountered the beginning of a %s tag" % tag 
     64            sys.stdout.write("\n") 
     65 
     66    def getAttrib(self, attrs, tag): 
     67        string = u"" 
     68        for i in attrs: 
     69            if i[0] == 'href' and tag == 'href': 
     70                string += i[1].rstrip('\n') 
     71            if tag == 'id' and i[0] == tag: 
     72                string += r'''%''' + "id:%s " % i[1]  
     73        return string 
     74 
     75    def handle_endtag(self, tag): 
     76        if self.unwanted(tag): 
     77            return 
     78        if tag in self.etags: 
     79            sys.stdout.write("%s" % self.etags[tag]) 
     80        elif tag in ['ol', 'ul']: 
     81            self.listDepth.pop() 
     82            #sys.stdout.write("\n") 
     83        else: 
     84            #print "Encountered the end of a %s tag" % tag 
     85            sys.stdout.write("\n") 
     86 
     87 
     88 
     89 
     90parser = MyHTMLParser() 
     91parser.feed(sys.stdin.read()) 
     92parser.close()          
     93 

  • user_docs/wikiTools/readme.txt 

    === added file 'user_docs/wikiTools/readme.txt'
     
     1creole2html.py 
     2 
     3This file describes the additional 'features' that were added to the standard creole wiki markup to html parser, to better suit NVDA documentation needs. 
     4 
     5We also show how a standard document should look like. 
     6 
     7Additions to the creole 1.0 standard (www.wikicreole.org/): 
     8the parser: http://wiki.sheep.art.pl/Wiki%20Creole%20Parser%20in%20Python 
     9 
     10formatting within headings is interpreted. 
     11== this is **some bold** text within a heading == 
     12the 1.0 standard leaves the text alone, but markup within headings is proposed for version 2. So the modified parser for NVDA wiki documents already implements this. 
     13 
     14 
     15Local element properties: %tagname:value, where  
     16tagname has to match [a-zA-Z]+ and  
     17value has to match [0-9a-zA-Z_\.]+ 
     18Example add an id property to current element: 
     19%id:Introduction 
     20 
     21The local properties will be printed as arguments of the enclosing tag. 
     22<p id='Introduction'> ... </p> 
     23 
     24 
     25global properties: %%tagname:value, where  
     26tagname has to match [a-zA-Z]+ and  
     27value has to match [0-9a-zA-Z_\.]+ 
     28example define the language to English: 
     29%%lang:en 
     30 
     31the global properties will be printed as arguments of the body tag. 
     32<body lang='en'> ... </body> 
     33 
     34Special case: 
     35%%title:Free text to the end of the line. 
     36When we come across the %%title: command, the rest of the line is taken to be the title text, to be printed as part of the head of the html page. 
     37<head> 
     38    ... 
     39    <title>Free text to the end of the line.</title> 
     40</head> 
     41 
     42 
     43 
     44 
     45 
     46example wiki document: 
     47 
     48---start cut--- 
     49%%title:NVDA 2009.1 User Guide 
     50%%lan:en 
     51 
     52=NVDA 2009.1 User Guide= 
     53 
     54==Table of Contents== 
     55 
     56* [[#1 | 1. Introduction]] 
     57** [[#1.1 | 1.1. General features]] 
     58** [[#1.2 | 1.2. Internationalization]] 
     59 
     60==%id:1 1. Introduction== 
     61===%id:1.1 1.1. General Features=== 
     62 
     63 
     64Providing feedback by synthetic speech, Nonvisual Desktop Access allows blind and vision impaired people to access and interact with the Windows operating system and many third party applications. 
     65 
     66... 
     67 
     68 
     69===%id:1.2 1.2. Internationalization=== 
     70 
     71 
     72It is important that people anywhere in the world, no matter what language they speak, get equal access to technology. NVDA currently has been translated into over 20 languages. 
     73  
     74 
     75---end cut--- 
     76 
     77 
     78 
     79html2wiki.py 
     80 
     81Incomplete parser, but automates most of the conversion from html to wiki markup. 
     82 
     83Care is to be taken for element properties/attributes, because they are not converted back into wiki format unless it is an "id" attribute. 
     84The %%lang:<language code> is also not output, so we have to edit the output document to include this. 
     85 
     86The html2wiki.py should probably be removed once all languages has migrated to wiki markup. 
     87 
     88both creole2html.py and html2wiki.py read from standard in, and write to standard out.