[gnome-terminal/wip/mallard-merge: 175/249] help: modified three help files



commit b79e901bfc4a91c40504b14366b6910da33f87e3
Author: Sindhu S <sindhus live in>
Date:   Sun Feb 24 16:11:09 2013 +0530

    help: modified three help files
    
    gs-execute-commands.page:
    Changed incorrect page ID.
    Added link seealso.
    Reworded help on how to run a command or launch GUI programs
    to obtain debugging information to aid in filing a bug report.
    Added explanation on how programs can be installed on various
    locations on the computer and that Terminal may not always be
    by default able to see them without the locations being added
    to the PATH variable. A user can find out the exact location
    of the program by using which program.
    Reworded introductory explanation on what a command is.
    Added seealso links to overview to enable the user to read
    more about command line, prompt and other Terminal jargon.
    
    pref-custom-shells.page:
    Reworded help to explain relationship between shells, programs
    and commands.
    Added one more step for user to verify whether the custom shell
    or command set if working OK.
    
    overview.page
    Added description to all terms to be used throughout the Terminal
    help.
    Added examples of shells.
    Reflowed paragraphs.

 help/C/gs-execute-commands.page |   24 ++++++++---
 help/C/overview.page            |   83 ++++++++++++++++++++++++++-------------
 help/C/pref-custom-shells.page  |   51 ++++++++++++------------
 help/C/txt-copy-paste.page      |    2 +-
 4 files changed, 98 insertions(+), 62 deletions(-)
---
diff --git a/help/C/gs-execute-commands.page b/help/C/gs-execute-commands.page
index 08f3f5f..99406fd 100644
--- a/help/C/gs-execute-commands.page
+++ b/help/C/gs-execute-commands.page
@@ -1,10 +1,12 @@
 <page xmlns="http://projectmallard.org/1.0/";
       type="guide"
-      id="execute-commands">
+      id="gs-execute-commands">
 
   <info>
     <revision version="0.1" date="2013-01-10" status="draft"/>
     <link type="guide" xref="index#getting-started"/>
+    <link type="seealso" xref="txt-copy-paste"/>
+    <link type="seealso" xref="overview"/>
 
     <credit type="author copyright">
       <name>Sindhu S</name>
@@ -22,10 +24,11 @@
 
   <title>Execute a command</title>
 
-  <!-- Explain why this may be userful: for example, if a programme is not
-  running properly and the user intends to file a bug, it may output some
-  useful error message. -->
-  <p>To launch programs or execute commands using <app>Terminal</app>:</p>
+  <p>Any input entered in the <app>Terminal</app> to be executed is referred to
+  as a command. You can run both command line and Graphical User Interface (GUI)
+  programs in <app>Terminal</app>.</p>
+
+  <p>To execute commands using <app>Terminal</app>:</p>
 
   <steps>
     <item>
@@ -36,9 +39,16 @@
     </item>
   </steps>
 
+  <p>Programs may end abruptly without any warning or error message. You can run
+  such GUI programs using <app>Terminal</app> to allow the program to output any
+  error or debugging messages to the <app>Terminal</app>. This information is
+  helpful in filing a bug report.</p>
+
   <note style="tip">
-    <!-- Why is this useful? -->
-    <p>To find out where the program is installed on your computer, type
+    <p>Programs can be installed at different locations on your computer. If
+    these locations are not added to the <code>PATH</code> variable of your
+    computer, <app>Terminal</app> will not be able to run the desired program.
+    To find out where the program is installed on your computer, type
     <code>which</code> followed by the program name.</p>
   </note>
   
diff --git a/help/C/overview.page b/help/C/overview.page
index bf71924..c043a82 100644
--- a/help/C/overview.page
+++ b/help/C/overview.page
@@ -1,6 +1,6 @@
 <page xmlns="http://projectmallard.org/1.0/";
       type="guide" style="task"
-      id="overview1">
+      id="overview">
   <info>
     <revision version="0.1" date="2013-01-10" status="draft"/>
     <link type="guide" xref="index"/>
@@ -21,50 +21,77 @@
 
   <title>Overview of a terminal</title>
 
