<?xml version="1.0" encoding="UTF-8"?>

<!--
    Document   : xvidcap-manual.xml
    Created on : 17. September 2006, 12:01
    Author     : kb87850
    Description:
        Purpose of the document follows.
-->

<!DOCTYPE article  PUBLIC "PUBLIC:-//OASIS//DTD DocBook XML V4.4//EN" 
	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY appversion "1.1.7">
  <!ENTITY manrevision "0.3">
  <!ENTITY date "April 2007">
  <!ENTITY app "xvidcap">
  <!ENTITY mf-cap "multi-frame capture">
  <!ENTITY sf-cap "single-frame capture">
  ]
>
<article id="index" lang="en">
    <!-- please do not change the id; for translations, change lang to -->
    <!-- appropriate code -->
    <articleinfo>
        <title>&app; Manual V&manrevision;</title>
        <copyright>
            <year>2008</year>
            <holder>Karl H. Beckers</holder> 
        </copyright>

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

        <publisher>
            <publishername>Karl H. Beckers</publishername>
        </publisher>

        <!-- FIXME later
        <xi:include href="legal.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
        --> 

        <authorgroup>
            <author role="maintainer">
                <firstname>Karl</firstname>
                <othername>H.</othername>
                <surname>Beckers</surname>
                <email>karl.h.beckers@gmx.net</email>
            </author>
        </authorgroup>

        <!-- According to GNU FDL, revision history is mandatory if you are -->
        <!-- modifying/reusing someone else's document.  If not, you can omit it. -->
        <revhistory>
            <!-- Remember to remove the &manrevision; entity from the revision entries other
            than the current revision. -->
            <revision>
                <revnumber>&app; V0.1</revnumber>
                <date>2006</date>
                <revdescription>
                    <para role="author">Karl H. Beckers <email>karl.h.beckers@gmx.net</email>
                    </para>
                    <para role="publisher">Karl H. Beckers</para>
                </revdescription>
            </revision>
            <revision>
                <revnumber>&app; V0.2</revnumber>
                <date>2007</date>
                <revdescription>
                    <para role="author">Karl H. Beckers <email>karl.h.beckers@gmx.net</email>
                    </para>
                    <para role="publisher">Karl H. Beckers</para>
                </revdescription>
            </revision>
            <revision>
                <revnumber>&app; V&manrevision;</revnumber>
                <date>2008</date>
                <revdescription>
                    <para role="author">Karl H. Beckers <email>karl.h.beckers@gmx.net</email>
                    </para>
                    <para role="publisher">Karl H. Beckers</para>
                </revdescription>
            </revision>

        </revhistory>
        <releaseinfo> This manual describes version &appversion; of &app;.
        </releaseinfo>
        <legalnotice>
            <title>Feedback</title>
            <para>
                To report a bug or make a suggestion regarding the <application>&app;</application> application or this 
                manual, follow the directions on <ulink url="http://www.sourceforge.net/projects/xvidcap">&app;'s site at SF.net</ulink>.
            </para>
            <!-- Translators may also add here feedback address for translations -->
        </legalnotice>
        <abstract role="description">
            <para>User manual for the &app; screencam application.</para>
        </abstract>
    </articleinfo>
    <indexterm><primary>xvidcap</primary></indexterm>
    <indexterm><primary>screencam</primary></indexterm>
    <indexterm><primary>screencast</primary></indexterm>

    <!-- ============= Document Body ============================= -->
    <!-- ============= Introduction ============================== -->
    <sect1 id="xvidcap-intro">
        <title>Introduction</title>
        <para>
            <application>&app;</application> is a tool that captures movement on a selected area of an X11 screen to files. 
            It does this by taking a configurable number of screenshots per second and saving them either as individual
            screenshots or as a video. This kind of application, today, is commonly labelled screencam or screencast utility. 
            In fact, one of the oldest of those utilities was <application>Lotus Screencam</application> which served as the 
            inspiration for <application>&app;</application>.
        </para>

        <para>
            <application>&app;</application> can be used in two distinct modes of operation:
            <orderedlist>
                <listitem>
                    <para>
                        <guilabel>&sf-cap;</guilabel> -- capture individual screenshots to one file each.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <guilabel>&mf-cap;</guilabel> -- capture and encode to video on the fly.
                    </para>
                </listitem>
            </orderedlist>
        </para>    

        <tip>
            <title>Mnemonic</title>
            <para>
                The naming of the modes of operation derives from the number of frames that get stored in the output file:
                One or many.
            </para>
        </tip>

        <caution>
            <title>Audio Capture</title>
            <para>
                <application>&app;</application> can capture audio, but only in &mf-cap; operation.
            </para>
        </caution>

        <para>
            Recording in single-frame capture mode may be more convenient if you wish to preprocess the images before 
            encoding, or if you need other video codecs <application>&app;</application> does not support. Individual images can later be encoded 
            with tools like <ulink type="help" url="man:ffmpeg">ffmpeg</ulink>, 
            <ulink type="help" url="man:mencoder">mencoder</ulink>, or 
            <ulink type="help" url="man:transcode">transcode</ulink>.
        </para>

        <para>
            To report a bug or make a suggestion regarding the <application>&app;</application> application or this manual, 
            follow the directions on <ulink url="http://www.sourceforge.net/projects/xvidcap">&app;'s site at SF.net</ulink>.
        </para>
    </sect1>
    
    <sect1 id="xvidcap-get-started">
        <title>Getting Started</title>
    
        <sect2 id="xvidcap-get-started-to-start">
            <title>To Start &app;</title>
            <para>You can start <application>&app;</application> in the following ways:</para>
            <variablelist>
                <varlistentry>
                    <term><guimenu>Applications</guimenu> menu</term>
                    <listitem>
                        <para>
                            Choose <menuchoice><guisubmenu>Sound &amp; Video</guisubmenu>
                            <guimenuitem>XVidCap Screen Capture</guimenuitem></menuchoice>.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Command line</term>
                    <listitem>
                        <para>
                            Execute the following command: <command>xvidcap</command>. For more 
                            information about command line usage see <ulink type="help" url="man:xvidcap">the xvidcap manpage</ulink>.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect2>

        <sect2 id="xvidcap-get-started-u-start">

            <title>When You Start <application>&app;</application></title>
            <para>When you start <application>&app;</application>, the following window is displayed:</para>

            <figure id="xvidcap-window">
                <title>&app; Control</title>
                <screenshot>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="figures/xvidcap-main-ctrl.png" format="PNG"/>
                        </imageobject>
                        <textobject> <phrase>Shows <application>&app;</application> control.</phrase>
                        </textobject>
                    </mediaobject>
                </screenshot>
            </figure>

            <para>
                The window with a proper title and buttons is &app;'s main control, while the red rectangle is
                the selection frame enclosing the area to capture.
            </para>

            <table frame="all" id="xvidcap-get-started-u-start-TBL">
                <title>
                    &app;'s main control elements: 
                </title>
                <tgroup cols="2" align="char" charoff="50" char=".">
                    <tbody>
                        <row id="xvidcap-get-started-u-start-TBL-filename">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/filename-button.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Filename Display and Menu</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    The <guilabel>Filename Display and Menu</guilabel> displays the current output filename and, 
                                    if in &mf-cap; mode, the index number of the most recently captured frame in square brackets.
                                    In &sf-cap; mode the index number of the current frame will typically be part of the filename.
                                </para>
                                <para>
                                    When in &sf-cap; mode a left click resets the frame count to the start. A right-click while
                                    not capturing will pop up the <ulink type="help" url="ghelp:xvidcap?xvidcap-menu">main menu</ulink>.
                                </para>
                                <tip>
                                    <title>Default Capture Mode</title>
                                    <para>By default, <application>&app;</application> starts in &mf-cap; mode.</para>
                                </tip>

                            </entry>
                        </row>
                        <row id="xvidcap-get-started-u-start-TBL-frame-drop-meter">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/frame-drop-meter.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Frame Drop Meter</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    The <guilabel>Frame Drop Meter</guilabel> provides an indication of how well your capture session can capture at 
                                    your desired frame rate. If your system is under heavy load, it may not be able to capture
                                    as many frames per second as you wish. This will result in a video that plays back too quickly.
                                    <application>&app;</application> displays a green status if you can or can almost capture at the desired frame rate. If
                                    you have some frame drop the status turns to yellow, or red if there is excessive frame drop.
                                    To reduce frame drop you can capture a smaller part of your screen, select a lower frame rate,
                                    quit as many other applications putting stress on your system as possible, or run on a more 
                                    powerful machine. It may also help to <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-rescale">downscale</ulink>
                                    the captured data. Another means for making screen capture lighter on your system is to
				    make use of the XDamage extension. See the corresponding paragraph about the 
				    <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-general">general options tab</ulink>
				    of the preferences dialog.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-get-started-u-start-TBL-stop">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/stop-toggle.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Stop Button</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>			
                            </entry>
                            <entry>
                                <para>
                                    The <guilabel>Stop Button</guilabel> stops a running recording session.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-get-started-u-start-TBL-pause">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/pause-toggle.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Pause Button</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    The <guilabel>Pause Button</guilabel> pauses a running or continues a paused recording session.
                                    You can also select this before starting to record to start paused.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-get-started-u-start-TBL-record">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/record-toggle.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Record Button</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>			
                            </entry>
                            <entry>
                                <para>
                                    The <guilabel>Record Button</guilabel> starts a recording session.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-get-started-u-start-TBL-step">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/step-button.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Single Snaphot Button</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    The <guilabel>Single Snapshot Button</guilabel> is only active in a paused &sf-cap; mode capturing session.
                                    Then it allows you to take individual snapshots on a click of this button.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-get-started-u-start-TBL-back">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/back-button.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Rewind Button</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>			
                            </entry>
                            <entry>
                                <para>
                                    The <guilabel>Rewind Button</guilabel> has different uses depending on the current capture mode.
                                </para>
                                <para>
                                    In &sf-cap; mode <quote>rewinding</quote> relates to the index number of the current frame to
                                    capture. Imagine you have a stopped capture session that has captured ten PNG images. The filename 
                                    display may show <quote>test-0010.png</quote>. You then realize, the last two snapshots weren't
                                    what you needed. You can then click the rewind button twice. This changes the filename display to 
                                    <quote>test-0008.png</quote>. If you continue to capture, frames eight and nine in images <quote>test-0008.png</quote>
                                    and <quote>test-0009.png</quote> will be overwritten.
                                </para>
                                <para>
                                    In &mf-cap; mode the rewind button works quite similar. It does not, however, manipulate the
                                    index number of the current frame, but rather of the current movie as it relates to the 
                                    <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-autocontinue">autocontinue</ulink>
                                    feature.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-get-started-u-start-TBL-fwd">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/fwd-button.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Forward Button</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>			
                            </entry>
                            <entry>
                                <para>
                                    The <guilabel>Forward Button</guilabel> does the opposite of the rewind button in that it 
                                    increments the current frame's index number or the movie index number depending on capture mode.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-get-started-u-start-TBL-lock">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/lock-toggle.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Frame Selection Lock</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>			
                            </entry>
                            <entry>
                                <para>
                                    The <guilabel>Frame Selection Lock</guilabel> makes the capture selection move with the
                                    main control if selected. If deselected, the capture selection will stay where it is when
                                    the main control moves. If, in the
				    <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-cmd">preferences dialog</ulink>, you 
				    have checked "Capture Area Follows Mouse" the capture selection follows the mouse pointer
				    instead.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-get-started-u-start-TBL-selector">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/selector-button.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Frame Selector Button</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    Click the <guilabel>Frame Selector Button</guilabel> to change the area you want to capture.
                                    When you click it, the cursor changes to a cross-hair cursor. After that you can either:
                                </para>
                                <itemizedlist>
                                    <listitem>
                                        <para>
                                            click on a single window to capture that window.
                                        </para>
                                        <caution>
                                            <title>Moving Captured Windows</title>
                                            <para>
                                                Note that the area selection is not sticky to the window in the sense that it
                                                would follow the window you originally selected, if you move it away. All it
                                                does is adjust position and dimension of the selected capture area to match
                                                the contents of the window clicked on. If you move the window afterwards, the
                                                capture area will stay where it is, unless you have the frame selection lock
                                                enabled and manually move the main control to the right position.
                                            </para>
                                        </caution>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            click and drag to select an arbitrary portion of the screen.
                                        </para>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            click on the backdrop to select full-screen capture.
                                        </para>
                                        <caution>
                                            <title>Full-Screen Capture</title>
                                            <para>
                                                With current display sizes, full-screen capture has a very high probability of
                                                putting too much stress on your system. Watch the frame drop monitor and possibly
                                                adjust your screen resolution if you absolutely must capture full-screen. 
                                                Remember that DVDs typically contain resolutions of 720 x 486. Capturing full-screen 
                                                at a resolution of 1400 x 1050 means encoding about 4 times the data rate of a DVD
                                                in real time -- not something you will be doing with a pencil and paper.
                                            </para>
						It is not just the encoding of a full screen capture, though, that may put 
						too much stress on your system. Grabbing the complete capture area from the X11 
						display is a heavy task on its own right. Using the XDamage extension may ease
						the effect of that, however there may be caveats. See the corresponding paragraph about the 
						<ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-set-xdamage">general options tab</ulink>
						of the preferences dialog.
                                            <para>
                                            </para>
                                        </caution>
                                    </listitem>
                                </itemizedlist>
        			<tip>
            				<title>Resize By Dragging</title>
            				<para>
					Starting with version 1.1.5, you can also resize the area to capture by dragging on
					the edges of the frame while not capturing. Use that feature as you would resize a
					normal window.
					</para>
        			</tip>
                            </entry>
                        </row>
                        <row id="xvidcap-get-started-u-start-TBL-edit">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/edit-button.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Edit Button</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    The <guilabel>Edit Button</guilabel> calls an external program to edit the most recently
                                    captured frame in &sf-cap; mode or the current video in &mf-cap; mode. <application>&app;</application> does not
                                    provide those applications. By default, <application>&app;</application> calls <application>gimp</application> in
                                    &sf-cap; mode and nothing at all in &mf-cap; mode. Both settings can be changed through
                                    the <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-cmd">preferences dialog</ulink>.
                                </para>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
    
        </sect2>

        <sect2 id="xvidcap-menu">

            <title>Main Menu</title>
            <para>A right-click on the filename display pops up the following menu:</para>

            <figure id="xvidcap-menu-screenshot">
                <title>Main Menu</title>
                <screenshot>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="figures/menu.png" format="PNG"/>
                        </imageobject>
                        <textobject> <phrase>Main Menu</phrase>
                        </textobject>
                    </mediaobject>
                </screenshot>
            </figure>

            <table frame="all" id="xvidcap-menu-TBL">
                <title>
                    the main menu's items: 
                </title>
                <tgroup cols="2" align="char" charoff="50" char=".">
                    <tbody>
                        <row id="xvidcap-menu-TBL-prefs">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/menu-prefs.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Preferences Menuitem</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    open the preferences dialog
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-menu-TBL-save-prefs">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/menu-save-prefs.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Save Preferences Menuitem</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    save the current settings
                                </para>
                                <tip>
                                    <title>Volatile Settings</title>
                                    <para>
                                        Note that <application>&app;</application> does not save changed preferences automatically. You can
                                        modify settings, exit <application>&app;</application>, and return to your previous settings by just
                                        restarting <application>&app;</application>. If you want to make changes to your settings persistent,
                                        select this. It will write your settings to a file <filename>.xvidcaprc</filename>
                                        in your home directory.
                                    </para>
                                </tip>
                            </entry>
                        </row>
                        <row id="xvidcap-menu-TBL-mf">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/menu-mf.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Multi-Frame Menuitem</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    select multi-frame capture mode
                                </para>
                                <tip>
                                    <title>Parallel Settings for Capture Modes</title>
                                    <para>
                                        Keep in mind that you can have distinct settings for &mf-cap; and &sf-cap; 
                                        modes configured and stored in parallel. Choosing this menuitem or the next
                                        toggles between the two modes and their respective settings.
                                    </para>
                                </tip>
                            </entry>
                        </row>
                        <row id="xvidcap-menu-TBL-sf">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/menu-sf.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Single-Frame Menuitem</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    select single-frame capture mode
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-menu-TBL-autocontinue">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/menu-cont.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Autocontinue Menuitem</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    toggle autocontinue feature on/off
                                </para>
                                <para>
                                    This is selectable only in &mf-cap; mode
                                    and only if the filename is mutable. Refer to 
                                    <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-autocontinue">the autocontinue prefernces
                                    setting</ulink> for more information.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-menu-TBL-show-frame">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/menu-show-frame.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Show Frame</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    show frame around capture area (yes/no)
                                </para>
                                <para>
				    If this is unchecked, the frame around the area to capture is hidden.
                                </para>
                                <tip>
                                    <title>Hiding frame around the area to capture</title>
                                    <para>
					This is esp. helpful, if you are running a compositing window manager
					like compiz and use effects which make the capture frame lag behind
					the movement of the area to capture (e. g. wobbly windows). In such
					a case the lagging frame parts may move inside the area to capture
					ending up visible in the finished video.
				    </para>
				    <para>
					The cleaner solution, however, is to disable the effect for windows
					of class "Xvidcap". That makes hiding the frame unnecessary.
                                    </para>
                                </tip>
                            </entry>
                        </row>
                        <row id="xvidcap-menu-TBL-make-video">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/menu-make-video.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Make Video Menuitem</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    execute encoding command set in preferences
                                </para>
                                <para>
                                    In &mf-cap; mode this is not at all
                                    needed and not set by default. It can, however, be set to allow executing a custom
                                    transcoding command if output is needed in a format other than <application>&app;</application> can generate.
                                    The script used in &sf-cap; mode by default is provided by <application>&app;</application> but may need to be
                                    copied to your executable path to make it available. Refer to 
                                    <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-cmd">the commands
                                    preferences tab</ulink> for more information on setting encoding commands.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-menu-TBL-animate">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/menu-animate.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Animate/Play Menuitem</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    execute playback command set in preferences
                                </para>
                                <para>
                                    In &mf-cap; mode this is <application>mplayer</application>
                                    and <application>animate</application> (part of ImageMagick) by default. Refer to 
                                    <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-cmd">the commands
                                    preferences tab</ulink> for more information on setting encoding commands.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-menu-TBL-help">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/menu-help.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Help Menuitem</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    pop up online help
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-menu-TBL-about">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/menu-about.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>About Menuitem</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    pop up <application>&app;'s</application> about dialog
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-menu-TBL-quit">
                            <entry>
                                <screenshot>
                                    <mediaobject>
                                        <imageobject>
                                            <imagedata fileref="figures/menu-quit.png" format="PNG"/>
                                        </imageobject>
                                        <textobject> <phrase>Quit Menuitem</phrase>
                                        </textobject>
                                    </mediaobject>
                                </screenshot>
                            </entry>
                            <entry>
                                <para>
                                    exit <application>&app;</application>
                                </para>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>

        </sect2>
    </sect1>
    
    <sect1 id="xvidcap-prefs">
        <title>Preferences</title>
    
        <para>
            You can start the Preferences dialog either by right-clicking on the main control's
            filename display and selecting <quote>Preferences</quote> or pressing CTRL-P. The
            dialog itself is divided into four tabs.
        </para>

        <sect2 id="xvidcap-prefs-general">
            <title>General Preferences</title>

            <para>
                The first tab of the preferences dialog contains miscellaneous settings around
                general behaviour of <application>&app;</application>.
            </para>

            <figure id="xvidcap-prefs-general-screenshot">
                <title>General Preferences</title>
                <screenshot>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="figures/prefs-general.png" format="PNG"/>
                        </imageobject>
                        <textobject> <phrase>General Preferences</phrase>
                        </textobject>
                    </mediaobject>
                </screenshot>
            </figure>

            <table frame="all" id="xvidcap-prefs-general-TBL">
                <title>
                    the general settings are: 
                </title>
                <tgroup cols="2" align="char" charoff="50" char=".">
                    <tbody>
                        <row id="xvidcap-prefs-general-TBL-dflt-mode">
                            <entry>
                                <para>
                                    Default Capture Mode
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    This setting governs which capture mode is used by <application>&app;</application> by default, i. e. if
                                    no other settings give <application>&app;</application> a clue.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-TBL-cap-mouse">
                            <entry>
                                <para>
                                    Capture Mouse Pointer
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Check this to capture the mouse pointer.
                                </para>
                                <caution>
                                    <title>Custom Mouse Pointer Shapes</title>
                                    <para>
					Without the XFixes extension to X11, there is no way for <application>&app;</application> to 
                                    	capture the real, current mouse pointer, only its position. If the extension is not available both
					on the machine where <application>&app;</application> was built and where it is run, 
					<application>&app;</application> generates a dummy mouse pointer in the captured movie.
					In this case you will find a radiobutton next to this checkbox which
					allows you to select whether the dummy pointer should be white or black.
                                    </para>
                                </caution>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-TBL-save-cap-geometry">
                            <entry>
                                <para>
                                    Save Capture Geometry
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Check this if you want to store size and position of the currently 
                                    selected area to capture along with other preferences on selecting
                                    <quote>Save Preferences</quote> from the main menu.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-TBL-frame-follows-mouse">
                            <entry>
                                <para>
                                    Capture Area Follows Mouse
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Check this if you want a locked frame to follow the mousepointer's
				    movement rather than that of the main control windows.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-TBL-hide-frame">
                            <entry>
                                <para>
                                    Hide Frame
                                </para>
                            </entry>
                            <entry>
                                <para>
				    Check this if you want the frame around the area to capture to be
				    hidden. See the <ulink type="help" url="ghelp:xvidcap?xvidcap-menu-TBL-show-frame">Show Frame</ulink>
				    menu item for more information, but notice that this works the other 
				    way around, i. e. a check hides the frame.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-TBL-use-shm">
                            <entry>
                                <para>
                                    Use Shared Memory
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Check this if capturing frames should make use of X11's shared
                                    memory extension.
                                </para>
                                <caution>
                                    <title>Shared Memory X11 Access</title>
                                    <para>
                                        Use of shared memory is enabled by default if the machine where
                                        <application>&app;</application> was built supported shared memory access in X11, which is
                                        typically the case, nowadays. You will need to turn this off, however, if
                                        X11 server and client are not running on the same machine, e. g. 
                                        if you are on a X terminal thin client.
                                    </para>
                                </caution>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-TBL-set-xdamage">
                            <entry>
                                <para>
                                    Manually Set XDamage
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Check this if you want to override the decision <application>&app;</application> makes
				    about whether or not to use the XDamage extension to speed up screen capture. This 
				    extension allows <application>&app;</application> to be notified about the portions
				    of the screen that have changed between individual frames, so it does not need to 
				    fetch the complete area to capture for every frame. <application>&app;</application> will
				    default to using XDamage if it was available at build-time, if it is available at
				    runtime, and if the window manager used is not compiz or beryl. If you are using
				    beryl and still want to use the XDamage extension, check this control to enable the
				    radiobuttons to the right and choose "enabled".
                                </para>
                                <caution>
                                    <title>XDamage and compiz or beryl</title>
                                    <para>
					Due to the advanced visual effects possible with compiz, beryl and the likes,
					the notifications received by <application>&app;</application> through XDamage
					may not be sufficient for determining the right screen portions to capture.
					You can still force <application>&app;</application> to use it as described
					above, but your mileage may vary.
                                    </para>
                                </caution>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-TBL-autocontinue">
                            <entry>
                                <para>
                                    Autocontinue
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    If recording in &mf-cap; mode and using a maximum number of frames to 
                                    capture or a maximum capture duration, <application>&app;</application> can automatically continue
                                    capturing to a new video once the specified maximum number of frames or
                                    capture duration have been reached. This can effectively create a series
                                    of movies split to chunks of the specified maximum length. To use this
                                    you need to specify a <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-sf-TBL-file-name">mutable target filename</ulink>.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-TBL-always-show-results">
                            <entry>
                                <para>
                                    Always Show Results Dialog
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Check this to always show a dialog with an overview of capture results
                                    on stopping a capture session. The dialog will always be shown if 
                                    required (e. g. to specify a target filename). This makes the dialog
                                    be shown where it would not strictly be required. By default the results
                                    dialog is always displayed. If, however, you have unchecked the 
                                    <quote>Show this dialog next time</quote> in the results dialog before,
                                    you can turn it back on here.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-TBL-minimize-to-tray">
                            <entry>
                                <para>
                                    Minimize to System Tray
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Check this to make <application>&app;</application> minimize to the
				    system tray on starting a recording session. In that case the main
				    control panel will hide and the frame drop monitor will apear in the
				    system tray. A right-click on it will allow you to pause or stop the
				    recording session. On stopping the main control window will be
				    displayed again.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-TBL-rescale">
                            <entry>
                                <para>
                                    Rescale Output Percentage
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Use this to make the output video smaller than the original size of the
                                    portion of the screen captured. The percentage specified here is the 
                                    size of the output relative to the input. For example, specifying
                                    <quote>25</quote> will make the output width and height half the 
                                    original each. Thus the image size of the output will be 25 percent of
                                    the captured area.
                                </para>
                                <caution>
                                    <title>Rescale does not work with XWD output</title>
                                    <para>
					Rescaling output frames does work with all output formats and codecs
					other than XWD.
                                    </para>
                                </caution>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect2>

        <sect2 id="xvidcap-prefs-sf">
            <title>Single-Frame Capture Preferences</title>

            <para>
                This tab contains the settings for &sf-cap; mode. Because &sf-cap; mode does
                not support audio capture, only video settings are configurable here.
            </para>

            <figure id="xvidcap-prefs-sf-screenshot">
                <title>Single-Frame Capture Preferences</title>
                <screenshot>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="figures/prefs-sf.png" format="PNG"/>
                        </imageobject>
                        <textobject> <phrase>Single-Frame Capture Preferences</phrase>
                        </textobject>
                    </mediaobject>
                </screenshot>
            </figure>

            <table frame="all" id="xvidcap-prefs-sf-TBL">
                <title>
                    the &sf-cap; mode settings are: 
                </title>
                <tgroup cols="2" align="char" charoff="50" char=".">
                    <tbody>
                        <row id="xvidcap-prefs-sf-TBL-file-name">
                            <entry>
                                <para>
                                    File Name
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Enter a file name pattern here to use for saving the individual
                                    frames captured. The file name must contain a pattern that will
                                    be replaced by the actual frame count for each individual file.
                                    The patterns used here are those understood by 
                                    <ulink type="help" url="man:fprintf">fprintf</ulink>. 
                                    A file name containing this kind of pattern will henceforth be
                                    called a <quote>mutable</quote> file name.
                                </para>
                                <tip>
                                    <title>File Name Selection</title>
                                    <para>
                                        Instead of typing in a filename you can also click on the file
                                        selector button (<guibutton>...</guibutton>). Be sure to put a
                                        numeric pattern in the file name afterwards, though. If in 
                                        doubt use <quote>%5d</quote> somewhere in your file name.
                                    </para>
                                </tip>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-sf-TBL-format">
                            <entry>
                                <para>
                                    File Format
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    A check in the <guilabel>auto</guilabel> checkbox makes <application>&app;</application>
                                    automatically select an appropriate output format based on the
                                    filename specified. For example, if you specify <quote>test-%4d.png</quote>
                                    the output format will be <quote>Portable Network Graphics File (png)</quote>.
                                    If the <guilabel>auto</guilabel> checkbox is unchecked, the dropdown
                                    menu allows for manually selecting a format, possibly overriding 
                                    <application>&app;'s</application> decision.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-sf-TBL-fps">
                            <entry>
                                <para>
                                    Frames per Second
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    The number of frames to capture per second.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-sf-TBL-max-time">
                            <entry>
                                <para>
                                    Maximum Time
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Maximum time to record in seconds
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-sf-TBL-max-frames">
                            <entry>
                                <para>
                                    Maximum Frames
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Maximum frames to capture
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-sf-TBL-frame-start">
                            <entry>
                                <para>
                                    Frame Start Number
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Start counting frames with this number
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-sf-TBL-frame-increment">
                            <entry>
                                <para>
                                    Frame Number Increment
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    When capturing increment the frame count by the specified number
                                    for each frame captured.
                                </para>
                                <caution>
                                    <title>Deprecated Settings</title>
                                    <para>
                                        Due to the limited use of <quote>Frame Start Number</quote> and
                                        <quote>Frame Number Increment</quote> those settings may go away
                                        in future versions.
                                    </para>
                                </caution>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-sf-TBL-quality">
                            <entry>
                                <para>
                                    Quality
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Desired output quality
                                </para>
                                <caution>
                                    <title>Quality Setting changed in 1.1.5</title>
                                    <para>
					The effect of setting quality to a value below 100 % has changed in
					<application>&app;</application> 1.1.5. Be sure to test the values
					in your stored preferences. Quality settings do not apply to XWD
					output.
                                    </para>
                                </caution>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect2>

        <sect2 id="xvidcap-prefs-mf">
            <title>Multi-Frame Capture Preferences</title>

            <para>
                This tab contains the settings for &mf-cap; mode.
            </para>

            <figure id="xvidcap-prefs-mf-screenshot">
                <title>Multi-Frame Capture Preferences</title>
                <screenshot>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="figures/prefs-mf.png" format="PNG"/>
                        </imageobject>
                        <textobject> <phrase>Multi-Frame Capture Preferences</phrase>
                        </textobject>
                    </mediaobject>
                </screenshot>
            </figure>

            <table frame="all" id="xvidcap-prefs-mf-TBL">
                <title>
                    the &mf-cap; mode video settings are: 
                </title>
                <tgroup cols="2" align="char" charoff="50" char=".">
                    <tbody>
                        <row id="xvidcap-prefs-mf-TBL-file-name">
                            <entry>
                                <para>
                                    File Name
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Enter a file name or file name pattern here to use for saving the individual
                                    frames captured. For &mf-cap; the string supplied here only needs to be
                                    a <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-sf-TBL-file-name">mutable filename</ulink> 
                                    if the <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-autocontinue">autocontinue feature</ulink>
                                    is to be used. Otherwise a simple filename is sufficient here, which may also be
                                    selected through the file selector button (<guibutton>...</guibutton>).
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-mf-TBL-format">
                            <entry>
                                <para>
                                    File Format
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    A check in the <guilabel>auto</guilabel> checkbox makes <application>&app;</application>
                                    automatically select an appropriate output format based on the
                                    filename specified. For example, if you specify <quote>test.avi</quote>
                                    the output format will be <quote>Microsoft Audio Video Interleaved File (avi)</quote>.
                                    If the <guilabel>auto</guilabel> checkbox is unchecked, the dropdown
                                    menu allows for manually selecting a format, possibly overriding 
                                    <application>&app;'s</application> decision.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-mf-TBL-vid-codec">
                            <entry>
                                <para>
                                    Video Codec
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    A check in the <guilabel>auto</guilabel> checkbox makes <application>&app;</application>
                                    automatically select an appropriate video codec for the output format selected.
                                    For example, if <quote>Microsoft Audio Video Interleaved File (avi)</quote> is
                                    selected the video codec will be <quote>Microsoft DIVX 2</quote>.
                                    If the <guilabel>auto</guilabel> checkbox is unchecked, the dropdown
                                    menu allows for manually selecting a codec, possibly overriding 
                                    <application>&app;'s</application> decision.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-mf-TBL-fps">
                            <entry>
                                <para>
                                    Frames per Second
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    The number of frames to capture per second. This control can either be 
                                    a scale or a dropdown menu, if the selected codec only supports certain
                                    frame rates.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-mf-TBL-max-time">
                            <entry>
                                <para>
                                    Maximum Time
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Maximum time to record in seconds
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-mf-TBL-max-frames">
                            <entry>
                                <para>
                                    Maximum Frames
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Maximum frames to capture
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-mf-TBL-quality">
                            <entry>
                                <para>
                                    Quality
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Desired output quality
                                </para>
                                <caution>
                                    <title>Quality Setting changed in 1.1.5</title>
                                    <para>
					The effect of setting quality to a value below 100 % has changed in
					<application>&app;</application> 1.1.5. Be sure to test the values
					in your stored preferences. In the past a quality setting of <quote>20</quote>
					could yield good results depending on the codec chosen. This is no longer
					the case. A setting of <quote>75</quote> may be acceptable to you, a
					value of <quote>85</quote> will typically be. A video resulting from a
					capture with a quality setting of <quote>90</quote> will not normally
					be easy to distinguish from one captured at <quote>100</quote> percent
					quality.
                                    </para>
                                </caution>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>

            <table frame="all" id="xvidcap-prefs-mf-TBL-audio">
                <title>
                    the &mf-cap; mode audio settings are: 
                </title>
                <tgroup cols="2" align="char" charoff="50" char=".">
                    <tbody>
                        <row id="xvidcap-prefs-mf-TBL-audio-enable">
                            <entry>
                                <para>
                                    Enable Audio
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Check this to capture audio along with video frames.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-mf-TBL-audio-device">
                            <entry>
                                <para>
                                    Input Device
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Type in the name of the input device to caputer audio from or
                                    select it through the file selector button (<guibutton>...</guibutton>).
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-mf-TBL-audio-codec">
                            <entry>
                                <para>
                                    Audio Codec
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    A check in the <guilabel>auto</guilabel> checkbox makes <application>&app;</application>
                                    automatically select an appropriate audio codec for the video output format selected.
                                    For example, if <quote>Microsoft Audio Video Interleaved File (avi)</quote> is
                                    selected the audio codec will be <quote>MPEG2</quote>.
                                    If the <guilabel>auto</guilabel> checkbox is unchecked, the dropdown
                                    menu allows for manually selecting a codec, possibly overriding 
                                    <application>&app;'s</application> decision.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-mf-TBL-audio-smpl-rate">
                            <entry>
                                <para>
                                    Sample Rate
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Audio sample rate. If you're using piped input audio the audio stream
                                    is resampled to the specified rate if required.
                                </para>
                                <tip>
                                    <title>Piped Audio Input</title>
                                    <para>
                                        Instead of capturing audio from a real-time audio source, you can
                                        also pipe a pre-recorded audio file to <application>&app;</application>. This way you can
                                        effectively dub your recording with a given audio track. To do
                                        this you need to:
                                    </para>
                                    <para>
                                        <application>cat</application> my.mp3 | <application>&app;</application>
                                        <parameter>--mf</parameter> <parameter>--audio yes</parameter>
                                        <parameter>--audio_in -</parameter> <parameter>--file test.avi</parameter>
                                    </para>
                                    <para>
                                        When you start the recording session in <application>&app;</application> it will sample audio
                                        from the piped file.
                                    </para>
                                </tip>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-mf-TBL-audio-bit-rate">
                            <entry>
                                <para>
                                    Bit Rate
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Audio bit rate. If you're using piped input audio the audio stream
                                    is resampled to the specified rate if required.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-mf-TBL-audio-channels">
                            <entry>
                                <para>
                                    Channels
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    Number of audio channels. If you're using piped input audio the audio stream
                                    is resampled to the specified number of channels if required.
                                </para>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>

        </sect2>

        <sect2 id="xvidcap-prefs-cmd">
            <title>Command Preferences</title>

            <para>
                This tab contains various settings regarding which commands to execute
                for certain actions.
            </para>

            <figure id="xvidcap-prefs-cmd-screenshot">
                <title>Command Preferences</title>
                <screenshot>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="figures/prefs-commands.png" format="PNG"/>
                        </imageobject>
                        <textobject> <phrase>Command Preferences</phrase>
                        </textobject>
                    </mediaobject>
                </screenshot>
            </figure>

            <table frame="all" id="xvidcap-prefs-cmd-TBL">
                <title>
                    possible commands to set are: 
                </title>
                <tgroup cols="2" align="char" charoff="50" char=".">
                    <tbody>
                        <row id="xvidcap-prefs-cmd-TBL-sf-playback">
                            <entry>
                                <para>
                                    Single Frame Playback Command
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    The command specified here is executed when the item <guimenuitem>Animate / Play</guimenuitem>
                                    is selected from the main menu or the play button is pressed on the capture
                                    results dialog while in &sf-cap; mode. 
                                </para>
                                <tip>
                                    <title>Specifying Commands</title>
                                    <para>
                                        Any command can be configured here. It could theoretically be
                                        completely unrelated to video capture. You will always want to
                                        make sure that the called application is in your path and that
                                        you end your command line with the <application>&amp;</application> to avoid that <application>&app;</application>
                                        waits for the called application to finish before continuing
                                        itself.
                                    </para>
                                    <para>
                                        <application>&app;</application> makes the following environment variables available to
                                        the called application:
                                    </para>
                                    <table frame="non" id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL">
                                        <tgroup cols="2" align="char" charoff="50" char=".">
                                            <tbody>
                                                <row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-fframe">
                                                    <entry>
                                                        <para>
                                                            XVFFRAME
                                                        </para>
                                                    </entry>
                                                    <entry>
                                                        <para>
                                                            number of the first frame captured
                                                        </para>
                                                    </entry>
                                                </row>
                                                <row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-lframe">
                                                    <entry>
                                                        <para>
                                                            XVLFRAME
                                                        </para>
                                                    </entry>
                                                    <entry>
                                                        <para>
                                                            number of the last frame captured
                                                        </para>
                                                    </entry>
                                                </row>
                                                <row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-width">
                                                    <entry>
                                                        <para>
                                                            XVWIDTH
                                                        </para>
                                                    </entry>
                                                    <entry>
                                                        <para>
                                                            width of the area captured
                                                        </para>
                                                    </entry>
                                                </row>
                                                <row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-height">
                                                    <entry>
                                                        <para>
                                                            XVHEIGHT
                                                        </para>
                                                    </entry>
                                                    <entry>
                                                        <para>
                                                            height of the area captured
                                                        </para>
                                                    </entry>
                                                </row>
                                                <row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-fps">
                                                    <entry>
                                                        <para>
                                                            XVFPS
                                                        </para>
                                                    </entry>
                                                    <entry>
                                                        <para>
                                                            desired (!) frame rate
                                                        </para>
                                                    </entry>
                                                </row>
                                                <row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-time">
                                                    <entry>
                                                        <para>
                                                            XVTIME
                                                        </para>
                                                    </entry>
                                                    <entry>
                                                        <para>
                                                            desired (!) time per frame
                                                        </para>
                                                    </entry>
                                                </row>
                                                <row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-filename">
                                                    <entry>
                                                        <para>
                                                            XVFILE
                                                        </para>
                                                    </entry>
                                                    <entry>
                                                        <para>
                                                            file name
                                                        </para>
                                                    </entry>
                                                </row>
                                            </tbody>
                                        </tgroup>
                                    </table>
                                    <para>
                                        The file name, however, needs special treatment for &sf-cap;. Here the 
                                        pattern used for <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-sf-TBL-file-name">mutable file names</ulink>
                                        is sent literally as specified for the Single Frame Encoding Command further down only.
                                        For the Single Frame Playback Command the pattern is converted to wildcards, i. e.
                                        <quote>test-%4d.png</quote> becomes <quote>test-????.png</quote>. For the
                                        Single Frame Edit Command the pattern is replaced with the number of the
                                        current frame, i. e. <quote>test-%4d.png</quote> becomes <quote>test-0001.png</quote>.
                                        For all Multi Frame commands the latter is used where if the filename is mutable
                                        and the number used is the index number of the most recently recorded video as
                                        with the <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-autocontinue">autocontinue feature</ulink>.
                                    </para>
                                </tip>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-cmd-TBL-sf-encode">
                            <entry>
                                <para>
                                    Single Frame Encoding command
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    The command here is executed when the main menu's <guimenuitem>Make Video</guimenuitem> 
                                    item is selected while in &sf-cap; mode.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-cmd-TBL-sf-edit">
                            <entry>
                                <para>
                                    Single Frame Edit Command
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    The command here is executed when the main control's <guibutton>Edit Button</guibutton>
                                    is clicked while in &sf-cap; mode.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-cmd-TBL-mf-playback">
                            <entry>
                                <para>
                                    Multi Frame Playback Command
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    The command specified here is executed when the item <guimenuitem>Animate / Play</guimenuitem>
                                    is selected from the main menu or the play button is pressed on the capture
                                    results dialog while in &mf-cap; mode. 
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-cmd-TBL-mf-encode">
                            <entry>
                                <para>
                                    Multi Frame Transcoding command
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    The command here is executed when the main menu's <guimenuitem>Make Video</guimenuitem> 
                                    item is selected while in &mf-cap; mode.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-prefs-cmd-TBL-mf-edit">
                            <entry>
                                <para>
                                    Multi Frame Edit Command
                                </para>
                            </entry>
                            <entry>
                                <para>
                                    The command here is executed when the main control's <guibutton>Edit Button</guibutton>
                                    is clicked while in &mf-cap; mode.
                                </para>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect2>
    </sect1>
    
    <sect1 id="xvidcap-results">
        <title>Capture Results Dialog</title>
    
        <para>
            When you first stop a recording session, a dialog will pop up displaying
            the results of the capture session. This popup can be prevented from
            appearing again by unchecking the <guibutton>Show Next Time</guibutton>
            checkbox or <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-always-show-results">this button</ulink>
            in the preferences dialog.
        </para>
        <para>
            The dialog itself can take one of two forms depending on whether or not
            you configured <application>&app;</application> to ask you for a target file name after the capture.
        </para>
        <tip>
            <title>Ask User For File Name</title>
            <para>
                For the time being, the only way to configure <application>&app;</application> to ask the user
                to specify a file name after the capture rather than providing one
                up-front it by providing an empty file name either through the
                command line using <parameter>--file ""</parameter> or in the preferences
                dialog. This requires manually specifying an output file format.
                In this configuration <application>&app;</application> will store the video in a temporary file
                in your home directory which can lateron be renamed / moved to the
                desired destination. This is not compatible with autocontinue.
            </para>
        </tip>

        <para>
            If <application>&app;</application> is configured to ask the user for a file name, the results dialog
            will look like this:
        </para>
        <figure id="xvidcap-results-ask-screenshot">
            <title>Capture Results Dialog with Ask User For File name</title>
            <screenshot>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="figures/results-dialog-ask.png" format="PNG"/>
                    </imageobject>
                    <textobject> <phrase>Capture Results Dialog with Ask User For File name</phrase>
                    </textobject>
                </mediaobject>
            </screenshot>
        </figure>

        <para>
            Besides the overview of the used settings and information about the desired
            and achieved frame rates, you can select name and location of the file you
            want the video to be stored in through clicking <guibutton>Save As</guibutton>. 
            Once a file has been selected, the label next to the button will display the
            absolute file name. You can also choose to preview the video through
            <guibutton>Play</guibutton> or abandon it through <guibutton>Delete</guibutton>.
            Note that the latter does not immediately delete the temporary file, though.
        </para>

        <para>
            Normally, the results dialog will look like this:
        </para>
        <figure id="xvidcap-results-screenshot">
            <title>Normal Capture Results Dialog</title>
            <screenshot>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="figures/results-dialog.png" format="PNG"/>
                    </imageobject>
                    <textobject> <phrase>Normal Capture Results Dialog</phrase>
                    </textobject>
                </mediaobject>
            </screenshot>
        </figure>

    </sect1>
    
    <sect1 id="xvidcap-warning">
        <title>The Preferences Warning Dialog</title>
        <para>
            Whenever <application>&app;</application> determines that the settings you have chosen will
            not work well, it will display those issues in a standardized format. Unless you run
            <application>&app;</application> with the <parameter>--gui no</parameter> parameter,
            it will pop up the following dialog:
        </para>

            <figure id="xvidcap-warn-window">
                <title>Preferences Warning Dialog</title>
                <screenshot>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="figures/xvidcap-warning.png" format="PNG"/>
                        </imageobject>
                        <textobject> <phrase>Preferences Warning Dialog</phrase>
                        </textobject>
                    </mediaobject>
                </screenshot>
            </figure>

        <tip>
            <title>GUI-less operation</title>
            <para>
                When running from the command line with the <parameter>--gui no</parameter> parameter,
                those warnings will be displayed in plain text on the terminal. You will not be seeing the
                <quote>Details</quote> section unless you also specified <parameter>-v</parameter>.
            </para>
        </tip>

            <table frame="all" id="xvidcap-warn-situations-TBL">
                <title>
                    There are a few situations in which such messages can be displayed:
                </title>
                <tgroup cols="2" align="char" charoff="50" char=".">
                    <tbody>
                        <row id="xvidcap-warn-situations-TBL-start">
                            <entry>
                                <para>On start</para>
                            </entry>
                            <entry>
                                <para>
                                    When <application>&app;</application> is started, it checks the 
                                    consistency of the settings for the current capture mode and will
                                    report on issues it finds there. You will not be able to cancel out
                                    of this dialog, but have to revisit your preferences.
                                </para>
                                <para>
                                    <application>&app;</application> <emphasis>only</emphasis>
                                    checks on the current capture mode and will not care
                                    about inconsistencies with the respective other mode. Therefore,
                                    there is the second situation.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-warn-situations-TBL-change-mode">
                            <entry>
                                <para>On change of capture mode</para>
                            </entry>
                            <entry>
                                <para>
                                    If you change the current capture mode through the 
                                    <ulink type="help" url="ghelp:xvidcap?menu xvidcap-menu-TBL-mf">menu</ulink> 
                                    <application>&app;</application> will check the consistency of the settings 
                                    for the new capture mode and will report on issues it finds there. If you 
                                    cancel the warning dialog, you will return to your previous capture mode
                                    selection.
                                </para>
                            </entry>
                        </row>
                        <row id="xvidcap-warn-situations-TBL-preferences">
                            <entry>
                                <para>When submitting changed preferences</para>
                            </entry>
                            <entry>
                                <para>
                                    When you leave the preferences dialog <application>&app;</application> 
                                    will check the settings for both capture modes. Cancelling the warning
                                    dialog will take you back to the preferences dialog.
                                </para>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>

            <para>
                In the Preferences Warning Dialog you will find one or more messages consisting of three
                rows each. The first one contains a message type or severity, a unique numeric ID and a 
                short name for the error. The second row gives a more detailed description, and the third
                one tells about the action <application>&app;</application> is going to take if you
                chose to click <guibutton>OK</guibutton>.
            </para>

            <para>
                Such an action might be to automatically correct the issue by chosing a plausible default,
                to ignore the issue if it is not severe or to quit <application>&app;</application> if no
                solution can automatically be determined.
            </para>

            <para>
                The severity of an issue can be <quote>INFO</quote> for purely informational messages
                where no change is made to any settings, <quote>WARNING</quote> where a minor change
                to current settings is suggested, <quote>ERROR</quote> where a major change to current
                settings is required, or <quote>FATAL ERROR</quote>. A fatal error is always an error
                where the suggested action is to quit <application>&app;</application>. You will not
                see issues of severity <quote>INFO</quote> unless you run <application>&app;</application>
                in verbose mode.
            </para>
    </sect1>




    <!--    
    <sect1 id="c1-s1">
    <title>section 1</title>
    <para>may or may not exist</para>

    <example>
    <title>sample command line session</title>
    <screen id="sc1">
    <prompt>$</prompt> <userinput>ncftp ftp://ftp.cygnus.com/pub/home/rosalia/</userinput>
    <prompt>ncftp></prompt> <userinput>cd docware/RPMS/i386/</userinput>
    <prompt>ncftp></prompt> <userinput>mget *.rpm</userinput>
    <prompt>ncftp></prompt> <userinput>quit</userinput>
    </screen>	    
    </example>
	    
    <tip>
    <title>sample tip with parameters</title>		
    <para>
    sample parameter details 
    To validate DocBook without displaying the document, add the
    argument <parameter class="option">-noout</parameter> to the
    <application>xmllint</application> command.
    </para>	    
    </tip>
	    
    <example id="ex1">
    <title>A simple C program</title>
    <programlisting role="C">
    #include &lt;stdio.h&gt;
    main()
    {
    printf("Hello, world!\n");
    }
    </programlisting>
    </example>	    
	       
    <figure id="app-FIG-shot1">
    <title>Screenshot</title>
    <screenshot>
    <mediaobject>
    <imageobject>
    <imagedata fileref="figures/example_screenshot.png" format="PNG"/>
    </imageobject>
    <textobject>
    <phrase>Shows the application screenshot with several buttons.</phrase>
    </textobject>
    <caption>
    <para>Screenshot of a program</para>
    </caption>
    </mediaobject>
    </screenshot>
    </figure>	    
	    
	    
    </sect1>
    <sect1 id="a1-s1">
    <title>doinker</title>
    <para>this is an <emphasis>example</emphasis></para>
	    
    <table frame="all">
    <title>Convergence of dynamical equations and constraints for
    various choices of constrained edges</title>
    <tgroup cols="5" align="char" charoff="50" char=".">
    <thead>
    <row>
    <entry>Constrained edges</entry>
    <entry>Model</entry>
    <entry># of iter.</entry>
    <entry>E <subscript>i</subscript><superscript>2</superscript></entry>
    <entry>C <subscript>i</subscript><superscript>2</superscript></entry>
    </row>
    </thead>
    <tbody>
    <row>
    <entry>AD, AF, AG, AA'</entry>
    <entry>Flat space</entry>
    <entry>5</entry>
    <entry>1.15<superscript>-24</superscript></entry>
    <entry>1.77<superscript>-19</superscript></entry>
    </row>
    <row>
    <entry>AD, AF, AG, AA'</entry>
    <entry>Kasner universe</entry>
    <entry>6</entry>
    <entry>1.43<superscript>-19</superscript></entry>
    <entry>1.77<superscript>-8</superscript></entry>
    </row>
    <row>
    <entry>AB, AC, AE, AA'</entry>
    <entry>Flat space</entry>
    <entry>4</entry>
    <entry>1.15<superscript>-24</superscript></entry>
    <entry>4.09<superscript>-24</superscript></entry>
    </row>
    <row>
    <entry>AB, AC, AE, AA'</entry>
    <entry>Kasner universe</entry>
    <entry>7</entry>
    <entry>1.33<superscript>-19</superscript></entry>
    <entry>8.07<superscript>-7</superscript></entry>
    </row>
    </tbody>
    </tgroup>
    </table>
	    
    </sect1>
    -->    
</article>
