PT-1851 Formatting escape chars as code. Other fixes for Sphinx warnings.

PT-1833 missing Release Notes 3.1.0

bin/pt-archiver

@@ -7696,8 +7696,8 @@ Example:
 
 The file's contents are in the same format used by SELECT INTO OUTFILE, as
 documented in the MySQL manual: rows terminated by newlines, columns
-terminated by tabs, NULL characters are represented by \N, and special
-characters are escaped by \.  This lets you reload a file with LOAD DATA
+terminated by tabs, NULL characters are represented by C<\N>, and special
+characters are escaped by C<\>.  This lets you reload a file with LOAD DATA
 INFILE's default settings.
 
 If you want a column header at the top of the file, see L<"--header">.  The file
@@ -7856,8 +7856,10 @@ type: string
 Used with L<"--file"> to specify the output format.
 
 Valid formats are:
-  dump: MySQL dump format using tabs as field separator (default)
-  csv : Dump rows using ',' as separator and optionally enclosing fields by '"'.
+
+- dump: MySQL dump format using tabs as field separator (default)
+
+- csv : Dump rows using ',' as separator and optionally enclosing fields by '"'.
         This format is equivalent to FIELDS TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"'.
 
 =item --password
@@ -7887,10 +7889,10 @@ Specify the Perl module name of a general-purpose plugin.  It is currently used
 only for statistics (see L<"--statistics">) and must have C<new()> and a
 C<statistics()> method.
 
-The C<new( src => $src, dst => $dst, opts => $o )> method gets the source
+The C<new( src =E<gt> $src, dst =E<gt> $dst, opts =E<gt> $o )> method gets the source
 and destination DSNs, and their database connections, just like the
 connection-specific plugins do.  It also gets an OptionParser object (C<$o>) for
-accessing command-line options (example: C<$o->get('purge');>).
+accessing command-line options (example: C<$o-E<gt>get('purge');>).
 
 The C<statistics(\%stats, $time)> method gets a hashref of the statistics
 collected by the archiving job, and the time the whole job started.

bin/pt-heartbeat

