<?xml version="1.0" encoding="utf-8"?>
<sect2 id="usage-execution">
  <title>Action à exécuter</title>
  <para>Vous souhaitez selon toute vraisemblance que votre action soit clôturée par l'exécution de quelque chose. Et bien, pragmatiquement, avoir quelque chose à exécuter est une des quelques conditions requises pour qu'une action soit considérée comme valide.</para>
  <para>
    As we have already seen, the command to be executed is configured
      <!-- i18n: "Command" is a UI label -->
    in the <guilabel>Command</guilabel> page.
  </para>
  <para>Cette commande peut prendre des paramètres, qui eux-mêmes peuvent incorporer d'autres paramètres. Ces paramètres sont développés lors de l'exécution avec les valeurs dépendantes des éléments actuellement sélectionnés.</para>

  <sect3 id="usage-execution-parameters">
    <title>Paramètres disponibles</title>
    <para>
      <!-- i18n: "Command" is a UI label -->
      In the <guilabel>Command</guilabel> page,
      <!-- i18n: "Legend" is a UI label -->
      click on <guilabel>Legend</guilabel>
      button to see the list of available parameters.
    </para>
    <figure id="cact-FIG-legend">
      <title>Liste des paramètres disponibles</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-legend.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Affiche la liste des paramètres disponibles.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
    <tip>
      <para>
        <!-- i18n: "Legend" is a UI label -->
        The <guibutton>Legend</guibutton> button has a toggling action:
        <!-- i18n: "Parameter Legend" is a UI label -->
        click once to display the <guilabel>Parameter Legend</guilabel>
        dialog box; click a second time to hide it.
      </para>
    </tip>
    <note>
      <para>
        <!-- i18n: "first" is a UI label -->
        The word « <guilabel>first</guilabel> » may be
        misleading as it only refers to the list of selected items
        internally provided by the file manager to the <productname>Caja-Actions</productname> plugin.
      </para>
      <para>
        In particular, it has <emphasis>nothing to do</emphasis> with
        the visual selection you may have done in the file manager window.
        <!-- i18n: "first" is a UI label -->
        And, in fact, which is the « <guilabel>first</guilabel> »
        selected item in a multiple selection is absolutely undefined
        and rather unpredictable.
      </para>
    </note>
  </sect3>

  <sect3 id="usage-execution-work">
    <title>Emplacement où l'action est exécutée</title>
    <para>Votre action peut être exécutée dans un répertoire de travail donné.</para>
    <para>
      <!-- i18n: "Command" is a UI label -->
      You may specify it in the <guilabel>Command</guilabel> tab, in the
      <!-- i18n: "Working directory" is a UI label -->
      <guilabel>Working directory</guilabel> entry box, or by clicking
      <!-- i18n: "Browse" is a UI (button) label -->
      on <guibutton>Browse</guibutton> to select a folder on the 
      filesystem.
    </para>
    <figure id="cact-FIG-work-dir-frame">
      <title>Encadré Répertoire de travail</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-working-directory-frame.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Détail de l'encadré pour la sélection du répertoire de travail.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
    <para>
      The working directory defaults to <literal>%d</literal>, which
      runs the command in the base directory of the (first) selected
      item.
    </para>
    <para>
      In the particular case of the <literal>%d</literal> parameter,
      <!-- i18n: "first" is a UI label -->
      the « <guilabel>first</guilabel> » selected item
      is not very important because it is very likely that all selected
      items are located in the same base directory.
    </para>
  </sect3>

  <sect3 id="usage-execution-how">
    <title>Mode d'exécution de l'action</title>
    <para>
      Apart from configuring the conditions, the selection must be met
      in order your action be displayed in file manager menus, <productname>Caja-Actions</productname>
      allows you to configure how exactly your command will be
      executed.
    </para>
    <para>
      <!-- i18n: "Execution" is a UI label -->
      Click on the <guilabel>Execution</guilabel> tab to show the page
      which configures the execution of your command.
    </para>
    <figure id="cact-FIG-execution">
      <title>Configuration des modes d'exécution</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-execution-tab.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Affiche comment configurer les modes d'exécution d'une commande.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>

    <sect4 id="usage-execution-how-mode">
      <title>Mode d'exécution</title>
      <figure id="cact-FIG-execution-mode">
        <title>Configuration du mode d'exécution</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/cact-exec-mode-frame.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase>Détail de l'encadré concernant le mode d'exécution.</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
      <para>Le mode d'exécution de la commande peut être choisi parmi les valeurs suivantes :</para>
      <variablelist>
        <varlistentry>
          <term>Normal</term>
          <listitem>
            <para>Lance la commande dans l'interface utilisateur graphique standard.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Dans un terminal</term>
          <listitem>
            <para>Ouvre le terminal préféré de l'environnement bureau et y lance la commande.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Incorporé</term>
          <listitem>
            <para>Utilise une fonctionnalité spéciale du gestionnaire de fichiers qui peut autoriser l'ouverture d'un terminal dans sa fenêtre.</para>
            <para>
              As <productname>Caja</productname> does not have this feature, this option is strictly
              equivalent to <literal>Terminal</literal> option.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Affichage des sorties</term>
          <listitem>
            <para>Ouvre le terminal préféré de l'environnement bureau et y lance la commande. À la fin, les flux standard (stdout, stderr) sont rassemblés et affichés.</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>
        The execution mode of a command defaults to <literal>Normal</literal>.
        That is, the command is executed without any particular pre- or
        post-work.
      </para>
    </sect4>

    <sect4 id="usage-execution-how-notify">
      <title>Notification de lancement</title>
      <figure id="cact-FIG-startup-mode">
        <title>Configuration des modes de lancement</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/cact-startup-mode-frame.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase>Détail de l'encadré du mode de lancement.</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
      <para>
        If the execution mode of the command is <literal>Normal</literal>,
        <!-- i18n: "remove" is a X literal, do not translate -->
        and if you know that the application will send a <literal>remove</literal>
        message with the <envar>DESKTOP_STARTUP_ID</envar> environment variable set,
        <!-- i18n: "Startup notify" is a UI label -->
        then check the <guilabel>Startup notify</guilabel> checkbox.
      </para>
      <para>See the <ulink url="http://www.freedesktop.org/Standards/startup-notification-spec" type="http"><citetitle>Startup Notification Protocol Specification</citetitle></ulink> for more details.</para>
    </sect4>

    <sect4 id="usage-execution-how-class">
      <title>Classe de la fenêtre</title>
      <para>
        If the execution mode of the command is <literal>Normal</literal>,
        and if you know that the application will map at least one window
        with a given class name, then enter that name into the
        <!-- i18n: "Startup Window Manager class" is a UI label -->
         <guilabel>Startup Window Manager class</guilabel>
        entry box.
      </para>
      <para>See the <ulink url="http://www.freedesktop.org/Standards/startup-notification-spec" type="http"><citetitle>Startup Notification Protocol Specification</citetitle></ulink> for more details.</para>
    </sect4>

    <sect4 id="usage-execution-how-user">
      <title>Propriétaire de l'exécution</title>
      <figure id="cact-FIG-execute-as">
        <title>Configuration du propriétaire du lancement</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/cact-execute-as-frame.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase>Focus on the <guilabel>Execute as</guilabel> frame.</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
      <para>
        Enter in the <guilabel>Execute as user</guilabel> entry box the
        username or the <acronym>UID</acronym> of the user your command
        will be run as.
      </para>
      <para>Si vous ne saisissez rien dans ce champ, la commande est alors exécutée au nom de l'utilisateur en cours.</para>
    </sect4>

    <sect4 id="usage-execution-how-singular">
      <title>Exécutions multiples</title>
      <para>Vous pouvez souhaiter que la commande soit exécutée une fois, en lui donnant la liste des éléments sélectionnés comme argument.</para>
      <para>Vous pouvez aussi préférer que votre commande soit répétée pour chaque élément sélectionné, en donnant pour chaque exécution un élément différent comme argument.</para>
      <para>
        Actually, <productname>Caja-Actions</productname> automatically handles these two behaviors,
        depending of the form and the order of the parameters in the
        command arguments.
      </para>
      <para>
        Though some parameters are not depending on the count of the
        selection (<abbrev>e.g.</abbrev> « <literal>%c</literal> »,
        the selection count itself), most have two declensions:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            a « singular » one, <abbrev>e.g.</abbrev>
            « <literal>%b</literal> »,
            the basename of the selected item;
          </para>
        </listitem>
        <listitem>
          <para>
            a « plural » one, <abbrev>e.g.</abbrev>
            « <literal>%B</literal> »,
            the space-separated list of the basenames of selected items.
          </para>
        </listitem>
      </itemizedlist>
      <para>Quand la sélection est vide ou ne comporte qu'un seul élément, ces deux formes sont rigoureusement équivalentes pour ce qui concerne ce paragraphe.</para>
      <para>Quand la sélection comporte plus d'un élément :</para>
      <itemizedlist>
        <listitem>
          <para>
            if the first relevant parameter is of a singular form,
            then <productname>Caja-Actions</productname> will consider that the command is only able
            to deal with one item at a time, and thus that it has to be
            ran one time for each selected item;
          </para>
        </listitem>
        <listitem>
          <para>
            contrarily, if the first relevant parameter found is of the
            plural form, then <productname>Caja-Actions</productname> will consider that the command
            is able to deal with a list of items, and thus the command
            will be executed only once;
          </para>
        </listitem>
        <listitem>
          <para>
            if all found parameters are irrelevant, then <productname>Caja-Actions</productname> defaults
            to consider that the command should be executed only once.
          </para>
        </listitem>
      </itemizedlist>
      <table id="cact-TAB-multiple-execution" frame="all" tocentry="1">
        <title>Characterization of the parameters <abbrev>vs.</abbrev> multiple execution</title>
        <tgroup cols="5">
          <colspec align="center" colwidth="*"/>
          <colspec align="left" colwidth="5*"/>
          <colspec align="center" colwidth="*" colname="c3"/>
          <colspec align="center" colwidth="*"/>
          <colspec align="center" colwidth="*" colname="c5"/>
          <thead>
            <row>
              <entry>Paramètre</entry>
              <entry>Description</entry>
              <entry namest="c3" nameend="c5">Répétition</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>%b</literal></entry>
              <entry>(premier) nom de base</entry>
              <entry>au singulier</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%B</literal></entry>
              <entry>liste des noms de base séparés par des espaces</entry>
              <entry/>
              <entry/>
              <entry>au pluriel</entry>
            </row>
            <row>
              <entry><literal>%c</literal></entry>
              <entry>nombre d'éléments sélectionnés</entry>
              <entry/>
              <entry>non pertinent</entry>
              <entry/>
            </row>
            <row>
              <entry><literal>%d</literal></entry>
              <entry>(premier) répertoire de base</entry>
              <entry>au singulier</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%D</literal></entry>
              <entry>liste des répertoires de base de chaque élément sélectionné séparés par des espaces</entry>
              <entry/>
              <entry/>
              <entry>au pluriel</entry>
            </row>
            <row>
              <entry><literal>%f</literal></entry>
              <entry>(premier) nom de fichier</entry>
              <entry>au singulier</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%F</literal></entry>
              <entry>liste des noms des fichiers sélectionnés séparés par des espaces</entry>
              <entry/>
              <entry/>
              <entry>au pluriel</entry>
            </row>
            <row>
              <entry><literal>%h</literal></entry>
              <entry>nom d'hôte du (premier) URI</entry>
              <entry/>
              <entry>non pertinent</entry>
              <entry/>
            </row>
            <row>
              <entry><literal>%m</literal></entry>
              <entry>type MIME du (premier) élément sélectionné</entry>
              <entry>au singulier</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%M</literal></entry>
              <entry>liste des types MIME des éléments sélectionnés séparés par des espaces</entry>
              <entry/>
              <entry/>
              <entry>au pluriel</entry>
            </row>
            <row>
              <entry><literal>%n</literal></entry>
              <entry>nom d'utilisateur du (premier) URI</entry>
              <entry/>
              <entry>non pertinent</entry>
              <entry/>
            </row>
            <row>
              <entry><literal>%o</literal></entry>
              <entry>opérateur qui force l'exécution de l'action fichier par fichier</entry>
              <entry>au singulier</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%O</literal></entry>
              <entry>opérateur qui force l'exécution de l'action simultanément sur plusieurs fichiers</entry>
              <entry/>
              <entry/>
              <entry>au pluriel</entry>
            </row>
            <row>
              <entry><literal>%p</literal></entry>
              <entry>numéro de port du (premier) URI</entry>
              <entry/>
              <entry>non pertinent</entry>
              <entry/>
            </row>
            <row>
              <entry><literal>%s</literal></entry>
              <entry>protocole du (premier) URI</entry>
              <entry/>
              <entry>non pertinent</entry>
              <entry/>
            </row>
            <row>
              <entry><literal>%u</literal></entry>
              <entry>(premier) URI</entry>
              <entry>au singulier</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%U</literal></entry>
              <entry>liste des URI sélectionnés séparés par des espaces</entry>
              <entry/>
              <entry/>
              <entry>au pluriel</entry>
            </row>
            <row>
              <entry><literal>%w</literal></entry>
              <entry>(premier) nom de base sans extension</entry>
              <entry>au singulier</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%W</literal></entry>
              <entry>liste des noms de base sans extension séparés par des espaces</entry>
              <entry/>
              <entry/>
              <entry>au pluriel</entry>
            </row>
            <row>
              <entry><literal>%x</literal></entry>
              <entry>(première) extension</entry>
              <entry>au singulier</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%X</literal></entry>
              <entry>liste des extensions séparées par des espaces</entry>
              <entry/>
              <entry/>
              <entry>au pluriel</entry>
            </row>
            <row>
              <entry><literal>%%</literal></entry>
              <entry>the « <literal>%</literal> » character</entry>
              <entry/>
              <entry>non pertinent</entry>
              <entry/>
            </row>
          </tbody>
        </tgroup>
      </table>
      <example>
        <title>Usage of singular <abbrev>vs.</abbrev> plural forms</title>
        <para>
          Say the current folder is <filename>/data</filename>,
          and the current selection contains the three files
          <filename>pierre</filename>, <filename>paul</filename>
          and <filename>jacques</filename>.
        </para>
        <formalpara>
          <title>
            If we have requested <command>echo %b</command>,
          </title>
          <para>alors les trois commandes suivantes sont successivement exécutées :</para>
        </formalpara>
        <simplelist>
          <member><command>echo pierre</command></member>
          <member><command>echo paul</command></member>
          <member><command>echo jacques</command></member>
        </simplelist>
        <para>
          This is because <literal>%b</literal> marks a <emphasis>singular</emphasis>
          parameter. The command is then run once for each of the selected items.
        </para>
        <formalpara>
          <title>
            Contrarily, if we have requested <command>echo %B</command>,
          </title>
          <para>alors la commande suivante est lancée :</para>
        </formalpara>
        <simplelist>
          <member><command>echo pierre paul jacques</command></member>
        </simplelist>
        <para>
          This is because <literal>%B</literal> marks a <emphasis>plural</emphasis>
          parameter. The command is then run only once, with the list of selected
          items as arguments.
        </para>
        <formalpara>
          <title>
            If we have requested <command>echo %b %B</command>,
          </title>
          <para>alors les trois commandes suivantes sont successivement exécutées :</para>
        </formalpara>
        <simplelist>
          <member><command>echo pierre pierre paul jacques</command></member>
          <member><command>echo paul pierre paul jacques</command></member>
          <member><command>echo jacques pierre paul jacques</command></member>
        </simplelist>
        <para>
          This is because the first <emphasis>relevant</emphasis> parameter
          is <literal>%b</literal>, and so the command is run once for each
          selected item, replacing at each occurrence the <literal>%b</literal>
          parameter with the corresponding item. The second parameter is
          computed and added as arguments to the executed command.
        </para>
        <formalpara>
          <title>
            And if we have requested <literal>echo %B %b</literal>,
          </title>
          <para>alors la commande ci-après serait lancée :</para>
        </formalpara>
        <simplelist>
          <member><command>echo pierre paul jacques pierre</command></member>
        </simplelist>
        <para>
          This is because the first <emphasis>relevant</emphasis>
          parameter here is <literal>%B</literal>. The command is then
          run only once, replacing <literal>%B</literal> with the
          space-separated list of basenames. As the command is only run
          once, the <literal>%b</literal> is substituted only once with
          the (first) basename. 
        </para>
      </example>
   </sect4>
  </sect3>

</sect2>
