rsync - Aug 2007 - Rewritten rsync man page

Dear Wayne, C Sights, and list,

I have started working on my rewritten version of the rsync man page.
So far, I have redone the top of the man page and the list of options;
I improved many of the one-line option descriptions.  The yodl and man
versions of my man page are available here and here:

http://www.kepreon.com/~matt/private/rsync-new-manpage/rsync.yo
http://www.kepreon.com/~matt/private/rsync-new-manpage/rsync.1

What do you all think so far?  Am I going in the right direction?

Matt

On Sat, Aug 04, 2007 at 07:26:19PM -0400, Matt McCutchen
wrote:
> What do you all think so far?  Am I going in the right direction?
I'll hopefully have some time to check into it more later on, but I did
give your pages a look and they look pretty good.  One thing I had been
trying to do was to keep the option section from wrapping on an 80-
column screen (which is why none of the lines were longer than 72
characters).  What do you think?  Is that constraint needed these days?
(I've used 128 columns for quite a while...)

I didn't get a chance to delve into the content and categorizations yet,
but if anyone has taken a read and has a reaction, it would be nice to
hear what folks think.

..wayne..

Hi Matt,
	Sorry I didn't write earlier, hopefully my suggestions are still useful.  
Also, I'm not subscribed to the rsync list so I might duplicate or conflict 
with other suggestions you've received. :)
	The first suggestion is that the order of the options listed be changed so 
that the least esoteric ones are placed before (as much as the grouping 
allows) the more often used ones.  For example, some of the more often used 
groups are "Source File Selection", "Deletion", and
"Name-based filter rules"
	I like the way a default action is included in the short option descriptions.
	Perhaps -H should be under "Destination file handling" rather 
than "Attributes"->"Others"?
	In "HOW RSYNC WORKS" the server might be on the local computer. :)
	"If  the  check  passes,  the  generator  applies" -> "If 
the  quick check
passes,  the  generator  applies" .  Might as well use the bolded phrase 
again!  (I think "quick check" is not very descriptive. "file
data sameness
check", "file sameness check", or "sameness check" seem
more informative).
	For the part starting "For  each  regular file, it compares", here is
a
rephrasing:
	"For  each  regular file, it compares the information specified by the
"quick
check" rule to determine whether the file's data are identical.  If the
information match, then files are assumed to be the same and the generator 
applies any preserved source attributes to the destination file (tweaks
it)."

	I think the description of how rsync works is nice and, if nothing else, this 
should be added to the existing man page.

Thanks Matt,
	C.

On Saturday 04 August 2007 19:26, Matt McCutchen wrote:
> Dear Wayne, C Sights, and list,
>
> I have started working on my rewritten version of the rsync man page.
> So far, I have redone the top of the man page and the list of options;
> I improved many of the one-line option descriptions.  The yodl and man
> versions of my man page are available here and here:
>
> http://www.kepreon.com/~matt/private/rsync-new-manpage/rsync.yo
> http://www.kepreon.com/~matt/private/rsync-new-manpage/rsync.1
>
> What do you all think so far?  Am I going in the right direction?
>
> Matt