@@ -6386,19 +6386,6 @@ sub main {
          sleep $next_interval - $time;
          PTDEBUG && _d('Woke up at', ts(time));
 
-         if ( $o->get('check-read-only') && $o->get('update') ) {
-           my $read_only_interval = $o->get('read-only-interval') || $interval;
-           while (server_is_readonly($dbh)) {
-              PTDEBUG && _d("Server is read only. Sleeping for $read_only_interval seconds...");
-              sleep($read_only_interval);
-              if (
-                 -f $sentinel
-              ) {
-                 return 0;
-              }
-           }
-         }
-
          # Connect or reconnect if necessary.
          if ( !$dbh->ping() ) {
             $dbh = $dp->get_dbh($dp->get_cxn_params($dsn), { AutoCommit => 1 });
@@ -6409,6 +6396,17 @@ sub main {
             $heartbeat_sth = undef;
          }
 
+         if ( $o->get('check-read-only') && $o->get('update') ) {
+           my $read_only_interval = $o->get('read-only-interval') || $interval;
+           while (server_is_readonly($dbh)) {
+              PTDEBUG && _d("Server is read only. Sleeping for $read_only_interval seconds...");
+              sleep($read_only_interval);
+              if (-f $sentinel) {
+                  return 0;
+              }
+           }
+         }
+
          if ( $o->get('monitor') ) {
             $heartbeat_sth ||= $dbh->prepare($heartbeat_sql);
             my ($delay) = $get_delay->($heartbeat_sth);

bin/pt-kill

@@ -8323,9 +8323,9 @@ Print information to STDOUT about what is being done.
 
 These actions are taken for every matching query from all classes.
 The actions are taken in this order: L<"--print">, L<"--execute-command">,
-L<"--kill">/L<"--kill-query">.  This order allows L<"--execute-command">
+L<"--kill"> / L<"--kill-query">.  This order allows L<"--execute-command">
 to see the output of L<"--print"> and the query before
-L<"--kill">/L<"--kill-query">.  This may be helpful because pt-kill does
+L<"--kill"> / L<"--kill-query">.  This may be helpful because pt-kill does
 not pass any information to L<"--execute-command">.
 
 See also L<"GROUP, MATCH AND KILL">.

bin/pt-online-schema-change

@@ -11918,7 +11918,7 @@ The tool exits with an error if the host is a cluster node and the table
 is MyISAM or is being converted to MyISAM (C<ENGINE=MyISAM>), or if
 C<wsrep_OSU_method> is not C<TOI>.  There is no way to disable these checks.
 
-=head1 MySQL 5.7+ Generated columns
+=head1 MySQL 5.7 + Generated columns
 
 The tools ignores MySQL 5.7+ C<GENERATED> columns since the value for those columns
 is generated according to the expresion used to compute column values.

bin/pt-slave-delay

@@ -4602,7 +4602,7 @@ server.  Before using this tool, please:
 C<pt-slave-delay> watches a slave and starts and stops its replication SQL
 thread as necessary to hold it at least as far behind the master as you
 request.  In practice, it will typically cause the slave to lag between
-L<"--delay"> and L<"--delay">+L<"--interval"> behind the master.
+L<"--delay"> and L<"--delay"> + L<"--interval"> behind the master.
 
 It bases the delay on binlog positions in the slave's relay logs by default,
 so there is no need to connect to the master.  This works well if the IO

bin/pt-stalk

@@ -1993,7 +1993,7 @@ then compared to L<"--threshold"> as usual.  The C<$EXT_ARGV> variable
 contains the MySQL options mentioned in the L<"SYNOPSIS"> above.
 
 The file should not alter the tool's existing global variables.  Prefix any
-file-specific global variables with "PLUGIN_" or make them local.
+file-specific global variables with C<PLUGIN_> or make them local.
 
 =item --help
 

bin/pt-table-checksum

@@ -13324,7 +13324,8 @@ first option on the command line.
 
 See the L<"--help"> output for a list of default config files.
 
-=item --[no]create-replicate-table
+=item --create-replicate-table
+=item --no-create-replicate-table
 
 default: yes
 
@@ -13687,7 +13688,7 @@ structure (MAGIC_create_replicate):
 
 Note: lower_boundary and upper_boundary data type can be BLOB. See L<"--binary-index">.
 
-By default, L<"--[no]create-replicate-table"> is true, so the database and
+By default, L<"--create-replicate-table"> is true, so the database and
 the table specified by this option are created automatically if they do not
 exist.
 

docs/index.rst

@@ -4,7 +4,7 @@
 ===============================
 
 Percona Toolkit is a collection of advanced command-line tools
-used by `Percona <http://www.percona.com/>`_) support staff
+used by `Percona <http://www.percona.com/>`_ support staff
 to perform a variety of MySQL, MongoDB, and system tasks
 that are too difficult or complex to perform manually.
 
@@ -59,6 +59,8 @@ Miscellaneous
    :maxdepth: 2
 
    bugs
+   ipv6_support
+   special_option_types
    authors
    copyright_license_and_warranty
    version

docs/release_notes.rst

@@ -1,7 +1,7 @@
 Percona Toolkit
 ***************
 
-v3.2.0 released 2019-04-23
+v3.2.0 released 2020-04-23
 ==========================
 
 Improvements:
@@ -27,6 +27,39 @@ Bug fixes:
 * :jirabug:`PT-1793`: ``pt-query-digest`` was unable to handle the year 2020 because of wrong ``tcpdump`` parsing. (Thank you, Kei Tsuchiya.)
 
 
+v3.1.0 released 2019-09-12
+==========================
+
+New Features:
+
+* :jirabug:`PT-1663`: Implement retention by bytes for pt-stalk
+
+Improvements:
+
+* :jirabug:`PT-1705`: Make pt-online-schema-change exit with different codes depending on the status
+* :jirabug:`PT-1761`: Prevent pt-osc to run under MySQL 8.0.14+ & 8.0.17
+* :jirabug:`PT-1746`: diskstats not working for kernel 4.18+
+
+Bugs Fixed:
+
+* :jirabug:`PT-1736`: pt-kill ignores --busy-time and --kill-busy-commands=Query when there is a process with Command=Execute
+* :jirabug:`PT-1575`: pt-mysql-summary does not print PXC section for PXC 5.6 and 5.7
+* :jirabug:`PT-1728`: Pt-table-checksum failing to scan small tables that get wiped out often
+* :jirabug:`PT-1720`: pt-pmp parses configuration files that lead to errors
+* :jirabug:`PT-1114`: LP #1182180: pt-table-checksum fails when table is empty
+* :jirabug:`PT-1715`: pt-upgrade documentation doesn't have the type tcpdump
+* :jirabug:`PT-1344`: LP #1580428: pt-online-schema-change: Use of uninitialized value $host in string
+* :jirabug:`PT-1492`: pt-kill in version 3.0.7 seems not to respect busy-time any longer
+* :jirabug:`PT-1798`: CLONE - yum repos do not contain 3.1.1 of percona toolkit
+* :jirabug:`PT-1797`: yum repos do not contain 3.1.1 of percona toolkit
+* :jirabug:`PT-1633`: pt-config-diff doesn't handle innodb_temp_data_file_path correctly
+* :jirabug:`PT-1630`: pt-table-checksum not working with galera cluster anymore since 3.0.11
+* :jirabug:`PT-1734`: Tailing log_error in pt-stalk doesn't work
+* :jirabug:`PT-1732`: Typo in link on percona.com
+
+
+
+  
 v3.0.13 released 2019-01-03
 ===========================
 
@@ -77,8 +110,7 @@ New features
 
 * :jirabug:`PT-1571`: Improved hostname recognition in ``pt-secure-collect``
 * :jirabug:`PT-1569`: Disabled ``--alter-foreign-keys-method=drop_swap`` in ``pt-online-schema-change``
-* :jirabug:`PT-242`: (``pt-stalk``) Include ``SHOW SLAVE STATUS`` on MySQL 5.7 (Thanks `Marcelo Altmann <https://www.p
-ercona.com/blog/author/marcelo-altmann/>`_)
+* :jirabug:`PT-242`: (``pt-stalk``) Include ``SHOW SLAVE STATUS`` on MySQL 5.7 (Thanks `Marcelo Altmann <https://www.percona.com/blog/author/marcelo-altmann/>`_)
 
 Fixed bugs
 
@@ -1105,17 +1137,17 @@ pt-query-digest --output json includes query examples as of v2.2.3. Some people
 When using drop swap with pt-online-schema-change there is some production impact. This impact can be measured because tool outputs the current timestamp on lines for operations that may take awhile.
 
 * Fixed bug #1163735: pt-table-checksum fails if explicit_defaults_for_timestamp is enabled in 5.6
-pt-table-checksum would fail if variable explicit_defaults_for_timestamp was enabled in MySQL 5.6.
+  pt-table-checksum would fail if variable explicit_defaults_for_timestamp was enabled in MySQL 5.6.
 
 * Fixed bug #1182856: Zero values causes "Invalid --set-vars value: var=0"
-Trying to assign 0 to any variable by using --set-vars option would cause “Invalid --set-vars value” message. 
+  Trying to assign 0 to any variable by using --set-vars option would cause “Invalid --set-vars value” message. 
 
 * Fixed bug #1188264: pt-online-schema-change error copying rows: Undefined subroutine &pt_online_schema_change::get
 
 * Fixed the typo in the pt-online-schema-change code that could lead to a tool crash when copying the rows.
 
 * Fixed bug #1199591: pt-table-checksum doesn't use non-unique index with highest cardinality
-pt-table-checksum was using the first non-unique index instead of the one with the highest cardinality due to a sorting bug.
+  pt-table-checksum was using the first non-unique index instead of the one with the highest cardinality due to a sorting bug.
 
 Percona Toolkit packages can be downloaded from
 http://www.percona.com/downloads/percona-toolkit/ or the Percona Software

docs/rn.3-1-0.txt

@@ -0,0 +1,44 @@
+.. _PT-3.1.0:
+
+================================================================================
+*Percona Toolkit* 3.1.0
+================================================================================
+
+:Date: September 12, 2019
+:Installation: `Installing Percona Toolkit <https://www.percona.com/doc/percona-toolkit/LATEST/installation.html>`_
+
+New Features
+================================================================================
+
+* :jirabug:`PT-1663`: Implement retention by bytes for pt-stalk
+
+
+
+Improvements
+================================================================================
+
+* :jirabug:`PT-1705`: Make pt-online-schema-change exit with different codes depending on the status
+* :jirabug:`PT-1761`: Prevent pt-osc to run under MySQL 8.0.14+ & 8.0.17
+* :jirabug:`PT-1746`: diskstats not working for kernel 4.18+
+
+
+
+Bugs Fixed
+================================================================================
+
+* :jirabug:`PT-1736`: pt-kill ignores --busy-time and --kill-busy-commands=Query when there is a process with Command=Execute
+* :jirabug:`PT-1575`: pt-mysql-summary does not print PXC section for PXC 5.6 and 5.7
+* :jirabug:`PT-1728`: Pt-table-checksum failing to scan small tables that get wiped out often
+* :jirabug:`PT-1720`: pt-pmp parses configuration files that lead to errors
+* :jirabug:`PT-1114`: LP #1182180: pt-table-checksum fails when table is empty
+* :jirabug:`PT-1715`: pt-upgrade documentation doesn't have the type tcpdump
+* :jirabug:`PT-1344`: LP #1580428: pt-online-schema-change: Use of uninitialized value $host in string
+* :jirabug:`PT-1492`: pt-kill in version 3.0.7 seems not to respect busy-time any longer
+* :jirabug:`PT-1798`: CLONE - yum repos do not contain 3.1.1 of percona toolkit
+* :jirabug:`PT-1797`: yum repos do not contain 3.1.1 of percona toolkit
+* :jirabug:`PT-1633`: pt-config-diff doesn't handle innodb_temp_data_file_path correctly
+* :jirabug:`PT-1630`: pt-table-checksum not working with galera cluster anymore since 3.0.11
+* :jirabug:`PT-1734`: Tailing log_error in pt-stalk doesn't work
+* :jirabug:`PT-1732`: Typo in link on percona.com
+
+