<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appletversion "2.5.4">
  <!ENTITY manrevision "2.7">
  <!ENTITY date "February 2004">
  <!ENTITY applet "Command Line">
]>
<!-- 
      (Do not remove this comment block.)
  Maintained by the GNOME Documentation Project
  http://developer.gnome.org/projects/gdp 
  Template version: 2.0 beta
  Template last modified Feb 12, 2002
  
-->
<!-- =============Document Header ============================= -->
<article id="index" lang="en">
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->
  <articleinfo> 
     <title>&applet; Applet Manual V&manrevision;</title> 
     <copyright> 
			<year>2002</year>
        <year>2003</year> 
        <year>2004</year> 
        <holder>Sun Microsystems</holder> 
     </copyright>    
      
     <copyright> 
        <year>1998</year> 
        <holder>Oliver Maruhn</holder> 
     </copyright>
     <copyright> 
        <year>1998</year> 
        <holder>Dan Mueth</holder> 
     </copyright>
<!-- translators: uncomment this:

  <copyright>
   <year>2003</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

   -->
<!-- An address can be added to the publisher information.  If a role is 
     not specified, the publisher/author is the same for all versions of the 
     document.  -->
     <publisher> 
        <publishername> GNOME Documentation Project </publishername> 
     </publisher> &legal;
<!-- This file  contains link to license for the documentation (GNU FDL), and 
     other legal stuff such as "NO WARRANTY" statement. Please do not change 
     any of this. -->
     <authorgroup> 
        <author>
          <firstname>Sun </firstname> 
          <surname>GNOME Documentation Team</surname> 
          <affiliation> 
             <orgname>Sun Microsystems</orgname> 
             <address></address> 
          </affiliation> 
        </author> 
        <author> 
          <firstname>Oliver </firstname> 
          <surname> Maruhn</surname> 
          <affiliation> 
             <orgname>GNOME Documentation Project</orgname> 
             <address> <email>oliver@maruhn.com</email> </address> 
          </affiliation> 
        </author> 
        <author> 
          <firstname>Dan </firstname> 
          <surname> Mueth</surname> 
          <affiliation> 
             <orgname>GNOME Documentation Project</orgname> 
             <address> <email>d-mueth@uchicago.edu</email> </address> 
          </affiliation> 
        </author> 
      <!-- This is appropriate place for other contributors: translators,
           maintainers,  etc. Commented out by default.
           <othercredit role="translator">
         <firstname>Latin</firstname> 
         <surname>Translator 1</surname> 
         <affiliation> 
           <orgname>Latin Translation Team</orgname> 
           <address> <email>translator@gnome.org</email> </address> 
         </affiliation>
         <contrib>Latin translation</contrib>
           </othercredit>
