From 1a38093af568c7a738e44f6f3e68175a7c86167a Mon Sep 17 00:00:00 2001 From: Jens Lammert Date: Fri, 19 Jul 2013 15:18:46 +0200 Subject: completely revised "Getting Started" chapter and "Config File" chapter, adding some screenshots --- doc/experiment-player.xml | 351 +++++++++++++++++++++++++---------- doc/images/format-expressions.png | Bin 0 -> 49243 bytes doc/images/format-file-selection.png | Bin 0 -> 41771 bytes doc/images/format-menu.png | Bin 0 -> 5214 bytes 4 files changed, 256 insertions(+), 95 deletions(-) create mode 100644 doc/images/format-expressions.png create mode 100644 doc/images/format-file-selection.png create mode 100644 doc/images/format-menu.png diff --git a/doc/experiment-player.xml b/doc/experiment-player.xml index 8d2f3a8..a9dcc34 100644 --- a/doc/experiment-player.xml +++ b/doc/experiment-player.xml @@ -20,7 +20,7 @@ The following document illustrates how to install, configure and use the Experiment Player to analyze experiments. - +
https://github.com/rhaberkorn/experiment-player @@ -80,7 +80,7 @@
Player Window - + @@ -97,13 +97,13 @@ Experiments can be opened via the File menu or the Quick Open menu. The process of opening experiments via the Quick Open menu - is explained later on. + is explained later on. The remaining interface components are self-explanatory.
Data Window - + @@ -123,25 +123,57 @@ The current implementation is able to display an experiment transcript (in the Transcript view area). - The transcript view is divided up into a left part showing the - proband's text contributions and a right part showing the - wizard's text contributions. + 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 can also be highlighted but this feature is - explained later on. + Transcripts may also be searched and highlighted but this feature is + explained later on. + + 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. + + The playback position of the experiment may be influenced in the + following ways: + + + by clicking or scrolling the slider in the + data window with the mouse + wheel, + + + by scrolling the transcript widgets with the mouse wheel, + + + by using the transcript view's scroll bar, or + + + by double-clicking an entry in the navigation hierarchy. + + + Single clicking an entry in the navigation hierarchy + mereley highlights that part of the transcript by the shading the + transcript view's background.
Getting Started -
+
How to load a file with Quick Open - A video recording of an experiment and its related transcript file + 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. - The experiment's files can be opened separately or by using the + while transcript files are special XML applications generated from + + FOLKER XML transcripts. + Transcript XML files must conform to the session.dtd + schema shipped with the Experiment Player + application. + Experiment's files can be opened separately or by using the Quick Open feature. @@ -179,111 +211,240 @@ persists after application restarts.
-
+
Transcript Highlighting - If the transcript is opened and a files was selected the transcript widget - shows the dialog between proband and wizard. The dialog monitor is divided - up into two seperate widgets so there can be different settings and fonts - at each widget. Also it is possible to markup matches separate from each other. - There two way to search matches: regular expressions and format files. + 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 Quick Open 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 + text boxes for interactive highlighting + 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. -
+
Regular Expressions - For more information how to use regular expressions have a look at - glib documentation for Perl compatible regular expression. - Regular expressions are case-insensitive so both lower-case and upper-case character - will match the same expression. Regular expression matches will be formated bold by default. - Captures are not be supported. + By default, if the Markup toggles are inactive, + search expressions are interpreted as regular expressions. + 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 configuration file. + Regular Expressions + are case-insensitive so both lower-case and upper-case character + will match both lower and upper case text. + For more information about the Regular Expression + syntax supported by the program, have a look at the + + glib documentation for Perl compatible Regular Expression. + All constructs are supported, except captures. + + An icon next to the pattern entry box signals well-formedness of + the entered search expression.
Format Expression - By default a search term will be regarded as regular expression. If the - markup toggle is activated the input expression will be regarded as - format expression which is a combination of regular expression and Pango mark up. - That means if the regular expression matchs at the text the markup - expressions will apply. - For more information refer to the Pango Markup documentation.. + By default a search term will be regarded as + Regular Expression and matches found + will be highlighted bold. + However if the Markup toggle is activated + the input expression will be regarded as a + Format Expression which is a combination of + Regular Expression and Pango Markup. + Pango Markup is a simple HTML-like formatting + markup language. + + 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 within 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 + ABC]]>, + case-insensitively matches against all occurrences of ABC, + formatting all the characters bold and only B in italics. + + The following screenshot shows a transcript with all consonants followed + by vowels highlighted + (expression [^aeiou][aeiou]]]>): + + + + + + + + + + For more information about Pango Markup, please read the + + Pango Markup documentation.
Format Files - Format files are collection of multiple format expressions. At first there - has to be selected a quick open directory in menue Format entry Choose Directory. - After that all available format files in the selected directory will be listed - under menue Formats. To create an own format file care the following: - - - Each line will regarded as a single mark up statement. - - - - Leading whitespace characters will be ignored. - - - - A line beginning with '#' will be ignored complete. - - - - Only whole lines can be ignored. - - - - The format file has to save as a FMT-file (*.fmt). - - - - Incorrect lines will cause an error message. - - + Format Files are files which contain a sequence of + format expressions. + So any collection of format expressions for + analyzing dialogs can be saved in those files and used with different + experiments. + + + Sample Format File (sample.fmt) + ABC +[^aeiou][aeiou]]]> + + + Format Files are loaded in a similar manner as experiments + when using the Quick Open feature. + First a directory containing format files must be chosen via the + Choose Directory... item in the Formats + menu of the data window. + + + + + + + "Formats" menu + + + + 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 + sample.fmt + being selected: + + + + + + + + + + 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 Format File. + 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 program + is formatted blue instead of red: + + programm +programm]]> + + The syntax of format files is as follows: + + + Format Files have the file extension + fmt. + + + Every line will be regarded as a distinct + Format Expression. + + + Leading whitespace characters are ignored. + + + A line beginning with # + is ignored completely (comment line). + + + Empty lines are ignored. + + + Incorrect lines will cause an error message. + - Let be the whole text referring to a single time stamp a text fragment. - For each text fragment each format expression in the format file will be - iterated and the associated regular expression will matched. - For each match all associated mark ups will apply cumulatively at the - matching text.
- + Config File - The config file is located in the users default directory where each config - files are. By editing the config-file default keys which can not changed via - gui can set. More details about the structure of the config file can be - found in the + The Experiment Player's configuration file + is located in different locations depending on the platform: + + + + Under Linux, it will be located in the user's data directory as specified + in the + XDG Base Directory Specification + (usually $HOME/.local/share/.experiment-player). + + + Under Windows, it will be located in the local application data directory + (usually C:\Documents and Settings\%USERNAME%\Local Settings\Application Data\.experiment-player). + + + + The syntax of the configuration file is documented in the glib documentation. - - The following table shows all additional keys : - - - - - - - - - - - - - - - - - - - - - - -
KeyDescription
Default-Format-FontFor detailed information follow pango font description
Default-Format-Text-ColorAn RGB color specification such as '#00FF00' or a color name such as 'red'
Default-Format-BG-ColorAn RGB color specification such as '#00FF00' or a color name such as 'red'
+ + Sometimes it is useful to edit the configuration file directly in order to tweak options that are not + accessible via the Experiment Player GUI. + The following table lists such configuration keys: + + Configuration Keys + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionFormat
Default-Format-Font + The font used for highlighting plain regular expressions. + + See + Pango Font description +
Default-Format-Text-Color + The foreground color used for highlighting plain regular expressions. + + An RGB color specification such as #FF0000 or a color name such as + red. +
Default-Format-BG-Color + The background color used for highlighting plain regular expressions. + + An RGB color specification such as #FF0000 or a color name such as + red. +
diff --git a/doc/images/format-expressions.png b/doc/images/format-expressions.png new file mode 100644 index 0000000..7d49b6c Binary files /dev/null and b/doc/images/format-expressions.png differ diff --git a/doc/images/format-file-selection.png b/doc/images/format-file-selection.png new file mode 100644 index 0000000..8210491 Binary files /dev/null and b/doc/images/format-file-selection.png differ diff --git a/doc/images/format-menu.png b/doc/images/format-menu.png new file mode 100644 index 0000000..463cc0e Binary files /dev/null and b/doc/images/format-menu.png differ -- cgit v1.2.3