List:Commits« Previous MessageNext Message »
From:john.russell Date:October 18 2010 11:12pm
Subject:svn commit - mysqldoc@docsrva: r23210 - trunk/mysql-enterprise-backup-3.5
View as plain text  
Author: jrussell
Date: 2010-10-19 01:12:57 +0200 (Tue, 19 Oct 2010)
New Revision: 23210

Log:
More cleanup throughout the afternoon, mostly in the first few chapters.


Modified:
   trunk/mysql-enterprise-backup-3.5/all-entities.ent
   trunk/mysql-enterprise-backup-3.5/manual.xml


Modified: trunk/mysql-enterprise-backup-3.5/all-entities.ent
===================================================================
--- trunk/mysql-enterprise-backup-3.5/all-entities.ent	2010-10-18 20:19:27 UTC (rev 23209)
+++ trunk/mysql-enterprise-backup-3.5/all-entities.ent	2010-10-18 23:12:57 UTC (rev 23210)
Changed blocks: 1, Lines Added: 7, Lines Deleted: 0; 936 bytes

@@ -4,12 +4,19 @@
 current directory.  All ENTITY declarations should be given
 first, followed by references to the those entities.
 -->
+
+<!-- Major product-specific terms. -->
+
+<!ENTITY prodname "MySQL Enterprise Backup">
+
 <!-- Making the command names into entities in case of change. -->
 <!-- 'low level backup' and 'high level backup' commands. -->
+
 <!ENTITY llbackup "ibbackup">
 <!ENTITY hlbackup "mysqlbackup">
 
 <!-- Entities for LSN values that get updated every time the example output is refreshed. -->
+
 <!ENTITY example-3.1-lsn "32164666380">
 <!ENTITY example-3.2-lsn "32164666380">
 <!ENTITY example-5.6-lsn "2626689439">


Modified: trunk/mysql-enterprise-backup-3.5/manual.xml
===================================================================
--- trunk/mysql-enterprise-backup-3.5/manual.xml	2010-10-18 20:19:27 UTC (rev 23209)
+++ trunk/mysql-enterprise-backup-3.5/manual.xml	2010-10-18 23:12:57 UTC (rev 23210)
Changed blocks: 31, Lines Added: 111, Lines Deleted: 86; 18831 bytes

@@ -254,13 +254,13 @@
     </indexterm>
 
     <para>
-      The <literal>&llbackup;</literal> of MySQL Enterprise Backup lets
-      you back up InnoDB tables from a running MySQL database without
-      setting any locks or disturbing normal database processing. You
-      get a consistent copy of your database, as if the copy were taken
-      at a precise point in time. MySQL Enterprise Backup is also the
-      ideal method of setting up new slaves if you use MySQL replication
-      on InnoDB tables.
+      The <literal>&llbackup;</literal> of MySQL Enterprise Backup backs
+      up InnoDB tables from a running MySQL database without disturbing
+      normal database processing. You get a consistent copy of your
+      database, as if the copy were taken at a precise point in time,
+      even though the backup job could take minutes or hours. MySQL
+      Enterprise Backup is also the ideal method of setting up new
+      slaves if you use MySQL replication on InnoDB tables.
     </para>
 
     <para>

@@ -278,16 +278,17 @@
 
       <para>
         You specify two filenames on the &llbackup; command line. These
-        <literal>.cnf</literal> files represent MySQL options files.
-        These options file have the following requirements:
+        <literal>.cnf</literal> files represent MySQL options files and
+        use similar syntax. These options file have the following
+        requirements:
       </para>
 
       <itemizedlist>
 
         <listitem>
           <para>
-            Each options file must contain the following parameter
-            values:
+            Each options file must contain the following
+            <emphasis role="bold">parameter values</emphasis>:
           </para>
 
 <programlisting>

@@ -304,15 +305,16 @@
 
         <listitem>
           <para>
-            The directory paths must be absolute, because
-            <literal>&llbackup;</literal> is not aware of the defaults.
+            The <emphasis role="bold">directory paths</emphasis> must be
+            absolute, because <literal>&llbackup;</literal> is not aware
+            of the defaults.
           </para>
         </listitem>
 
         <listitem>
           <para>
-            The specification of the number of data files and their
-            sizes must match in <literal>my.cnf</literal> and
+            The number of <emphasis role="bold">data files</emphasis>
+            and their sizes must match in <literal>my.cnf</literal> and
             <literal>my2.cnf</literal>. For example, if the last data
             file is specified as auto-extending in
             <literal>my.cnf</literal>, it must be specified as

@@ -322,10 +324,10 @@
 
         <listitem>
           <para>