-->
     </authorgroup> 
     <revhistory> 
        <revision> 
          <revnumber>&applet; Applet Manual V&manrevision;</revnumber> 
          <date>&date;</date> 
          <revdescription> 
             <para role="author">
                Sun Microsystems
             </para>
             <para role="publisher">
                GNOME Documentation Project
             </para>
          </revdescription> 
        </revision>

	<revision> 
          <revnumber>Command Line Applet Manual V2.6</revnumber> 
          <date>September 2003</date> 
          <revdescription> 
             <para role="author">Sun Microsystems</para>
             <para role="publisher">GNOME Documentation Project</para>
          </revdescription> 
        </revision>
	<revision> 
          <revnumber>Command Line Applet Manual V2.5</revnumber> 
          <date>August 2003</date> 
          <revdescription> 
             <para role="author">Sun Microsystems</para>
             <para role="publisher">GNOME Documentation Project</para>
          </revdescription> 
        </revision>
			<revision> 
          <revnumber>Command Line Applet Manual V2.4</revnumber> 
          <date>April 2003</date> 
          <revdescription> 
             <para role="author">
                Sun Microsystems
             </para>
             <para role="publisher">
                GNOME Documentation Project
             </para>
          </revdescription> 
        </revision>
        
			<revision> 
          <revnumber>Command Line Applet Manual V2.3</revnumber> 
          <date>January 2003</date> 
          <revdescription> 
             <para role="author">
                Sun Microsystems
             </para>
             <para role="publisher">
                GNOME Documentation Project
             </para>
          </revdescription> 
        </revision> 

        <revision> 
          <revnumber>Command Line Applet Manual V2.2</revnumber> 
          <date>August 2002</date> 
          <revdescription> 
             <para role="author">
                Sun Microsystems
             </para>
             <para role="publisher">
                GNOME Documentation Project
             </para>
          </revdescription> 
        </revision> 
        
         
        <revision> 
          <revnumber>Command Line Applet Manual V2.1</revnumber> 
          <date>July 2002</date> 
          <revdescription> 
             <para role="author">
                Sun Microsystems
             </para>
             <para role="publisher">
                GNOME Documentation Project
             </para>
          </revdescription> 
        </revision> 
        <revision> 
          <revnumber>Command Line Applet Manual V2.0</revnumber> 
          <date>March 2002</date> 
          <revdescription> 
             <para role="author">
                Sun Microsystems
             </para>
             <para role="publisher">
                GNOME Documentation Project
             </para>
          </revdescription> 
        </revision> 
        <revision> 
          <revnumber>Mini-Commander Applet Manual</revnumber> 
          <date>1998</date> 
          <revdescription> 
             <para role="author">
                Oliver Maruhn <email>oliver@maruhn.com</email>
             </para>
             <para role="publisher">
                GNOME Documentation Project
             </para>
             <para role="author">
                Dan Mueth <email>d-mueth@uchicago.edu</email>
             </para>
             <para role="publisher">
                GNOME Documentation Project
             </para>
          </revdescription> 
        </revision> 
     </revhistory> 
     <releaseinfo> This manual describes version &appletversion; of &applet;.
        </releaseinfo> 
     <legalnotice> 
        <title>Feedback</title> 
        <para>
          To report a bug or make a suggestion regarding the &applet; applet or this manual, follow the directions in the <ulink url="ghelp:gnome-feedback" type="help">GNOME Feedback Page</ulink>. 
        </para>
     </legalnotice> 
  </articleinfo> 
  <indexterm zone="index"> 
     <primary>Command Line</primary> 
  </indexterm> 
  <indexterm zone="index"> 
     <primary>command line applet</primary> 
  </indexterm>

<!-- ============= Introduction =====-->
  <sect1 id="command-line-introduction"> 
     <title>Introduction</title> 
     
     <!-- ==== Figure ==================-->
     <figure id="applet-fig"> 
        <title>&applet; Applet</title> 
        <screenshot> 
          <mediaobject> 
             <imageobject><imagedata fileref="figures/command-line.png"
                format="PNG"/> 
             </imageobject> 
             <textobject> 
                <phrase>Shows &applet; applet.</phrase> 
             </textobject> 
          </mediaobject> 
        </screenshot> 
     </figure> 
     <para>
        The <application>&applet;</application> applet provides a command line that you can use within any panel on the desktop. </para>
     <para>
        <application>&applet;</application> contains the following interactive elements: </para>
        
        <variablelist>
          <varlistentry>
             <term>
                <guilabel>Entry</guilabel> field</term>
             <listitem>
                <para>
                  You can enter commands, macros, and programs in the <guilabel>entry field</guilabel>.
                </para>
             </listitem>
          </varlistentry>
          <varlistentry>
             <term>
                <guilabel>Browser</guilabel> button</term>
             <listitem>
                <para>
                  You can use the <guibutton>Browser</guibutton> button to look through your file system for programs. A solid-circle icon identifies the <guibutton>Browser</guibutton> button.
                </para>
             </listitem>
          </varlistentry>
          <varlistentry>
             <term>
                <guibutton>History</guibutton> button</term>
             <listitem>
                <para>
                  You can use the <guibutton>History</guibutton> button to recall previous commands. A down-arrow icon identifies the <guibutton>History</guibutton> button.
                </para>
             </listitem>
          </varlistentry>
        </variablelist> 
        
        <para><application>&applet;</application> provides the following features: </para>
        
        <variablelist>
          <varlistentry>
             <term>History list of previously executed commands</term>
             <listitem>
                <para>
                  You can execute commands directly from the history list display. You can also cycle the history list contents through the <guilabel>entry field</guilabel> to display and then execute a command. A vertical scrollbar appears when more than 20 commands are in the history list.
                </para>
             </listitem>
          </varlistentry>
          <varlistentry>
             <term>History-based autocompletion function</term>
             <listitem>
                <para>
                  <application>&applet;</application> uses the history-based autocompletion function to complete commands in the <guilabel>entry field</guilabel>. This function compares the contents of the <guilabel>entry field</guilabel> with the history list. If <application>&applet;</application> finds a match then the applet completes the command.
                </para>
             </listitem>
          </varlistentry>
          <varlistentry>
             <term>User-requestable command completion function</term>
             <listitem>
                <para>
                  This command completion function compares character strings in the <guilabel>entry field</guilabel> with commands in the user path. The command completion function is useful if you do not know the exact character sequence or spelling of a command. After you type the first few letters of the command name, press the <keycap>Tab</keycap> key. If <application>&applet;</application> recognizes the character sequence as unique, then the applet completes the command name.
                </para>
             </listitem>
          </varlistentry>
          <varlistentry>
             <term>Macro facility</term>
             <listitem>
                <para>
                  The macro facility provides up to 99 shortcut commands. In addition to predefined commands you can create your own commands for use with <application>&applet;</application>.
                </para>
             </listitem>
          </varlistentry>
        </variablelist>

      <sect2 id="command-line-introduction-add">       
        <title>To Add &applet; to a Panel</title> 
        <para>To add <application>&applet;</application> to a panel, right-click on the panel, then choose 
        <menuchoice> 
          <guimenu>Add to Panel</guimenu> 
          <guisubmenu>Utility</guisubmenu> 
          <guimenuitem>&applet;</guimenuitem> 
        </menuchoice>.
     </para>
      </sect2>

  </sect1>
