Why newbies don't RTFM...

From: Random Penguin (nonexistent2032_at_yahoo.co.uk)
Date: 09/12/05


Date: 12 Sep 2005 05:13:34 -0700

Hi guys. Even though I've used Linux before, I've never had to do any
admin tasks until recently when I had to install a dual boot system at
home because some programs from college must use Linux. All of a sudden
I have to use more commands than cd/ls/cp/rm.

I'm sure you all have been wondering what is it with newbies and not
reading manuals...well, an honest answer would be that some people find
the manuals just too confusing, long and unhelpful.

In the output of "man cd" below, see how confusing, long and unhelpful
it is. I gave up copying and pasting after about line 300. I'm not
trying to belittle the author(s) work here, and I'm sure there are
people out there who find a use for each paragraph....

But surely you Linux experts could help the beginners by having either
separate manuals for advanced users or appending the long bits to the
end of an "easy" manual? I have to websurf to find out how to do things
in Linux (apart from asking NGs). I find the answers on websites a lot
more direct to what I'm looking for (especially if I have specific
keywords in Google, like "adsl usb modem installation linux").

A manual I'd classify as easy/helpful:
- Is brief and to the point
- Gives **examples** (very important!) in descending order of how
frequently they're used

Please don't take this as a troll post, instead take it as constructive
criticism. Personally I think Linux is the way forward; I loathe having
to pay other people for permission + the ability to use my own computer
hardware I paid for.

Hope this helps the guys writing the next kernel :)

-----------------------

BASH_BUILTINS(1)
       BASH_BUILTINS(1)

