Update suggested usage for smart_change.pl

Update the script itself, and references in the docs

3 files changed, 45 insertions, 65 deletions

diff --git a/english/devel/website/using_git.wml b/english/devel/website/using_git.wml
index 04af9112d75..acd5dcd658d 100644
--- a/english/devel/website/using_git.wml
+++ b/english/devel/website/using_git.wml
@@ -177,17 +177,37 @@ translation header.</p>
 
 <h3><a name="translation-smart-change">Translation changes with smart_change.pl</a></h3>
 
-<p>There is a *NEW* implementation of smart_change.pl which is limited to
-supporting git commit hashes. To use it:</p>
+<p><code>smart_change.pl</code> is a script designed to make it easier
+to update original files and their translations together. There are
+two ways to use it, depending on what changes you are making.</p>
 
-<ul>
+To use <code>smart_change</code> to just update the translation-check
+headers when you're working on files manually:
+
+<ol>
   <li>Make the changes to the original file(s), and commit</li>
   <li>Update translations</li>
   <li>Run smart_change.pl - it will pick up the changes and update
-      headers in the translation files</li>
-  <li>Review the changes (for example with <q>git diff</q>)</li>
-  <li>Commit and push the changes</li>
-</ul>
+    headers in the translated files</li>
+  <li>Review the changes (e.g. with "git diff")</li>
+  <li>Commit the translation changes</li>
+</ol>
+
+<p>Or, if you're using smart_change with a regular expression to make
+multiple changes across files in one pass:</p>
+
+<ol>
+  <li>Run <code>smart_change.pl -s s/FOO/BAR/ origfile1 origfile2 ...</code></li>
+  <li>Review the changes (e.g. with <code>git diff</code>)
+  <li>Commit the original file(s)</li>
+  <li>Run <code>smart_change.pl origfile1 origfile2</code>
+    (i.e. <strong>without the regexp</strong> this time);it will now
+    just update headers in the translated files</li>
+  <li>Finally, commit the translation changes</li>
+</ol>
+
+<p>This is more involved than previously (needing two commits), but
+unavoidable due to the way git commit hashes work/<p>
 
 <h3><a name="notifications">Getting notifications</a></h3>
 
diff --git a/english/devel/website/working.wml b/english/devel/website/working.wml
index aa229df910a..212178d2c71 100644
--- a/english/devel/website/working.wml
+++ b/english/devel/website/working.wml
@@ -103,60 +103,8 @@ in order to avoid bothering two dozen people for something that can be done
 quickly by a single person.</p>
 
 <p>In addition, to make such changes easier to apply, you can use the
-<code>smart_change.pl</code> script from the top-level directory in
-the webwml git module.</p>
-
-<h4>Usage of smart_change.pl</h4>
-#### salsa use git, not cvs
-#### Please update following description for git
-#### Some change done. cvs to git
-<pre>smart_change.pl [options] origfile</pre>
-
-<p>Currently only files in <code>/english/</code> are allowed as
-<var>origfile</var>. <code>smart_change.pl</code> takes the
-following arguments:</p>
-
-<dl>
-      <dt><code>-s, --substitute=<var>REGEXP</var></code></dt>
-      <dd>Specify a Perl regular expression applied to source files (may be used
-	more than once). Example:
-	<pre>
-	  $&gt; ./smart_change.pl -s "s,http://oldurl/,http://newurl/,g" english/devel/index.wml
-	  $&gt; git diff -u */devel/index.wml | less
-	  $&gt; git commit -m "1.23: Updated oldurl to current location" */devel/index.wml
-	</pre>
-	The first command does the change, the second command is for checking
-	the English original file and every translation of it. You should
-	do this to review the actual changes before committing. If everything
-	looks like you expected, commit your changes with the third command.
-      </dd>
-
-      <dt><code>-l, --lang=<var>STRING</var></code></dt>
-      <dd>Process this language (may be used more than once). If no
-	language is specified, all available ones are processed.</dd>
-
-      <dt><code>-n, --no-bump</code></dt>
-      <dd>Do not bump versions in translation-check headers.
-	Normally, the version in each translation-check header is increased
-	by one in the translated files that are up-to-date, and left
-	untouched in those that are out-of-date.
-	If this option is specified, no
-	translation-check headers are touched. See <q>keeping
-	translations up to date</q> for an <a href="uptodate">\
-	  explanation on translation-check headers</a>.
-      </dd>
-
-      <dt><code>-p, --previous</code></dt>
-      <dd>Show the previous CVS revision. This is mainly useful when the
-	English file is already committed and you want to check the
-	translation-check headers against the previous version.</dd>
-
-      <dt><code>-h, --help</code></dt>
-      <dd>Display short usage information.</dd>
-
-      <dt><code>-v, --verbose</code></dt>
-      <dd>Display verbose messages while running.</dd>
-</dl>
+<a href="using_git#translation-smart-change"><code>smart_change.pl</code></a>
+script from the top-level directory in the webwml git module.</p>
 
 <toc-add-entry name="links">Links</toc-add-entry>
 
diff --git a/smart_change.pl b/smart_change.pl
index 42a27b3c0d2..0814ac118d6 100755
--- a/smart_change.pl
+++ b/smart_change.pl
@@ -31,17 +31,29 @@ Options:
                      (may be used more than once)
 
 This is a *NEW* implementation of smart_change.pl which is limited to
-supporting git commit hashes. To use this:
+supporting git commit hashes. To use this to just update the
+translation-check headers:
 
  1. Make the changes to the original file(s), and commit
  2. Update translations
  3. Run smart_change.pl - it will pick up the changes and update
-    headers in the translation files
- 4. Review the changes (e.g. with "git diff -u")
+    headers in the translated files
+ 4. Review the changes (e.g. with "git diff")
  5. Commit the translation changes
 
+Or, if you're using smart_change with a regexp to make multiple
+changes across files:
+
+ 1. Run "smart_change.pl -s s/FOO/BAR/ origfile1 origfile2 ..."
+ 2. Review the changes (e.g. with "git diff")
+ 3. Commit the original file(s)
+ 4. Run "smart_change.pl origfile1 origfile2" (i.e. *without the
+    regexp* this time) - it will now just update headers in the
+    translated files
+ 5. Finally, commit the translation changes
+
 This is more involved than previously (needing two commits), but
-unavoidable...
+unavoidable due to the way git commit hashes work.
 
 EOT
         exit(0);