@node shar Invocation
@section Invoking shar
@pindex shar
@cindex create a shell archive
@ignore
#  -*- buffer-read-only: t -*- vi: set ro:
#
# DO NOT EDIT THIS FILE   (invoke-shar.texi)
#
# It has been AutoGen-ed
# From the definitions    shar-opts.def
# and the template file   agtexi-cmd.tpl
@end ignore

If no @file{file}s are specified, the list of input files is read
from standard input.  Standard input must not be a terminal.
@command{shar} creates "shell archives" (or shar files) which are in
text format and can be emailed.  These files may be unpacked later by
executing them with @file{/bin/sh}.  The resulting archive is sent to
standard out unless the @option{-o} option is given.  A wide range of
features provide extensive flexibility in manufacturing shars and in
specifying @command{shar} "smartness".  Archives may be fairly simple
(@option{--vanilla-operation}) or essentially a mailable @command{tar}
archive.

Options may be specified in any order until a @code{file} argument is
recognized.  If the @option{--intermix-type} option has been specified,
more compression and encoding options will be recognized between the
@file{file} arguments.

Though this program supports @command{uuencode}-d files, they
are deprecated.  If you are emailing files, please consider
mime-encoded files.  If you do @command{uuencode}, base64 is the
preferred encoding method.

This section was generated by @strong{AutoGen},
using the @code{agtexi-cmd} template and the option descriptions for the @code{shar} program.
This software is released under the GNU General Public License, version 3 or later.

@menu
* shar usage::                  shar help/usage (@option{--help})
* shar compression::            compression options
* shar encoding::               encoding options
* shar in-out::                 in-out options
* shar headers::                headers options
* shar xmit-defenses::          xmit-defenses options
* shar shar-flavors::           shar-flavors options
* shar internationalization::   internationalization options
* shar feedback::               feedback options
* shar config::                 presetting/configuring shar
* shar exit status::            exit status
* shar Authors::                Authors
* shar Bugs::                   Bugs
* shar Examples::               Examples
* shar Warnings::               Warnings
* shar See Also::               See Also
@end menu

@node shar usage
@subsection shar help/usage (@option{--help})
@cindex shar help

This is the automatically generated usage text for shar.

The text printed is the same whether selected with the @code{help} option
(@option{--help}) or the @code{more-help} option (@option{--more-help}).  @code{more-help} will print
the usage text by passing it through a pager program.
@code{more-help} is disabled on platforms without a working
@code{fork(2)} function.  The @code{PAGER} environment variable is
used to select the program, defaulting to @file{more}.  Both will exit
with a status code of 0.