NAME
       bash, :, ., [, alias, bg, bind, break, builtin, cd, command,
compgen, complete, con‚
       tinue, declare, dirs, disown, echo, enable, eval, exec, exit,
export, fc, fg, getopts,
       hash, help, history, jobs, kill, let, local, logout, popd,
printf, pushd, pwd, read,
       readonly, return, set, shift, shopt, source, suspend, test,
times, trap, type, typeset,
       ulimit, umask, unalias, unset, wait - bash built-in commands,
see bash(1)

BASH BUILTIN COMMANDS
       Unless otherwise noted, each builtin command documented in
this section as accepting
       options preceded by - accepts -- to signify the end of the
options.
       : [arguments]
              No effect; the command does nothing beyond expanding
arguments and performing any
              specified redirections. A zero exit code is returned.

        . filename [arguments]
       source filename [arguments]
              Read and execute commands from filename in the
current shell environment and
              return the exit status of the last command executed from
filename. If filename
              does not contain a slash, file names in PATH are used to
find the directory con‚
              taining filename. The file searched for in PATH need not
 be executable. When
              bash is not in posix mode, the current directory is
searched if no file is found
              in PATH. If the sourcepath option to the shopt builtin
command is turned off,
              the PATH is not searched. If any arguments are
supplied, they become the posi‚
              tional parameters when filename is executed. Otherwise
the positional parameters
              are unchanged. The return status is the status of the
last command exited within
              the script (0 if no commands are executed), and false if
filename is not found or
              cannot be read.
       alias [-p] [name[=value] ...]
              Alias with no arguments or with the -p option prints
the list of aliases in the
              form alias name=value on standard output. When arguments
are supplied, an alias
              is defined for each name whose value is given. A
trailing space in value causes
              the next word to be checked for alias substitution when
the alias is expanded.
              For each name in the argument list for which no value
is supplied, the name and
              value of the alias is printed. Alias returns true unless
a name is given for
              which no alias has been defined.

       bg [jobspec]
              Resume the suspended job jobspec in the background,
as if it had been started
              with &. If jobspec is not present, the shell's notion
of the current job is
              used. bg jobspec returns 0 unless run when job control
is disabled or, when run
              with job control enabled, if jobspec was not found or
started without job con‚
              trol.

       bind [-m keymap] [-lpsvPSV]
       bind [-m keymap] [-q function] [-u function] [-r keyseq]
       bind [-m keymap] -f filename
       bind [-m keymap] -x keyseq:shell-command
       bind [-m keymap] keyseq:function-name
       bind readline-command
              Display current readline key and function bindings,
bind a key sequence to a
              readline function or macro, or set a readline variable.
Each non-option argument
              is a command as it would appear in .inputrc, but each
binding or command must be
              passed as a separate argument; e.g., '"\C-x\C-r":
re-read-init-file'. Options,
              if supplied, have the following meanings:
              -m keymap
                     Use keymap as the keymap to be affected by
the subsequent bindings.
                     Acceptable keymap names are emacs, emacs-standard,
emacs-meta, emacs-ctlx,
                     vi, vi-move, vi-command, and vi-insert. vi is
equivalent to vi-command;

                     emacs is equivalent to emacs-standard.
              -l List the names of all readline functions.
              -p Display readline function names and bindings in
such a way that they can
                     be re-read.
              -P List current readline function names and bindings.
              -v Display readline variable names and values in
such a way that they can be
                     re-read.
              -V List current readline variable names and values.
              -s Display readline key sequences bound to macros and
the strings they output
                     in such a way that they can be re-read.
              -S Display readline key sequences bound to macros
and the strings they out‚
                     put.
              -f filename
                     Read key bindings from filename.
              -q function
                     Query about which keys invoke the named function.
              -u function
                     Unbind all keys bound to the named function.
              -r keyseq
                     Remove any current binding for keyseq.
              -x keyseq:shell-command
                     Cause shell-command to be executed whenever keyseq
is entered.

              The return value is 0 unless an unrecognized option
is given or an error
              occurred.

      break [n]
              Exit from within a for, while, until, or select loop. If
n is specified, break n
              levels. n must be ‚• 1. If n is greater than the
number of enclosing loops, all
              enclosing loops are exited. The return value is 0
unless the shell is not exe‚
              cuting a loop when break is executed.

       builtin shell-builtin [arguments]
              Execute the specified shell builtin, passing it
arguments, and return its exit
              status. This is useful when defining a function
whose name is the same as a
              shell builtin, retaining the functionality of the builtin
 within the function.
              The cd builtin is commonly redefined this way. The
return status is false if
              shell-builtin is not a shell builtin command.

       cd [-L|-P] [dir]
              Change the current directory to dir. The variable HOME
is the default dir. The
              variable CDPATH defines the search path for the directory
containing dir. Alter‚
              native directory names in CDPATH are separated by a colon
(:). A null directory
              name in CDPATH is the same as the current directory,
i.e., ‚‚.''. If dir begins
              with a slash (/), then CDPATH is not used. The -P option
says to use the physical
              directory structure instead of following symbolic links
(see also the -P option
              to the set builtin command); the -L option forces
symbolic links to be followed.
              An argument of - is equivalent to $OLDPWD. If a
non-empty directory name from
              CDPATH is used, or if - is the first argument, and the
directory change is suc‚
              cessful, the absolute pathname of the new working
directory is written to the
              standard output. The return value is true if the
directory was successfully
              changed; false otherwise.
       caller [expr]
              Returns the context of any active subroutine call (a
shell function or a script
              executed with the . or source builtins. Without expr,
caller displays the line
              number and source filename of the current subroutine
call. If a non-negative
              integer is supplied as expr, caller displays the line
number, subroutine name,
              and source file corresponding to that position in
the current execution call
              stack. This extra information may be used, for example,
to print a stack trace.
              The current frame is frame 0. The return value is 0
unless the shell is not exe‚
              cuting a subroutine call or expr does not correspond to a
valid position in the
              call stack.

       command [-pVv] command [arg ...]
              Run command with args suppressing the normal shell
function lookup. Only builtin
              commands or commands found in the PATH are executed. If
the -p option is given,
              the search for command is performed using a default
value for PATH that is guar‚
              anteed to find all of the standard utilities. If either
the -V or -v option is
              supplied, a description of command is printed. The
-v option causes a single
              word indicating the command or file name used to invoke
command to be displayed;
              the -V option produces a more verbose description.
If the -V or -v option is
              supplied, the exit status is 0 if command was found, and
1 if not. If neither
              option is supplied and an error occurred or command
cannot be found, the exit
              status is 127. Otherwise, the exit status of the command
 builtin is the exit
              status of command.

       compgen [option] [word]
              Generate possible completion matches for word according
to the options, which may
              be any option accepted by the complete builtin with the
exception of -p and -r,
              and write the matches to the standard output. When
using the -F or -C options,
              the various shell variables set by the programmable
completion facilities, while
              available, will not have useful values.

             The matches will be generated in the same way as if the
programmable completion
              code had generated them directly from a completion
specification with the same
              flags. If word is specified, only those completions
matching word will be dis‚
              played.

              The return value is true unless an invalid option is
supplied, or no matches were
              generated.

       complete [-abcdefgjksuv] [-o comp-option] [-A action] [-G
globpat] [-W wordlist] [-P
       prefix] [-S suffix]
              [-X filterpat] [-F function] [-C command] name [name ...]
       complete -pr [name ...]
              Specify how arguments to each name should be completed.
If the -p option is sup‚
              plied, or if no options are supplied, existing
completion specifications are
              printed in a way that allows them to be reused as input.
The -r option removes a
              completion specification for each name, or, if no names
are supplied, all comple‚
              tion specifications.

              The process of applying these completion specifications
when word completion is
              attempted is described above under Programmable
Completion.

              Other options, if specified, have the following meanings.
 The arguments to the
              -G, -W, and -X options (and, if necessary, the -P
and -S options) should be
              quoted to protect them from expansion before the complete
builtin is invoked.
              -o comp-option
                      The comp-option controls several aspects of
the compspec's behavior
                      beyond the simple generation of completions.
comp-option may be one of:
                      bashdefault
                              Perform the rest of the default bash
completions if the compspec

                              generates no matches.
                      default Use readline's default filename
completion if the compspec gener‚
                              ates no matches.
                      dirnames
                              Perform directory name completion if
the compspec generates no
                              matches.
                      filenames
                              Tell readline that the compspec generates
filenames, so it can
                              perform any filename-specific processing
(like adding a slash to
                              directory names or suppressing trailing
spaces). Intended to be
                              used with shell functions.
                      nospace Tell readline not to append a space
(the default) to words com‚
                              pleted at the end of the line.
              -A action
                      The action may be one of the following to
generate a list of possible
                      completions:
                      alias Alias names. May also be specified as
-a.
                      arrayvar
                              Array variable names.
                      binding Readline key binding names.
                      builtin Names of shell builtin commands. May
also be specified as -b.
                      command Command names. May also be specified as
-c.
                      directory
                              Directory names. May also be specified
as -d.
                      disabled
                              Names of disabled shell builtins.
                      enabled Names of enabled shell builtins.

                      export Names of exported shell variables. May
also be specified as -e.
                      file File names. May also be specified as -f.
                      function
                              Names of shell functions.
                      group Group names. May also be specified as
-g.
                      helptopic
                              Help topics as accepted by the help
builtin.
                      hostname
                              Hostnames, as taken from the file
specified by the HOSTFILE shell
                              variable.
                      job Job names, if job control is active.
May also be specified as
                              -j.
                      keyword Shell reserved words. May also be
specified as -k.
                      running Names of running jobs, if job control is
active.
                      service Service names. May also be specified as
-s.
                      setopt Valid arguments for the -o option to the
set builtin.
                      shopt Shell option names as accepted by the
shopt builtin.
                      signal Signal names.
                      stopped Names of stopped jobs, if job control is
active.
                      user User names. May also be specified as -u.
                      variable
                              Names of all shell variables. May also
be specified as -v.
              -G globpat
                      The filename expansion pattern globpat is
expanded to generate the possi‚
                      ble completions.
              -W wordlist
                      The wordlist is split using the characters in the
IFS special variable as
                      delimiters, and each resultant word is expanded.
 The possible comple‚
                      tions are the members of the resultant list
which match the word being
                      completed.
              -C command
                      command is executed in a subshell environment,
and its output is used as
                      the possible completions.
              -F function
                      The shell function function is executed in the
current shell environment.
                      When it finishes, the possible completions are
retrieved from the value
                      of the COMPREPLY array variable.
              -X filterpat
                      filterpat is a pattern as used for filename
expansion. It is applied to
                      the list of possible completions generated by the
preceding options and
                      arguments, and each completion matching
filterpat is removed from the
                      list. A leading ! in filterpat negates the
pattern; in this case, any
                      completion not matching filterpat is removed.
              -P prefix
                      prefix is added at the beginning of each
possible completion after all
                      other options have been applied.
              -S suffix
                      suffix is appended to each possible completion
after all other options
                      have been applied.

              The return value is true unless an invalid option is
supplied, an option other
              than -p or -r is supplied without a name argument, an
attempt is made to remove a
              completion specification for a name for which no
specification exists, or an
              error occurs adding a completion specification.

       continue [n]
              Resume the next iteration of the enclosing for, while,
until, or select loop. If
              n is specified, resume at the nth enclosing loop.
n must be ‚• 1. If n is
              greater than the number of enclosing loops, the last
enclosing loop (the ‚‚top-
              level'' loop) is resumed. The return value is 0 unless
the shell is not execut‚
              ing a loop when continue is executed.

       declare [-afFirtx] [-p] [name[=value] ...]
       typeset [-afFirtx] [-p] [name[=value] ...]
              Declare variables and/or give them attributes. If no
names are given then dis‚
              play the values of variables. The -p option will display
the attributes and val‚
              ues of each name. When -p is used, additional options
are ignored. The -F
              option inhibits the display of function definitions;
only the function name and
              attributes are printed. If the extdebug shell option is
enabled using shopt, the
              source file name and line number where the function is
defined are displayed as
              well. The -F option implies -f. The following options
can be used to restrict
              output to variables with the specified attribute or to
give variables attributes:
              -a Each name is an array variable (see Arrays above).
              -f Use function names only.
              -i The variable is treated as an integer; arithmetic
evaluation (see ARITH‚
                     METIC EVALUATION ) is performed when the variable
is assigned a value.
              -r Make names readonly. These names cannot then be
assigned values by subse‚
                     quent assignment statements or unset.
              -t Give each name the trace attribute. Traced
functions inherit the DEBUG
                     trap from the calling shell. The trace
attribute has no special meaning
                     for variables.
              -x Mark names for export to subsequent commands via
the environment.

              Using ‚+' instead of ‚-' turns off the attribute
instead, with the exception that
              +a may not be used to destroy an array variable. When
used in a function, makes
              each name local, as with the local command. If a
variable name is followed by
              =value, the value of the variable is set to value. The
return value is 0 unless
              an invalid option is encountered, an attempt is made to
define a function using
              ‚‚-f foo=bar'', an attempt is made to assign a value
to a readonly variable, an
              attempt is made to assign a value to an array variable
without using the compound
              assignment syntax (see Arrays above), one of the names is
not a valid shell vari‚
              able name, an attempt is made to turn off readonly status
for a readonly vari‚
              able, an attempt is made to turn off array status for
an array variable, or an
              attempt is made to display a non-existent function with
-f.

       dirs [-clpv] [+n] [-n]
              Without options, displays the list of currently
remembered directories. The
              default display is on a single line with directory
names separated by spaces.
              Directories are added to the list with the pushd
command; the popd command
              removes entries from the list.
              +n Displays the nth entry counting from the left
of the list shown by dirs
                     when invoked without options, starting with zero.
              -n Displays the nth entry counting from the right of
the list shown by dirs
                     when invoked without options, starting with zero.
              -c Clears the directory stack by deleting all of the
entries.
              -l Produces a longer listing; the default
listing format uses a tilde to
                     denote the home directory.
              -p Print the directory stack with one entry per line.
              -v Print the directory stack with one entry per line,
 prefixing each entry
                     with its index in the stack.

              The return value is 0 unless an invalid option is
supplied or n indexes beyond
              the end of the directory stack.

       disown [-ar] [-h] [jobspec ...]
              Without options, each jobspec is removed from the table
of active jobs. If the
              -h option is given, each jobspec is not removed from the
table, but is marked so
              that SIGHUP is not sent to the job if the shell receives
a SIGHUP. If no jobspec
              is present, and neither the -a nor the -r option is
supplied, the current job is
              used. If no jobspec is supplied, the -a option means to
remove or mark all jobs;
              the -r option without a jobspec argument restricts
operation to running jobs.
              The return value is 0 unless a jobspec does not specify a
valid job.

       echo [-neE] [arg ...]
              Output the args, separated by spaces, followed by a
newline. The return status
              is always 0. If -n is specified, the trailing newline
is suppressed. If the -e
              option is given, interpretation of the following
backslash-escaped characters is
              enabled. The -E option disables the interpretation of
these escape characters,
              even on systems where they are interpreted by default.
The xpg_echo shell option
              may be used to dynamically determine whether or not
echo expands these escape
              characters by default. echo does not interpret -- to
mean the end of options.
              echo interprets the following escape sequences:
              \a alert (bell)
              \b backspace
              \c suppress trailing newline
              \e an escape character
              \f form feed
              \n new line
              \r carriage return
              \t horizontal tab
              \v vertical tab
              \\ backslash
              \0nnn the eight-bit character whose value is the octal
value nnn (zero to three
                     octal digits)
              \nnn the eight-bit character whose value is the octal
value nnn (one to three
                     octal digits)
              \xHH the eight-bit character whose value is the
hexadecimal value HH (one or
                     two hex digits)

       enable [-adnps] [-f filename] [name ...]
              Enable and disable builtin shell commands. Disabling a
builtin allows a disk
              command which has the same name as a shell builtin to be
executed without speci‚
              fying a full pathname, even though the shell normally
searches for builtins
              before disk commands. If -n is used, each name is
disabled; otherwise, names are
              enabled. For example, to use the test binary found via
the PATH instead of the
              shell builtin version, run ‚‚enable -n test''. The
-f option means to load the
              new builtin command name from shared object filename, on
 systems that support
              dynamic loading. The -d option will delete a builtin
previously loaded with -f.
              If no name arguments are given, or if the -p option is
supplied, a list of shell
              builtins is printed. With no other option arguments,
the list consists of all
              enabled shell builtins. If -n is supplied, only disabled
builtins are printed.
              If -a is supplied, the list printed includes all
builtins, with an indication of
              whether or not each is enabled. If -s is supplied, the
output is restricted to
              the POSIX special builtins. The return value is 0
unless a name is not a shell
              builtin or there is an error loading a new builtin from a
shared object.
       eval [arg ...]
              The args are read and concatenated together into a single
command. This command
              is then read and executed by the shell, and its exit
status is returned as the
              value of eval. If there are no args, or only null
arguments, eval returns 0.

       exec [-cl] [-a name] [command [arguments]]
              If command is specified, it replaces the shell. No new
process is created. The
              arguments become the arguments to command. If the -l
option is supplied, the
              shell places a dash at the beginning of the zeroth arg
passed to command. This
              is what login(1) does. The -c option causes command to
be executed with an empty
              environment. If -a is supplied, the shell passes name as
the zeroth argument to
              the executed command. If command cannot be executed
for some reason, a non-
              interactive shell exits, unless the shell option execfail
is enabled, in which
              case it returns failure. An interactive shell returns
failure if the file cannot
              be executed. If command is not specified, any
redirections take effect in the
              current shell, and the return status is 0. If there is
a redirection error, the
              return status is 1.

       exit [n]
              Cause the shell to exit with a status of n. If n is
omitted, the exit status is
              that of the last command executed. A trap on EXIT is
executed before the shell
              terminates.

       export [-fn] [name[=word]] ...
       export -p
              The supplied names are marked for automatic export to the
environment of subse‚
              quently executed commands. If the -f option is given,
the names refer to func‚
              tions. If no names are given, or if the -p option is
supplied, a list of all
              names that are exported in this shell is printed.
The -n option causes the
              export property to be removed from each name. If a
variable name is followed by