<?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.3.6">
  <!ENTITY manrevision "2.6">
  <!ENTITY date "September 2003">
  <!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> 
        <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.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>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>
     <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>
  </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>
          </listitem> 
          <listitem>
             <para>
                If you want, you can instruct <application>&applet;
                </application> to try to complete the command name. Press the 
                <keycap>Tab</keycap> key to give this instruction.
             </para>
          </listitem> 
          <listitem>
             <para>
                Type any options that you want to run with the command in the 
                <guilabel>entry field</guilabel>. 
             </para>
          </listitem> 
          <listitem>
             <para>
                Press 
                <keycap>Return</keycap>. 
             </para>
          </listitem> 
        </orderedlist> 
        <para>
          If the 
          <xref linkend="autocompletion"/> option is selected then during steps 1 to 3,
          <application>&applet;</application> searches for a match in the history list.
          If there is a match in the history list, <application>&applet;</application> 
          completes the command. To accept the command, press 
          <keycap>Return</keycap>. Alternatively, if you do not want to accept
          the command, type more characters in the <guilabel>entry field</guilabel>.
        </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 autocompletion</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</guilabel> </term>
		<listitem>
		<para>Use this spin box to specify the applet width in pixels.</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> 
