Re: improve rsync(1) manual page
Ingo Schwarze wrote:
> >> * Change the misleading argument placeholder "portnumber" to "service";
> >>even the default ("rsync") isn't a number. In the description,
> >>mention services(5), and also mention the default.
>
> > I don't object, but I wonder how much detail is needed. Since time
> > immemorial, ports could always be specified as a number or a service
> > name ("telnet mailserver smtp"). It's only worth mentioning if
> > service names are _not_ supported for some reason. I pondered the
> > issue when I added support for service names to ssh, and eventually
> > decided to just leave it alone.
>
> I agree that often, it isn't feasible to re-explain basic concepts
> at every place where they are used. But here, it is merely one
> short sentence, and i see no downside in being explicit. It may
> help people who haven't been UNIX users since "time immemorial".
> So i left the sentence in place.
BTW,
rsync --port=rsync
rsync: --port=rsync: invalid numeric value
rsync error: syntax or usage error (code 1) at main.c(1578) [client=3.1.3]
Doing a service lookup in openrsync is an miraculous modern extension,
rsync is still living in the pre-1981 or so..
Re: improve rsync(1) manual page
Hi Christian,
Christian Weisgerber wrote on Mon, Apr 01, 2019 at 09:13:27AM +0200:
> Ingo Schwarze:
>> here are serveral bugfixes and improvements for the rsync(1) manual.
> ok
Thanks for checking, committed with the following tweaks:
> I have some comments, but I think you should commit this. Further
> tweaks can follow later.
>> Missing information:
>> * Change the misleading argument placeholder "portnumber" to "service";
>>even the default ("rsync") isn't a number. In the description,
>>mention services(5), and also mention the default.
> I don't object, but I wonder how much detail is needed. Since time
> immemorial, ports could always be specified as a number or a service
> name ("telnet mailserver smtp"). It's only worth mentioning if
> service names are _not_ supported for some reason. I pondered the
> issue when I added support for service names to ssh, and eventually
> decided to just leave it alone.
I agree that often, it isn't feasible to re-explain basic concepts
at every place where they are used. But here, it is merely one
short sentence, and i see no downside in being explicit. It may
help people who haven't been UNIX users since "time immemorial".
So i left the sentence in place.
>> * Remove excessive verbosity from -g and -o, and improve precision:
> I find "Set the group name to match the source" incomprehensible.
> The example given in the previous text may be unelegant, but it helps
> me understand what this actually does,
Fair enough, i restored the example given that people consider it
important, adjusting the wording around it to make it fit.
I also excluded changes to EXAMPLES from the commit because deraadt@
had a concern about them, and i reworded STANDARDS because deraadt@
observed that the old wording allowed the misinterpretation that
the rsync *protocol* would be under GPL, which it is not. No other
changes to the patch before commit.
Yours,
Ingo
Re: improve rsync(1) manual page
Christian Weisgerber wrote: > > * Remove excessive verbosity from -g and -o, and improve precision: > > I find "Set the group name to match the source" incomprehensible. > The example given in the previous text may be unelegant, but it helps > me understand what this actually does, Yes, probably wise. group and owner handling is negotiated over the protocol sometimes by name sometimes by id; it is complex and needs a long explanation so people don't skip over it.
Re: improve rsync(1) manual page
Ingo Schwarze:
> here are serveral bugfixes and improvements for the rsync(1) manual.
>
> OK?
ok
I have some comments, but I think you should commit this. Further
tweaks can follow later.
> Missing information:
> * Change the misleading argument placeholder "portnumber" to "service";
>even the default ("rsync") isn't a number. In the description,
>mention services(5), and also mention the default.
I don't object, but I wonder how much detail is needed. Since time
immemorial, ports could always be specified as a number or a service
name ("telnet mailserver smtp"). It's only worth mentioning if
service names are _not_ supported for some reason. I pondered the
issue when I added support for service names to ssh, and eventually
decided to just leave it alone.
> * Remove excessive verbosity from -g and -o, and improve precision:
I find "Set the group name to match the source" incomprehensible.
The example given in the previous text may be unelegant, but it helps
me understand what this actually does,
--
Christian "naddy" Weisgerber na...@mips.inka.de
improve rsync(1) manual page
Hi,
here are serveral bugfixes and improvements for the rsync(1) manual.
OK?
Ingo
Bugfixes:
* For -D and -l: s/Transfer/Also transfer/.
* In the EXAMPLES, the renaming rsync -> openrsync caused a mess;
the worst aspect is the --rsync-path in the last example.
I don't have a good solution. I fear we will have to edit the
section again once we rename the program back to plain "rsync".
Missing information:
* Change the misleading argument placeholder "portnumber" to "service";
even the default ("rsync") isn't a number. In the description,
mention services(5), and also mention the default.
* Document the missing option --numeric-ids.
* Add the missing sections EXIT STATUS, HISTORY, AUTHORS.
Minor improvements:
* Drop the redundant phrases "Archive mode" and "Dry-run mode"
which are already clear form the long options right above: long
options cause enough verbosity already, so at least give them
the chance to convey some useful meaning.
* Add missing full stop for -D.
* Clarify which kind of program -e specifies; there are options
for specifying two different kinds of programs.
* Remove excessive verbosity from -g and -o, and improve precision:
- These options do *not* set the ID to match the source by default.
- The meaning of "verbatim" is unclear.
- Use the standard wording "user ID" and "group ID" like in
chgrp(1) find(1) ls(1) chown(2) stat(2) group(5) passwd(5) chown(8);
i can't see "group identifier" used anywhere else, and given
that the distinction between "group name" and "group ID" matters
here, let's avoid the unusual term.
* Recommend -v with -n, or people may either wonder what the point is
or incorrectly expect that -n might already imply -v.
* Describe -o in a self-contained way. It isn't so long that it
would justify giving readers the runaround.
* Do not call the source directory "the root directory";
the latter term generally refers to /.
* For --rsync-path, consistently use .Ar program, not .Ar prog, and
correct the markup of the default remote program name "rsync".
* Fix markup of argument syntax: host, module, and path have to be
replaced separately and the punctuation in between has to remain
exactly as shown in the manual, so do not mark up the punctuation
with .Ar. Also, "rsync" is a keyword in this context, to be given
verbatim, not a placeholder for something else.
* Move the compatibility statement into a STANDARDS section.
Even though the rsync protocal may not be a formal standard,
that's where such information fits best.
* Remove commented out sections that will never make sense in this page.
Index: main.c
===
RCS file: /cvs/src/usr.bin/rsync/main.c,v
retrieving revision 1.42
diff -u -r1.42 main.c
--- main.c 31 Mar 2019 13:17:44 - 1.42
+++ main.c 31 Mar 2019 16:24:03 -
@@ -505,8 +505,9 @@
exit(rc);
usage:
fprintf(stderr, "usage: %s"
- " [-aDglnoprtv] [-e program] [--del] [--port=portnumber]\n"
- "\t[--rsync-path=program] [--version] source ... directory\n",
+ " [-aDglnoprtv] [-e program] [--del] [--numeric-ids]\n"
+ "\t[--port=portnumber] [--rsync-path=program] [--version]\n"
+ "\tsource ... directory\n",
getprogname());
exit(1);
}
Index: rsync.1
===
RCS file: /cvs/src/usr.bin/rsync/rsync.1,v
retrieving revision 1.15
diff -u -r1.15 rsync.1
--- rsync.1 31 Mar 2019 13:17:44 - 1.15
+++ rsync.1 31 Mar 2019 16:24:04 -
@@ -25,7 +25,8 @@
.Op Fl aDglnoprtv
.Op Fl e Ar program
.Op Fl -del
-.Op Fl -port Ns = Ns Ar portnumber
+.Op Fl -numeric-ids
+.Op Fl -port Ns = Ns Ar service
.Op Fl -rsync-path Ns = Ns Ar program
.Op Fl -version
.Ar source ...
@@ -47,13 +48,12 @@
The arguments are as follows:
.Bl -tag -width Ds
.It Fl a , -archive
-Archive mode.
Shorthand for
.Fl Dgloprt .
.It Fl D
-Transfer device and special files.
+Also transfer device and special files.
Shorthand for
-.Fl -devices -specials
+.Fl -devices -specials .
.It Fl -del , -delete
Delete files in
.Ar directory
@@ -63,36 +63,50 @@
Only applicable with
.Fl r .
.It Fl -devices
-Transfer device files.
+Also transfer device files.
.It Fl e Ar program , Fl -rsh Ns = Ns Ar program
-Specify alternative program, defaults to
+Specify alternative communication program, defaults to
.Xr ssh 1 .
.It Fl g , -group
-Set group identifier to match the source.
-Groups are matched by name: group
-.Qq kristaps
-with id 1000 on a remote server will be properly assigned group
-.Qq kristaps
-on the local machine with id 2000.
-If the sender's group is unknown on the local machine, it is used
-verbatim.
+Set the group name to match the source.
+If
+.Fl -numeric-ids
+is also given or if the remote group name is unknown on the local machine,
+set the