<!-- ================ Usage =======-->
  <sect1 id="command-line-usage"> 
     <title>Usage</title> 
     
     <sect2 id="command-line-run">
        <title>To Run a Command From the Entry Field</title>
        <para>
          To run a command from the <guilabel>entry field</guilabel>, perform the following steps: 
        </para>
        <orderedlist> 
          <listitem>
             <para>
                Type the command in the <guilabel>entry field</guilabel>. 
             </para>
             <para>
                To instruct <application>&applet; </application> to try to complete the command name, press the <keycap>Tab</keycap> key.
             </para>
          </listitem> 
          <listitem>
             <para>
                Type the command-line options, if any, in the <guilabel>entry field</guilabel>. 
             </para>
          </listitem> 
          <listitem>
             <para>
                Press <keycap>Return</keycap>. 
             </para>
          </listitem> 
        </orderedlist> 
        <para>
          If the autocompletion option is selected, <application>&applet;</application> searches for a match in the history list during steps 1 and 2. If there is a match in the history list, <application>&applet;</application> completes the command. To accept the command, press <keycap>Return</keycap>. If you do not want to accept the command, type more characters in the <guilabel>entry field</guilabel>. For more information about the autocompletion option, see <xref linkend="command-line-prefs-1"/>.
        </para>
     </sect2>
     <sect2 id="command-line-runmacro"> 
        <title>To Run a Macro From the Entry Field</title> 
        <para>
          To run a macro that is defined in the <application>&applet;</application> <xref linkend="command-line-prefs-2"/> list, type the macro in the <guilabel> entry field</guilabel>, then press <keycap>Return</keycap>. 
        </para>
        <para>
          The <xref linkend="autocompletion"/> function also works for macros. 
        </para>
        <para>
          The following list shows some examples of <application>&applet;</application> macros: 
        </para>
        <informaltable frame="none"> 
          <tgroup cols="2" colsep="0" rowsep="0"><colspec
             colwidth="29.29*"/><colspec colwidth="70.71*"/> 
             <tbody> 
                <row valign="top"> 
                  <entry>
                     <para>
                        <userinput>t</userinput>
                     </para>
                  </entry> 
                  <entry>
                     <para>
                        Starts a terminal. 
                     </para>
                  </entry> 
                </row> 
                <row valign="top"> 
                  <entry>
                     <para>
                        <userinput>n</userinput>
                     </para>
                  </entry> 
                  <entry>
                     <para>
                        Starts a Netscape browser.
                     </para>
                  </entry> 
                </row> 
                <row valign="top"> 
                  <entry>
                     <para>
                        <userinput>dictionary</userinput>
                     </para>
                  </entry> 
                  <entry>
                     <para>
                        Starts a Netscape browser displaying a dictionary search page. 
                     </para>
                  </entry> 
                </row> 
             </tbody> 
          </tgroup> 
        </informaltable>
     </sect2> 
     <sect2 id="command-line-filesys"> 
        <title>To Run a Program From Your File System</title> 
        <para>
          Click on the <guibutton>Browser</guibutton> button to display the file system, then double-click on the program you want to run. 
        </para>
        <para>
          You can use <application>&applet;</application> to run scripts, execute commands, or run other programs from your file system. 
        </para>
     </sect2> 
     <sect2 id="command-line-histlist"> 
        <title>To Run a Previous Command, Macro, or Program From the History List
          </title> 
        <para>
          You can run a previously executed command, macro, or program from the history list in one of the following ways: 
          <itemizedlist> 
             <listitem>
                <para>
                  Click on the <guibutton>History</guibutton> button to display the history list. Click on a history list item to run the command, macro, or program that you require.
                </para>
             </listitem> 
             <listitem>
                <para>
                  Click on the <guilabel>entry field</guilabel>, then use the keyboard up and down arrows to cycle through the history list. Press <keycap>Return</keycap> to run a specific command, macro, or program when the history list item you want is displayed in the <guilabel>entry field</guilabel>.
                </para>
             </listitem> 
          </itemizedlist>
        </para>
     </sect2> 
  </sect1>
