<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY legal SYSTEM "legal.xml">
<!ENTITY appversion "0.1.5">
<!ENTITY manrevision "0.2.0">
<!ENTITY date "2007-06-29">
<!ENTITY app "<application>Accerciser</application>">
]>
<!-- 
      (Do not remove this comment block.)
  Maintained by the GNOME Documentation Project
  http://developer.gnome.org/projects/gdp
  Template version: 2.0 beta
  Template last modified Apr 11, 2002
-->
<!-- =============Document Header ============================= -->
<article id="index" lang="sl">
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->
  <articleinfo> 
    <title><application>Accerciser</application> Manual v0.2.0</title>       

    <copyright> 
      <year>2006</year> 
      <year>2007</year> 
      <year>2008</year> 
      <holder>IBM Corporation</holder> 
    </copyright> 

<!-- translators: uncomment this:

  <copyright>
   <year>2002</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

   -->
<!-- An address can be added to the publisher information.  If a role is 
     not specified, the publisher/author is the same for all versions of the 
     document.  -->
    <publisher> 
      <publishername> GNOME Documentation Project </publishername> 
    </publisher> 

	<!-- This file  contains link to license for the documentation (GNU FDL), and 
        other legal stuff such as "NO WARRANTY" statement. Please do not change 
	any of this. -->

    <authorgroup> 
      <author role="maintainer"> 
        <firstname>Eitan</firstname> 
        <surname>Isaacson</surname> 
        <affiliation> 
          <orgname>Accerciser team</orgname> 
          <address> <email>eitan@ascender.com</email> </address> 
        </affiliation> 
      </author> 

      <author role="editor"> 
        <firstname>Peter</firstname> 
        <surname>Parente</surname> 
        <affiliation> 
          <orgname>Accerciser team</orgname> 
          <address> <email>pparent@us.ibm.com</email> </address> 
        </affiliation> 
      </author> 
      
<!-- This is appropriate place for other contributors: translators,
     maintainers,  etc. Commented out by default.
     
      <othercredit role="translator">
        <firstname>Latin</firstname> 
        <surname>Translator 1</surname> 
        <affiliation> 
          <orgname>Latin Translation Team</orgname> 
          <address> <email>translator@gnome.org</email> </address> 
          </affiliation>
          <contrib>Latin translation</contrib>
      </othercredit>
-->
    </authorgroup>


<!-- According to GNU FDL, revision history is mandatory if you are -->
<!-- modifying/reusing someone else's document.  If not, you can omit it. -->
<!-- Remember to remove the &manrevision; entity from the revision entries other
-->
<!-- than the current revision. -->
<!-- The revision numbering system for GNOME manuals is as follows: -->
<!-- * the revision number consists of two components -->
<!-- * the first component of the revision number reflects the release version of the GNOME desktop. -->
<!-- * the second component of the revision number is a decimal unit that is incremented with each revision of the manual. -->
<!-- For example, if the GNOME desktop release is V2.x, the first version of the manual that -->
<!-- is written in that desktop timeframe is V2.0, the second version of the manual is V2.1, etc. -->
<!-- When the desktop release version changes to V3.x, the revision number of the manual changes -->
<!-- to V3.0, and so on. -->  
    <revhistory>
      <revision> 
        <revnumber>Accerciser Manual v0.2.0</revnumber> 
        <date>2007-06-29</date> 
        <revdescription> 
          <para role="author">
            Eitan Isaacson <email>eitan@ascender.com</email>
          </para>
          <para role="publisher">Accerciser team</para>
        </revdescription> 
      </revision> 
    </revhistory> 

    <releaseinfo>This manual describes version 0.1.5 of Accerciser.</releaseinfo> 
    <abstract role="description">
      <para>This manual describes the use of <application>Accerciser</application>.</para>
    </abstract> 
    <legalnotice> 
      <title>Feedback</title> 
      <para>To report a bug or make a suggestion regarding the <application>Accerciser</application>       application or this manual, follow the directions in the <ulink url="ghelp:gnome-feedback" type="help">GNOME Feedback Page</ulink>.
      </para>
<!-- Translators may also add here feedback address for translations -->
    </legalnotice> 
  </articleinfo> 

  <indexterm zone="index"> 
    <primary>Accerciser</primary> 
  </indexterm> 

