Re: Documenation update

Hi Wiebe,

I've replied with some extensive comments, mostly because I found this
all to be rather interesting. Sorry to be too oratorical.

If all this seems too complex, just keep doing what you feel like doing.

On Wed, 2006-03-22 at 22:36 +0100, Wiebe Cazemier wrote:
> 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.

I see what you're saying, but that stuff is actually formated by man.
It's supposed to put explanations of the same line only for really short
parameters and break if they are longer.

One problem with the current man page is that there are perhaps too many
indentations. Most man pages limit this to two tabs *at the most*. Other
stuff is usually broken out into another section. Too many tabs makes it
really hard to read the page on narrow consoles (like standard 80).

Another problem is that there are fuck to many options for DAR. (In a
good way!) That makes documenting the whole thing in a man page really
hard. Although I hate them, at some point it may be a good idea to put
the main documentation in an info file and pare down the man page to
just the most important options.

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

The current man page seems to say that it enforces a stricter ordering
of masks. I agree the example is a little confusing. Consider this (or
skip to "WHAT TO TAKE AWAY"):


RULE: !(EXCLUDE_MASKS) & (INCLUDE_MASKS)
EXAMPLE: !("*.mp?") & ("*.mp3" | "*")
ARGUMENT: -X "*.mp?" -I "*.mp3" -I "*"
MATCHES:
 ! toto.mp2
 ! toto.mp3
 ! toto.mp4
 ! toto.mp5
   toto.mp12
   asdf


RULE: [I] PREVIOUS | MASK   [X] PREVIOUS & ~MASK
      where RULE is recursive for each mask with PREVIOUS the state
EXAMPLE: ( !("*.mp?") | ("*.mp3") ) & !("a*")
ARGUMENT: -am -X "*.mp?" -I "*.mp3" -X "a*"
MATCHES:
 ! toto.mp2
   toto.mp3
 ! toto.mp4
 ! toto.mp5
   toto.mp12
 ! asdf


The "*" in the first example and the "a*" in the second demonstrate
matching for "toto.mp12" and "asdf". Ignore them for now.

(1)
The normal operation, demonstrated by the first rule, simply ORs all the
exclude rules and include rules into two respective masks, which are
then ANDed together.

The problem with the first rule is that you cannot create a general
exclusion and then narrow it by selectively including files. This is
because the rule states this: "If a file is not on the exclusion list
then include it ONLY IF it is on the inclusion list".

(2)
Under ordered mask operation (the -am operation), demonstrated by the
second rule, each mask is applied successively to the result of the
previous masks. The method of application necessarily differs for an
exclusion or inclusion mask (because of the rules of boolean logic) to
get the desired effect.

What the second rule solves is this problem of wide exclusion followed
by selective inclusion. Another layer of selective exclusion could even
be applied within the previous set. The rule states: "Take the first
mask as the current state, then for each successive mask apply the
appropriate transformation to the current state. The transformation
should cause exclusion or inclusion as desired".


(3) FURTHER NOTE
I added the "*" and "a*" to the first and second examples respectively
to show what would be required to affect a wider arrange of matches. The
"*" demonstrates a weakness in the normal operation, namely that using
any set of rules will automatically exclude any file not explicitly
included. The "a*" simply demonstrates how an exclusion is applied after
other masks. By default, the ordered mask operation will not cause files
that are not explicitly excluded from being so.
 

*** WHAT TO TAKE AWAY ***

If you are more confused now, I'm sorry. How the masking modes work is
seemingly complicated, but what is important is what they do for the
user. The documentation should probably simply illustrate what the
goals, advantages, and weaknesses of each mode are:

NORMAL
- explicitly exclude a group of patterns
- include a group of patterns only if they are mentioned and are not
excluded
- all desired patterns must be indicated

ORDERED:
- explicitly indicate one or more sets of masks
- for each exclusion a subset may be included
- for each inclusion a subset may be excluded
- subsets may be increasingly more precise
- precision indicated by mask order; first is broader, last is narrower
- all patterns are included by default, exclusion must be explicit

Sorry.


*** ALSO ***

I don't know how proficient you are at reading code. For future
reference, I figured all this out with the following steps:

(1) Looked at the current man page, obviously ;)
(2) Looked at the code in CVS[2] that interprets the command line
options. This is located in command_line.cpp[3]. The function
get_args_recursive() processes all arguments in a switch statement.
(3) In the argument processor, the code in each case will often set
variables which are later used in other functions. I find the functions
where the variables are used and see what they do.
(4) Step 3 is the hard part.
(5) If the options that are set are passed to libdar calls, the API
documentation[4] is often more up-to-date than the current man page.

If you're actually interested in doing this yourself I can give you more
advice anytime. If not, don't worry. That's understandable ;).

> 
> 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.

I don't know how Denis wants to handle it, but it is sometimes
advantageous to provide patches. Do you know how to do this? If you are
running Unix you can issue the following command:

$ diff -ruN OLDFILE NEWFILE > changes.patch

On many lists the patches are then submitted in-line or as attachments
on messages. Denis may prefer you use the patch tracker[1] on
Sourceforge.

Of course, creating a patch is only useful on actual man sources. They
are located in the man directory[6] and are written in a specific
format[5].


*** LASTLY, I PROMISE ***

I'm writing all this assuming you're not that familiar with Linux
programming and packaging. I'm really sorry if I'm mistaken. But
assuming I'm not, do you need help checking out the sources from CVS to
work on them?


[1] http://sourceforge.net/tracker/?group_id=65612&atid=511614
[2] http://cvs.sourceforge.net/viewcvs.py/dar/dar/src/
[3]
http://cvs.sourceforge.net/viewcvs.py/dar/dar/src/dar_suite/command_line.hpp?view=auto
[4] http://dar.linux.free.fr/doc/html/group__API.html
[5] http://www.linuxfocus.org/English/November2003/article309.shtml
[6] http://cvs.sourceforge.net/viewcvs.py/dar/dar/man/
[snip]

> 
> 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.
-- 
Wesley Leggette <lists-+42/j/[email protected]>

GPG Key:         http://www.kaylix.net/kaylix.asc or http://pgp.mit.edu
GPG Fingerprint: 9B6F 19FB 5296 5E6C 21FE  7614 2A20 5688 F848 9BDD

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.1 (GNU/Linux)

iD8DBQBEIlBzKiBWiPhIm90RAn3OAJ4hlEw9cUK33SRPv5/VzG8kUJLSVQCfSsqa
SNY7qGsErlqTgfOMAB42hH0=
=L+ta
-----END PGP SIGNATURE-----