<chapter id="configuring">
<title>Configuring &frescobaldi;</title>

<para>This chapter documents how to configure &frescobaldi; for your needs.</para>

<sect1 id="settings-menu">
<title>The Settings Menu</title>

<para>
The <guimenu>Settings</guimenu> menu has options to show the full path of the
file currently being edited in the window title bar or just the filename, to
show or hide the toolbar and to switch the &frescobaldi; window to full screen
mode.
</para>

<para>
The <guisubmenu>Tool Views</guisubmenu> sub menu lets you alter some settings of
the tools in the sidebar docks of the &frescobaldi; window. (Note that you can
right-click on the tabs in the sidebar docks for more tool options.)
</para>

<para>
Finally, &frescobaldi; has the usual menu entries
<guimenuitem>Configure Shortcuts...</guimenuitem>,
<guimenuitem>Configure Toolbars...</guimenuitem> and
<link linkend="settings-dialog"><guimenuitem>Configure &frescobaldi;...</guimenuitem></link>.
</para>

</sect1>

<sect1 id="settings-dialog">
<title>The Settings Dialog</title>

<sect2 id="settings-general-preferences">
<title>General Preferences</title>

<para>
Here you can set some general preferences to influence the behaviour of
&frescobaldi;.
</para>

<variablelist>

<varlistentry>
<term><guilabel>Session to load if &frescobaldi; is started without arguments</guilabel></term>
<listitem>
  <para>
  Here you can choose if you want &frescobaldi; to load documents by default.
  You can let &frescobaldi; start up empty, with the last used session or with a specific
  session.
  See <link linkend="sessions">Sessions</link> for more information.
  </para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>When saving documents</guilabel></term>
