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

Peter Hercek peter at syncad.com
Mon Mar 7 15:25:36 UTC 2005

David Roundy wrote:
>>I did not do the grouping of commands. The only idea (I have) how
>>to do it is to add an enum to each command structure which would
>>specify its group. I'm not sure how it would look in Haskell yet but in
>>OCAML the type would be like:
>>type cmd_group =
>> Working_copy_manipulation of string
>>| Working_copy_Local_repository_transfer of string
>>| ....  ;;
>>If you like the proposal please reply, I may look at it sometimes.
>>I work primary on windows and darcs seems a bit "rough" there
>>(lately, I had some issues there with editor for long comments)
>>so I'll try to find out whether it does not work because of my
>>weak knowledge or whether these are errors.
> I think it might be simpler to simply include in the DarcsCommand data
> structure a string indicating the section heading for the command.  The
> annoying bit would that we'd have that then if you rename a section you'd
> have to modify all the commands in that section.  Either way, I agree that
> an infrastructure change to support command grouping would be wise.
> As a starting point for grouping the commands, however, I'd prefer the
> grouping used in darcs.lhs, which is also the grouping used in the manual.
> (Although perhaps with less silliness).

Sorry I had some very bad time when describing my proposal. I wanted
  the type to be a simple enum and in some place there would be
  a map from the enum values to the group description strings (so there
  would not be any string duplications in diferent files).
Then it makes sense to put the enum definition and the map
  definition to a common place (probably darcs.lhs - whatever) and
  to add command_group (of the enum type) to the command structure.

I'm not a native speeker so I definitely accept the corrections :-D
  I added some text to clear up some. I removed all the corrections
  (and the corresponding original text) which are good from my
  point of view.

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

Makes sense. I used copy to stress that it is not move (we have quite
  lot of commands which are "dangerous" (ie they modify history or may
  lead to data loss). It is probably better to return there pull and push
  words instead of copy/retrieve.
The problem also is that if the commands are not grouped (with the group
  name) then some information is lost. E.g. Pull and Push command are in
  the group with name: "Copying patches between repositories with working
  directory update"
Check: http://article.gmane.org/gmane.comp.version-control.darcs.user/5704
As for as the command help (which contains the description as its first
  line) the clarification can te in the help text.

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


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

I'm curious where I got my text :) I have a feeling I read it somewhere
  but it seems to be ok in the documenatation now.
What did you mean by "... indicate any conflicts that may not be apparent"?
... expecially I'm curious about the world "apparent" in that context.

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

It should have been:
  "Record an inverse patch to some alrady in repository."
... or something like that.

OK, I missed here completely. I considered it to be some special kind
  of revert. By local copy I meant "working direcotory and not
  the local repository. This also explains why nobody responded to my
  question how to do "rollforward". This may confuse more people who
  use svn. It allows to merge a patch (and its inverse too) to the working
  directory. It looks like this is not possible with darcs without doing
  unpull/pull (but these require network connection or two local copies
  of repositories).
It would be a good idea to define terms:
  * working directory - I used "local copy" in this sense; consists of
    the files/directories in the latest version plus unrecorded local
    modifications (with some metadata for patches revert/unrevert)
  * local repository - stores recorded patches localy
  * remote repository - any other repository (together with its "remote
Do we have such definitions already? I noticed only some implicit
  info about them in Command voerview in the manual.

I think it is important to specify what datastore each command
  works with (this was also my main goal when deviding commands into
  the gropus). It is important even more which commands are not safe
  ie may lead to a data loss (revert, unpull, potentionally


More information about the darcs-users mailing list