[darcs-users] Request for comments: command description and documentation patch

[zander at kde.org]

On Mon, Mar 07, 2005 at 08:06:43AM -0500, David Roundy wrote:
> Quoting the patch as a whole, since others may have comments on bits that I
> don't see a problem with...
> > hunk ./Apply.lhs 75
> > - "Apply patches to a repo."
> > + "Apply patches (from the email bundle) to a repository."
> 
> >From *an* email bundle?

Also; to *the* repository. Since you can't supply just any repo.


> > hunk ./Get.lhs 55
> > - "Get a repository."
> > + "Create new local repository with content of remote one."
> 
> "Create a local copy of a repote repository"?
remote, you mean.  Other then that, I like Davids one best.

> > hunk ./Mv.lhs 41
> > - "Move one or more files or directories to a different location."
> > + "Move/rename one or more files or directories."
> > hunk ./Pull.lhs 69
> > - "Pull patches from another repo."
> > + "Copy patches from remote to local repository."
> 
> Here and later, I'm not sure I'm comfortable with the use of the word
> "copy".  Copying a patch doesn't imply to me applying the patch to the
> working directory.  Perhaps something like retrieve?  :( I haven't come up
> with a better wording.
> 
> I'm also not sure about the general principle of using the name of a
> command in its short description.  I see that I've often done so in the
> existing short descriptions, and it does sort of seem like it might help in
> understanding the sense in which the command name is meant, but on the
> other hand, it might explain nothing to users...

Next to that; I'm not comfortable with the overuse of remote and local. I
would personally go for "other" and "current" repositories since the other
really does not have to be remote, it can be just another dir on the same
filesystem.

What about:
Copy and apply patches from another repository to the current one.

> > hunk ./Push.lhs 48
> > - "Push patches into another repo."
> > + "Copy patches from local to remote repository."
Copy and apply patches from the current to another repository.

> > hunk ./Record.lhs 64
> > - "Record changes as a named patch."
> > + "Save working copy changes to repository as a patch."
Hmm.. IMO Thats a bit to short for a nice sentence (but maybe thats me not
speaking native English).
I would use:
Save changes in working copy to the repository as a named patch.

> > hunk ./Remove.lhs 42
> > - "Remove one or more files or directories from the repository."
> > + "Remove one or more files or directories."

I disagree with this one; the remove is _only_ from the repository.
Not from the local dir...  The original is better IMO.

> > hunk ./Resolve.lhs 40
> > - "Resolve conflicts."
> > + "Record the conflicting patch and its resolution."
> 
> This isn't what resolve does--it doesn't record a patch.  It really just
> marks the working directory to indicate any conflicts that may not be
> apparent.
What about:
Alter working copy to mark any conflicts so you can resolve them by hand.

> > hunk ./Revert.lhs 47
> > - "Revert to recorded version."
> > + "Revert to recorded version (safe the first time only)."

Shouldn't that be 'save' ?? Or am I loosing it ? :)

> > hunk ./Revert.lhs 61
> > - "wish to undo.\n"
> > + "wish to undo. The last revert can be undone safely using unrevert\n"++
> > + "command if the working copy was not modified in the meantime.\n"
> 
> ... using *the* unrevert command...
ack.

> > hunk ./Rollback.lhs 43
> > - "Roll back a named patch."
> > + "Apply an inverse patch in repository to local copy."
> 
> I'm unclear here what local copy means... if it means the working
> directory, then this description is incorrect.  Rollback doesn't affect the
> working directory, but just "records" an inverse patch.
Right; this may be confusing since a whatsnew registers a change :)

What about:
Register a patch which undoes the changes of a named patch, without
changing the working copy.

> > hunk ./Unrecord.lhs 48
> > - "Unrecord a named patch."
> > + "Remove a recorded patch (without working copy change)."
> 
> I think working directory would be clearer than working copy (since copy
> could also be used as a verb).  Perhaps "(without modifying working
> directory)"

But the working dir is just one dir and can be misunderstood to be the one
the user is in now, and not any others.  Working copy is used more often
IMO.
But I would make it more readable like such:
Remove a recorded patch without changing the working copy.

> > hunk ./Unrevert.lhs 53
> > - "Undo the last revert operation."
> > + "Undo the last revert (may fail if changes after the revert)."
changes *made* after...

-- 
Thomas Zander