<chapter id="editing">
<title>Editing Features</title>

<para>
While editing, &frescobaldi; provides many ways to change and manipulate already entered music. 
</para>

<sect1 id="rhythm">
<title>Rhythm</title>

<para>
In the <menuchoice><guimenu>&lilypond;</guimenu><guisubmenu>Rhythm</guisubmenu></menuchoice>
menu there are many options to manipulate the durations
of a selected music fragment. You can double or halve the durations, add or
remove dots, remove scaling (the <userinput>*n/m</userinput> suffix) or remove all durations.
<guimenuitem>Make implicit</guimenuitem> removes durations that are equal to the previous note, and
<guimenuitem>Make explicit</guimenuitem> adds the duration to every note or chord, even if it has the same
duration as the previous one. 
</para>

<para>
You can also copy a rhythm from a selected piece of music. The rhythm is then
copied to the clipboard. To "paste" the rhythm to other music you must then
select the target music. <guimenuitem>Paste Rhythm</guimenuitem> will then apply the copied rhythm to the
newly selected music. This is nice when you enter e.g. hymns that have multiple
voices that share the same rhythm. You can also use <guimenuitem>Apply Rhythm...</guimenuitem> to manually
enter some durations and apply them to a selected fragment of music.
If there are more notes than durations, the durations will be repeated.
</para>
</sect1>

<sect1 id="pitch">
<title>Pitch</title>

<para>
The <menuchoice><guimenu>&lilypond;</guimenu><guisubmenu>Pitch</guisubmenu></menuchoice>
menu has several commands to manipulate pitches of already entered music:
</para>

<variablelist>

<varlistentry>
<term><guilabel>Pitch Name Language</guilabel></term>
<listitem>
  <para>
  This command is very powerful: it translates pitch names in your
  document to a different &lilypond; language. This is useful when you want to edit
  a work started by someone else, but are not accustomed to entering notes with e.g.
  Dutch or Italian names. 
  </para>
  <para>
  The pitch translation function is quite accurate: it almost 100% correctly
  parses &lilypond; input and finds all pitches, without altering e.g. markup,
  lyrics, strings or comments that might contain words (like "do") that are
  also pitch names. It even warns you when quarter tones are used and the target
  languages does not have definitions for them. But just to be sure: run &lilypond;
  after translating the pitches and carefully examine the document. If anything
  went wrong, press <keycap>Ctrl+Z</keycap> and try again.
  </para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Convert Relative to Absolute</guilabel></term>
<listitem>
  <para>
  This command converts all notes in the document or selected fragment that
  are inside a <userinput>\relative { ... }</userinput> section to absolute
  pitches. It honors octave checks (see the &lilypond; manual) but does not print
  warnings.
  </para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Convert Absolute to Relative</guilabel></term>
<listitem>
  <para>
  This command converts all notes in the selected music expression(s) to
  relative pitches, inserting a <userinput>\relative</userinput> command
  at the beginning of each selected music expression.
  A music expression is a piece of music enclosed in
  <userinput>&lt;&lt; ... &gt;&gt;</userinput> or <userinput>{ ... }</userinput>.
  If no music is selected, all toplevel expressions that contain notes are made relative.
  Chordmode sections (music inside <userinput>\chordmode</userinput> or <userinput>\chords</userinput>)
  are not made relative.
  </para>
</listitem>
</varlistentry>

<varlistentry id="transpose">
<term><guilabel>Transpose...</guilabel></term>
<listitem>
  <para>
  This command transposes all music in the document or selected fragment.
  A dialog is displayed where you can enter two pitches,
  the &quot;from&quot; and the &quot;to&quot; pitch.
  &frescobaldi; then computes the distance between the two pitches and transposes the music
  over the same distance. Both absolute and relative music can be transposed.
  Chordmode sections are transposed without changing the octave.
  </para>
</listitem>
</varlistentry>

</variablelist>


</sect1>

<sect1 id="lyrics">
<title>Lyrics</title>

<para>
&frescobaldi; can automatically place hyphens <userinput>'&nbsp;--&nbsp;'</userinput> inside texts to make those
texts usable as lyrics. It can use hyphenation dictionaries of <productname>OpenOffice.org</productname>,
<productname>Scribus</productname>, <productname>KOffice</productname>, etc.
</para>

<para>
To use this feature you must first select the text you want to hyphenate. Then
choose &menu.lilypond.hyphenation;.
In the dialog that appears, select the language. Click <guibutton>OK</guibutton>
or press <keycap>Enter</keycap> to have the hyphenation take place. 
</para>

<para>
A small limitation is that word processor hyphenation dictionaries often don't
want to break a word right after the first letter (e.g. <userinput>a&nbsp;--&nbsp;men</userinput>), because that
does not look nice in word processor texts. So it might be possible that you
have to add some hyphens after the first letter of such lyrics. 
</para>

