[olug] addendum/correction and more ways of helping yourself

[Mark A. Martin]

I'd first like to correct and add to my description of the info
facility.  You do not have to traverse the tree of info documents to
find the documentation for a specific command (although you can if you
want).  Issuing the command

info command

will bring up the documentation for "command".

There are three other ways of helping yourself that I'd like to
suggest.  They are

* Check the logs and use error messages
* Read the code
* Read books

Check the logs and use error messages
-------------------------------------
Many pieces of software log problems, events, and changes in status to
files.  It is usually worthwhile to determine if a program logs and, if
so, where, and then read the corresponding log entries if you're having
problems.  In particular, many programs make entries in the system log
/var/log/messages.  Other programs such as cron and mail transfer agents
(MTAs) keep their own log files under /var/log.  Often, where a program
logs may be configured at compile time or through a configuration file. 
Consult the documentation for particular programs to see where they
might log.

Error messages might also be written to stderr, i.e. to the console or a
window, rather than or in addition to being written to a log file.  You
should carefully read error messages and include them in requests for
help.  It may be helpful to preserve error messages by copying them to a
file while trying to solve a problem.  This may be done by using the
mouse to cut and paste from a window or by redirecting stderr to a
file.  The "tee" command is useful for this purpose since it will allow
you to copy output to a file while it continues to display on the
screen.  My suggestion is to redirect stderr to stdout and then use tee
to capture both stdout and stderr in a file.  The way to execute
"command" and preserve stdout and stderr in "filename" using bash is

command 2>&1 | tee filename

See the man pages for tee and bash for more information.  I often use
tee in this way to preserve the messages generated while compiling in
case there is a problem.

Another useful trick is to search for the text of error messages in the
source code.  Sometimes error messages aren't very enlightening but
sometimes the code that generates an error message or the comments near
the code that generates the error message are more helpful.  I have used
this technique many times.  If there is a large source tree and you're
uncertain which source file contains the appropriate code, you can
recursively grep all of the source files for the error message.  Here's
how you might do this

cd /path/to/source/tree
grep -rn 'text of error message' | less

The grep command will not only print the path to the file containing the
text but will also print the number of the line containing the text. 
Sometimes you need to search for part of the error message rather than
the entire message since different routines in the code may generate
different parts of the message.  Once you've found where the error
message is generated, you can use an editor to look at the corresponding
code.

Read the code
-------------
No, I don't mean that everyone should read the source code for the Linux
kernel.  But reading through scripts that you're having trouble with or
looking at the source code of a program is sometimes helpful.  I've
already covered this to a large extent in the previous section.  I'd
just like to point out that it may be helpful to read through the code,
even if you aren't a programmer or don't know the language that the code
is written in.  The comments in the code can be very enlightening and
will sometimes refer you to good sources of information or a person to
contact.  If you are a programmer, reading the code can give you a
deeper insight into the problem you're having and can help you improve
your programming skills.  Tracing through the code can also help
increase your general knowledge of a piece of software or of the system.

While I'm on this topic, the man page for bash is excellent and
detailed.  If you find yourself wondering how to do something in bash or
don't understand a bash construct that you read in a script, read the
man page.  Also, don't forget that you can probably search through man
pages for strings.  How to search depends on your paging software but
less and more are vi-like and you search in them by typing a slash (/)
followed by the search string.

Read books
----------
This may be particularly helpful if you need more general knowledge
about Linux or UNIX.  I have found many O'Reilly and Associates books
(http://www.oreilly.com) to be very helpful and there are other
publishers that produce worthwhile books.  This method can be very
expensive but doesn't have to be.  Since computing is such a hot topic,
the local library may have more up-to-date computing books than you'd
expect.

In my opinion, reading books is most valuable when you need a better
general understanding or when the other available sources of information
are not very helpful.  Reading a book should not usually be your first
resort when trying to solve a problem.  The reason is that there is so
much good documentation freely available online.  Most of the computer
books that I encounter seem to be rewrites of online documentation (and
of each other).  So you should probably consult online sources of
documentation before going to the library or book store.  Also, most
books do not cover deeper topics and may not provide the details that
you need.

Of course, if you're having trouble with proprietary software, online
documentation may be sparse.  In this case, you may be able to search
mail archives or look through a tech support database but may otherwise
be stuck asking the vendor or manufacturer for assistance (and possibly
paying for it).  I rarely use proprietary software and my earlier
comments are restricted to the world of free (or semi-free, depending on
the license) software.

I felt compelled to share these few additional thoughts that trickled
through my brain over the past day.  As before, I hope that they help
you in your problem-solving endeavors.

Mark
-- 
---------------------------------------------------------------------------
Mark A. Martin					Dept of Applied Mathematics
http://www.amath.washington.edu/~mmartin	University of Washington
---------------------------------------------------------------------------

---------------------------------------------------------------------
To unsubscribe, e-mail: olug-unsubscribe at bstc.net
For additional commands, e-mail: olug-help at bstc.net