Re: [Groff] corrections of groff's README file

[Keith Marshall]

On Sunday 22 May 2005 5:35 pm, Bernd Warken wrote, quoting me:
> > Now, when I come to start a new session, working on groff, and want to
> > get my working copy up to date, I do
> >
> > cd ~/sandbox/cvs/groff
> > cvs -z5 up -dP
>
> Exactly, if you go into the groff subdirectory you get around without
> CVSROOT or -d. But this is different from `cvs co', which must be called in
> your directory ~/sandbox/cvs because it creates the groff tree there.

Right!  Now we are more or less on the same wavelength :-)

> These things have to be documented in README. The following patch will do.

My objection to your original patch was that it made out that an export of 
CVSROOT is required when you wish to perform an update, which is not the 
case.  You *do*, of course, need to explicitly specify the CVSROOT when you 
do the initial check out, either by exporting a CVSROOT variable, or by using 
the "-d $CVSROOT" form in the cvs command;  IMO, this has always been clear 
in the wording of the README file.

If you feel that additional "hand holding" is necessary, might I suggest the 
following slightly more explicit alternative wording:--

-----8<-----------------------------
--- README      21 May 2005 07:08:41 -0000      1.10
+++ README      22 May 2005 20:24:32 -0000
@@ -24,18 +24,23 @@

 A CVS repository is available (http://savannah.gnu.org/cvs/?group=groff),
 containing the current development version of groff.  You can access it
-with the commands
+by first selecting a parent directory in which to create a working copy,
+(call it, say ~/cvswork), and then executing the commands

-  export CVS_RSH=ssh
+  cd ~/cvswork
+  CVS_RSH=ssh; export CVS_RHS
   cvs -d:ext:address@hidden/cvsroot/groff -z5 co groff

 Note that you need an SSH client for security reasons.

-An update of a checked out repository should be done with
+The above commands create a "checked out" copy of the CVS repository
+in ~/cvswork/groff; an update of this checked out repository copy should
+be done with

+  cd ~/cvswork/groff
   CVS_RSH=ssh cvs -z5 update -dP

-Please read the info pages of cvs for further details.
+Please read the CVS info pages for further details.

 Alternatively, you can download snapshots (which are updated twice a
 day) from
-----8<-----------------------------

A couple of points to note:--

1) The syntax "export CVS_RSH=ssh", while ok for Korn shell and bash, is not
   valid Bourne shell syntax; for complete portability you need the modified
   syntax indicated above.

2) It is more natural, IMO, for a native English speaker, (which I am), to
   say "the CVS info pages", rather than "the info pages of CVS"; the meaning
   is unchanged.

Best regards,
Keith.