-            The number of log files and their size must be explicitly
-            specified, but their number and size can be different
-            between <literal>my.cnf</literal> and
-            <literal>my2.cnf</literal>.
+            The number of <emphasis role="bold">log files</emphasis> and
+            their size must be explicitly specified, but their number
+            and size can be different between <literal>my.cnf</literal>
+            and <literal>my2.cnf</literal>.
           </para>
         </listitem>
 

@@ -385,7 +387,7 @@
       <title>Command-Line Options</title>
 
       <para>
-        The call <literal>ibbackup --help</literal> displays usage
+        The command <literal>ibbackup --help</literal> displays usage
         information for the command-line options:
       </para>
 

@@ -583,10 +585,12 @@
         </para>
       </listitem>
 
+<!-- JDR: consider which other items to link to the InnoDB glossary, e.g. file-per-table, file format names. -->
+
       <listitem>
         <para>
           Any separate data files produced under the InnoDB
-          &quot;file-per-table&quot; setting.
+          <quote>file-per-table</quote> setting.
         </para>
       </listitem>
 

@@ -598,13 +602,13 @@
 
       <listitem>
         <para>
-          Data stored in both the original &quot;Antelope&quot; and new
-          &quot;Barracuda&quot; file formats. Barracuda is a relatively
-          recent file format that was first introduced with the InnoDB
-          plugin. In particular, it includes support for compression
-          within table data. Barracuda file format support is new in Hot
-          Backup Version 3.5. It is automatic, without any option
-          required for <literal>&llbackup;</literal>.
+          Data stored in both the original <quote>Antelope</quote> and
+          new <quote>Barracuda</quote> file formats. Barracuda is a
+          relatively recent file format that was first introduced with
+          the InnoDB plugin. In particular, it includes support for
+          compression within table data. Barracuda file format support
+          is new in &prodname; Version 3.5. It is automatic, without any
+          option required for <literal>&llbackup;</literal>.
         </para>
       </listitem>
 

@@ -622,12 +626,13 @@
       <title>Example: Making an Uncompressed Backup of InnoDB Tables</title>
 
       <para>
-        We have prepared an options file
-        <literal>/home/pekka/.backup-my.cnf</literal> which defines the
+        In this example, the options file
+        <literal>/home/pekka/.backup-my.cnf</literal> defines the
         location of the backup (as described in the previous section).
         The options file <literal>/home/pekka/.my.cnf</literal> defines
-        the MySQL installation we want to back up. We run
-        <literal>&llbackup;</literal>:
+        the MySQL installation to back up. Running
+        <literal>&llbackup;</literal> performs the first phase of the
+        process:
       </para>
 
 <programlisting id="example-2.1a">

@@ -695,9 +700,9 @@
             Make a note of the LSN value in the message at the end of
             both full and incremental backups, for example,
             <literal>ibbackup: Was able to parse the log up to lsn
-            928223244</literal>. You must specify this value when
-            performing incremental backups of changes that occur after
-            this full backup.
+            <replaceable>LSN_number</replaceable></literal>. You specify
+            this value when performing incremental backups of changes
+            that occur after this full backup.
           </para>
         </listitem>
 

@@ -707,7 +712,8 @@
             the uncompressed backup files, so that the full backup is
             ready to be restored at any time. You can move the backup
             data to a different server first, to avoid the CPU and I/O
-            overhead of this operation on the database server itself.
+            overhead of performing this operation on the database
+            server.
           </para>
         </listitem>
 

@@ -738,14 +744,13 @@
       </indexterm>
 
       <para>
-        Many users want to save disk space by compressing backup data
-        files. The <literal>--compress</literal> option instructs
-        <literal>&llbackup;</literal> to compress backup data files.
-        Compression allows you to keep more sets of backup data on hand,
-        and saves on transmission time when sending the backup data to
-        another server. The downside is extra CPU overhead during the
-        backup itself, and extra time needed during the restore process
-        as the data is uncompressed.
+        To save disk space, you can compress backup data files by using
+        the <literal>--compress</literal> option of
+        <literal>&llbackup;</literal>. Compression lets you keep more
+        sets of backup data on hand, and saves on transmission time when
+        sending the backup data to another server. The downside is extra
+        CPU overhead during the backup itself, and extra time needed
+        during the restore process as the data is uncompressed.
       </para>
 
       <para>

@@ -761,7 +766,7 @@
 
       <para>
         You can use the <literal>--compress</literal> option for full
