tutes-dump/site-tutorials/findinghelp.html

<h1>Finding Help From Within the Shell</h1>
<p>Note: Please look <a href="#sdfspecific">further down</a> about help
facilities specific to SDF, like the FAQ!</p>
<p>While the UNIX shell may seem a bit daunting and cold with cryptic 
two-letter commands, dozens of command line switches, and no animated 
paper clips to show you the way, there are several different ways of 
getting help from the system.</p>
<hr />
<h2><a id="#manpage" />Using Manpages</h2>
<h3>The Definitive Guide to RTFMing</h3>
<p>The easiest and most comprehensive way of getting help is reading the 
manpage. You've probably heard RTFM (Read The Fscking Manual) somewhere 
throughout your computer use, well, this is that Manual. Manpages are 
the standard form of documentation for every UNIX. Learn to use them. 
Learn to love them.</p>
<p>Where can you find them? It's pretty simple. Think of a command. (ls, 
rm, chmod, kill, grep) or a program (vi, mutt, snarf, majordomo) So go 
ahead, type</p>
<code>% man <i>command</i></code>
<p>command being the name of the command you want to learn about. As you 
can see, manpages are broken down into sections. We'll use mkdir as an 
example.</p>
<CODE>% man mkdir</CODE>
<pre>
MKDIR(1)                NetBSD General Commands Manual                
MKDIR(1)

NAME
     mkdir - make directories

SYNOPSIS
     mkdir [-p] [-m mode] directory_name ...

DESCRIPTION
     mkdir creates the directories named as operands, in the order specified,
     using mode rwxrwxrwx (0777) as modified by the current umask(2).

     The options are as follows:

     -m      Set the file permission bits of the final created directory to
             the specified mode.  The mode argument can be in any of the for-
             mats specified to the chmod(1) utility.  If a symbolic mode is
             specified, the operation characters ``+'' and ``-'' are inter-
             preted relative to an initial mode of ``a=rwx''.

     -p      Create intermediate directories as required.  If this option is
             not specified, the full path prefix of each operand must already
             exist.  Intermediate directories are created with permission bits
             of rwxrwxrwx (0777) as modified by the current umask, plus write
             and search permission for the owner.  Do not consider it an error
             if the argument directory already exists.

     The user must have write permission in the parent directory.
                                                                               
EXIT STATUS
     mkdir exits 0 if successful, and >0 if an error occurred.

SEE ALSO
     chmod(1), rmdir(1), mkdir(2), umask(2)

STANDARDS
     The mkdir utility is expected to be IEEE Std 1003.2 (``POSIX.2'') compat-
     ible.

NetBSD 2.0.2                   January 25, 1994                   NetBSD 
2.0.2
</pre>
<p>For our <CODE>mkdir</CODE> command, the man page displayed has six 
sections: NAME, SYNOPSIS, DESCRIPTION, EXIT STATUS, SEE ALSO, and 
STANDARDS. The NAME section simply shows the name of the command and a 
terse description of its function. The SYNOPSIS gives a brief 
outline of the command syntax, so you can see what the command you 
enter should look like. Items in square brackets [ ] are optional. The 
DESCRIPTION section provides a detailed description of how the command 
works, including information on the various options or modes of the 
command. The EXIT STATUS section describes what status codes are 
generated by the command when it completes (successfully 
or unsuccessfully). These codes can be read by programs (such as a shell 
script) to determine how to react to the command's result. SEE ALSO 
provides cross referencing information for related commands or others 
which may be helpful. And finally, the STANDARDS section lists 
information on which standards this particular command complies with.
</p>

<p>The manual is divided up into nine sections:</p>
<ol>
 <li>User commands.</li>
 <li>System calls and error numbers.</li>
 <li>Functions in the C libraries.</li>
 <li>Device drivers.</li>
 <li>File formats.</li>
 <li>Games and other diversions.</li>
 <li>Miscellaneous information.</li>
 <li>System maintenance and operation commands.</li>
 <li>Kernal developers.</li>
