<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
		<!ENTITY % darktable_dtd SYSTEM "../dtd/darktable.dtd">
		%darktable_dtd;
		]>
<sect1 status="final" id="session_options">

  <title>Session options</title>

  <indexterm>
    <primary>preferences and settings</primary>
    <secondary>session options</secondary>
  </indexterm>

  <para>
    These options define a naming pattern to organize images on disk when importing from a
    connected camera (see <xref linkend="import"/>) and when taking photos in the tethering view
    (see <xref linkend="tethering_chapter"/>).
  </para>

  <para>
    The naming pattern consists of three parts: a base part defining the parent folder, a
    session part defining a sub directory which is specific to the individual import session,
    and a file name part defining the filename structure for each imported image.
  </para>

  <para>
    Several pre-defined variables can be used in the pattern as placeholders:
  </para>

  <informaltable frame="none" width="80%">
    <tgroup cols="2" colsep="0" rowsep="0">
      <tbody>
        <row>
          <entry>
            $(HOME)
          </entry>
          <entry>
            the home folder as defined by the system
          </entry>
        </row>
        <row>
          <entry>
            $(PICTURES_FOLDER)
          </entry>
          <entry>
            the pictures folder as defined by the system (usually <quote>$HOME/Pictures</quote>)
          </entry>
        </row>
        <row>
          <entry>
            $(DESKTOP)
          </entry>
          <entry>
            the desktop folder as defined by the system (usually <quote>$HOME/Desktop</quote>)
          </entry>
        </row>
        <row>
          <entry>
            $(USERNAME)
          </entry>
          <entry>
            your user account name on the system
          </entry>
        </row>
        <row>
          <entry>
            $(FILE_NAME)
          </entry>
          <entry>
            basename of the imported image
          </entry>
        </row>
        <row>
          <entry>
            $(FILE_EXTENSION)
          </entry>
          <entry>
            extension of the imported image
          </entry>
        </row>
        <row>
          <entry>
            $(JOBCODE)
          </entry>
          <entry>
            unique identifier of the import job
          </entry>
        </row>
        <row>
          <entry>
            $(SEQUENCE)
          </entry>
          <entry>
            a sequence number within the import job
          </entry>
        </row>
        <row>
          <entry>
            $(ID)
          </entry>
          <entry>
            unique identification number of the image in darktable's database
          </entry>
        </row>
        <row>
          <entry>
            $(YEAR)
          </entry>
          <entry>
            year at the date of import
          </entry>
        </row>
        <row>
          <entry>
            $(MONTH)
          </entry>
          <entry>
            month at the date of import
          </entry>
        </row>
        <row>
          <entry>
            $(DAY)
          </entry>
          <entry>
            day at the date of import
          </entry>
        </row>
        <row>
          <entry>
            $(HOUR)
          </entry>
          <entry>
            hour at the time of import
          </entry>
        </row>
        <row>
          <entry>
            $(MINUTE)
          </entry>
          <entry>
            minute at the time of import
          </entry>
        </row>
        <row>
          <entry>
            $(SECOND)
          </entry>
          <entry>
            second at the time of import
          </entry>
        </row>
        <row>
          <entry>
            $(EXIF_YEAR)
          </entry>
          <entry>
            year the photo was taken (from Exif data)
          </entry>
        </row>
        <row>
          <entry>
            $(EXIF_MONTH)
          </entry>
          <entry>
            month the photo was taken (from Exif data)
          </entry>
        </row>
        <row>
          <entry>
            $(EXIF_DAY)
          </entry>
          <entry>
            day the photo was taken (from Exif data)
          </entry>
        </row>
        <row>
          <entry>
            $(EXIF_HOUR)
          </entry>
          <entry>
            hour the photo was taken (from Exif data)
          </entry>
        </row>
        <row>
          <entry>
            $(EXIF_MINUTE)
          </entry>
          <entry>
            minute the photo was taken (from Exif data)
          </entry>
        </row>
        <row>
          <entry>
            $(EXIF_SECOND)
          </entry>
          <entry>
            seconds the photo was taken (from Exif data)
          </entry>
        </row>
        <row>
          <entry>
            $(EXIF_ISO)
          </entry>
          <entry>
            ISO value of the photo (from Exif data)
          </entry>
        </row>
      </tbody>
    </tgroup>
  </informaltable>

  <bridgehead renderas="sect4">base directory naming pattern</bridgehead>

  <para>
    The base directory part of the naming pattern (default
    <quote>$(PICTURES_FOLDER)/Darktable</quote>).
  </para>

  <bridgehead renderas="sect4">sub directory naming pattern</bridgehead>

  <para>
    The sub directory part of the naming pattern (default
    <quote>$(YEAR)$(MONTH)$(DAY)_$(JOBCODE)</quote>).
  </para>

  <bridgehead renderas="sect4">file naming pattern</bridgehead>

  <para>
    The file name part of the naming pattern (default
    <quote>$(YEAR)$(MONTH)$(DAY)_$(SEQUENCE).$(FILE_EXTENSION</quote>).
  </para>

</sect1>