-  <p>A terminal is a text input point in a computer also called the Command
-  Line Interface (CLI). A terminal emulator, such as VTE, emulates a text
-  terminal inside a graphical user interface (GUI) environment.
-  <app>Terminal</app> is a terminal emulator for GNOME.</p>
+  <p><app>Terminal</app> is a terminal program for <gui>GNOME</gui>. The
+  following terms and their descriptions will help you to be familiar with
+  <app>Terminal</app> and it's capabilities.</p>
 
-<!-- Good use of a terms list! -->
   <terms>
     <item>
+      <title>A terminal</title>
+      <p>A terminal is a text input point in a computer also called the Command
+      Line Interface (CLI).</p>
+    </item>
+    <item>
+      <title>Physical terminals</title>
+      <p>IBM 3270, VT100 and many others are hardware terminals that are no
+      longer produced as physical devices. To emulate these terminals, there are
+      terminal emulators.</p>
+    </item>
+    <item>
+      <title>Terminal emulators</title>
+      <p>Emulation is the ability of a computer program to imitate another
+      program or device.</p>
+
+      <p>A terminal emulator also called tty is a software program that emulates
+      a video terminal in modern computers that use graphical user interfaces
+      and provide interactive access to applications that run only in the
+      command line environments. These applications may be running either on the
+      same machine or on a different one via <app>telnet</app>, <app>ssh</app>,
+      or <app>dial-up</app>.</p>
+    </item>
+    <item>
       <title>VTE</title>
-      <p><!---What is VTE? --></p>
-      <p><!--What is the connection between a terminal and a shell?--></p>
+      <p>Virtual Terminal Environment (VTE) is a terminal emulator which
+      emulates a text terminal inside a graphical user interface (GUI)
+      environment. <app>Terminal</app> is largely based on the <app>VTE</app>.
+      <app>VTE</app> has widgets that implement a fully functional terminal
+      emulator.</p>
     </item>
     <item>
       <title>Shell</title>
-      <p>A shell is a program that provides an interface to invoke or "launch"
-  commands or another program inside a terminal. It also allows you to view and
-  browse the contents of directories.</p>
+      <p>A <app>shell</app> is a program that provides an interface to invoke or
+      "launch" commands or another program inside a terminal. It also allows you
+      to view and browse the contents of directories. Popular shells are
+      <app>Bash</app>, <app>rsh</app>, <app>tsh</app>, <app>fish</app> and so
+      on.</p>
+    </item>
+    <item>
+      <title>Escape Sequences</title>
+      <p>An escape sequence is a series of characters used to change the meaning
+      of data in a terminal. Escape sequences are used when a computer has only
+      single channel to send information back and forth. Escape sequences are
+      used to distinguish if data being sent is a command to be executed or
+      information to be stored and displayed.</p>
     </item>
+
     <item>
       <title>Prompt</title>
-      <p>A prompt also called a command prompt is a sequence of characters used
-      in the CLI to indicate the readiness of the shell to accept commands.</p>
+      <p>A prompt also called a <em>command prompt</em>. It is a sequence of
+      characters used in the command line environment to indicate the readiness
+      of the shell to accept commands.</p>
 
-      <p>A prompt usually ends with characters $, %, # or > and includes
+      <p>A prompt usually ends with characters $, %, # or > and include
       information about path of present working directory. On Unix based
       systems, it is common for the prompt to end in a $ or % character
       depending on the user role such as $ for user and # for superuser (also
       called root).</p>
-
-      <p>Prompts are customisable to include colors, special characters and
-      variables for system time, user, working directory to make the prompt
-      informative and distinguishable from sessions on various machines.</p>
-
-      <p>In a bash shell, the $PS1 variable can be used to set the prompt.
-      <code>[time] user host: work_dir $ export PS1='[\t] \u \H: \W
-      $'</code></p>
-    </item>
-    <item>
-      <title>Escape Sequences</title>
-      <p><!--TODO: Write about escape sequences.--></p>
     </item>
     <item>