</ol>
<p>In some cases, the same topic will appear on more than one section of 
the manual. For example, there is a chmod user command and a chmod() 
system call. How would you find the appropriate manpage? You can tell 
man which section you'd like to look under. If you wanted to find the 
user command you would type:</p>
<code>% man 1 chmod</code>
<p>This would display the manpage for the user command chmod. 
References to the specific sections are traditionally placed in 
parenthesis after the command name like so: chmod(1)</p>
<p>Well, this is all fine and good if you know the name of the command, 
but what if you can't remember the name? 'man -k' can be used to search 
for keywords in the command descriptions. So, if you want to find a mail 
program you would type:</p>
<code>% man -k editor</code>
<p>A list of commands with the keyword "editor" in their descriptions 
will be presented on the screen.</p>

<h2>The GNU Info system</h2>
<p>For programs of the <a href="http://www.gnu.org">GNU Project</a>, you may
also use the <code>info</code> command. If you know the name of a program,
give it as an argument (like with <code>man</code>).
<br>In fact, you can use <code>info</code> as an alias to <code>man</code>,
because the info reader will simply display the man page if it cannot find an
info entry (but you cannot specify the manpage section).</p>
<p>However, navigation is different in the standard info reader, as it is
based on the <code>emacs</code> text editor.
<br>Quick key help (for more, consult <code>info info</code>):
<dl>
<dt>SPACE, BACKSPACE</dt>
<dd>page forward, backward</dd>
<dt>TAB</dt>
<dd>place cursor onto next menu item or link (info files are hyperlinked)</dd>
<dt>RETURN</dt>
<dd>jump to the place where the link the cursor is sitting on points to</dd>
<dt>l (the letter ell)</dt>
<dd>get back to the spot from where last jump started</dd>
<dt>u n p</dt>
<dd>up, next, previous node (info files are hierarchically structured)</dd>
<dt>q</dt>
<dd>quit the info reader</dd>
</dl>
With most terminals, you can also move around using the cursor keys (arrows).
</p>

<a id="sdfspecific"><h2>SDF specific help</h2></a>
<p>There are also a number of tools at SDF that you can use to get more help.
Type the following commands at a shell prompt.</p>
<dl>
<dt>help</dt><dd>The SDF help system.</dd>
<dt>faq</dt><dd>A collection of frequently asked questions.  Type 'g <topic>' to enter
a topic, 'l' to list the questions in the topic, and 't <number>' to read
the FAQ.  The FAQ is also available <a href="http://sdf.lonestar.org/index.cgi?faq">on the SDF website</a>.</dd>
<dt>helpdesk</dt><dd>If you cannot find your answer in the man pages, help, faq,
or googling post a question to the helpdesk and a friendly member of the community
will answer your question.  Any member with ARPA status can login as an attendent
to answer questions. Please note: in helpdesk you should only post questions
directly related to SDF's systems, but not about general UNIX, programming or
gardening - these belong to the bboard!</dd>
<dt>bboard</dt><dd>To enter the SDF Bulletin Board System (BBOARD), type
bboard at the command line. Help on using BBOARD may be found by typing
h and ? at the bboard Command: prompt or at the <a
href="http://sdf.org/?tutorials/bboard-tutorial">BBOARD tutorial</a>. If
you have a general question about using the SDF system, post in
HELPDESK. If you have a question that requires intervention from an
admin (e.g., software requests or membership queries), post in
REQUESTS.</dd>
<dt>com</dt><dd>Com and bboard are meeting places for the SDF community.  You
could also pose your question there.  Bboard and faq have the same interface.  See
<a href="http://sdf.lonestar.org/index.cgi?tutorials/comnotirc">COM is not IRC</a> for
how to use com.
</dl>
And of course there are the online tutorials that you are reading right now!  The top
level page is <a
href="http://sdf.lonestar.org/index.cgi?tutorials">http://sdf.lonestar.org/index.cgi?tutorials</a>.
<hr />
<cite>$Id: findinghelp.html,v 1.11 2016/12/07 20:17:49 jandal Exp $</cite>