Add command line utility to help convert remap plugin usage to ATS9.

doc/appendices/command-line/cvtremappi.en.rst

@@ -0,0 +1,69 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+.. include:: ../../common.defs
+
+.. _cvtremappi:
+
+cvtremappi
+**********
+
+Description
+===========
+
+To help convert your remapping configuration from pre-ATS9 to ATS9 and later.  It may be useful if you use any
+of the core plugins regex_remap.so, header_rewrite.so or gzip.so.  (For this script to work, the python3
+command has to be in your path.)  You can specify where your remap configuration file is with the option:
+
+--filepath FILEPATH
+
+If this parameter is omitted, it defaults to ``./remap.config`` .  The script will make necessary modifications
+to this file, and any files it includes with ``.include`` .  It will change `@plugin=gzip.so` to its new name,
+`@plugin=compress.so` .  When regex_remap.so is invoked as the first remap plugin, it will add the parameter
+@pparam=pristine .  (This makes it work the same as in pre-9 ATS, where the request URL is the pre-remapping
+URL for the first plugin for a remap rule.)  When `header_rewrite.so` is used as a remap plugin, no changes
+are needed in the remap configuration line invoking it.  However, changes may be necessary to the
+configuration files passed to it as parameters.  If a header rewrite configuration file is used for both the
+invocation of header rewrite as the first plugin for remap rules, and for other invocations, it may be
+necessary to generate two new versions of it.  In these cases, the prefix `1st-` is added to file's name,
+for the version used with header rewrite as the first plugin.  If you prefer that a different prefix be added,
+you can specify it with this option:
+
+--prefix PREFIX
+
+If you are also using header rewrite as a global plugin, you should also provide the filepath of the global
+plugin configuration file with this option:
+
+--plugin PLUGIN
+
+(Note that, if the PLUGIN filepath is relative, it should be relative to the directory containing the remap
+configuration file, not relative to the directory the script is run from.  Note also that, if relative paths
+for include files for header rewrite config files appear in the configuration files, they are assumed to be
+relative to the directory containing the remap configuration file.)
+
+Header rewrite previously had some logic that has been eliminated in ATS9.  If a line in a header rewrite
+configuration file relies on this deprecated logic, an error message will be output to standard error.  The
+text `ERROR:` will be prepended to the line in the configuration file causing the error.
+
+The script writes, one per line, a list of the files it is changing or creating to the standard output.  But
+both new and changed files will be written into entirely new files with the suffix `.new` added to the filepath.
+For example, if `remap.config` is changed by the script, it will put the changed version of the file in
+`remap.config.new` .  This gives you a chance to review the changes the script has made.  You can then put the
+changed files into effect with the tool script `insnew`.  This script reads a list of filepaths, one per line,
+from the standard input.  For each filepath `FP`, if it specifies an existing file, it will rename it to
+`FP.old`.  It will then rename the file `FP.new` to `FP`.  This second script should be run from the same
+current directory as the first script was run from.