hgbook

changeset 684:a66f6d499afa

Add paragraph IDs
author Bryan O'Sullivan <bos@serpentine.com>
date Fri Apr 24 00:27:21 2009 -0700 (2009-04-24)
parents 1a0a78e197c3
children 6b7818eb3d8e
files en/ch04-daily.xml en/ch11-mq.xml
line diff
     1.1 --- a/en/ch04-daily.xml	Fri Apr 24 00:27:05 2009 -0700
     1.2 +++ b/en/ch04-daily.xml	Fri Apr 24 00:27:21 2009 -0700
     1.3 @@ -677,17 +677,17 @@
     1.4    <sect1>
     1.5      <title>More useful diffs</title>
     1.6  
     1.7 -    <para>The default output of the <command role="hg-cmd">hg
     1.8 +    <para id="x_6c7">The default output of the <command role="hg-cmd">hg
     1.9  	diff</command> command is backwards compatible with the
    1.10        regular <command>diff</command> command, but this has some
    1.11        drawbacks.</para>
    1.12  
    1.13 -    <para>Consider the case where we use <command role="hg-cmd">hg
    1.14 +    <para id="x_6c8">Consider the case where we use <command role="hg-cmd">hg
    1.15  	rename</command> to rename a file.</para>
    1.16  
    1.17      &interaction.ch04-diff.rename.basic;
    1.18  
    1.19 -    <para>The output of <command role="hg-cmd">hg diff</command> above
    1.20 +    <para id="x_6c9">The output of <command role="hg-cmd">hg diff</command> above
    1.21        obscures the fact that we simply renamed a file.  The <command
    1.22  	role="hg-cmd">hg diff</command> command accepts an option,
    1.23        <option>--git</option> or <option>-g</option>, to use a newer
    1.24 @@ -696,7 +696,7 @@
    1.25  
    1.26      &interaction.ch04-diff.rename.git;
    1.27  
    1.28 -    <para>This option also helps with a case that can otherwise be
    1.29 +    <para id="x_6ca">This option also helps with a case that can otherwise be
    1.30        confusing: a file that appears to be modified according to
    1.31        <command role="hg-cmd">hg status</command>, but for which
    1.32        <command role="hg-cmd">hg diff</command> prints nothing. This
    1.33 @@ -705,7 +705,7 @@
    1.34  
    1.35      &interaction.ch04-diff.chmod;
    1.36  
    1.37 -    <para>The normal <command>diff</command> command pays no attention
    1.38 +    <para id="x_6cb">The normal <command>diff</command> command pays no attention
    1.39        to file permissions, which is why <command role="hg-cmd">hg
    1.40  	diff</command> prints nothing by default.  If we supply it
    1.41        with the <option>-g</option> option, it tells us what really
    1.42 @@ -717,28 +717,28 @@
    1.43    <sect1>
    1.44      <title>Which files to manage, and which to avoid</title>
    1.45  
    1.46 -    <para>Revision control systems are generally best at managing text
    1.47 +    <para id="x_6cc">Revision control systems are generally best at managing text
    1.48        files that are written by humans, such as source code, where the
    1.49        files do not change much from one revision to the next.  Some
    1.50        centralized revision control systems can also deal tolerably
    1.51        well with binary files, such as bitmap images.</para>
    1.52  
    1.53 -    <para>For instance, a game development team will typically manage
    1.54 +    <para id="x_6cd">For instance, a game development team will typically manage
    1.55        both its source code and all of its binary assets (e.g. geometry
    1.56        data, textures, map layouts) in a revision control
    1.57        system.</para>
    1.58  
    1.59 -    <para>Because it is usually impossible to merge two conflicting
    1.60 +    <para id="x_6ce">Because it is usually impossible to merge two conflicting
    1.61        modifications to a binary file, centralized systems often
    1.62        provide a file locking mechanism that allow a user to say
    1.63        <quote>I am the only person who can edit this
    1.64  	file</quote>.</para>
    1.65  
    1.66 -    <para>Compared to a centralized system, a distributed revision
    1.67 +    <para id="x_6cf">Compared to a centralized system, a distributed revision
    1.68        control system changes some of the factors that guide decisions
    1.69        over which files to manage and how.</para>
    1.70  
    1.71 -    <para>For instance, a distributed revision control system cannot,
    1.72 +    <para id="x_6d0">For instance, a distributed revision control system cannot,
    1.73        by its nature, offer a file locking facility.  There is thus no
    1.74        built-in mechanism to prevent two people from making conflicting
    1.75        changes to a binary file.  If you have a team where several
    1.76 @@ -746,7 +746,7 @@
    1.77        good idea to use Mercurial&emdash;or any other distributed
    1.78        revision control system&emdash;to manage those files.</para>
    1.79  
    1.80 -    <para>When storing modifications to a file, Mercurial usually
    1.81 +    <para id="x_6d1">When storing modifications to a file, Mercurial usually
    1.82        saves only the differences between the previous and current
    1.83        versions of the file.  For most text files, this is extremely
    1.84        efficient. However, some files (particularly binary files) are
    1.85 @@ -759,7 +759,7 @@
    1.86        affect both local storage needs and the amount of time it takes
    1.87        to clone a repository.</para>
    1.88  
    1.89 -    <para>To get an idea of how this could affect you in practice,
    1.90 +    <para id="x_6d2">To get an idea of how this could affect you in practice,
    1.91        suppose you want to use Mercurial to manage an OpenOffice
    1.92        document.  OpenOffice stores documents on disk as compressed zip
    1.93        files. Edit even a single letter of your document in OpenOffice,
    1.94 @@ -772,22 +772,22 @@
    1.95        to Mercurial's storage assumptions can easily have an outsized
    1.96        effect on the size of the repository.</para>
    1.97  
    1.98 -    <para>Even worse, if both you and someone else edit the OpenOffice
    1.99 +    <para id="x_6d3">Even worse, if both you and someone else edit the OpenOffice
   1.100        document you're working on, there is no useful way to merge your
   1.101        work. In fact, there isn't even a good way to tell what the
   1.102        differences are between your respective changes.</para>
   1.103  
   1.104 -    <para>There are thus a few clear recommendations about specific
   1.105 +    <para id="x_6d4">There are thus a few clear recommendations about specific
   1.106        kinds of files to be very careful with.</para>
   1.107  
   1.108      <itemizedlist>
   1.109        <listitem>
   1.110 -	<para>Files that are very large and incompressible, e.g. ISO
   1.111 +	<para id="x_6d5">Files that are very large and incompressible, e.g. ISO
   1.112  	  CD-ROM images, will by virtue of sheer size make clones over
   1.113  	  a network very slow.</para>
   1.114        </listitem>
   1.115        <listitem>
   1.116 -	<para>Files that change a lot from one revision to the next
   1.117 +	<para id="x_6d6">Files that change a lot from one revision to the next
   1.118  	  may be expensive to store if you edit them frequently, and
   1.119  	  conflicts due to concurrent edits may be difficult to
   1.120  	  resolve.</para>
   1.121 @@ -798,7 +798,7 @@
   1.122    <sect1>
   1.123      <title>Backups and mirroring</title>
   1.124  
   1.125 -    <para>Since Mercurial maintains a complete copy of history in each
   1.126 +    <para id="x_6d7">Since Mercurial maintains a complete copy of history in each
   1.127        clone, everyone who uses Mercurial to collaborate on a project
   1.128        can potentially act as a source of backups in the event of a
   1.129        catastrophe.  If a central repository becomes unavailable, you
   1.130 @@ -806,7 +806,7 @@
   1.131        repository from one contributor, and pulling any changes they
   1.132        may not have seen from others.</para>
   1.133  
   1.134 -    <para>It is simple to use Mercurial to perform off-site backups
   1.135 +    <para id="x_6d8">It is simple to use Mercurial to perform off-site backups
   1.136        and remote mirrors.  Set up a periodic job (e.g. via the
   1.137        <command>cron</command> command) on a remote server to pull
   1.138        changes from your master repositories every hour.  This will
   1.139 @@ -815,7 +815,7 @@
   1.140        you'll need to do a little scripting to refresh the list of
   1.141        repositories to back up.</para>
   1.142  
   1.143 -    <para>If you perform traditional backups of your master
   1.144 +    <para id="x_6d9">If you perform traditional backups of your master
   1.145        repositories to tape or disk, and you want to back up a
   1.146        repository named <filename>myrepo</filename>.  Use <command>hg
   1.147  	clone -U myrepo myrepo.bak</command> to create a
   1.148 @@ -824,7 +824,7 @@
   1.149        working directory after the clone completes, since that would be
   1.150        superfluous and make the backup take longer.
   1.151  
   1.152 -    <para>If you then back up <filename>myrepo.bak</filename> instead
   1.153 +    <para id="x_6da">If you then back up <filename>myrepo.bak</filename> instead
   1.154        of <filename>myrepo</filename>, you will be guaranteed to have a
   1.155        consistent snapshot of your repository that won't be pushed to
   1.156        by an insomniac developer in mid-backup.</para>
     2.1 --- a/en/ch11-mq.xml	Fri Apr 24 00:27:05 2009 -0700
     2.2 +++ b/en/ch11-mq.xml	Fri Apr 24 00:27:21 2009 -0700
     2.3 @@ -748,13 +748,13 @@
     2.4    <sect1>
     2.5      <title>More on patch management</title>
     2.6  
     2.7 -    <para>As you grow familiar with MQ, you will find yourself wanting
     2.8 +    <para id="x_6db">As you grow familiar with MQ, you will find yourself wanting
     2.9        to perform other kinds of patch management operations.</para>
    2.10  
    2.11      <sect2>
    2.12        <title>Deleting unwanted patches</title>
    2.13  
    2.14 -      <para>If you want to get rid of a patch, use the <command
    2.15 +      <para id="x_6dc">If you want to get rid of a patch, use the <command
    2.16  	  role="hg-ext-mq">hg qdelete</command> command to delete the
    2.17  	patch file and remove its entry from the patch series.  If you
    2.18  	try to delete a patch that is still applied, <command
    2.19 @@ -766,7 +766,7 @@
    2.20      <sect2>
    2.21        <title>Converting to and from permanent revisions</title>
    2.22  
    2.23 -      <para>Once you're done working on a patch and want to turn it
    2.24 +      <para id="x_6dd">Once you're done working on a patch and want to turn it
    2.25  	into a permanent changeset, use the <command
    2.26  	  role="hg-ext-mq">hg qdelete -r</command> command.  Pass a
    2.27  	revision to the <option>-r</option> option to identify the
    2.28 @@ -775,13 +775,13 @@
    2.29  
    2.30        &interaction.ch11-qdelete.convert;
    2.31  
    2.32 -      <para>It is also possible to turn an existing changeset into a
    2.33 +      <para id="x_6de">It is also possible to turn an existing changeset into a
    2.34  	patch, by passing the <option>-r</option> option to <command
    2.35  	  role="hg-ext-mq">hg qimport</command>.</para>
    2.36  
    2.37        &interaction.ch11-qdelete.import;
    2.38  
    2.39 -      <para>Note that it only makes sense to convert a changeset into
    2.40 +      <para id="x_6df">Note that it only makes sense to convert a changeset into
    2.41  	a patch if you have not propagated that changeset into any
    2.42  	other repositories.  The imported changeset's ID will change
    2.43  	every time you refresh the patch, which will make Mercurial