<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
 "/usr/share/xml/docbook/schema/dtd/4.3/docbookx.dtd"
[
<!ENTITY % vers   SYSTEM "version.xml">
<!ENTITY trelby "<application>Trelby</application>">
%vers;
]>

<book id="trelby-manual" lang="en">
  <title>Trelby Manual</title>

  <subtitle>Version &trelby.version;</subtitle>

  <bookinfo>

    <authorgroup>
	  <corpauthor>Trelby developers</corpauthor>
    </authorgroup>

    <copyright>
      <year>2012</year>
      <holder>Trelby developers</holder>
    </copyright>

  </bookinfo>

  <chapter>
	<title>Introduction</title>

	<para>This is the manual for the &trelby; screenwriting software. This
	version of the manual corresponds to version &trelby.version; of the
	software.</para>

	<sect1>
	  <title>Basic concepts</title>

	  <para>If you don't know anything about writing a screenplay, get a
	  copy of a book such as David Trottier's "The Screenwriter's Bible".
	  This manual will not cover the same ground, but focuses on concepts
	  specific to &trelby;.</para>

	  <para>&trelby; divides a screenplay into a long list of elements,
	  each with a specific <emphasis>element style</emphasis>. The
	  available element styles are:</para>

	  <variablelist>

		<varlistentry>
		  <term>Scene</term>
		  <listitem>

			<para>Scene header. Example: "INT. MOTEL ROOM - NIGHT".</para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Action</term>
		  <listitem>

			<para>Describes action. Example: "John grabs the gun from the
			desk."</para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Character</term>
		  <listitem>

			<para>A speaking character's name. Example: "HARRY".</para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Dialogue</term>
		  <listitem>

			<para>Speech. Example: "You could do that, sure. On the other
			hand, if you want to live beyond the next minute or so, you
			might want to rethink your approach."</para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Parenthetical</term>
		  <listitem>

			<para>Describes how the actor should say the following
			dialogue. Example: "(serious)".</para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Transition</term>
		  <listitem>

			<para>Describes a non-standard transition between scenes.
			Example: "DISSOLVE TO:".</para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Shot</term>
		  <listitem>

			<para>Describes an in-scene shot. Example: "THE
			NECKLACE".</para>

		  </listitem>
		</varlistentry>

        <varlistentry>
		  <term>Act break</term>
		  <listitem>

			<para>Defines an act (typically used in teleplays).
            Example: "ACT ONE" or "TEASER".
            </para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Note</term>
		  <listitem>

			<para>Note style is used to insert notes to yourself or to
			others about that part of the script. Example: "Should Bobby
			shoot first?".</para>

		  </listitem>
		</varlistentry>

	  </variablelist>

	</sect1>

  </chapter>

  <chapter>
	<title>Basic usage</title>

	<para>This chapter discusses basic usage of &trelby;.</para>

	<sect1>
	  <title>Main window</title>

	  <para>The main window has the following parts in it in top-to-bottom
	  order, after the standard menu bar:</para>

	  <variablelist>

		<varlistentry>
		  <term>Script tabs and status</term>
		  <listitem>

			<para>Each script gets its own tab, with the tab's name being
			the filename of each script. You can click on each tab to
			change the active script to that one, or the X at the end of
			each tab to close that tab.</para>

            <para>After tabs is a column showing the current element's
            style, a column showing what the Enter/Tab keys would do, and
            a column showing the current/total page number.</para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Main text area</term>
		  <listitem>

			<para>This is where the actual script is shown and
			edited.</para>

		  </listitem>
		</varlistentry>

	  </variablelist>

	</sect1>

	<sect1>
	  <title>Basic editing</title>

	  <sect2>
		<title>Moving around</title>

		<para>The usual movement keys are available: Up/Down/Left/Right to
		move around, Home/End to move to start/end of line, Page Up/Page
		Down to move up/down one page (actually one screenful), and CTRL +
		Home/End to move to start/end of script.</para>

		<para>CTRL + Up/Down moves one scene up or down.</para>

	  </sect2>

	  <sect2>
		<title>Deleting elements</title>

		<para>The Delete and Backspace keys delete text one character at a
		time. They also join elements to one another if pressed at,
		respectively, at the end or at the start of an element. The joined
		element will always have the style of the preceding
		element.</para>

	  </sect2>

	  <sect2 id="add_element">
		<title>Adding elements and changing their style</title>

		<para>The Enter key will always create a new element. If the
		cursor is at the end of an element, the new element will be an
		empty one, otherwise the current element is split at the cursor
		position.</para>

		<para>The Tab key will create a new element if the cursor is at
		the end of an element, otherwise it will switch the current
		element's style. Shift + Tab will always switch the element's
		style.</para>

		<para>What kind of element Enter/Tab/Shift + Tab will
		create/switch to is dependent on the current style of the element,
		and is configurable by the user (see <xref
		linkend="elements_gcfg"/>). These values for Enter/Tab are always
		shown to the right of the tab-bar.</para>

		<para>Other ways to change an element's style are right-clicking
		with the mouse which will show a menu where you can change the
		element's style, or pressing a short-cut key for each element
		style. Note that if you have selected text belonging to multiple
		elements, all of those elements' types will be changed.</para>

		<para>Shift + Enter or CTRL + Enter will insert a forced
		linebreak.</para>

	  </sect2>

	  <sect2>
		<title>Selecting text</title>

		<para>When selecting text, one end of the selection is always
		fixed and the other one moves around with the cursor. You can
		select text by clicking and dragging with the mouse (right-click
		unselects), or by pressing CTRL + Space which sets the fixed point
		of the selection at current position and then moving around, or by
		pressing some movement key together with Shift (e.g. Shift +
		Up).</para>

		<para>You can select the current scene with CTRL + A.</para>

		<para>After you've selected the desired text, you can use the
		cut/copy/paste commands to move text around, delete it, etc. You
		can also press Del or Backspace to simply delete it.</para>

		<para>You can unselect the selected text by pressing Esc., or simply
 		clicking the mouse on the screen.</para>

	  </sect2>

	  <sect2>
		<title>Auto-completion</title>

		<para>Auto-completion saves typing in scene / character /
		transition / shot elements by showing a list of other elements
		from the script that match the text in the current element. For
		example, if you've written the characters "MO" in a new character
		element, you'll see a list of all character elements that start
		with "MO" and if you want, you can select one of them and that
		text will complete the current element.</para>

		<para>The auto-completion list only appears after you've written
		at least one character. If you want to see a list of all possible
		choices, write a single character and delete it.</para>

		<para>You can move around in the list with the Up/Down/Page
		up/Page down keys. Pressing Enter will complete the text and start
		a new element, while pressing End will complete the text but will
		not start a new element. Pressing ESC will make the list go
		away.</para>

	  </sect2>

	  <sect2>
		<title>Miscellaneous</title>

		<para>When inserting a new empty parenthetical element, "()" will
		automatically be added to it and the cursor positioned in the
		middle. Likewise, when switching a parenthetical element to
		something else, if it only contains "()", it will be replaced by
		"" (empty). If you write a "(" in an empty dialogue or character
		element if will switch to a parenthetical element. If you press
		Enter or Tab at the ending ")" to start a new element, the ")"
		will stay in the parenthetical.</para>

		<para>If you write "EXT." or "INT." (case doesn't matter) at the
		start of any element, it will switch to a scene element
		automatically.</para>

	  </sect2>

	</sect1>

  </chapter>

  <chapter>
	<title>View modes</title>

	<para>This chapter describes the different view modes available. You
	can toggle between them using the View-menu or by keyboard
	shortcuts.</para>

	<sect1>
	  <title>Draft</title>

	  <para>In 'Draft' mode, the text area consists of an empty background
	  with the script's text drawn on top. This text includes only actual
	  script contents, so page headers, CONTINUED/(MORE) and other
	  automatically added texts are not shown at all. Page breaks, if
	  enabled, are shown as a horizontal line (see <xref
	  linkend="display_cfg"/>).</para>

	  <para>Reasons you might want to use this mode:</para>

	  <itemizedlist>

		<listitem>

		  <para>You want to see only actual words you've written, and not
		  be distracted by page-break related formatting.</para>

		</listitem>

		<listitem>

		  <para>Page breaks do not take space, so more lines fit onto the
		  screen.</para>

		</listitem>

		<listitem>

		  <para>It's the fastest view mode.</para>

		</listitem>

	  </itemizedlist>

	</sect1>

	<sect1>
	  <title>Layout</title>

	  <para>'Layout' mode shows an almost exact representation of the page
	  as it would appear when printed. Page borders, margins, headers,
	  CONTINUED/(MORE) and so on are all shown at their correct
	  places.</para>

	  <para>Ways in which the display in this mode can differ from the
	  printed output:</para>

	  <itemizedlist>

		<listitem>

		  <para>If pagination is not up-to-date, text around page breaks
		  can sometimes show in incorrect places. We recommend that when
		  using this mode, auto-pagination is kept on and the interval at
		  a low value, preferably 1 second (see <xref
		  linkend="misc_cfg"/>).</para>

		</listitem>

		<listitem>

		  <para>If you have scene continueds enabled, they will always
		  show as plain "CONTINUED:" on top of the page, whereas in the
		  PDF output, they will be "CONTINUED: (n)" if needed (see <xref
		  linkend="format_cfg"/>).</para>

		</listitem>

	  </itemizedlist>

	</sect1>

	<sect1>
	  <title>Side by side</title>

	  <para>'Side by side' mode shows multiple pages side by side, as many
	  as fit on your screen. You need to use a high resolution display
	  and/or small fonts in order to fit more than one page on the screen
	  at a time. Otherwise this mode is the same as the 'Layout'
	  mode.</para>

	  <para>Note that this mode also assumes that the entire pages fit
	  vertically on the screen, so Page up/down commands behave somewhat
	  differently.</para>

	</sect1>

  </chapter>

  <chapter>
	<title>Other commands</title>

	<para>This chapter describes commands not discussed elsewhere.</para>

	<sect1>
	  <title>File/New,Open,Save,Save as,Close</title>

	  <para>These do what you'd expect them to do.</para>

	</sect1>

	<sect1>
	  <title>File/Revert</title>

	  <para>Replaces the open script with the last version of it saved to
	  disk.</para>

	</sect1>

	<sect1>
	  <title>File/Print (via PDF)</title>

	  <para>This opens up the current script in your configured PDF viewer
	  program, from which you can print it, or just see what it looks
	  like.</para>

	</sect1>

	<sect1 id="globcfg_menu">
	  <title>File/Settings/(Change|Load|Save as)</title>

	  <para>These allow you to edit/load/save global settings (see <xref
	  linkend="settings"/>).</para>

	  <para>By default, &trelby; loads settings from a file named
	  "default.conf" on startup. See <xref linkend="cmdparams"/> for
	  customizing this.</para>

	</sect1>

	<sect1>
	  <title>File/Settings/Spell checker dictionary</title>

	  <para>This opens a dialog allowing you to edit the global spell
	  checker user-defined dictionary. Insert new words by entering them
	  on separate lines, or delete existing words by deleting the lines
	  they are on.</para>

	</sect1>

	<sect1>
	  <title>Edit/Undo,Redo</title>

	  <para>Every edit operation you do to the script is recorded and can
	  be undone/redone. There is a limit to the amount of memory that
	  &trelby; will use to store undo history, and different edit
	  operations take different amounts of memory (adding a single new
	  character takes very little memory, whereas doing a global
	  Find&amp;Replace can take a lot of memory), but in normal usage you
	  should be able to undo hundreds, or even thousands, of edit
	  operations.</para>

      <para>There are a few occasions when undo history is otherwise
      trimmed that you should be aware of:</para>

	  <itemizedlist>

		<listitem>

		  <para>Applying new script-specific settings clears all undo history.</para>

		</listitem>

		<listitem>

		  <para>If you do a new edit operation while you are in the middle
		  of the undo history (i.e., you have done one or more undo
		  operations without having done follow-up redo operations to
		  restore all your previously made changes), all recorded undo
		  history after the current point in it will be discarded.</para>

		</listitem>

	  </itemizedlist>

	</sect1>

	<sect1>
	  <title>Edit/Cut,Copy,Paste</title>

	  <para>Cut, copy and paste work pretty much the same way as in every
	  other program. Note that these commands use &trelby;'s internal
	  clipboard so can't be used for copying text to/from other programs.
	  For that, see below.</para>

	</sect1>

	<sect1>
	  <title>Edit/Copy/paste, system</title>

	  <para>These copy/paste text to the system wide clipboard so can be
	  used for communicating with other programs. Note that if you copy
	  text to the clipboard from &trelby;, you must keep &trelby; open until
	  you've pasted the text to the destination program.</para>

	  <para>There's two variants of the copy command: formatted and
	  unformatted. Which one you want to use depends on what you're trying
	  to do. Best to try out both and see which one works better.</para>

	</sect1>

	<sect1>
	  <title>Edit/Select scene</title>

	  <para>Select all the text of the current scene.</para>

	</sect1>

	<sect1>
	  <title>Edit/Select all</title>

	  <para>Select all the text in the entire script.</para>

	</sect1>

	<sect1>
	  <title>Edit/Goto page</title>

	  <para>This opens a dialog allowing you to type in a page number to
	  jump to. The Enter/Escape keys can be used as shortcuts for the
	  OK/Cancel buttons.</para>

	</sect1>

	<sect1>
	  <title>Edit/Goto scene</title>

	  <para>This opens a dialog allowing you to type in a scene number to
	  jump to. The Enter/Escape keys can be used as shortcuts for the
	  OK/Cancel buttons.</para>

	</sect1>

    <sect1>
      <title>Edit/Insert non-breaking space</title>

      <para>This adds a non-breaking space at the current cursor position.
      This will ensure that the line will not break at this position when
      it is being typed/formatted in.</para>

    </sect1>

	<sect1>
	  <title>Edit/Find &amp; Replace</title>

	  <para>This opens a dialog allowing you to search for and possibly
	  replace text. Usually it operates on all element styles, but if you
	  press the "More" button, you can select the element styles it
	  operates on, which is useful when renaming a character and so
	  on.</para>

	  <para>Pressing Enter while the cursor is in either text box is
	  equivalent to pressing the 'Find next' button. The Esc key will
	  close the dialog.</para>

	  <para>If you're doing partial replacing, i.e. replacing some, but
	  not all, occurrences of 'foo' with 'bar', the efficient way to do
	  that is to press Tab until the focus is on the 'Find next' button,
	  and then use the 'F' (Find next) and 'R' (Replace) keys on the
	  keyboard. Press 'F' whenever you don't want to replace that
	  occurrence, and 'R' when you do want to replace it.</para>

	</sect1>

	<sect1>
	  <title>Edit/Remove elements</title>

	  <para>'Remove elements' opens a dialog allowing you to select one or
	  more element styles to completely remove from the script.</para>

	  <para>You can use this for e.g. removing notes before sending out
	  copies of the script, or if you want a version of the script with
	  only the dialog, only the action, or only the scene headers, or
	  whatever else you can come up with.</para>

	</sect1>

	<sect1>
	  <title>View/Show formatting</title>

	  <para>This toggles whether formatting information is shown. It
	  consists of blue lines drawn at the right and left margins of each
	  line, plus a red marker indicating the type of the line ending for
	  that line. See fileformat.txt for information about the different
	  marker types.</para>

	  <para>When using the 'Find errors' command, if you can't figure out
	  what the error is, try switching this on to see if you have two
	  elements where you thought you only had one, or something else
	  that's not obvious in the normal display.</para>

	  <para>It's also useful for seeing exactly how much space you've got
	  left on a given line.</para>

	</sect1>

	<sect1>
	  <title>View/Fullscreen</title>

	  <para>Changes the display to fullscreen mode, hiding all
	  distractions. To exit fullscreen mode, either press F11 or press the
	  icon at top-left corner.</para>

	</sect1>

	<sect1>
	  <title>Script/Find next error</title>

	  <para>'Find next error' searches through the script, starting from
	  the cursor position, looking for errors. This means that to search
	  the entire script for errors you should first position the cursor at
	  the beginning of the script.</para>

	  <para>If it finds any errors, it positions the cursor on the line
	  containing the error and displays a message detailing the error. You
	  should fix the error, back up a few lines, and activate the command
	  again to search for more errors. Alternatively, if you don't want to
	  fix the error right now, move the cursor down one line if you want
	  to search for more errors.</para>

	  <para>It can detect the following errors:</para>

	  <itemizedlist>

		<listitem>

		  <para>An empty line, or a parenthetical element containing only
		  ().</para>

		</listitem>

		<listitem>

		  <para>A character element that is not followed by a
		  parenthetical or a dialogue element.</para>

		</listitem>

		<listitem>

		  <para>A parenthetical element that does not follow a character or
		  a dialogue element.</para>

		</listitem>

		<listitem>

		  <para>A dialogue element that does not follow a character or a
			parenthetical element.</para>

		</listitem>

		<listitem>

		  <para>Various error conditions that can only arise from bugs in
		  the program. This includes things like overlong lines, elements
		  that have lines with different element types, invalid characters
		  in the script, etc. You should never find any of these errors,
		  but if you do, you should try to fix them before saving the
		  script, otherwise you might not be able to load it again. You
		  should also notify us about the problem so we can fix it.</para>

		  <para>The messages for these all say "(BUG)" at the end so they
		  can be identified from normal errors.</para>

		</listitem>

	  </itemizedlist>

	</sect1>

	<sect1>
	  <title>Script/Paginate</title>

	  <para>'Paginate' simply repaginates the script. You normally don't
	  need to run this if you have automatic repagination enabled, but the
	  command is available for use when automatic repagination is disabled
	  or you want immediate repagination for some reason.</para>

	</sect1>

	<sect1 id="autocomp">
	  <title>Scripts/Auto-completion</title>

	  <para>Here you can define items to be added to the auto-completion
	  lists for Scene, Character and Transition elements, and optionally
	  disable auto-completion for any one of them.</para>

	  <para>Transition auto-completes are pretty generic so by default
	  there are a few of them here, but the Scene and Character lists are
	  empty. The main use for them are TV shows, where you have a
	  recurring cast of characters and locations, and it's nice to have
	  them always available, even if they haven't yet been used in the
	  current episode's script.</para>

	</sect1>

	<sect1>
	  <title>Script/Headers</title>

	  <para>'Headers' allows you to edit your script's headers. Headers
	  are lines that are automatically added to the top of each page of
	  the script, excluding title pages and the first page of the actual
	  script.</para>

	  <para>Topmost in the window is a setting for how many empty lines
	  you want inserted after your header lines.</para>

	  <para>After that is a listbox of all the strings in your headers.
	  Select the text string you want to edit in this listbox, and use the
	  add/delete buttons to add/delete text strings.</para>

	  <para>Below the listbox are the settings for the selected string.
	  You can adjust the string text, style, alignment, line and
	  positioning.</para>

	  <para>The text is first positioned according to the alignment
	  setting, and then its horizontal starting position is adjusted by
	  the number of characters given in 'X offset'. Note that this
	  parameter can be negative, so for example, if you want your header
	  string to start 2 characters before the left margin, select
	  'Alignment: Left' and 'X offset: -2'.</para>

	  <para>Any occurrences of '${PAGE}' in the text string will be
	  replaced by the page number in the actual headers.</para>

	  <para>Finally there are 'Preview' and 'Apply' buttons that you can
	  use to preview your changes. 'Preview' opens up a sample page in
	  your PDF viewer program, while 'Apply' applies the new headers to
	  the open script, so you can e.g. see how the page count of the
	  script would change.</para>

	</sect1>

	<sect1 id="locations_dlg">
	  <title>Scripts/Locations</title>

	  <para>This dialog allows you to define what scenes are part of the
	  same location (see <xref linkend="location_rep"/>). The top listbox
	  shows locations, separated by lines of "-----------", while the
	  bottom listbox shows scenes not part of a user-specified location.
	  In the middle are 'Add' and 'Delete' buttons for moving scenes
	  between the two listboxes. The bottom listbox allows you to select
	  many scenes at once.</para>

	  <para>An example of how to use this dialog: select the scenes "INT.
	  MOTEL ROOM - DAY", "INT. MOTEL ROOM - DAY - LATER" and "INT. MOTEL
	  ROOM - NIGHT" in the bottom listbox, then click 'Add' which adds
	  those three into a single location in the top listbox. Then, if you
	  want to add more scenes to the same location, make sure one of the
	  scenes for the location is selected in the top listbox, select the
	  new scenes you want to add in the bottom listbox, and click 'Add'.
	  If you want to add scenes to a new location, select one of the
	  "-----------" lines in the top listbox as the destination before
	  clicking 'Add'.</para>

	</sect1>

	<sect1>
	  <title>Script/Title pages</title>

	  <para>'Title pages' allows you to edit your script's title pages.
	  You can have as many title pages as you want, or none at all.</para>

	  <para>At the top of the window are add/delete/move/next buttons.
	  'Add' adds a page, 'Delete' deletes the current page, 'Move' swaps
	  the current page with the next page, and 'Next' changes the view to
	  the next page.</para>

	  <para>The strings listbox contains all text strings for the current
	  page. Select the text string you want to edit in this listbox, and
	  use the add/delete buttons to add/delete text strings.</para>

	  <para>On the right side of the listbox is a coarse preview showing
	  the approximate location of text strings on the current page, with
	  the selected text string shown in red.</para>

	  <para>At the bottom of the window are the settings for the selected
	  text string. There's the text itself (which can consist of multiple
	  lines), the position of it, and its font, size, and style.</para>

      <para>The aligment setting has three possible options:</para>

	  <variablelist>

		<varlistentry>
		  <term>Left</term>
		  <listitem>

			<para>Left-justified. X-Pos setting means the horizontal
			position of the leftmost edge of the first character.</para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Center</term>
		  <listitem>

			<para>Centered on the page. X-Pos setting is ignored.</para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Right</term>
		  <listitem>

			<para>Right-justified. X-Pos setting means the horizontal
			position of the rightmost edge of the last character.</para>

		  </listitem>
		</varlistentry>

	  </variablelist>

	  <para>Finally there's a 'Preview' button that you can use to get an
	  accurate preview of all of the title pages.</para>

	</sect1>

	<sect1>
	  <title>Script/Spell checker dictionary</title>

	  <para>This opens a dialog allowing you to edit the script-specific
	  spell checker dictionary. Insert new words by entering them on
	  separate lines, or delete existing words by deleting the lines they
	  are on.</para>

	</sect1>

	<sect1>
	  <title>Script/Settings/(Change|Load|Save as)</title>

	  <para>These allow you to edit/load/save script format settings (see
	  <xref linkend="format_settings"/>).</para>

	</sect1>

	<sect1>
	  <title>Tools/Spell checker</title>

	  <para>This spell checks the current script beginning at the current
	  position. If you want to spell check the entire script, be sure to
	  position the cursor at the first line of the script.</para>

	  <para>If it finds any words it doesn't recognize, it jumps to that
	  position in the script, highlights the word, and opens a dialog
	  window that has a text box for editing the word, and the following 5
	  buttons:</para>

	  <variablelist>

		<varlistentry>
		  <term>Replace</term>
		  <listitem>

			<para>Replace the word in the script with the (modified) one
			in the text box. You can also do this by pressing Enter in the
			text box.</para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Skip</term>
		  <listitem>

			<para>Skip the word for now.</para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Add to script dictionary</term>
		  <listitem>

			<para>Add the word to the script-specific dictionary.</para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Add to global dictionary</term>
		  <listitem>

			<para>Add the word to the (super-)global dictionary.</para>

		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Suggest replacement</term>
		  <listitem>

			<para>Search for the 5 most similar known words and allow
			choosing one of them. If selected, that word is put in the
			text box and you can either edit it further or press 'Replace'
			at once to replace the word in the script.</para>

			<para>Note that this only looks at words with the same two
			first characters as the misspelled word (mostly for speed
			reasons). So while it can correct "accommdoate" to
			"accommodate", it can't correct "cmoputer" to
			"computer".</para>

		  </listitem>
		</varlistentry>

	  </variablelist>

	  <para>After pressing any of the above buttons, the spell checker
	  looks for the next misspelled word. If none are found, it closes the
	  dialog. You can also press the Esc key at any time to close the
	  dialog.</para>

	  <para>Note that the spell checker currently only supports the
	  English language.</para>

	</sect1>

	<sect1>
	  <title>Tools/Name database</title>

	  <para>'Name database' opens a window allowing you browse and search
	  through a database of more than 200,000 character names, each name
	  being categorized by its nationality and sex.</para>

	  <para>On the left side of the window is a list of the name
	  categories. The main groups available are nationalities, but there
	  are some other interesting groups, e.g. Shakespeare, Medieval,
	  Flowers etc.</para>

	  <para>Select the groups you want to search in, either a single one
	  by simply clicking on it, or multiple ones by holding down CTRL and
	  then clicking on multiple items. If you want to go back to the
	  default of having all the groups selected, press the 'Select all'
	  button at the bottom of the list.</para>

	  <para>On the upper right side of the window are the other search
	  parameters. There's a text box in which you can write the text you
	  want to search for, and two radio button groups.</para>

	  <para>The first one affects how your search string is used. The
	  string has to match either a) at the start of the name, b) anywhere
	  in the name or c) at the end of the name.</para>

	  <para>The second one selects whether male/female/both names are
	  included in the search results.</para>

	  <para>The search is always case-insensitive, and a blank search
	  string matches all names.</para>

	  <para>After having set all the search parameters, press the 'Search'
	  button, at which point the results list will change to contain only
	  the names matching the search parameters. A count of the matching
	  names is shown at the bottom of the window.</para>

	  <para>You can select names from the result list and press 'Insert'
	  to insert that name at your script at the current cursor
	  position.</para>

	</sect1>

	<sect1>
	  <title>Tools/Character map</title>

	  <para>'Character map' opens a window allowing you to insert any
	  character from the supported ISO-8859-1 (i.e. Latin-1) character set
	  into your script.</para>

	</sect1>

	<sect1>
	  <title>Tools/Compare scripts</title>

	  <para>You need two different versions of the same script open to use
	  'Compare scripts'. Select the older one as the first script and the
	  newer one as the second script. &trelby; then goes through the
	  scripts looking for changes between them and displays the results as
	  a PDF file.</para>

	  <para>There's a checkbox allowing you to use the same configuration
	  parameters for the scripts you're comparing. This is useful if the
	  scripts differ in in their formatting settings, because in that case
	  practically the entire script would show up as changed.</para>

	  <para>The PDF file contains only the changed parts of the script.
	  The changes are color coded: Deleted lines are red, added lines are
	  green, non-changed lines (shown for context) are white, and marker
	  lines for single-line changes are yellow. The changed parts are
	  separated by two gray lines.</para>

	</sect1>

    <sect1>
      <title>Tools/Generate watermarked PDFs</title>

      <para>This tool allows you to generate multiple watermarked PDFs to
      distribute to multiple people. Watermarks are handy when you want to
      let your readers know overtly that the script is meant only for their
      viewing, and is not to be distributed.</para>

      <para>Enter details like directory, filename prefix, and watermark
      font size. You can have two lines of watermarks per file, and the
      first line is common in all files. The second line for each file
      is provided as a list under the "Watermarks" entry box.</para>

      <para>The watermark in the PDF is applied as slanted text, in light
      grey color, as part of the background of the page. The watermark is
      applied on every page.</para>

      <para>A unique ID is also saved in the 'Keywords' metadata
      of the PDF file, as a second source of identification of a PDF
      (if it is leaked with only the watermark removed).</para>

    </sect1>

	<sect1>
	  <title>Help/Commands</title>

	  <para>'Commands' opens a window showing all the commands and their
	  current keyboard shortcuts. It also has a menu allowing you to save
	  this as a HTML file if you e.g. want to print it for
	  reference.</para>

	</sect1>

	<sect1>
	  <title>Help/Manual</title>

	  <para>'Manual' opens this manual you're reading right now.</para>

	</sect1>

	<sect1>
	  <title>Help/About</title>

	  <para>'About' opens the about screen for &trelby;, showing
	  information such as the version of the program. It also shows a
	  random famous movie quote.</para>

	</sect1>

  </chapter>

  <chapter id="settings">
	<title>Settings</title>

	<para>&trelby; has 4 levels of settings: super-global settings, global
	settings, script format settings, and script-specific settings.</para>

	<para>Super-global settings are the current view mode, window size and
	position, and the global spell checker dictionary. There can only be
	one set of these.</para>

	<para>Global settings are things like interface colors, keyboard
	shortcuts, display fonts and other settings that only affect the user
	interface of the program, not the script output. You can have multiple
	sets of these and switch between them at will (see <xref
	linkend="globcfg_menu"/>). These settings are platform-dependent, so
	you can't share these between Windows/Linux machines, and even sharing
	between different machines on the same platform could be unreliable if
	you don't have the exact same fonts, PDF viewer applications, etc. on
	the machines.</para>

	<para>Script format settings are things like paper sizes,
	indendation/line widths/font styles for the different element types,
	whether to include scene numbers, and so on that directly affect
	script formatting and output but are not tied to any specific script,
	in the sense that they can be reused for different scripts with no
	changes. You can easily save/load these, so you can have ready-made
	settings for different scenarios. This, and script-specific settings,
	are completely platform-neutral, guaranteeing the exact same script
	output whatever platform you use.</para>

	<para>Script-specific settings are things that are specific to one
	particular script, like title pages, header strings, and
	auto-completion settings, and so can't be reused for different scripts
	without changes. However, if you want to have a template for these
	(e.g. your contact information on the title page is always the same,
	or you're writing several episodes of the same TV show), it's easy:
	just fill in the information you want, and save the script as
	"my_template.trel", then when you want to use that as a template,
	open that file, change what's needed, and save the script under a new
	name.</para>

	<sect1>
	  <title>Global settings</title>

	  <para>The global settings dialog is found under
	  File/Settings/Change. It has a list of categories on the left, the
	  selected category's settings on the right, and three buttons, Apply,
	  Cancel and OK on the bottom. Apply updates the settings to the ones
	  given in the dialog so you can easily preview your changes without
	  closing the dialog. Note that pressing Cancel after Apply has no
	  effect, it only cancels changes that haven't yet been
	  committed.</para>

	  <para>The following sections detail the various settings.</para>

	  <sect2>
		<title>Colors</title>

		<para>Color configuration. These only affect the display, the PDF
		output is always black on white.</para>

		<para>The 'Use per-element-type colors' checkbox controls whether
		to use the same text color for all element types (Text foreground)
		or whether to use the per-element color settings (Text foreground
		for Action, Text foreground for Character, etc.). </para>

	  </sect2>

	  <sect2 id="display_cfg">
		<title>Display</title>

		<para>The topmost listbox allows you to configure what font you
		want to use for normal, bold, italic, and bold + italic text. Note
		that you should use the same size font for each one.</para>

		<para>(Draft view mode only) The row spacing setting affects how
		many pixels there are between each row. It has an effect only in
		the 'Draft' view mode.</para>

		<para>(Draft view mode only) The 'Page break lines to show'
		setting affects how page breaks are shown. If you select 'None',
		they are not shown at all. 'Normal', you see solid gray lines in
		the scripts indicating actual page break positions. 'Normal +
		unadjusted', you see the solid lines, but you also see a dotted
		gray line, that shows where the page could have ended, but that
		the page break position was adjusted backwards to honor the
		settings in <xref linkend="format_cfg"/>.</para>

		<para>This is useful when you've finished your script and you're
		going through it trying to reduce the page count. If, for example,
		you have three lines, a Character, a Parenthetical, and a Dialogue
		element, all one line, and the unadjusted page break line is after
		the Parenthetical line, and the actual page break line is above
		the character line, you know that if you can trim just one line
		from the page, all three lines will then fit on the page instead
		of being pushed to the next page.</para>

	  </sect2>

	  <sect2 id="elements_gcfg">
		<title>Elements</title>

		<para>This is where you configure the interaction parameters for
		each element style.</para>

		<para>At the top is a combo box where you specify what element
		style you're configuring. All things below that are
		element-specific settings.</para>

		<para>The 'Enter/Tab creates' and 'Tab/Shift+Tab switches to'
		affect what element is created when Enter or Tab is pressed in
		this element style, or what element style Tab/Shift+Tab switches
		the element to. See <xref linkend="add_element"/> for more
		information.</para>

	  </sect2>

	  <sect2>
		<title>Keyboard</title>

		<para>Here you can configure keyboard shortcuts for each command.
		Note that a few command/keys (Enter, Tab, etc.) can't be changed
		because they're an integral part of the program's design.</para>

	  </sect2>

	  <sect2 id="misc_cfg">
		<title>Misc</title>

		<para>The default script directory setting allows you to specify
		the default directory for File/Open dialog on program
		startup.</para>

		<para>You can specify what application you want to use as your PDF
		viewer. On Windows, this is usually Adobe Acrobat, and the path is
		something like "C:\Program Files\Adobe\Acrobat
		7.0\Reader\AcroRd32.exe". On Linux, you can also use Adobe
		Acrobat, path being something like
		"/usr/local/Adobe/Acrobat7.0/bin/acroread".</para>

		<para>You can also specify arguments to give to the PDF viewer
		program.</para>

		<para>'Auto-capitalize sentences', if on, auto-capitalizes
		sentences as you write them. If it capitalizes something you don't
		want capitalized, write another letter, and then replace the
		capitalized letter by a lowercase one.</para>

		<para>'Auto-capitalize i -> I', if on, causes solitary 'i'
		characters in the middle of sentences to be changed to a 'I'
		character automatically.</para>

		<para>'When opening a script, start at last saved position' causes
		the cursor position be restored to the point it was at when the
		script was saved.</para>

		<para>'Recenter screen on scrolling' causes moving around the
		script using up/down keys to scroll a bit differently: when cursor
		is at bottom of the screen, and you press down, instead of moving
		the display down just one line, it will recenter the display on
		the cursor.</para>

        <para>'Typing replaces selected text' causes selected text to be
        removed and replaced with the character entered whenever a key is
        pressed and there's an active selection.</para>

		<para>'Check script for errors before print, export or compare',
		if checked, causes the program to run 'Script/Find next error' for
		the entire script automatically before print/export/compare
		operations. This is to avoid printing 100 pages and then finding
		there's an error on one of them, fixing of which causes
		repagination of the entire script, and having to print all the 100
		pages again.</para>

		<para>'Show splash screen for X seconds' can be used to customize
		for how long to show the splash screen on startup for, or to
		disable showing it completely.</para>

		<para>'Auto-paginate interval' defines how often to repaginate the
		script automatically. If you have a particularly slow machine, you
		might want to increase this number. Note that automatic
		repagination is only done when you modify the script, so you can't
		just sit back and wait for the repagination to happen, you have to
		keep making changes. (You can always use Script/Paginate if you
		want immediate repagination.)</para>

		<para>'Lines to scroll per mouse wheel event' needs no
		explaining.</para>

	  </sect2>

	</sect1>

	<sect1 id="format_settings">
	  <title>Script format settings</title>

	  <para>Script format settings are found in Script/Settings/Change. It
	  has the same Apply/Cancel/OK buttons as the global settings
	  dialog.</para>

	  <sect2 id="elements_cfg">
		<title>Elements</title>

		<para>This is where you configure the formatting parameters for
		each element style.</para>

		<para>At the top is a combo box where you specify what element
		style you're configuring. All things below that are
		element-specific settings.</para>

		<para>The Screen/Print areas hold four checkboxes,
		Caps/Bold/Italic/Underlined, affecting the text style for the
		element. Screen affects the editing screen, while Print affects
		PDF output.</para>

		<para>The 'Empty lines / 10 before' setting is linespacing before
		the element, divided by 10. So a value of 10 means normal
		linespacing, 15 means 1.5 linespacing, 20 is double linespacing,
		etc.</para>

		<para>The 'Empty lines / 10 between' is the same, but for
		intra-element linespacing, i.e. consecutive lines of the same
		element have this much space between them.</para>

		<para>The Indent and Width settings specify in characters how much
		the element is indented (i.e. set off from the left margin) and
		how wide it is. 10 characters (in the default 12-point font) equal
		one inch.</para>

	  </sect2>

	  <sect2 id="format_cfg">
		<title>Formatting</title>

		<para>Here you can configure parameters affecting the formatting
		of the script.</para>

		<para>The first two settings affect how many action and dialogue
		lines there must be left at the end of a page to allow breaking at
		that position. This only affects elements that are broken in the
		middle, i.e. if you have a one-line element, the page can always
		end after that.</para>

		<para>The font size specifies the font size to use. 12 is the
		default, and you should only deviate from this if you have a very
		good reason.</para>

		<para>'Include scene continueds', if enabled, inserts
		"(CONTINUED)" at the end of each page that has a scene that
		continues to the next page, and "CONTINUED: (n)" (n = number of
		CONTINUED pages for current scene, omitted if n = 1) for each page
		that continues a scene from previous page(s).</para>

		<para>'Scene continueds indent' is the number of characters to
		indent the "(CONTINUED)" text with.</para>

		<para>'Include scene numbers' causes scene numbers to be inserted
		to the left and right of each scene element. This is usually only
		done for scripts in production.</para>

		<para>'Show line numbers' prefixes each line with its line number
		(starting from 1 at the top of the page). It can be considered a
		debug option as it has no use in normal operation, but it can be
		useful if you're trying to figure out printing related
		problems.</para>

	  </sect2>

	  <sect2>
		<title>Paper</title>

		<para>Here you can configure your output paper size and margins.
		You can use A4, Letter, or a custom paper size. At the bottom of
		the page is shown the number of lines that will fit on a page with
		the given settings.</para>

	  </sect2>

	  <sect2>
		<title>PDF</title>

		<para>Here you can configure parameters affecting the generation
		of the PDF file for printing or exporting.</para>

		<para>'Add table of contents', if on, will cause the PDF file to
		have a table of contents listing all the scenes. Note that this is
		not printed, it's just shown in PDF viewer applications allowing
		one to quickly jump to the selected scene.</para>

		<para>'Show table of contents on PDF open', if on, will cause the
		table of contents to be shown by default when opening the PDF
		file.</para>

		<para>'Open PDF on current page', if on, will insert a command
		into the PDF file telling the PDF viewer application to show the
		current page when opening the file. Not all PDF viewer
		applications support this command. Note that this only affects PDF
		files generated through the File/Print command, File/Export
		command isn't affected by this. If you really want to generate a
		permanent PDF file opening on a non-standard page, use File/Print
		and save the PDF file from the PDF viewer application to a
		different name.</para>

		<para>'Omit Note elements', if on, will cause all Note elements to
		be omitted from the PDF output.</para>

		<para>'Draw rectangles around Note elements', if on, will cause
		rounded rectangles to be drawn around Note elements in the PDF
		output to make them stand out more.</para>

		<para>'Show margins' draws a rectangle on each page showing the
		margin settings. It can be considered a debug option as it has no
		use in normal operation, but it can be useful if you're trying to
		figure out printing related problems.</para>

	  </sect2>

	  <sect2>
		<title>PDF/Fonts</title>

		<para>Here you can configure the fonts used in generating the PDF
		files. Normally they use the standard PDF Courier fonts that are
		guaranteed to work everywhere, and it is strongly recommended to
		leave things as they are unless you have specific reasons to use
		other fonts.</para>

		<para>So, assuming you have a good enough reason, you can use the
		TrueType fonts of your choosing. There are four different font
		settings, one for each font style (Normal / Bold / Italic /
		Bold-Italic).</para>

		<para>Each font setting has two parts: a 'Name' field and a 'File'
		field. The 'Name' field is the internal Postscript name of the font and
		is used by the PDF viewer application to recognize the font to use.
		</para>

		<para>The 'File' field is the filename of the TrueType font to
		use. If you fill in this field, the font file is embedded in the
		generated PDF files.
		</para>

		<para>Embedding a font  will increase the size of the PDF
		files drastically, and not all fonts allow embedding in their
		license terms.</para>

		<para>When you use the 'Browse' button to locate a font file, the
		following things happen:</para>

		<itemizedlist>

		  <listitem>

			<para>The file is checked to be a valid TrueType font file.</para>

		  </listitem>

		  <listitem>

			<para>The font's Postscript name is located from the font file
			and put in the 'Name' field.</para>

		  </listitem>

		  <listitem>

			<para>The licensing terms of the font are checked and if
			embedding is not allowed, a warning is printed.</para>

		  </listitem>

		</itemizedlist>

		<para>Note that the chosen fonts have to be able to be substituted
		in place of the normal Courier fonts with no changes to the text
		layout, i.e., they have to be fixed width fonts with the same size
		as the Courier fonts are. If this is not the case, you will see
		characters overlapping each other and other errors in the
		output.</para>

		<para>Also note that random fonts downloaded from the Internet are
		very often broken in every sense of the word. They have names that
		violate the Postscript/PDF specifications, they lack essential
		characters (it is very rare for them to contain anything outside
		of the ASCII character set), and their quality is bad. So, if you
		feel you must use something besides the normal Courier fonts, at
		least use professional fonts made by people who know what they're
		doing.</para>

		<para>Note for Windows users: Microsoft, in their infinite wisdom,
		have found yet another way to obstruct people from using their
		computers. When you use the 'Browse' button and navigate to e.g.
		the 'C:\Windows\Fonts' directory to choose a TrueType font file,
		the files are listed correctly but you can't select them! One
		wonders what goes on in those meetings at Microsoft where things
		like this are decided... "Why would anyone ever want to select a
		font file from a normal file open dialog?" "Gee Bob, I don't know,
		maybe we should disallow that so that users aren't confused?"
		"Good idea Jim, let's do that!".</para>

		<para>To work around this bit of brokenness, once you're in the
		directory containing the font file you want to use, switch the
		keyboard focus to the filename entry field and type in the first
		few characters of the filename, after which a completion pop-up
		should show up from which you can select the correct
		filename.</para>

	  </sect2>

	  <sect2>
		<title>Strings</title>

		<para>Here you can customize the strings that are automatically
		added to the script in certain situations:</para>

		<variablelist>

		  <varlistentry>
			<term>(CONTINUED)</term>
			<listitem>

			  <para>Added at the end of a page when a scene spans multiple
			  pages.</para>

			</listitem>
		  </varlistentry>

		  <varlistentry>
			<term>CONTINUED:</term>
			<listitem>

			  <para>Added at the start of a page when a scene spans
			  multiple pages.</para>

			</listitem>
		  </varlistentry>

		  <varlistentry>
			<term>(MORE)</term>
			<listitem>

			  <para>Added at the end of a dialogue element that spans
			  multiple pages.</para>

			</listitem>
		  </varlistentry>

		  <varlistentry>
			<term> (cont'd)</term>
			<listitem>

			  <para>Added after the speaker's name at the start of a page
			  when a dialogue element spans multiple pages.</para>

			</listitem>
		  </varlistentry>

		</variablelist>

	  </sect2>

	</sect1>

	<sect1>
	  <title>Script-specific settings</title>

	  <para>Decriptions for these start at <xref
	  linkend="autocomp"/>.</para>

	</sect1>

  </chapter>

  <chapter>
	<title>Import and export</title>

	<para>This chapter discusses the import/export support of the
	program.</para>

	<sect1>
	  <title>Import</title>

	  <para>Existing screenplays can currently be imported from three
  	  file formats: as formatted ASCII text, Final Draft XML (.fdx),
      Celtx (.celtx), Adobe Story (.astx), Fountain (.fountain) and
      Fade In Pro (.fadein).
      The following section documents the format these
      files should have for optimal import processing.</para>

	  <sect2>
		<title>ASCII Text files</title>

		<para>ASCII text files should have the following
		  characteristics:</para>

		<itemizedlist>

		  <listitem>

			<para>Each element style should begin at a unique column. An
			exception is that Scene and Action can begin at the same
			column.</para>

			<para>There should only be one such starting column per
			element style, i.e. all dialogue should begin at the same
			column, it shouldn't sometimes start at column 25, sometimes
			at 27, etc.</para>

		  </listitem>

		  <listitem>

			<para>No production markings, e.g. scene numbers, page
			numbers, cast lists, or anything like that.</para>

		  </listitem>

		  <listitem>

			<para>Elements should be separated by a single empty
			line.</para>

		  </listitem>

		</itemizedlist>

		<para>Below is a short example of the kind of format best
		recognized by &trelby;.</para>

		<screen>
EXT. OCEAN - NIGHT

The package hits the water and is submerged. A few seconds
later, a rapidly inflating liferaft appears.

The people land into the water in their parachutes. They
dispose of them and swim toward the liferaft.

INT. LIFERAFT - NIGHT

They're all aboard, taking off their clothes. When they're
all naked, Sarah gathers the wet clothes, throws them out,
and closes the entrance to the tent-like liferaft. The men
openly admire Sarah's body, as she opens a storage locker
and takes out dry clothes for everyone which they then put
on.

                      KEVIN
          I know a great way to warm up.

                      SARAH
          Sorry, I got over the "older men"
          thing a while back.

                      KEVIN
          Anytime you have a flashback, let
          me know.

Something starts beeping.
		</screen>
	  </sect2>

	  <sect2>
		<title>Final Draft XML (.fdx)</title>

		<para>Final Draft files saved with version 8 of the program are
		supported with these contents imported:</para>

		<itemizedlist>

		  <listitem>

            <para>Text of the the screenplay elements (Action, Dialog,
            etc) that Trelby understands.</para>

            <para>Script notes in Final Draft are imported as
            notes.</para>

          </listitem>

        </itemizedlist>

		<para>Note that no formatting settings are imported at all.</para>

	  </sect2>

	  <sect2>
		<title>Celtx (.celtx)</title>

		<para>These files are created by the Celtx program.</para>

		<itemizedlist>

		  <listitem>

            <para>Screenplay elements (Action, Dialog, etc) that Trelby
            understands are imported. Others are converted to 'Action'
            type.</para>

          </listitem>

        </itemizedlist>

		<para>Note that no formatting settings are imported at all.</para>

	  </sect2>

	  <sect2>
		<title>Adobe Story (.astx)</title>

		<para>These files are created by the Adobe Story editor.</para>

		<itemizedlist>

		  <listitem>

            <para>Screenplay elements (Action, Dialog, etc) that Trelby
            understands are imported. Others are converted to 'Action'
            type.</para>

          </listitem>

        </itemizedlist>

		<para>Note that no formatting settings are imported at all.</para>

	  </sect2>

	  <sect2>
		<title>Fountain (.fountain)</title>

		<para>Fountain is an open, plaintext screenplay markup language.
        It is documented at http://fountain.io/syntax.</para>

        <para>Almost all of the spec is supported. The below are unsupported:
        </para>

		<itemizedlist>

		  <listitem>

            <para>Emphasis markup (bold, italic, etc) is not supported. When
            importing, you can choose to retain the syntax, or remove it.
            </para>

          </listitem>

          <listitem>

            <para>Dual dialogue is imported as a couple of dialogues instead.
            </para>

          </listitem>

          <listitem>

           <para>Section/Synopsis are imported as notes.</para>

          </listitem>

          <listitem>

          <para>Comments that are part of another element are not recognized.
            (Standalone comments are imported as notes).</para>

          </listitem>

          <listitem>

           <para>Title pages are imported as action lines. You can also choose
            not to do this when importing.</para>

          </listitem>

          <listitem>

           <para>Page breaks are not supported (imported as an action line).
            </para>

          </listitem>

        </itemizedlist>

		<para>Note that no formatting settings are imported at all.</para>

	  </sect2>

      <sect2>
		<title>Fade In Pro (.fadein)</title>

		<para>These files are created by the Fade In Pro screenwriting program.</para>

		<itemizedlist>

		  <listitem>

            <para>Screenplay elements (Action, Dialog, Notes, etc) that
            Trelby understands are imported. Others are converted to
            'Action' type.</para>

          </listitem>

        </itemizedlist>

		<para>Note that no formatting settings are imported at all.</para>

	  </sect2>

	</sect1>

	<sect1>
	  <title>Export</title>

	  <para>You can export the script in PDF, RTF, formatted ASCII, HTML,
      Final Draft XML (.fdx) and Fountain (.fountain) format.</para>

	  <para>All are found in the File/Export dialog, which allows you to
	  choose which one to export as. If you export as a text file, &trelby;
	  will ask whether you want the page markers included or not. If
	  you're planning on importing the script to some other program, you
	  shouldn't include them, otherwise you probably should.</para>

	  <para>The RTF file produced uses stylesheets, which not all RTF
	  reading programs support, so if you get unexpected output check with
	  something like OpenOffice to see whether the problem is with the
	  file or with the program you tried to use.</para>

	</sect1>

  </chapter>

  <chapter>
	<title>Reports</title>

	<para>This chapter discusses the various report types &trelby; can
	generate. All the reports are in PDF format so that you can easily
	view them on your computer, and if necessary also get high-quality
	printed output.</para>

	<sect1>
	  <title>Script report</title>

	  <para>The script report is a short, one-page report on general
	  script statistics. It has the following information:</para>

	  <itemizedlist>

		<listitem>

		  <para>Total line count of the script and line counts for each
		  element type, both in absolute terms and as a percentage of the
		  whole.</para>

		</listitem>

		<listitem>

		  <para>Percentage of lines found in interior and exterior scenes
		  (it determines this based solely on whether the scene element
		  starts with INT. or EXT.)</para>

		</listitem>

		<listitem>

		  <para>Maximum and average scene lengths in lines.</para>

		</listitem>

		<listitem>

		  <para>Maximum and average action element lengths in lines.</para>

		</listitem>

		<listitem>

		  <para>Number of different speaking characters.</para>

		</listitem>

	  </itemizedlist>

	</sect1>

	<sect1 id="location_rep">
	  <title>Location report</title>

	  <para>The location report is similar to the scene report, but
	  combines scenes taking place at the same location into one entity.
	  If you always use the same scene line to describe a single location,
	  you don't need to do anything special to get a correct location
	  report. If, however, you have e.g. scenes named "INT. MOTEL ROOM -
	  DAY", "INT. MOTEL ROOM - DAY - LATER" and "INT. MOTEL ROOM - NIGHT"
	  and you'd like them to be treated as the same location, see <xref
	  linkend="locations_dlg"/> for details on how to do that.</para>

	  <para>The location report lists the following information for each
	  location: list of scenes for the location (if more than one, each is
	  followed by a percentage showing its part of the total lines of the
	  location), total lines in location, percentage of action lines in
	  location, percentage of the location's total lines of the script's
	  total lines, how many scenes the location has, count of pages that
	  the location appears in, list of pages that the location appears in,
	  and optionally a list of all speaking characters in the location
	  along with the number of lines they speak.</para>

	</sect1>

	<sect1>
	  <title>Scene report</title>

	  <para>The scene report lists the following information for each
	  scene: scene number, scene name, total lines in scene, percentage of
	  action lines in scene, count of pages that the scene appears in,
	  list of pages that the scene appears in, and optionally a list of
	  all speaking characters in the scene along with the number of lines
	  they speak.</para>

	</sect1>

	<sect1>
	  <title>Character report</title>

	  <para>'Character report' first opens a window allowing you to
	  specify what to include in the generated report. You can select what
	  characters are included, and what kind of information to include for
	  each character:</para>

	  <variablelist>
		<varlistentry>
		  <term>Basic information</term>
		  <listitem>
			<para>Total number of speeches, total number of lines, the
			percentage of all the dialogue lines in the script that this
			character speaks (i.e. 25% would mean this character has
			one-fourth of the total dialogue in the script), average
			number of lines per speech, total words, average number of
			words per speech and average number of characters per word.
			</para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Page list</term>
		  <listitem>
			<para>Number of pages this character speaks on, followed by a
			list of all of those pages.</para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Location list</term>
		  <listitem>
			<para>A list of all the locations this character speaks in,
			preceded by the number of lines spoken at each
			location.</para>
		  </listitem>
		</varlistentry>

	  </variablelist>

	</sect1>

	<sect1>
	  <title>Dialogue chart</title>

	  <para>'Dialogue chart' first opens a window allowing you to specify
	  what to include in the generated chart. The 'Sorted by:' options
	  select what orderings to include, while the 'Characters &lt; 10
	  lines' option, if unselected, leaves out all characters that have
	  less than 10 dialogue lines, which is useful for trimming out minor
	  characters from long scripts.</para>

	  <para>It then generates a chart with one page for each selected
	  ordering and shows that.</para>

	  <para>The chart has two axes: The horizontal one, with page numbers
	  increasing from left to right, and the vertical one, with characters
	  ordered by the current page's sort criterion from top to
	  bottom.</para>

	  <para>If a character speaks on a given page, he will have a black
	  bar on that page's position on the chart. The bar's height is scaled
	  according to how many dialogue lines the character has on that page,
	  allowing easy visual identification of long monologues, etc.</para>

	  <para>Every other line has a light gray background to allow easier
	  visual matching of distant markings to character names.</para>

	  <para>You can use this chart in many ways. For example, you can at a
	  glance see if one of your side characters disappears for 50 pages in
	  the middle of the script, whether the villain is introduced too
	  late, and so on.</para>

	  <para>At the top is another graph showing the percentage of action,
	  dialogue, character and "other" lines on each page. This graph is
	  most useful for seeing how the percentage of action lines
	  fluctuates, allowing one to easily see where the major action scenes
	  are, etc.</para>

	</sect1>

  </chapter>

  <chapter id="cmdparams">
	<title>Command line parameters</title>

	<para>&trelby; supports the following command line parameters:</para>

	<variablelist>

	  <varlistentry>
		<term>--conf FILENAME</term>
		<listitem>

		  <para>Read global settings from the given file instead of
		  "default.conf".</para>

		</listitem>
	  </varlistentry>

	  <varlistentry>
		<term>FILENAME1 FILENAME2 ...</term>
		<listitem>

		  <para>Open the given script files.</para>

		</listitem>
	  </varlistentry>

	</variablelist>
  </chapter>

  <chapter>
	<title>Troubleshooting</title>

	<para>This chapter discusses some common problems you might
	encounter.</para>


	<itemizedlist>

	  <listitem>

		<para>The program usually works perfectly, but sometimes it's so
		much slower that it's almost unusable.</para>

		<itemizedlist>
		  <listitem>

			<para>This happens on certain machines with limited resources.
			Try stopping all other programs and restarting &trelby; and see
			if that helps; if so, make it a habit of starting &trelby;
			first so it can allocate the resources (video memory, mainly)
			that it needs for fast operation before starting other
			programs.</para>

		  </listitem>
		</itemizedlist>

	  </listitem>

	</itemizedlist>

  </chapter>

  <appendix>
	<title>File format</title>

	<para>The file format used by &trelby; for scripts is open and
	documented, and third parties are encouraged to add support for the
	format in their programs and/or write utility programs that use the
	file format in some way.</para>

	<para>For more information, see the file 'fileformat.txt' in the
	program's installation directory, and read through the sample script
	file provided. If you still have questions about the file format, feel
	free to contact us by email.</para>

  </appendix>

</book>
