<page xmlns="http://projectmallard.org/1.0/"
      xmlns:e="http://projectmallard.org/experimental/"
      type="guide"
      id="gui-edit">

  <info>
    <link type="guide" xref="gui"/>
    <revision pkgversion="1.2.14" version="0.1" date="2010-05-04" status="incomplete"/>
    <revision pkgversion="1.2.15" version="0.2" date="2010-11-29" status="final"/>
    <desc>
      Editing entries.
    </desc>
    <credit type="author">
      <name>Zolt&#225;n K&#243;ta</name>
      <email>zoltank@gmail.com</email>
    </credit>
    <credit type="author">
      <name>Fr&#233;d&#233;ric Gobry</name>
      <email>frederic.gobry@epfl.ch</email>
    </credit>
    <license>
      <p>Creative Commons Share Alike 3.0</p>
    </license>    
  </info>
    <title>Editing</title>

    <section id="gui-edit-basic">
      <title>Basic editing</title>


    <p><media type="image" mime="image/png" src="figures/edit.png">
    The Edition window
    </media></p>
      
      <p>The edition window is represented in the figure above.
      On the right of each field, a symbol indicates if <app>Pybliographer</app>
      has been able to render all the information given in that  field. For
      example, a BibTeX field containing an unknown command name cannot
      be correctly represented. In that case, <app>Pybliographer</app> provides
      a fake representation, and indicates it was not able to do a good job 
      on this field by setting a red symbol on its right, instead of a green one.
      </p>
    <note type="warning">
      <p>If you edit such an  entry, you can loose  the additional
      information it  contained. To avoid this,  consider using native
      editing (see <link xref="gui-edit#gui-edit-native" />).</p>
    </note>

    <p>To edit the entries, simply type the corresponding text, without
      any consideration for the database format being used. For example,
      with <app>BibTeX</app>, don't add any <em>{</em> or special characters
      to influence the result, as they will be quoted by the system. For
      fields requiring names (like author and editor), use the following
      format: type one name per line, in the <em>last name, lineage, first
      name</em> order. If an author or editor field has too many names,
      you can end the list of names with <em>others</em>; the standard bibtex
      styles convert this to <em>et al</em>.
    </p>
    <p>In addition to the standard fields, you can create your 
     own fields using the <gui>Create Field</gui> button.
    </p>
    <note style="tip">
      <p>You can customize the mandatory and optional fields for 
      the different type of entries. For example, associating the 
      <em>URL</em> field with a given type of entry, it is 
      possible to assign an url to an entry (e.g. the 
      location of the pdf version of an article or the address of a 
      website). See the window below. More information about 
      the association of fields can be found in 
      <link xref="gui-settings" />.</p>
    </note>

    <p><media type="image" mime="image/png" src="figures/edit2.png">
    The Edition window - Optional fields
    </media></p>

    <p>The  following  keyboard   shortcuts  are  available  during
      edition  (in   addition  to   the  standard  ones   provided  by
      Gtk):</p>
    <list>
      <item>
	<p>
        <keyseq><key>Ctrl</key><key>TAB</key></keyseq>
        to jump to the next field</p>
      </item>
      <item>
	<p>
        <keyseq><key>Shift</key><key>TAB</key></keyseq>
        to jump to the previous field</p>
      </item>
      <item>
	<p>
        <keyseq><key>Ctrl</key><key>Enter</key></keyseq>
        to accept the modifications</p>
      </item>
      <item>
	<p><key>Esc</key> to cancel the edition</p>
      </item>
    </list>

    <p>To specify a crossreference to another entry, just drag the
      entry from the main list to the <gui>Crossreference</gui> field.
      To remove a crossreference, drag an empty selection on the field.
      To unselect all the entries, you might need to use the
      <key>Control</key> key, while clicking on the  entry.</p>
    </section>

    <section id="gui-edit-native">
      <title>Native editing</title>

      <p>For databases like BibTeX that provide a specific syntax
	(called <em>native</em> syntax), it is possible to directly edit
        the entry in this format. Just click the button	called
        <gui>Native Editing</gui> at the bottom of the window and type 
        the entry in its native form.
      </p>
      
      <p>It is also possible to type native commands in the normal editing
	window. For example, if you want to use special LaTeX commands like
	<cmd>\textbf</cmd> in a title, you can type them  directly in the
	<gui>Title</gui> field by preceding the text with a <em>@</em>
	symbol (as the first character). After that symbol, you have to use
	all the BibTeX conventions (braces, backslashes,...), as none of
	them will be escaped or modified by <app>Pybliographer</app>.</p>

    </section>
    
  </page>