<para>
There is also a command to remove hyphenation. This can be useful if you have a
stanza of lyrics that you just want to display as a markup below the music.
Under &menu.settings.paths; you can enter a <link linkend="settings-paths">list of
directories</link> to search for hyphenation pattern files.
</para>
</sect1>

<sect1 id="cut-assign">
<title>Cut and Assign</title>

<para>
If you find that you want to use the same &lilypond; commands or music fragment
more than once in multiple places in your document, but have already entered
them in some structure, there is a quick command to cut the fragment out and
put it as a toplevel variable assignment in your &lilypond; document.
</para>

<para>
First select the exact text you want to store in a variable. Then choose
<menuchoice>
  <shortcut><keycombo><keycap>Ctrl+Shift+C</keycap></keycombo></shortcut>
  <guimenu>Edit</guimenu>
  <guimenuitem>Cut and Assign</guimenuitem>
</menuchoice> and enter a &lilypond; variable name.
This identifier name may only contain letters. Then click
<guibutton>Ok</guibutton>. The selected fragment will be cut from its original
place and assigned to the specified variable. The assignment is placed just
before the current section in your document. The fragment will be replaced
with a reference to the variable.
</para>
</sect1>

<sect1 id="keybindings">
<title>Keyboard Shortcuts</title>

<para>
&frescobaldi; uses the KatePart text editing component of KDE. So, in addition to the
shortcuts outlined below, you can also use the many keyboard shortcuts available in e.g.
<ulink url="help:/kate/working-with-kate.html#keystroke-commands">Kate</ulink> and
<ulink url="help:/kwrite/keybindings.html">KWrite</ulink>.
</para>

<informaltable>
<tgroup cols="2">
<tbody>

<row>
<entry><para><keycombo><keycap>Alt+Up/Down</keycap></keycombo></para></entry>
<entry><para> Move the cursor to the end of the next or previous blank line </para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Alt+Shift+Up/Down</keycap></keycombo></para></entry>
<entry><para> Select text till the next or previous blank line </para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Alt+Ctrl+Shift+Up/Down</keycap></keycombo></para></entry>
<entry><para> Move the selected block to the next or previous blank line </para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+D</keycap></keycombo></para></entry>
<entry><para> Comment out the current line or selected text </para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+Shift+D</keycap></keycombo></para></entry>
<entry><para> Uncomment the current line or selected text </para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+;</keycap></keycombo></para></entry>
<entry><para> Repeat the last entered note or chord with all added articulations, etc </para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+{</keycap></keycombo></para></entry>
<entry><para>
Insert a pair of braces <userinput>{ }</userinput> with an empty,
indented line in between and places the cursor there.
If text is selected, it is placed between the braces.
</para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+.</keycap></keycombo></para></entry>
<entry><para>
Replace the entered mnemonic with the corresponding snippet from the
<link linkend="expand">Expand Manager</link>,
or, if no existing mnemonic was typed, show the Expand Manager dialog
</para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+Space</keycap></keycombo></para></entry>
<entry><para> Show the available <link linkend="autocomplete">completions</link> </para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+'</keycap></keycombo></para></entry>
<entry><para>
Insert a single typographical quote. Left or right is automatically determined.
If text is selected, that text is put between left and right single quotes.
</para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+&quot;</keycap></keycombo></para></entry>
<entry><para>
Insert a double typographical quote. Left or right is automatically determined.
If text is selected, that text is put between left and right double quotes.
</para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+Shift+C</keycap></keycombo></para></entry>
<entry><para><link linkend="cut-assign">Cut and assign</link></para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+Shift+V</keycap></keycombo></para></entry>
<entry><para>
Insert a <userinput>\version</userinput> command with the default &lilypond; version number.
Which version number is used can be configured in the
<link linkend="settings-general-preferences">Settings dialog</link>.
</para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+Shift+R</keycap></keycombo></para></entry>
<entry><para>
Wrap the selected music in a <userinput>\repeat volta 2 { ... }</userinput>
construct.
</para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+Shift+N</keycap></keycombo></para></entry>
<entry><para> Show the <link linkend="scorewiz">Score Wizard</link> </para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+M</keycap></keycombo></para></entry>
<entry><para> Run &lilypond; on the current document in preview mode </para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+L</keycap></keycombo></para></entry>
<entry><para>
<link linkend="lyrics">Hyphenate</link> the currently selected lyric text
</para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+E</keycap></keycombo></para></entry>
<entry><para>
Email the generated output documents (PDF, MIDI, etc.) after a &lilypond; run
</para></entry>
</row>

<row>
<entry><para><keycombo><keycap>Ctrl+Shift+F</keycap></keycombo></para></entry>
<entry><para> Toggle Full-screen mode </para></entry>
</row>

</tbody></tgroup></informaltable>

<para>
You can change the keyboard shortcuts and also add shortcuts for actions that don't
have one by default, by choosing
<menuchoice>
  <guimenu>Settings</guimenu>
  <guimenuitem>Configure Shortcuts...</guimenuitem>
</menuchoice>
or by right-clicking the respective menu entries.
</para>

</sect1>
</chapter>