<!-- ============= Preferences ============================= -->
  <sect1 id="command-line-prefs-0"> 
     <title>Preferences</title> 
     <para>
        To configure <application>&applet;</application>, right-click on an area of the applet outside the interactive elements, then choose <guimenuitem>Preferences</guimenuitem>.
     </para>
     <para>
        The <guilabel>Preferences</guilabel> dialog contains the following tabbed sections:
     </para>
     <itemizedlist> 
        <listitem>
          <para>
             <xref linkend="command-line-prefs-1"/>
          </para>
        </listitem> 
        <listitem>
          <para>
             <xref linkend="command-line-prefs-2"/>
          </para>
        </listitem> 
     </itemizedlist> 
     
     <sect2 id="command-line-prefs-1"> 
     
        <title>General</title> 
        
        <variablelist>
		<varlistentry>
		<term><guilabel>Show handle</guilabel> </term>
		<listitem>
		<para>Select this option to attach a handle to the edge of the applet. You can use the handle to drag the <application>&applet;</application> display to any location on your desktop. </para>
		</listitem>
		</varlistentry>
		<varlistentry>
		<term><guilabel>Show frame</guilabel> </term>
		<listitem>
		<para>Select this option to show a frame around the <application>&applet;</application>.</para>
		</listitem>
		</varlistentry>
		<varlistentry id="autocompletion">
		<term><guilabel>Enable history-based auto completion</guilabel></term>
		<listitem>
		<para>Select this option to instruct <application>&applet;</application> to compare the <guilabel>entry field</guilabel> with the history list, and complete commands when there is a match. </para>
		</listitem>
		</varlistentry>
		<varlistentry>
		<term><guilabel>Width ... pixels</guilabel> </term>
		<listitem>
		<para>Use this spin box to specify the applet width.</para>
		</listitem>
		</varlistentry>
		<varlistentry>
		<term><guilabel>Use default theme colors</guilabel> </term>
		<listitem>
		<para>Select this option to use the colors from the default GNOME theme.</para>
		</listitem>
		</varlistentry>
		<varlistentry>
		<term><guilabel>Command line foreground</guilabel> </term>
		<listitem>
		<para>Click on this button to select a color for the command line text. This button is unavailable if the <guilabel>Use default theme colors</guilabel> check box is selected.</para>
		</listitem>
		</varlistentry>
		<varlistentry>
		<term><guilabel>Command line background</guilabel> </term>
		<listitem>
		<para>Click on this button to select a color for the 
		<guilabel>entry field</guilabel> background. This button is unavailable if the <guilabel>Use default theme colors</guilabel> check box is selected.</para>
		</listitem>
		</varlistentry>	
	</variablelist>
        
     </sect2> 
     
     <sect2 id="command-line-prefs-2"> 
        <title>Macros</title> 
        <para>
          This tabbed section contains a list of macros that you can use with <application>&applet;</application>. The list contains the following information: 
			</para>
          <itemizedlist> 
             <listitem>
                <para>
                  A list of UNIX regular expressions in the <guilabel>Pattern</guilabel> column. 
                </para>
                <para>
                  A regular expression is a pattern of characters or numbers that you use to match strings. See the <command>regex</command> man page for further information on how to construct a regular expression. 
                </para>
             </listitem> 
             <listitem>
                <para>
                  A list of commands in the <guilabel>Command</guilabel> column.
                </para>
                <para>
                  A command executes if the corresponding pattern successfully matches the text that you type into the <guilabel>entry field</guilabel>. The macros are commands that can take parameters parsed by the regular expression.
                </para>
             </listitem> 
          </itemizedlist> 
		<para>To add a new macro, click on the <guibutton>Add Macro</guibutton> button. To delete a macro, select the macro, then click on the <guibutton>Delete Macro</guibutton> button. 
     </para>
     </sect2> 
  </sect1> 
</article> 
