svn commit: r1875404 - /subversion/site/publish/docs/release-notes/1.14.html

[ha...@apache.org]

Author: hartmannathan
Date: Thu Mar 19 00:48:57 2020
New Revision: 1875404

URL: http://svn.apache.org/viewvc?rev=1875404&view=rev
Log:
1.14 release notes: Improve #editor-filename-escaping and add example

Follow-up to r1875312.

Mailing list thread "svn commit: r1875312..." on 17 Mar 2020, archived here:
https://lists.apache.org/thread.html/r037b3cf7e1cc4990c7d333c6499b34b45bc59806b8a43d3b06c0fbab%40%3Ccommits.subversion.apache.org%3E

* docs/release-notes/1.14.html
  (editor-filename-escaping): Implementing suggested improvements.
    Specifically, as danielsh points out, $SVN_EDITOR is only one of several
    ways to configure a user-defined editor. Also, add example CLI
    "screenshot" provided by danielsh (text conflict which leads to launching
    the editor). 

Suggested by: danielsh

Modified:
    subversion/site/publish/docs/release-notes/1.14.html

Modified: subversion/site/publish/docs/release-notes/1.14.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/release-notes/1.14.html?rev=1875404&r1=1875403&r2=1875404&view=diff
==============================================================================
--- subversion/site/publish/docs/release-notes/1.14.html (original)
+++ subversion/site/publish/docs/release-notes/1.14.html Thu Mar 19 00:48:57 2020
@@ -293,25 +293,67 @@ in a range of revisions. (See <a href="h
 </div> <!-- info-show-item-changelist -->
 
 <div class="h4" id="editor-filename-escaping">
-<h4>Escaping/quoting of pathname arguments to <tt>$SVN_EDITOR</tt>
+<h4>Escaping/quoting of pathname arguments to the user-defined editor
   <a class="sectionlink" href="#log-search"
      title="Link to this section">&para;</a>
 </h4>
 
-<p>When invoking the user-defined <tt>$SVN_EDITOR</tt>, such as during
-interactive conflict resolution, Subversion now performs escaping of any
-special characters in the pathname of the file to be edited. (See
+<p>When invoking the user-defined editor, such as during interactive conflict
+resolution, Subversion now performs escaping of any special characters in the
+pathname of the file to be edited. This corrects a problem that would occur
+previously when the file to be edited (and/or the path leading to it)
+contained spaces or other special characters. (See
 <a href="http://svn.apache.org/r1874057">r1874057</a>,
 <a href="http://svn.apache.org/r1874093">r1874093</a>, and
 <a href="http://svn.apache.org/r1875230">r1875230</a>.)</p>
 
-<p>Note that escaping is performed only on the pathname argument.
-<tt>$SVN_EDITOR</tt> itself is not escaped: As before, the editor is invoked
-through the shell and the user must properly escape/quote
-<tt>$SVN_EDITOR</tt>. See the related FAQ
-<a href="https://subversion.apache.org/faq.html#svn-editor">"How do I deal
-with spaces in the editor path?  Also, how can I define command line options
-for the editor?"</a></p>
+<p>Note that escaping is performed only on the pathname argument. As before,
+the editor itself is invoked through the shell and the user must properly
+quote/escape the command line used to launch it. This is intentional, as it
+allows the user to construct a shell command which itself contains command
+line arguments. See the related
+<a href="https://subversion.apache.org/faq.html#svn-editor">FAQ entry</a> for
+more on spaces and/or command line options in the editor path.</p>
+
+<p>The user-defined editor can be specified in the following ways, in this
+order of precedence:</p>
+
+<ul>
+  <li>The <tt>--editor-cmd</tt> command-line option</li>
+  <li>The <tt>$SVN_EDITOR</tt> environment variable</li>
+  <li>The <tt>editor-cmd</tt> runtime configuration option</li>
+  <li>The <tt>$VISUAL</tt> environment variable</li>
+  <li>The <tt>$EDITOR</tt> environment variable</li>
+</ul>
+
+<p>The escaped pathname of the file to be edited is passed to the editor as
+its last command line argument.</p>
+
+<p>For example, suppose that <tt>$SVN_EDITOR</tt> is set as follows:</p>
+
+<pre>SVN_EDITOR='vim -N --'
+export SVN_EDITOR
+</pre>
+
+<p>Furthermore, suppose 'svn up' finds a text conflict in a file called
+<tt>foo bar.txt</tt>:</p>
+
+<pre>
+$ svn up 
+Updating '.':
+C    foo bar.txt
+Updated to revision 2.
+Summary of conflicts:
+  Text conflicts: 1
+Merge conflict discovered in file 'foo bar.txt'.
+Select: (p) Postpone, (df) Show diff, (e) Edit file, (m) Merge,
+        (s) Show all options: <b>e</b>
+</pre>
+
+<p>When Subversion launches the editor, the spaces in <tt>vim -N --</tt> will
+<strong>not</strong> be escaped, allowing vim to be invoked with <tt>-N</tt>
+and <tt>--</tt> as its first two arguments, but the space in
+<tt>foo bar.txt</tt> <strong>will</strong> be escaped.</p>
 
 </div> <!-- editor-filename-escaping -->