<!-- ============= Document Body ============================= -->
<!-- ============= Introduction ============================== -->
<!-- Use the Introduction section to give a brief overview of what
     the application is and what it does. -->
  <sect1 id="myapp-introduction">
    <title>Uvod</title> 

    <para><application>Accerciser</application> is an interactive Python accessibility explorer for     the GNOME desktop. It uses <ulink url="http://directory.fsf.org/at-spi.html" type="http">AT-SPI</ulink> to inspect and control widgets,     allowing you to check if an application is providing correct     information to assistive technologies and automated test     frameworks. <application>Accerciser</application> has a simple plugin framework which you can use     to create custom views of accessibility information.</para>

    <para>In essence, <application>Accerciser</application> is a next generation <ulink url="http://svn.gnome.org/viewcvs/at-poke" type="http">at-poke</ulink> tool.</para>

  </sect1>

<!-- =========== Getting Started ============================== -->
<!-- Use the Getting Started section to describe the steps required
     to start the application and to describe the user interface components
     of the application. If there is other information that it is important
     for readers to know before they start using the application, you should
     also include this information here. 
     If the information about how to get started is very short, you can 
     include it in the Introduction and omit this section. -->

  <sect1 id="accerciser-getting-started"> 
    <title>Getting Started</title> 

    <sect2 id="myapp-start">
      <title>To Start <application>Accerciser</application></title>
      <para>You can start <application>Accerciser</application> in the following ways:</para> 
      <variablelist>
        <varlistentry>
          <term><guimenu>Applications</guimenu> menu</term>
          <listitem>
            <para>Choose the
            <menuchoice>
              <guisubmenu>Programming</guisubmenu>
              <guimenuitem>Accerciser</guimenuitem>
            </menuchoice> menu item. </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Command line</term>
          <listitem>
            <para>Type the following command in a console window
            then press <keycap>Return</keycap>:</para>
            <para> 
              <command>accerciser</command> 
            </para> 
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="accerciser-when-start">
      <title>When You Start <application>Accerciser</application></title>
      <para>When you start <application>Accerciser</application>, the following window is displayed.</para>

      <!-- ==== Figure ==== -->
      <figure id="mainwindow-fig"> 
        <title><application>Accerciser</application> Main Window</title> 
        <screenshot> 
          <mediaobject> 
            <imageobject><imagedata fileref="figures/accerciser.png" format="PNG"/> 
            </imageobject>
            <textobject> 
              <phrase>
				Shows <application>Accerciser</application> main window. Contains title bar, menu bar,
				accessible tree , right plugin display area, and bottom plugin
				display area. The menu bar contains File, Edit, Bookmarks, 
				View, and Help menus.
			  </phrase> 
            </textobject> 
          </mediaobject> 
        </screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->

    <!-- Include any descriptions of the GUI immediately after 
		 the screenshot of the main UI, -->
    <!-- for example, the items on the menubar and on the toolbar. 
		 This section is optional. -->

      <para>The main <application>Accerciser</application> window contains the following elements:</para>
      <variablelist>
        <varlistentry>
          <term>Menijska vrstica</term>
          <listitem>
			<para>
			  The menu bar contains commands for managing plugins, 
			  managing and using bookmarks, refreshing the accessible 
			  tree view, and accessing this help system.
			</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Accessible tree view</term>
          <listitem>
			<para>
			  The accessible tree view allows to view all of the accessibles 
			  starting at the desktop level. Selecting an accessible makes 
			  it available for further inspection using the loaded plugins. 
			</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Right plugin view</term>
          <listitem>
            <para>
			  This is one of the two default plugin views. 
			  When <application>Accerciser</application> is first run, most plugins will reside here. 
			  You can drag plugin tabs to the bottom plugin view or to 
			  the desktop to show two or more plugins simultaneously.
			</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Bottom plugin view</term>
          <listitem>
            <para>You can drag plugins to or from this area just like the right             plugin view.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>
	<sect2>
	  <title>Plugin View Management</title>
	  <para>
		<application>Accerciser</application> has two modes for viewing plugins. The current view mode 
		could be toggled with 
        <menuchoice>
          <guimenu>View</guimenu><guimenuitem>Single plugin view</guimenuitem> 
        </menuchoice> 
        or by pressing 
        <keycombo><keycap>Control</keycap><keycap>t</keycap></keycombo>. 
        When single mode is enabled, all plugins will be put in the top 
        right plugin view and ordered alphabetically, this could be useful 
        for screen reader users who have no use for <application>Accerciser</application>'s flexible plugin 
        spacial layout scheme. When single view mode is disabled plugin tabs 
        could be dragged and dropped in to different plugin views, 
        or could be dragged to the desktop to put the given plugin in a 
        new view. The placement of plugins could also be manipulated with 
        the plugin context menu that could be brought up either from the 
        plugin tab, or the plugin preferences dialog.
	  </para>
	</sect2>
  </sect1>
