Documenation update

Hi there,

I've rewritten some sections of the manpage, as I said I would. First, a
few general remarks:

1) it would be more clear if the explanation of an option is written on
a new line, like in most manpages. When it's on the same line, it
appears as the beginning of a sentence sometimes, which is confusing.

2) The -am (--alter=mask), what exactly does that do? The manpage
doesn't give me a clue...

3) The --help option places -ac and -aa under common options, which they
are not. They are create and compare options.

OK, here are the sections. First the old one, then my new one.

=====================================
Old version:

--alter=SI  and  --alter=binary can be used several times, they affect all
prefix which follow even those found in file included by -B option up to the
next --alter=... occurrence. Note that if in  a  file  included  by  -B
option
an  --alter=binary  or  --alter=SI  is  met, it affects all the following
prefix even those outside the included files (for example in the
following "-B
some.dcf -s 1K" 1K may be equal to 1000 or 1024  depending  on the 
presence of
an --alter=SI or --alter=binary in the file some.dcf. By default (before any
--alter=SI/binary argument has been reached), binary interpretation of
suffix
is done (for compatibility with older versions).

New version:

The --alter=SI and --alter=binary options can be used several times on
the command line. They affect all prefixes which follow, even those
found in files included by the -B option, up to the next --alter=binary
or --alter=SI occurrence. Note that if in a file included by the -B
option, an --alter=binary or --alter=SI is encountered, it affects all
the following prefixes, even those outside the included files. For
example, when running with the parameters "-B some.dcf -s 1K", 1K may be
equal to 1000 or 1024, depending on --alter=binary or --alter=SI being
present in the some.dcf file. By default (before any --alter=SI/binary
option is reached), binary interpreration of prefixes is done, for
compatibility with older versions.

=====================================
Old version:

-Q      Do not display initial warning on stderr when not launched from  a
terminal  (for  example when  launched  from  an  at job or crontab).
Remains
that any question to the user will be assumed a 'no' answer, which most
of the
time  will  abort  the  program.  Important,  this option cannot be used
inside
configuration files (see -B option), it must be present on the command line.
Since version 2.2.2, giving this option on command-line also forces 
the  non
interactive  mode  even if dar is launched from terminal, this makes dar
possible to run in background (it is recommended to then redirect the stdout
and/or stderr to some files).

New version (I'm not really sure if I interpreted the meaning correctly,
so please check. Specificly, I left out the "initial" in the first
sentence. And, does -Q really only refer to stderr, and not stdout?):

-Q     
Do not display anything on stderr when not launched from a terminal
(when launched from a cronjob for example). This means that all
questions to the user will be answered with 'no', which most of the time
will abort the program. Please note that this option cannot be used in
the configuration file, it must be given on the command line. Since
version 2.2.2, giving this option also forces the non-interactive mode,
even if dar is launched from a terminal. This makes it possible for dar
to run in the background. When you do, it's recommended to redirect
stdout and/or sterr to files.

=====================================
Old version:

-aa, --alter=atime  when reading a filesystem, while doing a backup (-c
option)
or  comparing  (-d  option)  by default  dar tries to be as much
transparent as
possible, and set back the last access time (atime) of read files and
directories, as if they have not been read. But, preserving atime of  read
files, make their ctime to be changed (last inode change). There is no
possibility to preserve both atime and ctime. If you want to overcome the
default original behavior  of dar  and want to keep ctime unchanged, the
--alter=atime is for you. Some security software rely on the ctime to be
preserved, some other software rely on the atime  to  be  preserved like
leafnode NNTP caching software.

        -ac, --alter=ctime  set back the date alteration to ctime (see
--alter=atime above), this is the default behav- ior. The use of this
switch is
to override the -aa option in  dar  configuration  files  or
command-line  (see
-B option). From -aa and -ac the one which is last parsed from command-
line or
included files takes the win.

New version (When writing this, I took into account that you will be
changing the default behaviour to the -aa option. Also note that I
switched the order, because it better fits my text):

-ac, --alter=ctime
When reading a filesystem (when doing a backup or compare), restore the
atime of all files to what it was before the file was read. This makes
it appear as if it had not been read at all. However, because there is
no system call to let applications set the ctime (last inode change) of
a file, setting back the atime results in that the ctime will change
(hence the alter=ctime). There is no possibililty to preserve both ctime
and atime. However, for most users, having the atimes of the files
changed shouldn't be a problem, since they can be changed by any other
program (running by any user!) as well (like the content-index program
Beagle). Ctimes on the other hand, are the only way for security
software to detect if files on your system have been replaced (by so
called root-kits mostly). This means, that should you run dar with -ac,
security software which uses ctimes to check, will mark every file on
your system as compromised after the backup. In short, this means this
option should only be used by people who know what they are doing. It's
the opinion of this writer that any software susceptible to atime
changes is flakey or even broken (because of the afore mentioned reasons
why atimes can change). But, that doesn't take away that there are
programs who rely on atimes remaining the same, like Leafnode NNTP
chaching software. Therefore this option exists.

-aa, --alter=atime
First see the -ac option. When specifing -aa, the atime of every file
changes, and the ctime remains the same. Or, in other words, Dar itself
does nothing with atimes and ctimes, it only lets the system change
atimes (which it is supposed to do). This is in occordance with what
atimes and ctimes were meant to represent. This is Dar's default, and is
safe for most people.

=====================================

I hope you are in agreement over the contents. Let me know if you think
something needs to be changed or added or something. I haven't reviewed
the entire man page, so perhaps I'll send more later.

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFEIcN0MHkUjYo9d9ARAg42AKCIAY9EBUbQE147zDaWh5v1pemXywCgwHP8
VSHhvGlXju8lZ/bkNOajdnY=
=64SB
-----END PGP SIGNATURE-----