-      <title>Emulators</title>
-      <p><!--TODO: What are emulators, what can a user expect from them.--></p>
+      <title>Command</title>
+      <p>An input entered in the prompt to be executed is called a
+      <em>command</em>. It is a combination of the program name along with any
+      other additional parameteres passed as flags to alter the execution of the
+      program.</p>
     </item>
   </terms>
 
diff --git a/help/C/pref-custom-shells.page b/help/C/pref-custom-shells.page
index 54faff8..8bf704b 100644
--- a/help/C/pref-custom-shells.page
+++ b/help/C/pref-custom-shells.page
@@ -16,6 +16,7 @@
     </credit>
 
     <link type="guide" xref="index#preferences"/>
+    <link type="seealso" xref="gs-execute-commands"/>
 
     <desc>Start your <app>Terminal</app> with a command or a different shell</desc>
 
@@ -23,34 +24,32 @@
 
   <title>Custom shells</title>
 
-  <!-- Reflow. Launch does not need to be in quotes, run is more apropriate
-  than either term. Check with Christian if one can actually run a "custom
-  command" or whether the UI means just run another shell and is referring only
-  to commands that run a shell. -->
-  <p>A shell is software that provides an interface for users of an operating system to invoke or "launch" 
another program; however, shells frequently have additional capabilities such as viewing the contents of 
directories.</p>
-
-  <p>To start <app>Terminal</app> to run a command or a shell other than <gui>Bash</gui>:</p>
-  <!-- Bash is an app more than a GUI. Check if gnome-user-help mentions it and
-  if yes, how it is marked up. -->
-
-  <!-- Indent steps only by two spaces as they are on the same "level" as
-  paragraphs. -->
-    <steps>
-      <item>
-        <p>Select <guiseq><gui style="menu">Edit</gui><gui style="menuitem">Profile Preferences…</gui><gui 
style="tab">Title and Command</gui></guiseq></p>
-      </item>
-      <item>
-        <p>Select <gui>Run a command instead of my shell</gui>.</p>
-      </item>
-      <item>
-        <p>In the input box, type the name of the command or the desired shell.</p>
-      </item>
-    </steps>
+  <p>A shell is software that provides an interface for users of an operating
+  system to run programs and view the contents of directories.
+  The default shell is <app>Bash</app>.</p>
+
+  <p><app>Terminal</app> can be set to run a custom shell or the default shell with additional parameters 
such a configuration file other than the default. A shell is a type of program and hence <app>Terminal</app> 
can also be exclusively set to run standalone programs such as <code>ls</code>, <code>top</code>, 
<code>iwconfig</code> etc.</p>
+
+  <p>Programs that are executed in the command line environment are also referred to as commands.</p>
+
+  <p>To start <app>Terminal</app> to run a command or a shell:</p>
+  <steps>
+    <item>
+      <p>Select <guiseq><gui style="menu">Edit</gui><gui style="menuitem">Profile Preferences…</gui><gui 
style="tab">Title and Command</gui></guiseq></p>
+    </item>
+    <item>
+      <p>Select <gui>Run a command instead of my shell</gui>.</p>
+    </item>
+    <item>
+      <p>In the input box, type the name of the command or the desired shell.</p>
+    </item>
+    <item>
+      <p>Open a new <app>Terminal</app> tab or window to view the execution of your custom shell or 
command.</p>
+    </item>
+  </steps>
 
   <note style="important">
-    <p>You may have to enter full path to the command or shell in case you have not added the directory 
where the command or shell resides to the system's PATH variable.</p>
-  <!-- Do not use possessive for inanimate objects. the PATH should be marked
-  up. -->
+    <p>You may have to enter full path to the command or the shell in case you have not added the directory 
where the command or shell resides in the <code>PATH</code> variable of your your system.</p>
   </note>
 
 </page>
diff --git a/help/C/txt-copy-paste.page b/help/C/txt-copy-paste.page
index 3ded2c9..977425d 100644
--- a/help/C/txt-copy-paste.page
+++ b/help/C/txt-copy-paste.page
@@ -1,6 +1,6 @@
 <page xmlns="http://projectmallard.org/1.0/";
       type="task"
-      id="copy-paste">
+      id="txt-copy-paste">
   <info>
     <revision version="0.1" date="2013-01-10" status="draft"/>
 


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]