<!-- ================ Usage ================================ -->
<!-- Use this section to describe how to use the application to perform the tasks for 
  which the application is designed. -->
  <sect1 id="myapp-usage"> 
    <title>Uporaba</title> 
    <para>You can use <application>Accerciser</application> to inspect any accessible widget shown in the tree     view using the available plugins. The first step is to select an accessible     to inspect using one of the following methods:
    <itemizedlist> 
      <listitem> 
        <para><xref linkend="accerciser-tree-select"/></para> 
      </listitem> 
      <listitem> 
        <para><xref linkend="accerciser-bookmarks"/></para> 
      </listitem> 
    </itemizedlist> 
    </para>
    <!-- ================ Usage Subsection ================================ -->

    <sect2 id="accerciser-tree-select"> 
      <title>Select an accessible through the tree view.</title> 
      <para>
        Use the tree view to navigate the hierarchy of accessible objects
        rooted at desktop. Unfolding a tree node reveals its immediate children
        while folding it hides them. Each node shows an icon for its associated
        application or widget role and its accessible name, if available. 
        The second column lists how many nodes will be shown 
        if the item is unfolded.
      </para>
      
    </sect2> 
    <sect2 id="accerciser-bookmarks"> 
      <title>Using bookmarks</title> 
      <para>
        Accerciser allows bookmarking selected accessibles for later examining.
        This could be helpful if the target application must be restarted, 
        for example after rebuilding it. To bookmark the currently selected 
        accessible do 
        <menuchoice>
          <guimenu>Bookmarks</guimenu>
          <guimenuitem>Add Bookmark...</guimenuitem> 
        </menuchoice> 
        or press 
        <keycombo><keycap>Control</keycap><keycap>d</keycap></keycombo>.
      </para>
      <para>
        Bookmarks to accessibles in Accerciser are defined by an 
        application name and a "path" in the application's internal 
        accessible hierarchy to the bookmarked accessible. When the target 
        application is in a different state (ie. multiple top level frames) 
        the path might not be correct.
      </para>
      <para>
        Bookmarks could be managed by accessing the bookmark editing 
        dialog through 
        <menuchoice>
          <guimenu>Bookmarks</guimenu>
          <guimenuitem>Edit Bookmarks...</guimenuitem> 
        </menuchoice>. 
      </para>
    </sect2> 
  </sect1>

  <!-- ============= Plugins =================================== -->
  <sect1 id="accerciser-default-plugins"> 
    <title>Default Plugins</title> <para><application>Accerciser</application> comes with several default     plugins. These plugins allow you to view a variety of information about the     currently selected accessible in the tree view and its neighbors. The     default plugins available in 0.1.5 are the following:</para>
    <itemizedlist> 
      <listitem> 
        <para><xref linkend="accerciser-iface-viewer"/></para> 
      </listitem> 
      <listitem> 
        <para><xref linkend="accerciser-event-monitor"/></para> 
      </listitem>
      <listitem> 
        <para><xref linkend="accerciser-console"/></para>
      </listitem> 
      <listitem> 
        <para><xref linkend="accerciser-api-browser"/></para>
      </listitem> 
      <listitem> 
        <para><xref linkend="accerciser-script-recorder"/></para>
      </listitem> 
      <listitem> 
        <para><xref linkend="accerciser-quick-select"/></para>
      </listitem> 
      <listitem> 
        <para><xref linkend="accerciser-validate"/></para>
      </listitem> 
    </itemizedlist> 

    <sect2 id="accerciser-iface-viewer"> 
      <title>Interface Viewer</title>
      <para>This plugin displays information about the available interfaces for       the selected tree view accessible. Unsupported interfaces are grayed       out. Various instruments for viewing and controlling an interface are       available under each expander.</para>

      <figure id="iface-viewer-fig"> 
        <title>Interface Viewer</title> 
        <screenshot> 
          <mediaobject> 
            <imageobject>
              <imagedata fileref="figures/interface_viewer.png" format="PNG"/> 
            </imageobject>
            <textobject> 
              <phrase>Interfaces that are supported by the selected accessible               are shown as sensitive.</phrase>
            </textobject> 
          </mediaobject> 
        </screenshot> 
      </figure>
    </sect2> 
    <sect2 id="accerciser-event-monitor"> 
      <title>Event Monitor</title> 
      <para>This plugin monitors the selected types of events from the selected       tree view accessible, from the selected tree view application, or the       entire desktop.</para>
      <figure id="event-monitor-fig"> 
        <title>Event Monitor</title> 
        <screenshot> 
          <mediaobject> 
            <imageobject><imagedata fileref="figures/event_monitor.png" format="PNG"/> 
            </imageobject>
            <textobject> 
              <phrase>The bottom part of the event monitor window
              allows you to pick the type and source of events.</phrase> 
            </textobject> 
          </mediaobject> 
        </screenshot> 
      </figure>
      <tip>
        <para>By pressing 
        <keycombo>
          <keycap>Control</keycap>
          <keycap>Alt</keycap>
          <keycap>l</keycap>
          </keycombo> anywhere on the desktop, the last logged event 
          will be highlighted for later reference. See 
        <xref linkend="accerciser-hotkey-config"/> for how to change
          this key combination.
        </para>
      </tip>
    </sect2> 
    <sect2 id="accerciser-console"> 
      <title>IPython Console</title> 
      <para>This plugin is a
      fully-fledged 
		<ulink url="http://ipython.scipy.org/moin/" type="http">IPython</ulink>
      console. Press <keycap>Tab</keycap> to show completions for the
      current       command. Press <keycap>Enter</keycap> to execute
      any valid Python code.       Commands at the console have access
      to the currently selected accessible       in the accessible
      tree by way of the <varname>acc</varname> variable. In
      addition, all functions and constants from the pyatspi package
      are       available as locals in the console. The most important
      of these are the       functions for querying to other
      accessibility interfaces.  For example,       to query to the
      Text interface: <command>t = acc.queryText() </command>. Imports from the current working directory or       Python path are also allowed.
      </para> 
    </sect2> 
    <sect2 id="accerciser-api-browser"> 
      <title>API Browser</title>
      <para>This plugin shows the interfaces, methods, and attributes supported       by the accessible selected in the tree view.</para>
      <figure id="api-browser-fig"> 
        <title>API Browser</title>
        <screenshot> 
          <mediaobject> 
            <imageobject><imagedata fileref="figures/api_browser.png" format="PNG"/> 
            </imageobject>
            <textobject> 
              <phrase>The API browser.</phrase> 
            </textobject> 
          </mediaobject> 
        </screenshot> 
      </figure>
    </sect2> 
    <sect2 id="accerciser-script-recorder"> 
      <title>Script recorder</title>
      <para>
        <application>Accerciser</application>'s script recorder allows users to record keyboard interaction 
        with other desktop applications for the purpose of authoring UI test 
        scripts. Currently the plug-in supports the generation of scripts for 
        three platforms: Dogtail, LDTP, and an Accerciser's built-in API. 
        Once you press the "Record" button every keyboard interaction will be 
        recorded in to a script that could be executed later as a stand 
        alone script.
      </para>
      <figure id="script-recorder-fig"> 
        <title>Script Recorder</title>
        <screenshot> 
          <mediaobject> 
            <imageobject><imagedata fileref="figures/script_recorder.png" format="PNG"/> 
            </imageobject>
            <textobject> 
              <phrase>The script recorder.</phrase> 
            </textobject> 
          </mediaobject> 
        </screenshot> 
      </figure>
    </sect2> 
    <sect2 id="accerciser-quick-select"> 
      <title>Quick select</title>
      <para>
        This plugin provides global hotkeys for allowing quick selection
        of accessibles through the target application's UI. Pressing 
        <keycombo>
          <keycap>Control</keycap><keycap>Alt</keycap>
          <keycap>a</keycap>
        </keycombo> 
        will select the last focused widget's accessible in <application>Accerciser</application>. Pressing 
        <keycombo>
          <keycap>Control</keycap><keycap>Alt</keycap>
          <keycap>t</keycap>
        </keycombo>
        will select the accessible of the widget that is under the pointer.
      </para>
    </sect2> 

    <sect2 id="accerciser-validate"> 
      <title>Validation</title>
      <para>
        This plugin checks applications for accessibility problems and
        generates a report including the severity and description of the
        problems. The report links errors to documentation about how to remedy
        common problems. The plugin is extensible with test schemas that define
        rules for validation.
      </para>

      <para>
        To run the validator, first select an item in the accessibility
        tree. The plugin will test the selected accessible and all of its
        descendants. Next select a schema to use for the test. Then click the 
        <guibutton>Validate</guibutton> button to start the test. While the test
        is running, click the button again to cancel it.
      </para>

      <para>
        When the test completes, the report table shows the severity and
        description of all errors. Double click a row in the table to show the
        associated accessible in the tree. With an item selected, click the 
        <guibutton>Help</guibutton> to get information about how to resolve
        the problem.
      </para>
    </sect2>

  </sect1>
  <!-- ============= Customization ============================= -->
  <!-- Use this section to describe how to customize the application. -->
  <sect1 id="accerciser-prefs"> 
    <title>Preferences</title>
    <para>There are some elements in <application>Accerciser</application> that are
    configurable:</para>
    <itemizedlist> 
      <listitem> 
        <para><xref linkend="accerciser-plugin-layout"/></para> 
      </listitem>
      <listitem> 
        <para><xref linkend="accerciser-hotkey-config"/></para> 
      </listitem>
    </itemizedlist>
    <sect2 id="accerciser-plugin-layout">
      <title>Plugin Layout</title> 
      <para>
        There are two methods for configuring plugin layout in <application>Accerciser</application>. First
        you may choose
        <menuchoice> 
          <guimenu>Edit</guimenu> 
          <guimenuitem>Preferences</guimenuitem> 
        </menuchoice> 
        to activate the <guilabel>Preferences</guilabel> dialog. 
        This dialog contains tabs for each section, select the 
        <guilabel>Plugins</guilabel> tab. Under this section you will
        find a list view of all the available plugins. Right-click on
        any of the plugins listed to configure it's view.</para>
        
      <para>You may bypass the <guilabel>Preferences</guilabel> dialog by
        using drag and drop to move plugin tabs. Dragging a plugin tab
        to the bottom or right plugin area in the main window will
        move the plugin. Dragging a tab to the desktop will create a
        new plugin window and drop the plugin in it.</para>
    </sect2>
    <sect2 id="accerciser-hotkey-config">
      <title>Global Hotkey Configuration</title>
      <para>Some elements in <application>Accerciser</application> may enable certain functionality
        via hotkeys. The hotkey combination could be changed via the 
        <guilabel>Preferences</guilabel> dialog, to do so you may
        select <menuchoice> 
          <guimenu>Edit</guimenu> 
          <guimenuitem>Preferences</guimenuitem> 
        </menuchoice> 
        to activate the <guilabel>Preferences</guilabel> dialog. 
        This dialog contains tabs for each section, select the 
        <guilabel>Global Hotkeys</guilabel> tab. Under this section you will
        find a list view of all the available hotkey features. Change
        the key bindings to you liking.
      </para>
    </sect2>
  </sect1>