<listitem>
  <variablelist>
    <varlistentry>
    <term><guilabel>Remember cursor position, bookmarks, etc.</guilabel></term>
    <listitem>
      <para>
      If checked, &frescobaldi; will save the cursor position, bookmarks and some
      view settings for a document when it is closed. This meta-information is
      retained for one month.
      </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><guilabel>Default folder</guilabel></term>
    <listitem>
      <para>
      Here you can configure a default folder that is displayed when saving a new document
      for the first time.
      </para>
    </listitem>
    </varlistentry>
  </variablelist>
  
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Warnings and notifications</guilabel></term>
<listitem>
  <para>
  Here you can check which warnings and notifications you want to get. Usually,
  warning messages have a checkbox &quot;Don't show this message again&quot;
  (or &quot;Don't ask this question again&quot;).
  When you enable a warning here, its dialog will be shown on the next occurrence.
  </para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Point and Click</guilabel></term>
<listitem>
  <para>
  Click this button if Point &amp; Click does not work, i.e. when clicking a note
  in the PDF preview does not move the cursor in the text editor.
  See also <link linkend="point-and-click">Configuring Point &amp; Click</link>.
  </para>
</listitem>
</varlistentry>

</variablelist>
</sect2>



<sect2 id="settings-lilypond">
<title>&lilypond; Preferences</title>

<para>
Here you can you configure all &lilypond;-related things.
</para>

<variablelist>

<varlistentry id="settings-paths-lilypond">
<term><guilabel>&lilypond; versions to use</guilabel></term>
<listitem>
  <para>
  This list normally shows just one item, "lilypond".
  But if you have multiple versions of &lilypond; installed you can add them to the list by clicking
  the <guibutton>Add</guibutton> button.
  Existing entries can be configured by clicking <guibutton>Configure</guibutton>.
  </para>

  <para>
  In the dialog that opens you can specify the exact path to &lilypond;.
  If you just enter <command>lilypond</command>, the first &lilypond; instance in your
  <envar>PATH</envar> environment variable is used.
  You can also enter the paths to related commands such as <command>convert-ly</command>
  and <command>lilypond-book</command>. But if you don't specify the paths, these commands will be
  searched for in the same directory as the <command>lilypond</command> command was found.
  </para>

  <para>
  Check <guilabel>Set as default</guilabel> to make the current &lilypond; entry the default,
  i.e. the one that is run for all actions (also the Blank Staff Paper tool, etc.).
  The other checkbox, <guilabel>Include in automatic version selection</guilabel>, if checked,
  will include the current &lilypond; entry in the automatic version selection (see below).
  The <guibutton>Download</guibutton> button lets you
  <link linkend="download-lilypond">download and install binary packages</link>
  from the &lilypond; website.
  </para>
  
  <para>
  Below the list of installed &lilypond; instances, there is a checkbox
  <guilabel>Enable automatic version selection</guilabel>.
  If checked, &frescobaldi; will check the <userinput>\version</userinput> statement in your
  document and choose the most suitable &lilypond; version from your installed list to run.
  This is the lowest available version number that's still higher than or equal to the document's version.
  You can exclude particular instances (e.g. development or testing versions) by unchecking the
  option <guilabel>Include in automatic version selection</guilabel> of that &lilypond; entry.
  </para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>&lilypond; version number to use for new documents</guilabel></term>
<listitem>
  <para>
  Here you can set which version number you want &frescobaldi; to insert by
  default with the <guilabel>Insert &lilypond; Version</guilabel> command or the
  Score Wizard. Choose one of three options:
  </para>
  <variablelist>
    <varlistentry>
    <term><guilabel>Use version number of installed &lilypond;</guilabel></term>
    <listitem>
      <para>
      &frescobaldi; will use the version number of the installed &lilypond; by
      default.
      </para>
      
      <para>
      (&frescobaldi; determines the version by running
      <command>lilypond</command> <option>-v</option> and looking at the first
      line of the output.)
      </para>
    </listitem>
    </varlistentry>
    
    <varlistentry>
    <term><guilabel>Use version number of last convert-ly rule</guilabel></term>
    <listitem>
      <para>
      &frescobaldi; will use the version number of last rule of the installed
      <command>convert-ly</command> program by default. This is useful if you
      just want your document to conform to the latest &lilypond; syntax without
      requiring the most recent available version.
      </para>
      
      <para>
      This makes document exchange easier.
      E.g. when you use <userinput>\version "2.12.2"</userinput>, another user's
      &lilypond; version 2.12.0 might complain about your document's version
      being to new, even though there are no syntax changes and the older
      &lilypond; would just compile the document fine.
      </para>
      
      <para>
      (&frescobaldi; determines the last convert-ly rule version by running
      <command>convert-ly</command> <option>--show-rules</option> and looking at
      the last line that starts with a version number.)
      </para>
    </listitem>
    </varlistentry>
    
    <varlistentry>
    <term><guilabel>Use custom version number</guilabel></term>
    <listitem>
      <para>
      Enables you to explicitly specify the version number you want to use by
      default for new documents.
      </para>
    </listitem>
    </varlistentry>
  </variablelist>
  
  <note><para>
  Note that the Score Wizard is able to adjust its output depending on the version
  you specify in the Score Wizard. It is therefore possible to write documents for
  older &lilypond; versions, although in general using the most recent stable
  &lilypond; release is recommended.
  </para></note>

</listitem>
</varlistentry>


<varlistentry>
<term><guilabel>Running &lilypond;</guilabel></term>
<listitem>
  <para>
  Here you can adjust how &lilypond; is run.
  </para>
  
  <variablelist>
    <varlistentry>
    <term><guilabel>Let &lilypond; delete intermediate files</guilabel></term>
    <listitem>
      <para>
      If checked, &frescobaldi; will run &lilypond; with the
      <option>delete-intermediate-files</option> option, so that e.g. PostScript
      files are deleted after the PDF file has been generated.
      </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><guilabel>Run &lilypond; with verbose output</guilabel></term>
    <listitem>
      <para>
      If checked, &frescobaldi; will run &lilypond; with the
      <option>verbose</option> option, displaying more information during the
      compile process.
      </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><guilabel>&lilypond; include path</guilabel></term>
    <listitem>
      <para>
      Here you can enter a list of directories that are searched for files that
      are included via the &lilypond; <userinput>\include</userinput> command.
      </para>
    </listitem>
    </varlistentry>
    
  </variablelist>
</listitem>
</varlistentry>
</variablelist>

</sect2>


<sect2 id="settings-paths">
<title>Paths</title>

<para>
Here you can specify the paths to use for different commands.
</para>

<variablelist>

<varlistentry>
<term><guilabel>Helper applications</guilabel></term>
<listitem>
  <para>
  Here you can specify paths to your favorite viewers for PDF and MIDI.
  If you leave the paths empty, the preferences set in KDE's System Settings
  are used.
  </para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>&lilypond; Documentation</guilabel></term>
<listitem>
  <para>
  You can also provide the URL or path to the documentation for the built-in
  <link linkend="lilydoc">&lilypond; documentation browser</link>.
  </para>
</listitem>
</varlistentry>

<varlistentry id="settings-hyphenation">
<term><guilabel>Hyphenation settings</guilabel></term>
<listitem>
  <para>
  Finally, at the bottom of the Paths section, you can configure a list of
  directories to search for hyphenation pattern files that can be used to break
  <link linkend="lyrics">lyrics</link> into syllables.
  </para>

  <para>
  &frescobaldi; currently does not include hyphenation pattern files by itself,
  but it can use the hyphenation patterns that are often installed with programs like
  <productname>OpenOffice.org</productname>, <productname>KOffice</productname>,
  <productname>Scribus</productname> or in specialized packages like <productname>myspell</productname>.
  </para>

  <para>
  If &frescobaldi; doesn't find any hyphenation files,
  while you're sure you installed some of the software mentioned above,
  try to find out where those files are in your file system, and list the paths
  in the text entry.
  If your operating system supports the <command>locate</command> command, you can open
  a terminal and use a command like this to get a list of paths that you can simply paste in the
  text entry to have &frescobaldi; find all installed pattern files:
  </para>

  <programlisting>locate '*/hyph_*.dic' | sed s,/[^/]*$,, | sort -u</programlisting>

  <para>or:</para>

  <programlisting>locate '*/hyph_*.dic' | xargs -n1 dirname | sort -u</programlisting>

</listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="settings-editor-component">
<title>Editor Component</title>

<para>
In this page you can configure the looks and behaviour of the documents tab bar.
</para>

<para>
Below this page,
configuration options can be set for the KatePart editor component that is used by &frescobaldi;.
Documentation for the editor component can be found in the manuals for
<ulink url="help:/kwrite/pref-dialog.html">KWrite</ulink> and
<ulink url="help:/kate/config-dialog-editor.html">Kate</ulink>.
</para>

</sect2>

</sect1>


<sect1 id="point-and-click">
<title>Configuring Point &amp; Click</title>

<para>
Point &amp; Click is a &lilypond; feature that embeds clickable URLs in the PDF output.
Those URLs contain the source file path and line and column numbers. Clicking on those
clickable objects lets the cursor in &frescobaldi; jump to the corresponding position
in the source document.
</para>

<para>
If all is well, Point &amp; Click should <trademark>"Just Work"</trademark>.
But this section is here to help you setting it up in the case it doesn't work
by default. Point &amp; Click in &frescobaldi; is handled differently in KDE 4.1 and KDE 4.2.
</para>

<para>
In KDE 4.1, you need to install the <literal>lilypond-kde4</literal> package.
This contains a program that handles the <literal>textedit:</literal> service.
If point and click still does not work, check if &frescobaldi; is tied to the
<literal>text/x-lilypond</literal> MIME type in the KDE System Settings
(File Associations).
</para>

<para>
In KDE 4.2, the Point &amp; Click URLs are handled by Okular itself.
When you install &frescobaldi;, on its first run it autoconfigures the Okular part
to run &frescobaldi; when a Point &amp; Click URL is clicked.
But if for some reason this didn't happen, you can configure Okular manually
to run &frescobaldi;.
The easiest way to do this is just clicking the button on the first page in the
<link linkend="settings-dialog">Settings Dialog</link>.
But you can also right-click the PDF preview tab and choose
<guimenuitem>Configure Okular...</guimenuitem> (or use
<menuchoice>
  <guimenu>Settings</guimenu>
  <guisubmenu>Tool Views</guisubmenu>
  <guimenuitem>Configure Okular...</guimenuitem>
</menuchoice>) to open the Okular settings dialog.
There, under <guilabel>Editor</guilabel>, you can configure a custom editor command.
Enter the following command and click <guibutton>Ok</guibutton>:
</para>

<programlisting>frescobaldi --smart --line %l --column %c</programlisting>

<para>
(The <option>smart</option> option tells &frescobaldi; to translate cursor positions according
to changes in the document. This way, Point &amp; Click URLs remain working, even if you
change the document without updating the PDF preview.)
</para>

<note><para>
Point &amp; Click URLs enlarge the PDF output documents significantly.
It is therefore better to build PDF documents in publish mode when you
want to distribute them (via e-mail or the World-wide Web) to others.
</para></note>

<warning><para>
In KDE 4.2, Okular's built-in Point &amp; Click support sometimes doesn't work
if the path of your &lilypond; source document contains spaces or accented characters.
This is due to Okular not fully understanding the way &lilypond; encodes URLs.
</para></warning>

</sect1>

<sect1 id="syntax">
<title>Highlighting and indenting</title>

<para>
&frescobaldi; uses the &lilypond; syntax highlighting and indenting algorithm from KDE's 
editing component KatePart. By default, indenting is switched on, using spaces,
and the indent-width is 2 spaces.
</para>

<para>
You can configure other indentation settings using kate variables in your document,
by setting kate variables in the &lilypond; Kate mode, or by simply adjusting the
default indentation in the
<link linkend="settings-editor-component">Editor component settings</link>.
</para>

<para>
Setting variables in the document is described
<ulink url="help:/kate/config-variables.html">here in the Kate manual</ulink>.
Setting variables globally for a specific file type (or Kate mode) is described
in the Kate manual under
&quot;<ulink url="help:/kate/config-dialog-editor.html#pref-open-save-modes-filetypes"
>Modes &amp; Filetypes</ulink>.&quot;
Select the <guilabel>Other/&lilypond;</guilabel> mode to enter settings that affect
&lilypond; files. (Kate and KWrite will also use the settings configured here.)
</para>

<para>
The default indentation settings will only have effect if they are not overridden
by variables set in the &lilypond; Kate mode or in the current document.
</para>

</sect1>

<sect1 id="download-lilypond">
<title>Download LilyPond packages</title>

<para>
&frescobaldi; can automatically download and install binary &lilypond; packages
(.sh packages) from the &lilypond; website.
</para>

<para>
To install e.g. a new development version of &lilypond;, go to &menu.settings.lilypond;
and click <guibutton>Add</guibutton>.
In the dialog that appears (to configure the path to a &lilypond; instance),
click <guibutton>Download</guibutton>.
Again a small dialog opens, where you can select the &lilypond; version you want to
download and a destination directory, which will be created if it doesn't exist.
</para>

<para>
Then click <guibutton>Install</guibutton>. After downloading and unpacking,
the dialog will disappear and the path to the newly installed &lilypond; will be
set in the underlying dialog.
Click <guibutton>Ok</guibutton> to add the new &lilypond; instance to the list
and then <guibutton>Ok</guibutton> to close the Settings dialog and apply your changes.
</para>

<para>
In the Download dialog,
you can also click <guibutton>Details</guibutton> to change the website where
the releases are downloaded from, or to manually browse to an already downloaded
package.
</para>

<note>
<para>
Inside the destination directory another directory will be created with the
version number of the &lilypond; version to be installed,
so different versions of &lilypond; can coexist in the same destination directory.
</para>

<para>
If you install the same version of &lilypond; again, &frescobaldi; will warn you
and offer the choice to remove and re-install it, or to just use it instead
of overwriting it.
</para>

<para>
When you remove versions of &lilypond; from the list in the settings dialog,
they are not removed from your file system.
If you really want to uninstall one of more &lilypond; versions,
you can just remove the directory of that version from the place where you
installed it.
</para>
</note>

</sect1>

</chapter>
