Re: Documenation update

Wesley Leggette wrote:
> Hi Wiebe,

Hello Wiebe, hello Wesley,


Wiebe, first thank you for your work.

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

exactly, and when the line is not very short but not long enough to have 
it on its own, things become more difficult to read, that's right... 
However I have not found any good solution for this problem, at least 
having two carriage-returns between the option definition and its 
description let things a bit more easy to read in some cases.

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

Yes, but I guess that having all in two level of indentation would not 
make things much clearer ...

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

I hate it too ;-) moreover I don't want to have two different 
documentations for the same things, as you know, users would see the 
first and ask support for what is written in the detailed documentation, 
which they would not read ... But in another way you are right, a 
monolithic document is not easy to use, maybe several man pages instead 
would be more interesting, one for file filtering for example, another 
for EA and so on...this would let things more readable no ?

> 
> 
>>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"):

the -am description refers to a section above in the man page about file 
filtering, where is described two ways of building a filter based on -I 
-X, -P, -g -[ and -] options. Does this paragraph is not correct or 
could not you find the reference given in the option description (in 
that case a separated man page would be more interesting)?

[...]

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

yes, that's right, this has been put in the common options to avoid 
duplicating the description of theses two options, as there is no common 
part for creation and comparison.

I can now see something interesting to do about man pages :

dar.1 -> general presentation of the command line tool
dar_filtering.1 -> all that concerns the filtering -am, -I -X, -g, -P, 
-[, -] -u, -U, -ac, -an
dar_ea -> all that concerns EA
dar_create.1 -> all that concerns archive creation (differential/full 
backup/snapshot)
dar_isolate.1 -> all that concerns catalogue isolation
dar_merge.1 -> all that concerns archive merging
dar_test.1 -> all that concerns testing
dar_diff.1 -> all that concerns diffing
dar_list.1 -> all that concerns listing (normal,tree-like,XML listings)

with cross references between theses pages.

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

Definitively yes. This would avoid me forgetting treating tasks and 
eases the review of changes. As I cannot treat patches as soon as they 
are available, using the sourceforge tracker lets the possibility to 
other users to know about pending patches and let users applying them 
while they are not yet integrated into CVS.

But that's OK to post here (as we have asked you to do so :-) )

[...]

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

No problem, I will keep you informed of your feedback integration in dar 
  (I'm currently finishing some work in source code, then I will have a 
look at your work).

Kind Regards,
Denis.

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

iD8DBQFEI7yOpC5CI8gYGlIRAv8aAJ0YO3r0/9cb+7ycgxdxFrJOmsHCngCfaLNH
eIioCSLsct3HlCXX1j+pW8s=
=ZuGS
-----END PGP SIGNATURE-----