<!-- ============= Bugs ================================== -->
<!-- This section is optional and is commented out by default. 
     You can use it to describe known bugs and limitations of the 
	  program if there are any - please be frank and list all
     problems you know of. 
  
  <sect1 id="mayapp-bugs">
  <title>Known Bugs and Limitations</title>
  <para> </para>
 </sect1>
-->
<!-- ============= About ================================== -->
<!-- This section contains info about the program (not docs), such as
      author's name(s), web page, license, feedback address. This
      section is optional: primary place for this info is "About.." box of
      the program. However, if you do wish to include this info in the
      manual, this is the place to put it. Alternatively, you can put this information in the title page.-->
  <sect1 id="myapp-about"> 
    <title>About <application>Accerciser</application></title> 
    <para> <application>Accerciser</application> was written by Eitan Isaacson     (<email>eitan@ascender.com</email>). To find more information about <application>Accerciser</application>,     please visit the <ulink url="http://live.gnome.org/Accerciser" type="http"><application>Accerciser</application> GNOME Live! page</ulink>. </para>

    <para>To report a bug or make a suggestion regarding this application or     this manual, follow the directions in this <ulink url="ghelp:gnome-feedback" type="help">document</ulink>.
    </para>

    <para>Redistribution and use in source and binary forms, with or without     modification, are permitted under the terms of the BSD License.</para>
  </sect1> 
</article>
