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

Trent W. Buck trentbuck at gmail.com
Thu Oct 1 05:51:15 UTC 2009

Eric Kow <kowey at darcs.net> writes:

> -------------------------------
>> --- 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)
>
> [analysis of original text]

OK; given my bias, someone else should do this bit of documentation :-)

> 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 :-)

I don't remember that being part of the text that delete-unhelpful
wanted to remove.  Are you requesting new documentation?  File a
wishlist ticket ;-)

I'm not sure that documentation is the right long-term fix for that,
though -- moving replaces to the front feels like the Wrong Thing.

> 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)

The new first paragraph says (emphasis added)

Diff can be used to create a diff between two versions which are in your
repository.  Specifying just --from-patch will get you a diff against
your working copy.  IF YOU GIVE DIFF NO VERSION ARGUMENTS, IT GIVES
YOU THE SAME INFORMATION AS WHATSNEW.

However, looking at that paragraph now, I think that "no arguments"
should be the first case, then --patch, then --from- and --to-patch.

Oh, and what is a "version argument"?  Hmph.

>> + "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.

I don't know.  In such a case I would normally pull out my Fowler (2e)
or Strunk and White, but unfortunately I don't own a copy of either --
time to bloody well address that...

>> -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.

It's not clear from the diff, but I realized that the -- style is
completely superseded by --diff-opts, so I took the liberty of omitting it.

>> -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.

See issue1579.  I guess I assumed my workaround there was sufficient.