<?xml version="1.0" encoding="utf-8"?>
<sect2 id="usage-execution">
  <title>¿Qué acción se debe ejecutar?</title>
  <para>Lo más probable es que quiera que su acción termine ejecutando algo. Y, de hecho, tener algo que ejecutar es una de las pocas condiciones que se requieren para que una acción se considere válida.</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>Este comando puede tomar argumentos, que pueden ser a su vez parámetros empotrados. Estos parámetros se expandirán en tiempo de ejecución, con valores que dependerán de los elementos actualmente seleccionados.</para>

  <sect3 id="usage-execution-parameters">
    <title>Parámetros 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>Lista de parámetros disponibles</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-legend.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Muestra la lista de parámetros 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>¿Dónde se debe ejecutar la acción?</title>
    <para>Su acción se puede ejecutar en una carpeta de trabajo en particular.</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>Cuadro de la carpeta de trabajo</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-working-directory-frame.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>De el foco al cuadro de selección de carpeta de trabajo.</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>¿Cómo se debe ejecutar la acción?</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>Configuración de los modos de ejecución</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/cact-execution-tab.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Muestra cómo configurar los modos de ejecución de un comando.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>

    <sect4 id="usage-execution-how-mode">
      <title>Modo de ejecución</title>
      <figure id="cact-FIG-execution-mode">
        <title>Configuración del modo de ejecución</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/cact-exec-mode-frame.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase>De el foco al cuadro de modo de ejecución.</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
      <para>El modo de ejecución de su comando puede elegirse de entre los siguientes valores:</para>
      <variablelist>
        <varlistentry>
          <term>Normal</term>
          <listitem>
            <para>Inicia el comando como una interfaz de usuario gráfica estándar.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Terminal</term>
          <listitem>
            <para>Inicia la terminal preferida del entorno de escritorio, y ejecuta el comando en ella.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Empotrado</term>
          <listitem>
            <para>Utiliza una característica especial del gestor de archivos que permite ejecutar una terminal en él.</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>Mostrar salida</term>
          <listitem>
            <para>Inicia la terminal preferida del entorno de escritorio, y ejecuta el comando en ella. Cuando finaliza, se recogen y muestran las salidas estándar (stdout, stderr).</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>Notificación de inicio</title>
      <figure id="cact-FIG-startup-mode">
        <title>Configuración de los modos de inicio</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/cact-startup-mode-frame.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase>De foco al cuadro de modo de ejecución.</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>Clase de ventana</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>Propietario de la ejecución</title>
      <figure id="cact-FIG-execute-as">
        <title>Configuración del propietario de la ejecución</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 no introduce nada en este campo, entonces su comando se ejecutará como el usuario actual.</para>
    </sect4>

    <sect4 id="usage-execution-how-singular">
      <title>Ejecuciones múltiples</title>
      <para>Puede desear que su comando se ejecute una vez, proporcionándole la lista de los elementos seleccionados como argumento.</para>
      <para>O puede preferir que su comando se repita por cada elemento seleccionado, proporcionando un elemento diferente como argumento por cada ejecución.</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>Cuando la selección está vacía o contiene sólo un elemento, y desde el punto de vista de este tema, estas dos formas son exactamente equivalentes.</para>
      <para>Cuando la selección contiene más de un elemento:</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>Parámetro</entry>
              <entry>Descripción</entry>
              <entry namest="c3" nameend="c5">Repetición</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>%b</literal></entry>
              <entry>(primer) nombre base</entry>
              <entry>singular</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%B</literal></entry>
              <entry>lista de los nombres base separados por un espacio</entry>
              <entry/>
              <entry/>
              <entry>plural</entry>
            </row>
            <row>
              <entry><literal>%c</literal></entry>
              <entry>conteo de elementos seleccionados</entry>
              <entry/>
              <entry>irrelevante</entry>
              <entry/>
            </row>
            <row>
              <entry><literal>%d</literal></entry>
              <entry>(primera) carpeta base</entry>
              <entry>singular</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%D</literal></entry>
              <entry>lista separada por espacios de carpetas base de cada elemento seleccionado</entry>
              <entry/>
              <entry/>
              <entry>plural</entry>
            </row>
            <row>
              <entry><literal>%f</literal></entry>
              <entry>(primer) nombre de archivo</entry>
              <entry>singular</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%F</literal></entry>
              <entry>lista de los nombres de archivo seleccionados, separados por un espacio</entry>
              <entry/>
              <entry/>
              <entry>plural</entry>
            </row>
            <row>
              <entry><literal>%h</literal></entry>
              <entry>nombre del servidor del (primer) URI</entry>
              <entry/>
              <entry>irrelevante</entry>
              <entry/>
            </row>
            <row>
              <entry><literal>%m</literal></entry>
              <entry>tipo MIME del (primer) elemento seleccionado</entry>
              <entry>singular</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%M</literal></entry>
              <entry>lista separada por espacios de tipos MIME de cada elemento seleccionado</entry>
              <entry/>
              <entry/>
              <entry>plural</entry>
            </row>
            <row>
              <entry><literal>%n</literal></entry>
              <entry>nombre de usuario del (primer) URI</entry>
              <entry/>
              <entry>irrelevante</entry>
              <entry/>
            </row>
            <row>
              <entry><literal>%o</literal></entry>
              <entry>operador de no operación que fuerza una forma de ejecución singular</entry>
              <entry>singular</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%O</literal></entry>
              <entry>operador de no operación que fuerza una forma de ejecución plural</entry>
              <entry/>
              <entry/>
              <entry>plural</entry>
            </row>
            <row>
              <entry><literal>%p</literal></entry>
              <entry>número de puerto del (primer) URI</entry>
              <entry/>
              <entry>irrelevante</entry>
              <entry/>
            </row>
            <row>
              <entry><literal>%s</literal></entry>
              <entry>esquema del (primer) URI</entry>
              <entry/>
              <entry>irrelevante</entry>
              <entry/>
            </row>
            <row>
              <entry><literal>%u</literal></entry>
              <entry>(primer) URI</entry>
              <entry>singular</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%U</literal></entry>
              <entry>lista de URI separados por un espacio</entry>
              <entry/>
              <entry/>
              <entry>plural</entry>
            </row>
            <row>
              <entry><literal>%w</literal></entry>
              <entry>(primer) nombre base sin la extensión</entry>
              <entry>singular</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%W</literal></entry>
              <entry>lista de los nombres base sin extensión, separados por un espacio</entry>
              <entry/>
              <entry/>
              <entry>plural</entry>
            </row>
            <row>
              <entry><literal>%x</literal></entry>
              <entry>(primera) extensión</entry>
              <entry>singular</entry>
              <entry/>
              <entry/>
            </row>
            <row>
              <entry><literal>%X</literal></entry>
              <entry>lista de extensiones separadas por un espacio</entry>
              <entry/>
              <entry/>
              <entry>plural</entry>
            </row>
            <row>
              <entry><literal>%%</literal></entry>
              <entry>the « <literal>%</literal> » character</entry>
              <entry/>
              <entry>irrelevante</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>se ejecutarán sucesivamente los siguientes comandos:</para>
        </formalpara>
        <simplelist>
          <member><command>echo pedro</command></member>
          <member><command>echo pablo</command></member>
          <member><command>echo juan</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>se ejecutará el siguiente comando:</para>
        </formalpara>
        <simplelist>
          <member><command>echo pedro pablo juan</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>se ejecutarán sucesivamente los siguientes comandos:</para>
        </formalpara>
        <simplelist>
          <member><command>echo pedro pedro pablo juan</command></member>
          <member><command>echo pablo pedro pablo juan</command></member>
          <member><command>echo juan pedro pablo juan</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>se ejecutarán los siguientes comandos:</para>
        </formalpara>
        <simplelist>
          <member><command>echo pedro pablo juan pedro</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>
