[darcs-users] darcs patch: Remove duplicated documentation. (and 4 more)

[Eric Kow]

On Sun, Sep 20, 2009 at 17:30:31 +1000, Trent W.Buck wrote:
> These are all orthogonal -- if some are OK to apply immediately and
> others are held during review, please apply the former right away.
> 
> Mon Sep 14 13:41:23 EST 2009  Trent W. Buck <trentbuck at gmail.com>
>   * Delete unhelpful documentation.

I don't think we should apply this one, but actually make it helpful

> Mon Sep 14 16:23:29 EST 2009  Trent W. Buck <trentbuck at gmail.com>
>   * Rewrite "darcs diff" help.

I think this could use a couple of modifications (marked 'COMMENT')

Delete unhelpful documentation.
-------------------------------
> --- FIXME: can  we just  delete the remaining  text?  It seems  more an
> --- instance of "look how clever  I am; I made commutation work" rather
> --- than information that is actually useful to users.

No.  I don't think it's accurate to attribute this to show-offiness, but
in any case the intention here is less relevant than the actual
usefulness (for that matter, the intention behind your patch is good).

I think this with a little rewriting, this could actually be made
useful.  As long as darcs replace is around we should make sure it is
well understood and clearly non-magical (note that this is orthogonal
to whether you like darcs replace or not: such clarity could lead users
to make the informed choice that they do *not* want to use darcs
replace)

> -\end{code}
> -There is a potentially confusing difference, however, when a replace is
> -used to make another replace possible:
> -\begin{verbatim}
> -$ darcs replace newtoken aaack ./foo.c
> -$ darcs replace oldtoken newtoken ./foo.c
> -$ darcs record
> -\end{verbatim}

So this is basically pointing out one of the ways that force replace
could have worked, just swap the new token out with something temporary

> -will be valid, even if \verb!newtoken! and \verb!oldtoken! are both present
> -in the recorded version of foo.c, while the sequence
> -\begin{verbatim}
> -$ [manually edit foo.c replacing newtoken with aaack]
> -$ darcs replace oldtoken newtoken ./foo.c
> -\end{verbatim}
> -will fail because ``newtoken'' still exists in the recorded version of
> -\verb!foo.c!. 

This old text is unclear because I don't know if he means manually
replacing all the known instances of newtoken (which would be a bit
surprising to me) or just some number of them (which is fairly
straightforward why that wouldn't work)

> The reason for the difference is that when recording, a -``replace''
> patch always is recorded \emph{before} any manual changes, -which is
> usually what you want, since often you will introduce new -occurrences
> of the ``newtoken'' in your manual changes.  In contrast, -multiple
> ``replace'' changes are recorded in the order in which -they were
> made.  -\begin{code}

I think it's important for users to know that when they use darcs
replace, the darcs replace operation will get bubbled up to the front
of whatever named patch they are constructing.  I didn't know that,
for example :-)

Rewrite "darcs diff" help.
--------------------------
>  diff_description :: String
>  diff_description = "Create a diff between two versions of the repository."
>  
>  diff_help =
>   "Diff can be used to create a diff between two versions which are in your\n"++
> hunk ./src/Darcs/Commands/Diff.lhs 69
>   "repository.  Specifying just --from-patch will get you a diff against\n"++
>   "your working copy.  If you give diff no version arguments, it gives\n"++
> - "you the same information as whatsnew except that the patch is\n"++
> - "formatted as the output of a diff command\n"
> + "you the same information as whatsnew.\n" ++
> + "\n" ++
> + "If you specify a set of files and directories, only unrecorded\n" ++
> + "changes to those files and directories are listed.\n" ++

COMMENT: You don't seem to account for the case where you just say
'darcs diff' with no arguments (which the old help text seems to be more
successful at)

> + "Diff calls the external utility diff(1) to do the actual work.\n" ++
> + "You can specify additional arguments to diff using the `--diff-opts'\n" ++
> + "flag, such as --diff-opts=-ud.\n" ++

Nice

> + "The --diff-command option can be used to specify an alternate utility,\n" ++

Do you have a good feel for when it's better to use 'alternate' vs
'alternative'?  I don't, but I remember having lots of my alternates
being corrected to alternatives and now I bet I'm overshooting a bit.

> + "such as meld (GNOME) or opendiff (OS X).  Arguments may be included,\n" ++
> + "separated by whitespace.  The value is not interpreted by a shell, so\n" ++
> + "shell constructs cannot be used.  The arguments %1 and %2 MUST be\n" ++
> + "included, these are substituted for the two working trees being\n" ++
> + "compared.  If this option is used, --diff-opts is ignored.\n"

Looks good too.

> -to get a diff in the unified format.  Actually, thanks to the wonders of
> -getopt you need the ``\verb!--!'' shown above before any arguments to diff.
> -You can also specify additional arguments to diff using the
> -\verb!--diff-opts! flag.  The above command would look like this:

Err, this seems like something you may be glossing over in the new text.

> -Note that the command is split into space-separated words and the first one is
> -\verb!exec!ed with the rest as arguments---it is not a shell command.  Also
> -the substitution of the \verb!%! escapes is only done on complete words.
> -See \ref{resolution} for how you might work around this fact, for example,
> -with Emacs' Ediff package.

COMMENT: Also, I think this info may be useful..  For example, would
'foo bar' confuse --diff-opts?  We seem to say that it would.

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
PGP Key ID: 08AC04F9
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 194 bytes
Desc: not available
URL: <http://lists.osuosl.org/pipermail/darcs-users/attachments/20090930/eeeb3fcf/attachment.pgp>