[PROPOSAL] Relaxing diff3 interface requirements documentation

[Erik Huelsmann <eh...@gmail.com>]

In both the internal and external diff3 routines, I found requirements
to which I can't find any evidence in the code. Nor did I find any
references in the mailing list archives of anybody having problems
indicating there would be requirements to this effect.

So I propose applying the patch below (so I can simplify svn_wc_merge2).


bye,

Erik.


Log:
[[[
Simplify diff3 requirements because they needlessly complicate calling code
and there's no evidence they are actually required.

* subversion/include/svn_diff.h
  (svn_diff_file_diff3_2): The paths don't need to be absolute; we just
  pass them to svn_io_file_open().

* subversion/include/svn_io.h
  (svn_io_run_diff3_2): There's no evidence we require the files to be
  relative to the working directory; we just pass them to diff3.
]]]

Index: subversion/include/svn_diff.h
===================================================================
--- subversion/include/svn_diff.h       (revision 20240)
+++ subversion/include/svn_diff.h       (working copy)
@@ -397,8 +397,8 @@
  * @since New in 1.4.
  *
  * Return a diff object in @a *diff (allocated from @a pool) that represents
- * the difference between an @a original file, @a modified file, and @a latest
- * file. (The file arguments must be full paths to the files.)
+ * the difference between an @a original file, @a modified file, and @a latest
+ * file.
  *
  * Compare lines according to the relevant fields of @a options.
  */
Index: subversion/include/svn_io.h
===================================================================
--- subversion/include/svn_io.h (revision 20240)
+++ subversion/include/svn_io.h (working copy)
@@ -912,8 +912,8 @@
  * If @a user_args is non-NULL, replace "-E" with the <tt>const char*</tt>
  * elements that @a user_args contains.
  *
- * @a mine, @a older, and @a yours are utf8-encoded paths, relative to @a dir,
- * to three files that already exist.  @a merged is an open file handle, and
+ * @a mine, @a older and @a yours are utf8-encoded paths to three files
+ * that already exist.  @a merged is an open file handle, and
  * is left open after the merge result is written to it. (@a merged
  * should *not* be the same file as @a mine, or nondeterministic things
  * may happen!)

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [PROPOSAL] Relaxing diff3 interface requirements documentation

[Erik Huelsmann <eh...@gmail.com>]

> * subversion/include/svn_diff.h
>   (svn_diff_file_diff3_2): The paths don't need to be absolute; we just
>   pass them to svn_io_file_open().

BTW: svn_wc_merge2 already doesn't respect this requirement (and it
seems it didn't from the start...).

bye,


Erik.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [PROPOSAL] Relaxing diff3 interface requirements documentation

[Julian Foad <ju...@btopenworld.com>]

Erik Huelsmann wrote:
> On 6/25/06, Julian Foad <ju...@btopenworld.com> wrote:
> 
>> The old text "must be full paths" was poor (not clear whether it meant
>> "absolute") but if relative paths are to be allowed you need to say 
>> what they are relative to.
> 
> Hmm. Why? svn_io_file_open() says nothing about absolute or relative
> paths and what they are relative to. I think that's implicit.

Yes, OK, I suppose it is implicit in many functions that relative paths are 
relative to the current working directory.  We just need to be careful in 
documenting functions that have another possible context to use, like the one 
below.

>> Same here: [for svn_io_run_diff3_2()]
> 
> Well, since they aren't relative to the current working directory, I
> agree with you on this point. I'll add that.
> 
> Thanks for your comments!

By the way, +1 on doing this and then avoiding copying files in the caller 
svn_wc_merge2() like you said.  Well spotted.

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [PROPOSAL] Relaxing diff3 interface requirements documentation

[Erik Huelsmann <eh...@gmail.com>]

On 6/25/06, Julian Foad <ju...@btopenworld.com> wrote:
> Erik Huelsmann wrote:
> > - * the difference between an @a original file, @a modified file, and @a
> > latest
> > - * file. (The file arguments must be full paths to the files.)
> > + * the difference between an @a original file, @a modified file, and @a
> > latest
> > + * file.
>
> The old text "must be full paths" was poor (not clear whether it meant
> "absolute") but if relative paths are to be allowed you need to say what they
> are relative to.

Hmm. Why? svn_io_file_open() says nothing about absolute or relative
paths and what they are relative to. I think that's implicit.

> > - * @a mine, @a older, and @a yours are utf8-encoded paths, relative to
> > @a dir,
> > - * to three files that already exist.  @a merged is an open file
> > handle, and
> > + * @a mine, @a older and @a yours are utf8-encoded paths to three files
> > + * that already exist.  @a merged is an open file handle, and
>
> Same here: you can't just remove that text.  Change it to something like
> "(absolute, or relative to @a dir)".

Well, since they aren't relative to the current working directory, I
agree with you on this point. I'll add that.

Thanks for your comments!

bye,

Erik.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [PROPOSAL] Relaxing diff3 interface requirements documentation

[Julian Foad <ju...@btopenworld.com>]

Erik Huelsmann wrote:
> - * the difference between an @a original file, @a modified file, and @a 
> latest
> - * file. (The file arguments must be full paths to the files.)
> + * the difference between an @a original file, @a modified file, and @a 
> latest
> + * file.

The old text "must be full paths" was poor (not clear whether it meant 
"absolute") but if relative paths are to be allowed you need to say what they 
are relative to.

> - * @a mine, @a older, and @a yours are utf8-encoded paths, relative to 
> @a dir,
> - * to three files that already exist.  @a merged is an open file 
> handle, and
> + * @a mine, @a older and @a yours are utf8-encoded paths to three files
> + * that already exist.  @a merged is an open file handle, and

Same here: you can't just remove that text.  Change it to something like 
"(absolute, or relative to @a dir)".

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org