diff options
Diffstat (limited to 'doc/experiment-player.xml')
| -rw-r--r-- | doc/experiment-player.xml | 450 |
1 files changed, 0 insertions, 450 deletions
diff --git a/doc/experiment-player.xml b/doc/experiment-player.xml deleted file mode 100644 index a9dcc34..0000000 --- a/doc/experiment-player.xml +++ /dev/null @@ -1,450 +0,0 @@ -<?xml version="1.0"?> - -<book xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink"> - <info> - <title>Experiment Player</title> - <subtitle>A tool to analyze audiovisual experiment recordings and transcripts</subtitle> - - <author> - <personname><firstname>Jens</firstname> <surname>Lammert</surname></personname> - <email>jens.lammert@st.ovgu.de</email> - </author> - <copyright> - <year>2012</year> - <year>2013</year> - <holder>Otto-von-Guericke Universität Magdeburg</holder> - </copyright> - - <abstract><para> - The following document illustrates how to install, configure - and use the Experiment Player to analyze experiments. - </para></abstract> - - <address> - <uri> - <link xlink:href="https://github.com/rhaberkorn/experiment-player">https://github.com/rhaberkorn/experiment-player</link> - </uri> - </address><address> - <uri> - <link xlink:href="http://sourceforge.net/projects/exp-player/">http://sourceforge.net/projects/exp-player/</link> - </uri> - </address> - </info> - - <chapter> - <title>Installation</title> - <section> - <title>Windows</title> - <para> - To install the <productname>Experiment Player</productname> on a Windows-based operating system, - the GTK+ 2 widget toolkit must first be downloaded and installed. - A convenient GTK+ installer can be downloaded from the - <link xlink:href="http://gtk-win.sourceforge.net/home/index.php/Main/Downloads"> - "GTK+ for Windows Runtime Environment Installer" project page</link>. - It is only necessary to install the - <link xlink:href="http://downloads.sourceforge.net/gtk-win/gtk2-runtime-2.24.10-2012-10-10-ash.exe?download"> - GTK+ runtime</link>. - <link xlink:href="http://downloads.sourceforge.net/gtk-win/gtk2-themes-2009-09-07-ash.exe?download"> - Additional themes</link> may be installed as well - but the default GTK+ theme should be sufficient. - </para><para> - Precompiled Windows 32-bit binaries of the <productname>Experiment Player</productname> itself - are available as ZIP archives from the - <link xlink:href="http://sourceforge.net/projects/exp-player/files/bin/">Sourceforge project page</link>. - The ZIP archive merely has to be extracted somewhere. - Afterwards the included <filename>experiment-player.exe</filename> can be executed. - All library dependencies except GTK+ are included in the ZIP archive. - </para> - </section> - <section> - <title>Linux</title> - <para> - To install the <productname>Experiment Player</productname> on a Linux-based operating system, - it first has to be built from source. - It can either be built from a local - <link xlink:href="https://github.com/rhaberkorn/experiment-player">Git repository</link> clone, - or from a source code package that can be downloaded from the - <link xlink:href="http://sourceforge.net/projects/exp-player/files/src/">project's download archive - on Sourceforge</link>. - In either case, further build instructions are given in the included - <filename>INSTALL</filename> file. - </para> - </section> - </chapter> - <chapter> - <title>Graphical User Interface</title> - <para> - After startup there will be two windows, a <emphasis>player</emphasis> - window and a <emphasis>data</emphasis> window. - They are explained in the following sections. - </para> - <section> - <title>Player Window</title> - <screenshot xml:id="player-window"> - <!-- <title>Player Window after startup</title> --> - <mediaobject> - <imageobject> - <imagedata fileref="images/player-window-new.png"/> - </imageobject> - <caption>Player Window after startup</caption> - </mediaobject> - </screenshot> - <para> - The image above depicts the player window after startup. - No experiment is yet opened in the application, so several - controls are greyed out. - </para><para> - Experiments can be opened via the <guimenu>File</guimenu> menu - or the <guimenu>Quick Open</guimenu> menu. - The process of opening experiments via the <guimenu>Quick Open</guimenu> menu - is <link linkend="quick-open">explained later on</link>. - The remaining interface components are self-explanatory. - </para> - </section> - <section> - <title>Data Window</title> - <screenshot xml:id="data-window-new"> - <!-- <title>Data Window after startup</title> --> - <mediaobject> - <imageobject> - <imagedata fileref="images/data-window-new.png"/> - </imageobject> - <caption>Data Window after startup</caption> - </mediaobject> - </screenshot> - <para> - The image above depicts the data window after startup. - The data window is used to display additional information of an - experiment. - This information is time-dependant and synchronized with other - time-dependant data, like the current video position. - If the time is changed in one component, it changes in all the - other ones as well. - </para><para> - The current implementation is able to display an experiment - transcript (in the Transcript view area). - The transcript view is divided into a left part showing the - wizard's text contributions and a right part showing the - proband's text contributions. - The different experiment phases are displayed hierachically - in the Transcript navigation area. - Transcripts may also be searched and highlighted but this feature is - <link linkend="highlighting">explained later on</link>. - </para><para> - Furthermore the look of the Transcript View may be customized - after loading an experiment by right-clicking the Transcript view. - Foreground and background colors, text alignment and scroll direction - can be changed this way. - </para><para> - The playback position of the experiment may be influenced in the - following ways: - <itemizedlist> - <listitem><para> - by clicking or scrolling the slider in the - <link linkend="data-window-new">data window</link> with the mouse - wheel, - </para></listitem> - <listitem><para> - by scrolling the transcript widgets with the mouse wheel, - </para></listitem> - <listitem><para> - by using the transcript view's scroll bar, or - </para></listitem> - <listitem><para> - by double-clicking an entry in the navigation hierarchy. - </para></listitem> - </itemizedlist> - Single clicking an entry in the navigation hierarchy - mereley highlights that part of the transcript by the shading the - transcript view's background. - </para> - </section> - </chapter> - <chapter> - <title>Getting Started</title> - <section xml:id="quick-open"> - <title>How to load a file with Quick Open</title> - <para> - A video recording of an experiment and its correspondig transcript file - are considered as an experiment. A video is an AVI or MP4 file - while transcript files are special XML applications generated from - <link xlink:href="http://agd.ids-mannheim.de/download/Folker_Schema.xsd"> - FOLKER XML transcripts</link>. - Transcript XML files must conform to the <filename>session.dtd</filename> - schema shipped with the <application>Experiment Player</application> - application. - Experiment's files can be opened separately or by using the - <emphasis>Quick Open</emphasis> feature. - </para> - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="images/quick-open-empty.png"/> - </imageobject> - <caption>Empty Quick Open menu</caption> - </mediaobject> - </screenshot> - <para> - <emphasis>Quick Open</emphasis> can be performed using the - <guimenu>Quick Open</guimenu> menu. - The menu has items for all experiments found in a selected - directory. - The directory may be selected using the <guimenuitem>Choose Directory...</guimenuitem> - menu item. - Experiment files with identical basenames (file name without extension) are - listed as single menu items. - For instance, if the directory contains two files <filename>20101117.xml</filename> and - <filename>20101117.mp4</filename>, the menu will look like: - </para> - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="images/quick-open.png"/> - </imageobject> - </mediaobject> - </screenshot> - <para> - When an experiment item is activated in the menu, the - corresponding experiment files are loaded (replacing any - already opened experiment). - The configured location of the <emphasis>Quick Open</emphasis> directory - persists after application restarts. - </para> - </section> - <section xml:id="highlighting"> - <title>Transcript Highlighting</title> - <para> - To analyze the dialog between proband and wizard the Experiment-Player offers - a feature to search for text patterns in the dialog and for highlighting the matches - in the transcript. - After loading an experiment via the <guimenu>Quick Open</guimenu> menu, - the dialog between proband and wizard will be displayed in the transcript widgets. - The highlighting feature can be used for both the wizard's and the proband's part - of the dialog independently of each other. - By entering a search expression in the - <link linkend="data-window-new">text boxes for interactive highlighting</link> - of the transcript will be highlighted on the fly. - The syntax of these search expressions and their exact semantics are - described in the following sections. - </para> - <section xml:id="regexp"> - <title>Regular Expressions</title> - <para> - By default, if the <guibutton>Markup</guibutton> toggles are inactive, - search expressions are interpreted as <emphasis>regular expressions</emphasis>. - The system will iterate all text fragments (dialog contributions - with distinct timestamps) and tries to match the regular expression - against them. - All the matches will be highlighted. - By default they will be formatted bold, but this may be changed - in the <link linkend="config-file">configuration file</link>. - <emphasis>Regular Expressions</emphasis> - are case-insensitive so both lower-case and upper-case character - will match both lower and upper case text. - For more information about the <emphasis>Regular Expression</emphasis> - syntax supported by the program, have a look at the - <link xlink:href="http://developer.gnome.org/glib/stable/glib-Perl-compatible-regular-expressions.html"> - glib documentation for Perl compatible Regular Expression</link>. - All constructs are supported, except captures. - </para><para> - An icon next to the pattern entry box signals well-formedness of - the entered search expression. - </para> - </section> - <section> - <title>Format Expression</title> - <para> - By default a search term will be regarded as - <emphasis>Regular Expression</emphasis> and matches found - will be highlighted bold. - However if the <guibutton>Markup</guibutton> toggle is activated - the input expression will be regarded as a - <emphasis>Format Expression</emphasis> which is a combination of - <emphasis>Regular Expression</emphasis> and <emphasis>Pango Markup</emphasis>. - <emphasis>Pango Markup</emphasis> is a simple HTML-like formatting - markup language. - </para><para> - Just like with plain regular expressions, all text fragments are iterated - and the format expression is matched against each of them. - The markup does not matter for matching but only the regular expressions - contained <emphasis>within</emphasis> the markup tags. - For every match in each of the text fragments, the markup will be applied - to all of the text matched by the regular expression within the - corresponding markup tag. - So for instance the format expression - <code><![CDATA[<b>A<i>B</i>C</b>]]></code>, - case-insensitively matches against all occurrences of <literal>ABC</literal>, - formatting all the characters bold and only <literal>B</literal> in italics. - </para><para> - The following screenshot shows a transcript with all consonants followed - by vowels highlighted - (expression <code><![CDATA[<span color="red">[^aeiou]</span><span color="blue">[aeiou]</span>]]></code>): - </para> - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="images/format-expressions.png"/> - </imageobject> - </mediaobject> - </screenshot> - <para> - For more information about <emphasis>Pango Markup</emphasis>, please read the - <link xlink:href="http://developer.gnome.org/pango/stable/PangoMarkupFormat.html"> - Pango Markup documentation</link>. - </para> - </section> - <section> - <title>Format Files</title> - <para> - <emphasis>Format Files</emphasis> are files which contain a sequence of - <emphasis>format expressions</emphasis>. - So any collection of format expressions for - analyzing dialogs can be saved in those files and used with different - experiments. - </para> - <example xml:id="sample.fmt"> - <title>Sample Format File (sample.fmt)</title> - <programlisting><![CDATA[# The samples from last section combined into one file: -<b>A<i>B</i>C</b> -<span color="red">[^aeiou]</span><span color="blue">[aeiou]</span>]]></programlisting> - </example> - <para> - <emphasis>Format Files</emphasis> are loaded in a similar manner as experiments - when using the <emphasis>Quick Open</emphasis> feature. - First a directory containing format files must be chosen via the - <guimenuitem>Choose Directory...</guimenuitem> item in the <guimenu>Formats</guimenu> - menu of the data window. - </para> - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="images/format-menu.png"/> - </imageobject> - <caption>"Formats" menu</caption> - </mediaobject> - </screenshot> - <para> - A format file may then be selected via the drop-down boxes below the - transcript view area. - The first entry of those boxes is always empty and may be selected to - disable format file processing. - The following screenshot shows - <link linkend="sample.fmt"><filename>sample.fmt</filename></link> - being selected: - </para> - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="images/format-file-selection.png"/> - </imageobject> - </mediaobject> - </screenshot> - <para> - If a format file is selected, for each text fragment every format expression - in the format file is evaluated (highlighting all matches as described earlier). - At last, any interactively entered search expression (plain regular expression or - format expression) is evaluated for each text fragment after the format expressions - in the currently selected <emphasis>Format File</emphasis>. - All formattings are applied cumulatively. - Where subsequent styles cannot be merged, later ones overwrite earlier ones. - For instance, when loading the following format file, the word <emphasis>program</emphasis> - is formatted blue instead of red: - </para> - <programlisting><![CDATA[<span color="red">programm</span> -<span color="blue">programm</span>]]></programlisting> - <para> - The syntax of format files is as follows: - <itemizedlist> - <listitem><para> - <emphasis>Format Files</emphasis> have the file extension - <literal>fmt</literal>. - </para></listitem> - <listitem><para> - Every line will be regarded as a distinct - <emphasis>Format Expression</emphasis>. - </para></listitem> - <listitem><para> - Leading whitespace characters are ignored. - </para></listitem> - <listitem><para> - A line beginning with <literal>#</literal> - is ignored completely (comment line). - </para></listitem> - <listitem><para> - Empty lines are ignored. - </para></listitem> - <listitem><para> - Incorrect lines will cause an error message. - </para></listitem> - </itemizedlist> - </para> - </section> - </section> - </chapter> - <chapter xml:id="config-file"> - <title>Config File</title> - <para> - The <application>Experiment Player's</application> configuration file - is located in different locations depending on the platform: - </para> - <itemizedlist> - <listitem><para> - Under Linux, it will be located in the user's data directory as specified - in the <link xlink:href="http://www.freedesktop.org/Standards/basedir-spec"> - XDG Base Directory Specification</link> - (usually <filename>$HOME/.local/share/.experiment-player</filename>). - </para></listitem> - <listitem><para> - Under Windows, it will be located in the local application data directory - (usually <filename>C:\Documents and Settings\%USERNAME%\Local Settings\Application Data\.experiment-player</filename>). - </para></listitem> - </itemizedlist> - <para> - The syntax of the configuration file is documented in the - <link xlink:href="developer.gnome.org/glib/unstable/glib-Key-value-file-parser.html">glib documentation</link>. - </para><para> - Sometimes it is useful to edit the configuration file directly in order to tweak options that are not - accessible via the <application>Experiment Player</application> GUI. - The following table lists such configuration keys: - </para> - <table border="1"> - <title>Configuration Keys</title> - <thead border="1"> - <tr> - <td>Key</td> - <td>Description</td> - <td>Format</td> - </tr> - </thead> - <tbody border="1"> - <tr> - <td><literal>Default-Format-Font</literal></td> - <td> - The font used for highlighting <link linkend="regexp">plain regular expressions</link>. - </td><td> - See <link xlink:href="http://developer.gnome.org/pango/stable/pango-Fonts.html#pango-font-description-from-string"> - Pango Font description</link> - </td> - </tr> - <tr> - <td><literal>Default-Format-Text-Color</literal></td> - <td> - The foreground color used for highlighting <link linkend="regexp">plain regular expressions</link>. - </td><td> - An RGB color specification such as <literal>#FF0000</literal> or a color name such as - <literal>red</literal>. - </td> - </tr> - <tr> - <td><literal>Default-Format-BG-Color</literal></td> - <td> - The background color used for highlighting <link linkend="regexp">plain regular expressions</link>. - </td><td> - An RGB color specification such as <literal>#FF0000</literal> or a color name such as - <literal>red</literal>. - </td> - </tr> - </tbody> - </table> - </chapter> -</book> |