@exampleindent 0
@example
shar (GNU sharutils) - create a shell archive
Usage:  shar [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [<file>...]

Specify compression:
   -p, --intermix-type        specify compression for input files
                                - prohibits the option 'vanilla-operation'
   -C, --compactor=PROG       specify compaction (compression) program PROG
                                - prohibits the option 'vanilla-operation'
                                - may appear multiple times
                                - it must be known to shar: xz gzip bzip2
   -g, --level-of-compression=LEVEL
                              pass LEVEL for compression
                                - it must be in the range: 1 to 9

Specify file encoding methodology:
   -M, --mixed-uuencode       decide uuencoding for each file
   -B, --uuencode             treat all files as binary
                                - an alternate for mixed-uuencode
   -T, --text-files           treat all files as text
                                - an alternate for mixed-uuencode

Specifying file selection and output modes:
   -o, --output-prefix=str    print output to file PREFIX.nn
   -l, --whole-size-limit=SIZE
                              split archive, not files, to SIZE
                                - requires the option 'output-prefix'
                                - is scalable with a suffix: k/K/m/M/g/G/t/T
                                - it must lie in one of the ranges:
                                  8 to 1023, or 8192 to 4194304
   -L, --split-size-limit=SIZE
                              split archive or files to SIZE
                                - requires the option 'output-prefix'
                                - is scalable with a suffix: k/K/m/M/g/G/t/T
                                - it must lie in one of the ranges:
                                  8 to 1023, or 8192 to 4194304
                                - an alternate for 'whole-size-limit'
   -I, --input-file-list=FILE read file list from FILE

Controlling the shar headers:
   -n, --archive-name=NAME    use NAME to document the archive
   -s, --submitter=NAME       override the submitter name with NAME
   -a, --net-headers          output Submitted-by: & Archive-name: headers
                                - requires the option 'archive-name'
   -c, --cut-mark             start the shar with a cut line
   -t, --translate            translate messages in the script

Protecting against transmission issues:
       --no-character-count   do not use `wc -c' to check size
   -D, --no-md5-digest        do not use md5sum digest to verify
   -F, --force-prefix         apply the prefix character on every line
   -d, --here-delimiter=DELIM use DELIM to delimit the files

Producing different kinds of shars:
   -V, --vanilla-operation    produce very simple shars
   -P, --no-piping            use temporary files between programs
   -x, --no-check-existing    blindly overwrite existing files
   -X, --query-user           ask user before overwriting files
                                - prohibits the option 'vanilla-operation'
   -m, --no-timestamp         do not restore modification times
   -Q, --quiet-unshar         avoid verbose messages at unshar time
   -f, --basename             restore in one directory, despite hierarchy

Internationalization options:
       --no-i18n              do not internationalize
       --print-text-domain-dir  print directory with shar messages

User feedback/entertainment:
   -q, --quiet                do not output verbose messages
       --silent               an alias for the 'quiet' option

Version, usage and configuration options:
   -v, --version[=MODE]       output version information and exit
   -h, --help                 display extended usage information and exit
   -!, --more-help            extended usage information passed thru pager
   -R, --save-opts[=FILE]     save the option state to a config file FILE
   -r, --load-opts=FILE       load options from the config file FILE
                                - disabled with '--no-load-opts'
                                - may appear multiple times

Options are specified by doubled hyphens and their name or by a single
hyphen and the flag character.
If no 'file's are specified, the list of input files is read from a
standard input.  Standard input must not be a terminal.

The following option preset mechanisms are supported:
 - reading file $HOME/.sharrc

'shar' creates "shell archives" (or shar files) which are in text format
and can be emailed.  These files may be unpacked later by executing them
with '/bin/sh'.  The resulting archive is sent to standard out unless the
'-o' option is given.  A wide range of features provide extensive
flexibility in manufacturing shars and in specifying 'shar' "smartness".
Archives may be fairly simple ('--vanilla-operation') or essentially a
mailable 'tar' archive.

Options may be specified in any order until a 'file' argument is
recognized.  If the '--intermix-type' option has been specified, more
compression and encoding options will be recognized between the 'file'
arguments.

Though this program supports 'uuencode'-d files, they are deprecated.  If
you are emailing files, please consider mime-encoded files.  If you do
'uuencode', base64 is the preferred encoding method.

Please send bug reports to:  <bug-gnu-utils@@gnu.org>
@end example
@exampleindent 4

@node shar compression
@subsection compression options
Specifying compression.
@subsubheading intermix-type option (-p).
@anchor{shar intermix-type}
@cindex shar-intermix-type

This is the ``specify compression for input files'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
must not appear in combination with any of the following options:
vanilla-operation.
@end itemize

Allow positional parameter options.  The compression method and
encoding method options may be intermixed with file names.
Files named after these options will be processed in the specified way.
@subsubheading compactor option (-C).
@anchor{shar compactor}
@cindex shar-compactor

This is the ``specify compaction (compression) program'' option.
This option takes a string argument @file{PROGRAM}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@item
must not appear in combination with any of the following options:
vanilla-operation.
@end itemize

The @command{gzip}, @command{bzip2} and @command{compress} compactor
commands may be specified by the program name as the option name,
e.g. @option{--gzip}.  Those options, however, are being deprecated.
There is also the @command{xz} compactor now.  Specify @command{xz}
with @option{-C xz} or @option{--compactor=xz}.

        Specifying the compactor "@samp{none}" will disable file compression.
Compressed files are never processed as plain text.  They are always
uuencoded and the recipient must have @command{uudecode} to unpack
them.

Specifying the compactor @command{compress} is deprecated.
@subsubheading level-of-compression option (-g).
@anchor{shar level-of-compression}
@cindex shar-level-of-compression

This is the ``pass @file{level} for compression'' option.
This option takes a number argument @file{LEVEL}.
Some compression programs allow for a level of compression.  The
default is @code{9}, but this option allows you to specify something
else.  This value is used by @command{gzip}, @command{bzip2} and
@command{xz}, but not @command{compress}.
@subsubheading bzip2 option (-j).
@anchor{shar bzip2}
@cindex shar-bzip2

This is the ``@command{bzip2} and @command{uuencode} files'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@end itemize

@command{bzip2} compress and @command{uuencode} all files
prior to packing.  The recipient must have @command{uudecode}
@command{bzip2} in order to unpack.

@strong{NOTE}@strong{: THIS OPTION IS DEPRECATED}
@subsubheading gzip option (-z).
@anchor{shar gzip}
@cindex shar-gzip

This is the ``@command{gzip} and @command{uuencode} files'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@end itemize

@command{gzip} compress and @command{uuencode} all files prior
to packing.  The recipient must have @command{uudecode} and
@command{gzip} in order to unpack.

@strong{NOTE}@strong{: THIS OPTION IS DEPRECATED}
@subsubheading compress option (-Z).
@anchor{shar compress}
@cindex shar-compress

This is the ``@command{compress} and @command{uuencode} files'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@item
must be compiled in by defining @code{HAVE_COMPRESS} during the compilation.
@end itemize

@command{compress} and @command{uuencode} all files prior to
packing.  The recipient must have @command{uudecode} and
@command{compress} in order to unpack.

@strong{NOTE}@strong{: THIS OPTION IS DEPRECATED}
@subsubheading level-for-gzip option.
@anchor{shar level-for-gzip}
@cindex shar-level-for-gzip

This is an alias for the @code{level-of-compression} option,
@pxref{shar level-of-compression, the level-of-compression option documentation}.

@subsubheading bits-per-code option (-b).
@anchor{shar bits-per-code}
@cindex shar-bits-per-code

This is the ``pass @file{bits} (default 12) to compress'' option.
This option takes a string argument @file{BITS}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
must be compiled in by defining @code{HAVE_COMPRESS} during the compilation.
@end itemize

This is the compression factor used by the @command{compress} program.

@strong{NOTE}@strong{: THIS OPTION IS DEPRECATED}
@node shar encoding
@subsection encoding options
Specifying file encoding methodology.
Files may be stored in the shar either as plain text or uuencoded.
By default, the program selects which by examining the file.
You may force the selection for all files.  In intermixed option/file
mode, this setting may be changed during processing.
@subsubheading mixed-uuencode option (-M).
@anchor{shar mixed-uuencode}
@cindex shar-mixed-uuencode

This is the ``decide uuencoding for each file'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
is a member of the mixed-uuencode class of options.
@end itemize

Automatically determine if the files are text or binary and archive
correctly.  Files found to be binary are uuencoded prior to packing.
This is the default behavior for @command{shar}.

For a file to be considered a text file instead of a binary file,
all the following should be true:
@enumerate
@item
The file does not contain any ASCII control character besides @key{BS}
(backspace), @key{HT} (horizontal tab), @key{LF} (new line) or
@key{FF} (form feed).
@item
The file contains no character with its eighth-bit set.
@item
The file contains no line beginning with the five letters
"@samp{from }", capitalized or not.  (Mail handling programs
will often gratuitously insert a @code{>} character before it.)
@item
The file is either empty or ends with a @key{LF} (newline) byte.
@item
No line in the file contains more than 200 characters.  For counting
purpose, lines are separated by a @key{LF} (newline).
@end enumerate
@subsubheading uuencode option (-B).
@anchor{shar uuencode}
@cindex shar-uuencode

This is the ``treat all files as binary'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
is a member of the mixed-uuencode class of options.
@end itemize

Use @command{uuencode} prior to packing all files.  This
increases the size of the archive.  The recipient must have
@command{uudecode} in order to unpack.  Compressed files are
always encoded.
@subsubheading text-files option (-T).
@anchor{shar text-files}
@cindex shar-text-files

This is the ``treat all files as text'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
is a member of the mixed-uuencode class of options.
@end itemize

If you have files with non-ascii bytes or text that some mail handling
programs do not like, you may find difficulties.  However, if you are
using FTP or SSH/SCP, the non-conforming text files should be okay.
@node shar in-out
@subsection in-out options
Specifying file selection and output modes.
@subsubheading output-prefix option (-o).
@anchor{shar output-prefix}
@cindex shar-output-prefix

This is the ``print output to file prefix.nn'' option.
This option takes a string argument @file{PREFIX}.
Save the archive to files @file{prefix.01} thru @file{prefix.nn}
instead of sending all output to standard out.  Must be specified when
the @option{--whole-size-limit} or @option{--split-size-limit}
options are specified.

When @var{prefix} contains a @samp{%} character, @var{prefix} is then
interpreted as a @code{sprintf} format, which should be able to display
a single decimal number.  When @var{prefix} does not contain such a
@samp{%} character, the string @samp{.%02d} is internally appended.
@subsubheading whole-size-limit option (-l).
@anchor{shar whole-size-limit}
@cindex shar-whole-size-limit

This is the ``split archive, not files, to @i{size}'' option.
This option takes a number argument @file{SIZE}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
is a member of the whole-size-limit class of options.
@item
must appear in combination with the following options:
output-prefix.
@end itemize

Limit the output file size to @file{size} bytes, but don't split input
files.  If @file{size} is less than 1024, then it will be multiplied
by 1024.  The value may also be specified with a k, K, m or M suffix.
The number is then multiplied by 1000, 1024, 1000000, or 1048576,
respectively.  4M (4194304) is the maximum allowed.

Unlike the @code{split-size-limit} option, this allows the recipient
of the shar files to unpack them in any order.
@subsubheading split-size-limit option (-L).
@anchor{shar split-size-limit}
@cindex shar-split-size-limit

This is the ``split archive or files to @i{size}'' option.
This option takes a number argument @file{SIZE}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
is a member of the whole-size-limit class of options.
@item
must appear in combination with the following options:
output-prefix.
@end itemize

Limit output file size to @file{size} bytes, splitting files if
necessary.  The allowed values are specified as with the
@option{--whole-size-limit} option.

The archive parts created with this option must be unpacked in the
correct order.  If the recipient of the shell archives wants to put
all of them in a single email folder (file), they will have to be
saved in the correct order for @command{unshar} to unpack them all at
once (using one of the split archive options).
@xref{unshar Invocation}.
@subsubheading input-file-list option (-I).
@anchor{shar input-file-list}
@cindex shar-input-file-list

This is the ``read file list from a file'' option.
This option takes a string argument @file{FILE}.
This option causes @file{file} to be reopened as standard input.  If
no files are found on the input line, then standard input is read for
input file names.  Use of this option will prohibit input files from
being listed on the command line.

Input must be in a form similar to that generated by @command{find},
one filename per line.  This switch is especially useful when the
command line will not hold the list of files to be archived.

If the @option{--intermix-type} option is specified on the command
line, then the compression options may be included in the standard
input on lines by themselves and no file name may begin with a hyphen.

For example:
@example
@{ echo --compact xz
   find . -type f -print | sort
@} | shar -S -p -L50K -o /somewhere/big
@end example
@subsubheading stdin-file-list option (-S).
@anchor{shar stdin-file-list}
@cindex shar-stdin-file-list

This is the ``read file list from standard input'' option.
This option is actually a no-op.  It is a wrapper for
@option{--input-file-list=-}.

@strong{NOTE}@strong{: THIS OPTION IS DEPRECATED}
@node shar headers
@subsection headers options
Controlling the shar headers.
@subsubheading archive-name option (-n).
@anchor{shar archive-name}
@cindex shar-archive-name

This is the ``use @file{name} to document the archive'' option.
This option takes a string argument @file{NAME}.
Name of archive to be included in the subject header of the shar
files.  See the @option{--net-headers} option.
@subsubheading submitter option (-s).
@anchor{shar submitter}
@cindex shar-submitter

This is the ``override the submitter name'' option.
This option takes a string argument @file{WHO@@WHERE}.
@command{shar} will normally determine the submitter name by querying
the system.  Use this option if it is being done on behalf of another.
@subsubheading net-headers option (-a).
@anchor{shar net-headers}
@cindex shar-net-headers

This is the ``output submitted-by: & archive-name: headers'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
must appear in combination with the following options:
archive-name.
@end itemize

Adds specialized email headers:
@example
Submitted-by: @i{who@@where}
Archive-name: @i{name}/part##
@end example
The @i{who@@where} is normally derived, but can be specified with the
@option{--submitter} option.  The @i{name} must be provided with the
@option{--archive-name} option.  If the archive name includes a slash
(@code{/}) character, then the @code{/part##} is omitted.  Thus
@samp{-n xyzzy} produces:
@example
xyzzy/part01
xyzzy/part02
@end example

@noindent
while @samp{-n xyzzy/patch} produces:
@example
xyzzy/patch01
xyzzy/patch02
@end example

@noindent
and @samp{-n xyzzy/patch01.} produces:
@example
xyzzy/patch01.01
xyzzy/patch01.02
@end example
@subsubheading cut-mark option (-c).
@anchor{shar cut-mark}
@cindex shar-cut-mark

This is the ``start the shar with a cut line'' option.
A line saying 'Cut here' is placed at the
start of each output file.
@subsubheading translate option (-t).
@anchor{shar translate}
@cindex shar-translate

This is the ``translate messages in the script'' option.
Translate messages in the script.  If you have set the @samp{LANG}
environment variable, messages printed by @command{shar} will be in the
specified language.  The produced script will still be emitted using
messages in the lingua franca of the computer world: English.  This
option will cause the script messages to appear in the languages
specified by the @samp{LANG} environment variable set when the script
is produced.
@node shar xmit-defenses
@subsection xmit-defenses options
Protecting against transmission issues.
@subsubheading no-character-count option.
@anchor{shar no-character-count}
@cindex shar-no-character-count

This is the ``do not use `wc -c' to check size'' option.
Do NOT check each file with 'wc -c' after unpack.
The default is to check.
@subsubheading no-md5-digest option (-D).
@anchor{shar no-md5-digest}
@cindex shar-no-md5-digest

This is the ``do not use @command{md5sum} digest to verify'' option.
Do @emph{not} use @command{md5sum} digest to verify the unpacked files.
The default is to check.
@subsubheading force-prefix option (-F).
@anchor{shar force-prefix}
@cindex shar-force-prefix

This is the ``apply the prefix character on every line'' option.
Forces the prefix character to be prepended to every line, even if
not required.  This option may slightly increase the size of the archive,
especially if @option{--uuencode} or a compression option is used.
@subsubheading here-delimiter option (-d).
@anchor{shar here-delimiter}
@cindex shar-here-delimiter

This is the ``use @i{delim} to delimit the files'' option.
This option takes a string argument @file{DELIM}.
Use DELIM to delimit the files in the shar instead of SHAR_EOF.
This is for those who want to personalize their shar files.
The delimiter will always be prefixed and suffixed with underscores.
@node shar shar-flavors
@subsection shar-flavors options
Producing different kinds of shars.
@subsubheading vanilla-operation option (-V).
@anchor{shar vanilla-operation}
@cindex shar-vanilla-operation

This is the ``produce very simple shars'' option.
This option produces @samp{vanilla} shars which rely only upon the
existence of @command{echo}, @command{test} and @command{sed} in the
unpacking environment.

It changes the default behavior from mixed mode
(@option{--mixed-uuencode}) to text mode (@option{--text-files}).
Warnings are produced if options are specified that will require
decompression or decoding in the unpacking environment.

@subsubheading no-piping option (-P).
@anchor{shar no-piping}
@cindex shar-no-piping

This is the ``use temporary files between programs'' option.
In the @file{shar} file, use a temporary file to hold file contents
between unpacking stages instead of using pipes.  This option is
mandatory when you know the unpacking will happen on systems that do
not support pipes.
@subsubheading no-check-existing option (-x).
@anchor{shar no-check-existing}
@cindex shar-no-check-existing

This is the ``blindly overwrite existing files'' option.
Create the archive so that when processed it will overwrite existing
files without checking first.  If neither this option nor the
@option{--query-user} option is specified, the unpack will not
overwrite pre-existing files.  In all cases, however, if
@option{--cut-mark} is passed as a parameter to the script when
unpacking, then existing files will be overwritten unconditionally.

@example
sh shar-archive-file -c
@end example
@subsubheading query-user option (-X).
@anchor{shar query-user}
@cindex shar-query-user

This is the ``ask user before overwriting files'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
must not appear in combination with any of the following options:
vanilla-operation.
@end itemize

When unpacking, interactively ask the user if files should be
overwritten.  Do not use for shars submitted to the net.

Use of this option produces shars which @emph{will} cause problems
with some unshar-style procedures, particularly when used
together with vanilla mode (@option{--vanilla-operation}).  Use this
feature mainly for archives to be passed among agreeable parties.
Certainly, @option{-X} is @emph{not} for shell archives which are to be
submitted to Usenet or other public networks.

The problem is that @command{unshar} programs or procedures often feed
@file{/bin/sh} from its standard input, thus putting @file{/bin/sh}
and the shell archive script in competition for input lines.  As an
attempt to alleviate this problem, @command{shar} will try to detect
if @file{/dev/tty} exists at the receiving site and will use it to
read user replies.  But this does not work in all cases, it may happen
that the receiving user will have to avoid using @command{unshar}
programs or procedures, and call @file{/bin/sh} directly.  In vanilla
mode, using @file{/dev/tty} is not even attempted.
@subsubheading no-timestamp option (-m).
@anchor{shar no-timestamp}
@cindex shar-no-timestamp

This is the ``do not restore modification times'' option.
Avoid generating 'touch' commands to restore the file modification
dates when unpacking files from the archive.

When file modification times are not preserved, project build programs
like "make" will see built files older than the files they get built
from.  This is why, when this option is not used, a special effort is
made to restore timestamps.
@subsubheading quiet-unshar option (-Q).
@anchor{shar quiet-unshar}
@cindex shar-quiet-unshar

This is the ``avoid verbose messages at unshar time'' option.
Verbose OFF.  Disables the inclusion of comments to be output when
the archive is unpacked.
@subsubheading basename option (-f).
@anchor{shar basename}
@cindex shar-basename

This is the ``restore in one directory, despite hierarchy'' option.
Restore by the base file name only, rather than path.  This option
causes only file names to be used, which is useful when building a
shar from several directories, or another directory.  Note that if a
directory name is passed to shar, the substructure of that directory
will be restored whether this option is specified or not.
@node shar internationalization
@subsection internationalization options
Internationalization options.
@subsubheading no-i18n option.
@anchor{shar no-i18n}
@cindex shar-no-i18n

This is the ``do not internationalize'' option.
Do not produce internationalized shell archives, use default English
messages.  By default, shar produces archives that will try to output
messages in the unpackers preferred language (as determined by the
LANG/LC_MESSAGES environmental variables) when they are unpacked.  If
no message file for the unpackers language is found at unpack time,
messages will be in English.
@subsubheading print-text-domain-dir option.
@anchor{shar print-text-domain-dir}
@cindex shar-print-text-domain-dir

This is the ``print directory with shar messages'' option.
Prints the directory shar looks in to find messages files
for different languages, then immediately exits.
@node shar feedback
@subsection feedback options
User feedback/entertainment.
@subsubheading quiet option (-q).
@anchor{shar quiet}
@cindex shar-quiet

This is the ``do not output verbose messages'' option.
omit progress messages.
@subsubheading silent option.
@anchor{shar silent}
@cindex shar-silent

This is an alias for the @code{quiet} option,
@pxref{shar quiet, the quiet option documentation}.



@node shar config
@subsection presetting/configuring shar

Any option that is not marked as @i{not presettable} may be preset by
loading values from configuration ("rc" or "ini") files.


@noindent
@code{libopts} will search in @file{$HOME} for configuration (option) data.
The environment variable @code{HOME, } is expanded and replaced when
the program runs
If this is a plain file, it is simply processed.
If it is a directory, then a file named @file{.sharrc} is searched for within that directory.

Configuration files may be in a wide variety of formats.
The basic format is an option name followed by a value (argument) on the
same line.  Values may be separated from the option name with a colon,
equal sign or simply white space.  Values may be continued across multiple
lines by escaping the newline with a backslash.

Multiple programs may also share the same initialization file.
Common options are collected at the top, followed by program specific
segments.  The segments are separated by lines like:
@example
[SHAR]
@end example
@noindent
or by
@example
<?program shar>
@end example
@noindent
Do not mix these styles within one configuration file.

Compound values and carefully constructed string values may also be
specified using XML syntax:
@example
<option-name>
   <sub-opt>...&lt;...&gt;...</sub-opt>
</option-name>
@end example
@noindent
yielding an @code{option-name.sub-opt} string value of
@example
"...<...>..."
@end example
@code{AutoOpts} does not track suboptions.  You simply note that it is a
hierarchicly valued option.  @code{AutoOpts} does provide a means for searching
the associated name/value pair list (see: optionFindValue).

The command line options relating to configuration and/or usage help are:

@subsubheading version (-v)

Print the program version to standard out, optionally with licensing
information, then exit 0.  The optional argument specifies how much licensing
detail to provide.  The default is to print the license name with the version.  The licensing infomation may be selected with an option argument.
Only the first letter of the argument is examined:

@table @samp
@item version
Only print the version.
@item copyright
Name the copyright usage licensing terms.  This is the default.
@item verbose
Print the full copyright usage licensing terms.
@end table

@node shar exit status
@subsection shar exit status

One of the following exit values will be returned:
@table @samp
@item 0 (EXIT_SUCCESS)
Successful program execution.
@item 1 (EXIT_OPTION_ERROR)
The command options were misconfigured.
@item 2 (EXIT_FILE_NOT_FOUND)
a specified input could not be found
@item 3 (EXIT_CANNOT_OPENDIR)
open/close of specified directory failed
@item 4 (EXIT_FAILED)
Resource limit/miscelleaneous shar command failure
@item 63 (EXIT_BUG)
There is a shar command bug.  Please report it.
@item 66 (EX_NOINPUT)
A specified configuration file could not be loaded.
@item 70 (EX_SOFTWARE)
libopts had an internal operational error.  Please report
it to autogen-users@@lists.sourceforge.net.  Thank you.
@end table
@node shar Authors
@subsection shar Authors
The @file{shar} and @file{unshar} programs is the collective work of
many authors.  Many people contributed by reporting problems,
suggesting various improvements or submitting actual code.  A list of
these people is in the @file{THANKS} file in the sharutils distribution.
@node shar Bugs
@subsection shar Bugs
Please put @samp{sharutils} in the subject line for emailed bug
reports.  It helps to spot the message.
@node shar Examples
@subsection shar Examples
The first shows how to make a shell archive out of all C program
sources.  The second produces a shell archive with all @file{.c} and
@file{.h} files, which unpacks silently.  The third gives a shell
archive of all uuencoded @file{.arc} files, into numbered files
starting from @file{arc.sh.01}.  The last example gives a shell
archive which will use only the file names at unpack time.

@example
shar *.c > cprog.shar
shar -Q *.[ch] > cprog.shar
shar -B -l28 -oarc.sh *.arc
shar -f /lcl/src/u*.c > u.sh
@end example
@node shar Warnings
@subsection shar Warnings
No attempt is made to restore the protection and modification dates
for directories, even if this is done by default for files.  Thus, if
a directory is given to @code{shar}, the protection and modification
dates of corresponding unpacked directory may not match those of the
original.

If a directory is passed to shar, it may be scanned more than once, to
conserve memory.  Therefore, do not change the directory contents
while shar is running.

Be careful that the output file(s) are not included in the inputs or
shar may loop until the disk fills up.  Be particularly careful when a
directory is passed to shar that the output files are not in that
directory or a subdirectory of it.

Use of the compression and encoding options will slow the archive
process, perhaps considerably.

Use of the @option{--query-user} produces shars which @emph{will}
cause problems with many unshar procedures.  Use this feature only for
archives to be passed among agreeable parties.  Certainly,
@code{query-user} is NOT for shell archives which are to be
distributed across the net.  The use of compression in net shars will
cause you to be flamed off the earth.  Not using the
@option{--no-timestamp} or @option{--force-prefix} options may also
get you occasional complaints.  Put these options into your
@file{~/.sharrc} file.
@node shar See Also
@subsection shar See Also
unshar(1)
