From: Jason McIntyre <jmc@kerhand.co.uk>
Subject: Re: [patch] rdist.1 partial rewrite
To: tech@openbsd.org
Date: Tue, 5 Nov 2024 06:48:13 +0000

On Mon, Nov 04, 2024 at 02:26:12PM -0800, Evan Silberman wrote:
> I was just going to come in here and zap some unnecessary \*(Lt but I
> got a bit carried away. This patch reorganizes and hopefully improves
> the DISTFILES section of rdist.1, which was a bit hard to follow and
> presented commands and subcommands in a weird way. This organizes the
> material in a way more familiar from other manual pages describing
> command languages.
> 
> Hopefully it's also accurate; I'm not actually an rdist user I just
> got sniped. I tried not to freelance too much and retained much of the
> previous material even if some of it seems a bit vague. And I still
> zapped the unnecessary \*(Gt and \*(Lt.
> 
> Evan
> 

hi. the patch does not apply cleanly - can you retry (maybe attach it)?
jmc

> diff /usr/src
> commit - 22896994b80273a9a0d8a8e5bb8286e98e08922c
> path + /usr/src
> blob - 0a9734d48e3b26211655841b94e946b0a5e9bef1
> file + usr.bin/rdist/rdist.1
> --- usr.bin/rdist/rdist.1
> +++ usr.bin/rdist/rdist.1
> @@ -119,7 +119,7 @@ Otherwise,
>  .Nm
>  will run the command:
>  .Bd -literal -offset indent
> -ssh \*(Lthost\*(Gt -l \*(Ltlogin_name\*(Gt rdistd -S
> +ssh <host> -l <login_name> rdistd -S
>  .Ed
>  .Pp
>  .Ar host
> @@ -140,7 +140,7 @@ option was specified,
>  .Nm
>  will attempt to run the command:
>  .Bd -literal -offset indent
> -\*(Ltrdistd path\*(Gt -S
> +<rdistd path> -S
>  .Ed
>  .Pp
>  If no
> @@ -180,7 +180,7 @@ $ rdist -c name ... [login@]host[:dest]
>  .Pp
>  The equivalent distfile is as follows:
>  .Bd -literal -offset indent
> -(  name ... ) -\*(Gt [login@]host
> +(  name ... ) -> [login@]host
>  	install	[dest] ;
>  .Ed
>  .It Fl D
> @@ -410,181 +410,243 @@ Print version information and exit.
>  .Sh DISTFILES
>  The
>  .Pa distfile
> -contains a sequence of entries that specify the files
> +contains a sequence of commands that specify the files
>  to be copied, the destination hosts, and what operations to perform
>  to do the updating.
> -Each entry has one of the following formats.
> -.Bd -literal -offset indent
> -\*(Ltvariable name\*(Gt = \*(Ltname list\*(Gt
> -[ label: ] \*(Ltsource list\*(Gt -\*(Gt \*(Ltdestination list\*(Gt \*(Ltcommand list\*(Gt
> -[ label: ] \*(Ltsource list\*(Gt :: \*(Lttimestamp file\*(Gt \*(Ltcommand list\*(Gt
> -.Ed
>  .Pp
> -The first format is used for defining variables.
> -The second format is used for distributing files to other hosts.
> -The third format is used for making lists of files that have been changed
> -since some given date.
> -The
> -.Ar source list
> -specifies a list of files and/or directories on the local host which are to
> -be used as the master copy for distribution.
> -The
> -.Ar destination list
> -is the list of hosts to which these files are to be copied.
> -Each file in the source list is added to a list of changes if the file
> -is out of date on the host which is being updated (second format) or
> -the file is newer than the
> -.Ar timestamp file
> -(third format).
> -.Pp
> -Newlines, tabs, and blanks are only used as separators and are
> -otherwise ignored.
> +Newlines, tabs, and blanks in a
> +.Pa distfile
> +are only used as separators and are otherwise ignored.
>  Comments begin with
>  .Sq #
>  and end with a newline.
>  .Pp
> -Variables to be expanded begin with
> -.Sq $
> -followed by one character or a name enclosed in curly braces
> -(see the examples at the end).
> +The commands in the
> +.Pa distfile
> +operate on
> +.Ar namelist Ns s ,
> +which can be given in the following formats:
> +.Bl -tag -width Ds -offset indent
> +.It Ar name
> +A single
> +.Ar name .
> +.It Cm \&( Oo Ar name ... Oc Cm \&)
> +Zero or more
> +.Ar name Ns s
> +separated by whitespace, enclosed by parentheses.
> +.It Ar nl1 Cm - Ar nl2
> +All names in list
> +.Ar nl1
> +not present in list
> +.Ar nl2 .
> +.It Ar nl1 Cm + Ar nl2
> +The union of
> +.Ar nl1
> +and
> +.Ar nl2 .
> +.It Ar nl1 & Ar nl2
> +The intersection of
> +.Ar nl1
> +and
> +.Ar nl2 .
> +.El
>  .Pp
> -Labels are optional.
> -They are used to identify a specific command to execute
> -(for example, allowing an update of a subset of a repository).
> -.Pp
> -The source and destination lists have the following format:
> -.Bd -literal -offset indent
> -\*(Ltname\*(Gt
> -.Ed
> -or
> -.Bd -literal -compact -offset indent
> -`(' \*(Ltzero or more names separated by whitespace\*(Gt `)'
> -.Ed
> -.Pp
> -These simple lists can be modified by using one level of set addition,
> -subtraction, or intersection like this:
> -.Pp
> -.Dl list - list
> -or
> -.Dl list + list
> -or
> -.Dl list & list
> -.Pp
> -If additional modifications are needed (e.g.\&
> -.Do
> -all servers and client machines except for the OSF/1 machines
> -.Dc )
> -then the list will have to be explicitly constructed in steps using
> -.Dq temporary
> -variables.
> -.Pp
> -The shell meta-characters `[', `]', `{', `}', `*', and `?'
> +Each
> +.Ar name
> +in a
> +.Ar namelist
> +is subject to expansion.
> +The shell meta-characters
> +.Sq \&[ ,
> +.Sq \&] ,
> +.Sq \&{ ,
> +.Sq \&} ,
> +.Sq * ,
> +and
> +.Sq \&?
>  are recognized and expanded (on the local host only) in the same way as
>  .Xr ksh 1 .
>  They can be escaped with a backslash.
> -The `~' character is also expanded in the same way as
> +The
> +.Sq ~
> +character is also expanded in the same way as
>  .Xr ksh 1
>  but is expanded separately on the local and destination hosts.
>  When the
> -.Fl o Ar whole
> -option is used with a file name that begins with `~', everything except the
> -home directory is appended to the destination name.
> -File names which do not begin with `/' or `~' use the destination user's
> +.Fl o Cm whole
> +option is used with a file name that begins with
> +.Sq \&~ ,
> +everything except the home directory is appended to the destination name.
> +File names which do not begin with
> +.Sq /
> +or
> +.Sq ~
> +use the destination user's
>  home directory as the root directory for the rest of the file name.
> +.Cm ${ Ns Ar var Ns Cm \&}
> +is expanded to the list assigned to
> +.Ar var
> +.Pq see below .
>  .Pp
> -The command list consists of zero or more commands of the following
> -format:
> -.Bl -column "except_pat" "<pattern list>" "opt_dest_name" ";" -offset indent
> -.It install Ta \*(Ltoptions\*(Gt Ta opt_dest_name Ta ;
> -.It notify Ta \*(Ltname list\*(Gt Ta "" Ta ;
> -.It except Ta \*(Ltname list\*(Gt Ta "" Ta ;
> -.It except_pat Ta \*(Ltpattern list\*(Gt Ta "" Ta ;
> -.It special Ta \*(Ltname list\*(Gt Ta string Ta ;
> -.It cmdspecial Ta \*(Ltname list\*(Gt Ta string Ta ;
> -.El
> -.Pp
> -The
> -.Cm install
> -command is used to copy out-of-date files and/or directories.
> -Each source file is copied to each host in the destination list.
> -Directories are recursively copied in the same way.
> -.Ar opt_dest_name
> -is an optional parameter to rename files.
> +Each command in
> +.Pa distfile
> +has one of the following formats.
> +.Bl -tag -width Ds
> +.It Ar var Cm = Ar namelist
> +Assign
> +.Ar namelist
> +to the variable
> +.Ar var .
> +.It Oo Ar label Ns Cm \&: Oc Ar sources Cm -> Ar destinations Op Ar subcommands
> +Apply
> +.Ar subcommands
> +to the local files in the namelist
> +.Ar sources
> +and the remote hosts in the namelist
> +.Ar destinations .
> +If a hostname in
> +.Ar destinations
> +ends in a
> +.Sq +
> +(plus sign),
> +then the plus
> +is stripped off and NFS checks are disabled.
> +This is equivalent to disabling the
> +.Fl o Cm chknfs
> +option just for this one host.
>  If no
> -.Cm install
> -command appears in the command list or the destination name is not specified,
> -the source file name is used.
> +.Ic install
> +command is present in
> +.Ar subcommands ,
> +each out-of-date file in
> +.Ar sources
> +will be copied to each host in
> +.Ar destinations .
> +The login name used on the destination host is the same as the local host
> +unless the destination name is of the format
> +.Ar login Ns Cm @ Ns Ar host ,
> +in which case
> +.Ar login
> +is used.
> +.It Oo Ar label Ns Cm \&: Oc Ar sources Cm \&:\&: Ar timestampfile Op Ar subcommands
> +Apply
> +.Ar subcommands
> +to the local files in the namelist
> +.Ar sources
> +which have a later modification time than the local file
> +.Ar timestampfile .
> +Any
> +.Ic install
> +.Ar subcommands
> +are ignored.
> +The
> +.Ic special
> +and
> +.Ic cmdspecial
> +commands are executed on the local host.
> +.El
> +.Pp
> +A command can be prefixed by a
> +.Ar label ,
> +which can be given as a
> +.Ar name
> +argument to
> +.Nm
> +as described above.
> +.Pp
> +The
> +.Ar subcommands
> +are one or more of the following:
> +.Bl -tag -width cmdspecial
> +.It Ic install Oo Fl o Ar distopts Oc Oo Ar destname Oc Cm \&;
> +Copy each file in
> +.Ar sources
> +to each host in
> +.Ar destinations
> +where the file is out-of-date.
> +If
> +.Ar destname
> +is given and there is more than one local file named in
> +.Ar sources ,
> +each local file will be copied into the directory
> +.Ar destname
> +on each destination host.
> +If
> +.Ar destname
> +is given and only one file is named in
> +.Ar sources ,
> +the file is copied to
> +.Ar destname
> +on each destination host.
> +Local directories in
> +.Ar sources
> +are copied recursively to their destination.
>  Directories in the path name will be created if they
>  do not exist on the remote host.
> +.Pp
>  The
>  .Fl o Ar distopts
> -option as specified above has the same semantics as
> -on the command line except
> +option has the same semantics as on the command line except
>  .Ar distopts
> -only applies to the files in the source list.
> -The login name used on the destination host is the same as the local host
> -unless the destination name is of the format
> -.Dq login@host .
> -.Pp
> -The
> -.Cm notify
> -command is used to mail the list of files updated (and any errors
> -that may have occurred) to the listed names.
> -If no `@' appears in the name, the destination host is appended to
> -the name
> -(e.g. name1@host, name2@host, ...).
> -.Pp
> -The
> -.Cm except
> -command is used to update all of the files in the source list
> -.Sy except
> -for the files listed in
> -.Ar name list .
> +only applies to the files in
> +.Ar sources .
> +.It Ic notify Ar addresses Cm \&;
> +Mail a list of files updated and any errors that may have occurred
> +to each address in the namelist
> +.Ar addresses .
> +If no
> +.Sq @
> +appears in an address in
> +.Ar addresses ,
> +the destination host is used as the host part of that address.
> +.It Ic except Ar names Cm \&;
> +Exclude the files in
> +.Ar sources
> +that are listed in
> +.Ar names
> +from processing by the command.
>  This is usually used to copy everything in a directory except certain files.
> -.Pp
> -The
> -.Cm except_pat
> -command is like the
> -.Cm except
> -command except that
> -.Ar pattern list
> -is a list of basic regular expressions
> -(see
> -.Xr re_format 7
> -for details).
> -If one of the patterns matches some string within a file name, that file will
> -be ignored.
> +.It Ic except_pat Ar patterns Cm \&;
> +Exclude any files in
> +.Ar sources
> +that match any of the basic regular expressions in namelist
> +.Ar patterns
> +from processing by the command.
>  Note that since `\e' is a quote character, it must be doubled to become
>  part of the regular expression.
>  Variables are expanded in
>  .Ar pattern list
>  but not shell file pattern matching characters.
>  To include a `$', it must be escaped with `\e'.
> +.It Ic special Oo Ar files Oc Cm \&" Ns Ar command Ns Cm \&"
>  .Pp
> -The
> -.Cm special
> -command is used to specify
> +Execute the shell commands in
> +.Ar command
> +on the remote host using
>  .Xr sh 1
> -commands that are to be executed on the remote host after the file in
> -.Ar name list
> +after each file in
> +.Ar files
>  is updated or installed.
> -If the
> -.Ar name list
> +If
> +.Ar files
>  is omitted then the shell commands will be executed for every file
>  updated or installed.
> -.Ar string
> -starts and ends with `"' and can cross multiple lines in
> +.Ar command
> +must be surrounded by
> +.Sq \&"
> +characters and can cross multiple lines in
>  .Pa distfile .
> -Multiple commands to the shell should be separated by `;'.
> -Commands are executed in the user's home directory on the host
> +Multiple commands to the shell should be separated by
> +.Sq \&; .
> +Shell commands are executed in the user's home directory on the host
>  being updated.
>  The
> -.Cm special
> -command can be used, for example, to rebuild private databases
> +.Ic special
> +subcommand can be used, for example, to rebuild private databases
>  after a program has been updated.
>  The following environment variables are set for each
> -.Cm special
> -command:
> +.Ic special
> +subcommand:
>  .Pp
>  .Bl -tag -width "BASEFILE" -offset 3n -compact
>  .It Ev FILE
> @@ -594,12 +656,10 @@ The full pathname of the remote file that was just upd
>  .It BASEFILE
>  The basename of the remote file that was just updated.
>  .El
> -.Pp
> -The
> -.Cm cmdspecial
> -command is similar to the
> -.Cm special
> -command, except it is executed only when the entire command is completed
> +.It Ic cmdspecial Oo Ar files Oc \&" Ns Ar command Ns Cm \&"
> +Similar to the
> +.Ic special
> +subcommand, except it is executed only when the entire command is completed
>  instead of after each file is updated.
>  The list of files is placed in the
>  .Ev FILES
> @@ -609,15 +669,7 @@ Each file name in
>  is separated by a
>  .Sq :\&
>  (colon).
> -.Pp
> -If a hostname ends in a
> -.Sq +
> -(plus sign),
> -then the plus
> -is stripped off and NFS checks are disabled.
> -This is equivalent to disabling the
> -.Fl o Ar chknfs
> -option just for this one host.
> +.El
>  .Sh MESSAGE LOGGING
>  .Nm
>  uses a collection of predefined message
> @@ -750,20 +802,20 @@ FILES = ( /bin /lib /usr/bin /usr/games
>  EXLIB = ( Mail.rc aliases aliases.db crontab dshrc
>  	sendmail.cf sendmail.hf sendmail.st uucp vfont )
>  
> -${FILES} -\*(Gt ${HOSTS}
> +${FILES} -> ${HOSTS}
>  	install -oremove,chknfs ;
>  	except /usr/lib/${EXLIB} ;
>  	except /usr/games/lib ;
>  	special /usr/lib/sendmail "/usr/lib/sendmail -bi" ;
>  
>  srcs:
> -/usr/src/bin -\*(Gt arpa
> +/usr/src/bin -> arpa
>  	except_pat ( \e\e.o\e$ /SCCS\e$ ) ;
>  
>  IMAGEN = (ips dviimp catdvi)
>  
>  imagen:
> -/usr/local/${IMAGEN} -\*(Gt arpa
> +/usr/local/${IMAGEN} -> arpa
>  	install /usr/local/lib ;
>  	notify ralph ;
>  
>