-        backups or for incremental backups (with the
+        backups, or for incremental backups in combination with the
         <literal>--incremental</literal> option.
       </para>
 

@@ -811,8 +816,8 @@
 
       <para>
         The backup directory is shown below. Compressed data files have
-        the suffix <literal>.ibz</literal>. Typically compression ratios
-        of more than 70% are achieved:
+        the suffix <literal>.ibz</literal>. Typically, compression
+        ratios of more than 70% are achieved:
       </para>
 
 <programlisting id="example-2.2b">

@@ -829,14 +834,16 @@
 
       <itemizedlist>
 
+<!-- JDR: some of these step-paragraphs are reused, could be entity-ized. -->
+
         <listitem>
           <para>
             Make a note of the LSN value in the message at the end of
             both full and incremental backups, for example,
             <literal>ibbackup: Was able to parse the log up to lsn
-            928223244</literal>. You must specify this value when
-            performing incremental backups of changes that occur after
-            this full backup.
+            <replaceable>LSN_number</replaceable></literal>. You specify
+            this value when performing incremental backups of changes
+            that occur after this full backup.
           </para>
         </listitem>
 

@@ -846,7 +853,8 @@
             the compressed backup files, so that the full backup is
             ready to be restored at any time. You can move the backup
             data to a different server first, to avoid the CPU and I/O
-            overhead of this operation on the database server itself.
+            overhead of performing this operation on the database
+            server.
           </para>
         </listitem>
 

@@ -868,15 +876,18 @@
       <title>Example: Making an Incremental Backup of InnoDB Tables</title>
 
       <para>
-        Incremental backup means that only changes are backed up, which
-        provides additional flexibility in designing a backup strategy
-        and reduces required storage for backups. Because an incremental
-        backup always adds to an existing set of backup files, this
-        procedure requires that you have already made a full
+        An incremental backup only backs up data that changed since the
+        previous backup. This technique provides additional flexibility
+        in designing a backup strategy and reduces required storage for
+        backups. Because an incremental backup always adds to an
+        existing set of backup files, make a full
         <link linkend="backup.uncompressed">uncompressed</link> or
-        <link linkend="backup.compressed">compressed</link> backup.
+        <link linkend="backup.compressed">compressed</link> backup
+        before doing any incremental backups.
       </para>
 
+<!-- JDR: if enough internal-style tips like this, consider a later "Internals" or "Troubleshooting" section. -->
+
       <para>
         Incremental backups detect changes at the level of pages in the
         data file, as opposed to table rows; each page that has changed

@@ -888,23 +899,23 @@
         Incremental backup is enabled through the
         <literal>--incremental</literal> option of the
         <literal>&llbackup;</literal> command. You must also indicate
-        the point in time of the previous <emphasis>full or
-        incremental</emphasis> backup, through the
-        <literal>--lsn</literal> option, where you specify the highest
-        log sequence number from a previous <emphasis>full or
-        incremental</emphasis> backup.
+        the point in time of the previous full or incremental backup,
+        through the <literal>--lsn</literal> option, where you specify
+        the highest log sequence number from a previous full or
+        incremental backup.
       </para>
 
       <para>
-        When running the &quot;apply log&quot; step for an incremental
-        backup, you specify the option sequence <literal>--apply-log
-        --incremental</literal>, and the paths to 2 MySQL configuration
-        files, first the <literal>.cnf</literal> file pointing to the
-        full backup that you are updating, then the .cnf file pointing
-        to the incremental backup data files. If you have taken several
-        incremental backups since the last full backup, you might run
-        several such <quote>apply log</quote> steps, one after the
-        other, to bring the full backup entirely up to date.
+        When running the <quote>apply log</quote> step for an
+        incremental backup, you specify the option sequence
+        <literal>--apply-log --incremental</literal>, and the paths to 2
+        MySQL configuration files, first the <literal>.cnf</literal>
+        file pointing to the full backup that you are updating, then the
+        .cnf file pointing to the incremental backup data files. If you
+        have taken several incremental backups since the last full
+        backup, you might run several such <quote>apply log</quote>
+        steps, one after the other, to bring the full backup entirely up
+        to date.
       </para>
 
       <para>

@@ -915,9 +926,11 @@
         command-line syntax.
       </para>
 
+<!-- JDR: see whether these LSN numbers should refer to one of the new entities. -->
+
       <para>
-        In this example, we run an incremental backup. The last full
-        backup we ran reported that the highest
+        This example shows an incremental backup. The last full backup
+        we ran reported that the highest
         <link linkend="glos_lsn">LSN</link> was 2244068296:
       </para>
 

@@ -1066,7 +1079,7 @@
             taking a full
             <link linkend="backup.uncompressed">uncompressed</link> or
             <link linkend="backup.compressed">compressed</link> backup.
-            Typically, this milestone is when you could archive and/or
+            Typically, this milestone happens when you can archive and
             clear out your oldest backup data.
           </para>
         </listitem>

@@ -1075,6 +1088,8 @@
 
     </section>
 
+<!-- JDR: really should have this section much later, so it doesn't come before the mysqlbackup instructions. -->
+
     <section remap="h2" id="backup.myisam">
 
       <title>Making a Point-in-Time Backup of Both InnoDB and MyISAM Tables</title>

@@ -1082,7 +1097,7 @@
       <note>
         <para>
           This section describes low-level backup techniques that are
-          only applicable for expert users. You can use the
+          intended for expert users. You can use the
           <literal>&hlbackup;</literal> command to automate the
           procedure presented in this section, as described in
           <xref linkend="mysqlbackup"/>.

@@ -1095,12 +1110,12 @@
         backup of both MyISAM and InnoDB tables. This option pauses the
         backup process when an <literal>&llbackup;</literal> run is
         close to ending, so that a script written by you can copy the
-        MyISAM tables to a backup. Since the backup taken by
-        <literal>&llbackup;</literal> corresponds to the time at the end
-        of the run, and your script will block modifications to the
-        MyISAM tables at that point, the backup contains a snapshot of
-        MyISAM tables at the same point in time. Your script must follow
-        this outline:
+        MyISAM tables and other non-InnoDB files to a backup. Since the
+        backup taken by <literal>&llbackup;</literal> corresponds to the
+        time at the end of the run, and your script blocks modifications
+        to the MyISAM tables at that point, the backup contains a
+        snapshot of MyISAM tables at the same point in time. Your script
+        must follow this outline:
       </para>
 
       <itemizedlist>

@@ -1169,6 +1184,8 @@
 
     <title>Preparing the Backup to be Restored</title>
 
+<!-- JDR: cf. "raw backup", "prepared backup". -->
+
     <para>
       The initial backup files might not be in a consistent state,
       because data could be changed while the backup is running. The

@@ -1188,7 +1205,7 @@
 
     <para>
       The option for applying the log is <literal>--apply-log</literal>.
-      In the old InnoDB Hot Backup Product, this option was called
+      In the prior InnoDB Hot Backup Product, this option was called
       <literal>--restore</literal>, but that option was renamed because
       it prepares the data to be restored, rather than actually
       restoring it.

@@ -1210,7 +1227,7 @@
 
       <para>
         The backup directory looks like this before applying the log to
-        the backup.
+        the backup:
       </para>
 
 <programlisting id="example-3.1a">

@@ -1293,7 +1310,7 @@
       </para>
 
       <para>
-        If the backup is compressed, give the
+        If the backup is compressed, specify the
         <literal>--uncompress</literal> option to
         <literal>&llbackup;</literal> when applying the log to the
         backup:

@@ -1378,6 +1395,8 @@
         <xref linkend="backup.incremental"/>.
       </para>
 
+<!-- JDR: cf. "raw backup", "prepared backup". -->
+
       <para>
         After you take an incremental backup, the changes reflected in
         those backup files must be applied to a full backup to bring the

@@ -1470,6 +1489,8 @@
 101004 13:02:41  ibbackup: Incremental backup applied successfully!
 </programlisting>
 
+<!-- JDR: clarify "that are labelled as". -->
+
       <para>
         Now the data files that are labelled as the full backup are
         fully up-to-date, as of the time of the incremental backup:

@@ -1507,10 +1528,12 @@
 
       <para>
         After applying the log and creating the new
-        <literal>ib_logfile</literal>s we are ready to start
+        <literal>ib_logfile</literal>s, we are ready to start
         <literal>mysqld</literal> on our backup database.
       </para>
 
+<!-- JDR: don't understand "by the user or automatically..." in the last sentence. -->
+
       <para>
         The backup database directory looks like this before we start
         <literal>mysqld</literal>. Note that the backup directory

@@ -1573,6 +1596,8 @@
         database and ready to serve clients.
       </para>
 
+<!-- JDR: is there another step where you use the binlog position for more rolling forward? -->
+
       <para>
         If you originally took the backup from a MySQL replication
         slave, then mysqld also prints the

@@ -2069,7 +2094,7 @@
             completed successfully, either by verifying that the
             <literal>&hlbackup;</literal> command returned exit code 0,
             or by observing that <literal>&hlbackup;</literal> has
-            printed the text &quot;innobackup completed OK!&quot;.
+            printed the text <quote>innobackup completed OK!</quote>.
           </para>
         </listitem>
 


Thread
svn commit - mysqldoc@docsrva: r23210 - trunk/mysql-enterprise-backup-3.5john.russell19 Oct