1.1 --- a/en/appA-cmdref.xml	Thu Mar 12 15:51:39 2009 +0800
     1.2 +++ b/en/appA-cmdref.xml	Fri Mar 20 16:43:35 2009 +0800
     1.3 @@ -3,113 +3,113 @@
     1.4  <appendix id="cmdref">
     1.5  <title>Command reference</title>
     1.6  
     1.7 -<para>\cmdref{add}{add files at the next commit}
     1.8 +<para id="x_653">\cmdref{add}{add files at the next commit}
     1.9  \optref{add}{I}{include}
    1.10  \optref{add}{X}{exclude}
    1.11  \optref{add}{n}{dry-run}</para>
    1.12  
    1.13 -<para>\cmdref{diff}{print changes in history or working directory}</para>
    1.14 -
    1.15 -<para>Show differences between revisions for the specified files or
    1.16 +<para id="x_654">\cmdref{diff}{print changes in history or working directory}</para>
    1.17 +
    1.18 +<para id="x_655">Show differences between revisions for the specified files or
    1.19  directories, using the unified diff format.  For a description of the
    1.20  unified diff format, see section <xref linkend="sec.mq.patch"/>.</para>
    1.21  
    1.22 -<para>By default, this command does not print diffs for files that Mercurial
    1.23 +<para id="x_656">By default, this command does not print diffs for files that Mercurial
    1.24  considers to contain binary data.  To control this behaviour, see the
    1.25  <option role="hg-opt-diff">-a</option> and <option role="hg-opt-diff">--git</option> options.</para>
    1.26  
    1.27  <sect2>
    1.28  <title>Options</title>
    1.29  
    1.30 -<para>\loptref{diff}{nodates}</para>
    1.31 -
    1.32 -<para>Omit date and time information when printing diff headers.</para>
    1.33 -
    1.34 -<para>\optref{diff}{B}{ignore-blank-lines}</para>
    1.35 -
    1.36 -<para>Do not print changes that only insert or delete blank lines.  A line
    1.37 +<para id="x_657">\loptref{diff}{nodates}</para>
    1.38 +
    1.39 +<para id="x_658">Omit date and time information when printing diff headers.</para>
    1.40 +
    1.41 +<para id="x_659">\optref{diff}{B}{ignore-blank-lines}</para>
    1.42 +
    1.43 +<para id="x_65a">Do not print changes that only insert or delete blank lines.  A line
    1.44  that contains only whitespace is not considered blank.
    1.45  </para>
    1.46  
    1.47 -<para>\optref{diff}{I}{include}
    1.48 -</para>
    1.49 -
    1.50 -<para>Include files and directories whose names match the given patterns.
    1.51 -</para>
    1.52 -
    1.53 -<para>\optref{diff}{X}{exclude}
    1.54 -</para>
    1.55 -
    1.56 -<para>Exclude files and directories whose names match the given patterns.
    1.57 -</para>
    1.58 -
    1.59 -<para>\optref{diff}{a}{text}
    1.60 -</para>
    1.61 -
    1.62 -<para>If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print
    1.63 +<para id="x_65b">\optref{diff}{I}{include}
    1.64 +</para>
    1.65 +
    1.66 +<para id="x_65c">Include files and directories whose names match the given patterns.
    1.67 +</para>
    1.68 +
    1.69 +<para id="x_65d">\optref{diff}{X}{exclude}
    1.70 +</para>
    1.71 +
    1.72 +<para id="x_65e">Exclude files and directories whose names match the given patterns.
    1.73 +</para>
    1.74 +
    1.75 +<para id="x_65f">\optref{diff}{a}{text}
    1.76 +</para>
    1.77 +
    1.78 +<para id="x_660">If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print
    1.79  diffs for files that it detects as binary. Specifying <option role="hg-opt-diff">-a</option>
    1.80  forces <command role="hg-cmd">hg diff</command> to treat all files as text, and generate diffs for
    1.81  all of them.
    1.82  </para>
    1.83  
    1.84 -<para>This option is useful for files that are <quote>mostly text</quote> but have a
    1.85 +<para id="x_661">This option is useful for files that are <quote>mostly text</quote> but have a
    1.86  few embedded NUL characters.  If you use it on files that contain a
    1.87  lot of binary data, its output will be incomprehensible.
    1.88  </para>
    1.89  
    1.90 -<para>\optref{diff}{b}{ignore-space-change}
    1.91 -</para>
    1.92 -
    1.93 -<para>Do not print a line if the only change to that line is in the amount
    1.94 +<para id="x_662">\optref{diff}{b}{ignore-space-change}
    1.95 +</para>
    1.96 +
    1.97 +<para id="x_663">Do not print a line if the only change to that line is in the amount
    1.98  of white space it contains.
    1.99  </para>
   1.100  
   1.101 -<para>\optref{diff}{g}{git}
   1.102 -</para>
   1.103 -
   1.104 -<para>Print <command>git</command>-compatible diffs.  XXX reference a format
   1.105 +<para id="x_664">\optref{diff}{g}{git}
   1.106 +</para>
   1.107 +
   1.108 +<para id="x_665">Print <command>git</command>-compatible diffs.  XXX reference a format
   1.109  description.
   1.110  </para>
   1.111  
   1.112 -<para>\optref{diff}{p}{show-function}
   1.113 -</para>
   1.114 -
   1.115 -<para>Display the name of the enclosing function in a hunk header, using a
   1.116 +<para id="x_666">\optref{diff}{p}{show-function}
   1.117 +</para>
   1.118 +
   1.119 +<para id="x_667">Display the name of the enclosing function in a hunk header, using a
   1.120  simple heuristic.  This functionality is enabled by default, so the
   1.121  <option role="hg-opt-diff">-p</option> option has no effect unless you change the value of
   1.122  the <envar role="rc-item-diff">showfunc</envar> config item, as in the following example.</para>
   1.123  
   1.124  <!-- &interaction.cmdref.diff-p; -->
   1.125  
   1.126 -<para>\optref{diff}{r}{rev}
   1.127 -</para>
   1.128 -
   1.129 -<para>Specify one or more revisions to compare.  The <command role="hg-cmd">hg diff</command> command
   1.130 +<para id="x_668">\optref{diff}{r}{rev}
   1.131 +</para>
   1.132 +
   1.133 +<para id="x_669">Specify one or more revisions to compare.  The <command role="hg-cmd">hg diff</command> command
   1.134  accepts up to two <option role="hg-opt-diff">-r</option> options to specify the revisions to
   1.135  compare.
   1.136  </para>
   1.137  
   1.138  <orderedlist>
   1.139 -<listitem><para>Display the differences between the parent revision of the
   1.140 +<listitem><para id="x_66a">Display the differences between the parent revision of the
   1.141    working directory and the working directory.
   1.142  </para>
   1.143  </listitem>
   1.144 -<listitem><para>Display the differences between the specified changeset and the
   1.145 +<listitem><para id="x_66b">Display the differences between the specified changeset and the
   1.146    working directory.
   1.147  </para>
   1.148  </listitem>
   1.149 -<listitem><para>Display the differences between the two specified changesets.
   1.150 +<listitem><para id="x_66c">Display the differences between the two specified changesets.
   1.151  </para>
   1.152  </listitem></orderedlist>
   1.153  
   1.154 -<para>You can specify two revisions using either two <option role="hg-opt-diff">-r</option>
   1.155 +<para id="x_66d">You can specify two revisions using either two <option role="hg-opt-diff">-r</option>
   1.156  options or revision range notation.  For example, the two revision
   1.157  specifications below are equivalent.
   1.158  </para>
   1.159  <programlisting>hg diff -r 10 -r 20
   1.160  hg diff -r10:20</programlisting>
   1.161  
   1.162 -<para>When you provide two revisions, Mercurial treats the order of those
   1.163 +<para id="x_66e">When you provide two revisions, Mercurial treats the order of those
   1.164  revisions as significant.  Thus, <command role="hg-cmd">hg diff -r10:20</command> will
   1.165  produce a diff that will transform files from their contents as of
   1.166  revision 10 to their contents as of revision 20, while
   1.167 @@ -119,23 +119,23 @@
   1.168  diffing against the working directory.
   1.169  </para>
   1.170  
   1.171 -<para>\optref{diff}{w}{ignore-all-space}
   1.172 -</para>
   1.173 -
   1.174 -<para>\cmdref{version}{print version and copyright information}
   1.175 -</para>
   1.176 -
   1.177 -<para>This command displays the version of Mercurial you are running, and
   1.178 +<para id="x_66f">\optref{diff}{w}{ignore-all-space}
   1.179 +</para>
   1.180 +
   1.181 +<para id="x_670">\cmdref{version}{print version and copyright information}
   1.182 +</para>
   1.183 +
   1.184 +<para id="x_671">This command displays the version of Mercurial you are running, and
   1.185  its copyright license.  There are four kinds of version string that
   1.186  you may see.
   1.187  </para>
   1.188  <itemizedlist>
   1.189 -<listitem><para>The string <quote><literal>unknown</literal></quote>. This version of Mercurial was
   1.190 +<listitem><para id="x_672">The string <quote><literal>unknown</literal></quote>. This version of Mercurial was
   1.191    not built in a Mercurial repository, and cannot determine its own
   1.192    version.
   1.193  </para>
   1.194  </listitem>
   1.195 -<listitem><para>A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a
   1.196 +<listitem><para id="x_673">A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a
   1.197    build of a revision of Mercurial that was identified by a specific
   1.198    tag in the repository where it was built.  (This doesn't necessarily
   1.199    mean that you're running an official release; someone else could
   1.200 @@ -143,11 +143,11 @@
   1.201    built Mercurial.)
   1.202  </para>
   1.203  </listitem>
   1.204 -<listitem><para>A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>.  This
   1.205 +<listitem><para id="x_674">A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>.  This
   1.206    is a build of the given revision of Mercurial.
   1.207  </para>
   1.208  </listitem>
   1.209 -<listitem><para>A hexadecimal string followed by a date, such as
   1.210 +<listitem><para id="x_675">A hexadecimal string followed by a date, such as
   1.211    <quote><literal>875489e31abe+20070205</literal></quote>.  This is a build of the given
   1.212    revision of Mercurial, where the build repository contained some
   1.213    local changes that had not been committed.
   1.214 @@ -161,14 +161,14 @@
   1.215  <sect3 id="cmdref.diff-vs-status">
   1.216  <title>Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ?</title>
   1.217  
   1.218 -<para>When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files
   1.219 +<para id="x_676">When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files
   1.220  that Mercurial will record changes for the next time you perform a
   1.221  commit.  If you run the <command role="hg-cmd">hg diff</command> command, you may notice that it
   1.222  prints diffs for only a <emphasis>subset</emphasis> of the files that <command role="hg-cmd">hg status</command>
   1.223  listed.  There are two possible reasons for this.
   1.224  </para>
   1.225  
   1.226 -<para>The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications
   1.227 +<para id="x_677">The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications
   1.228  that <command role="hg-cmd">hg diff</command> doesn't normally display.  The <command role="hg-cmd">hg diff</command> command
   1.229  normally outputs unified diffs, which don't have the ability to
   1.230  represent some changes that Mercurial can track.  Most notably,
   1.231 @@ -176,12 +176,12 @@
   1.232  executable, but Mercurial records this information.
   1.233  </para>
   1.234  
   1.235 -<para>If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will
   1.236 +<para id="x_678">If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will
   1.237  display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this
   1.238  extra information.
   1.239  </para>
   1.240  
   1.241 -<para>The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs
   1.242 +<para id="x_679">The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs
   1.243  for a subset of the files displayed by <command role="hg-cmd">hg status</command> is that if you
   1.244  invoke it without any arguments, <command role="hg-cmd">hg diff</command> prints diffs against the
   1.245  first parent of the working directory.  If you have run <command role="hg-cmd">hg merge</command>
   1.246 @@ -199,14 +199,14 @@
   1.247  <sect3>
   1.248  <title>Generating safe binary diffs</title>
   1.249  
   1.250 -<para>If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print
   1.251 +<para id="x_67a">If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print
   1.252  diffs of files that are either <quote>mostly text</quote> or contain lots of
   1.253  binary data, those diffs cannot subsequently be applied by either
   1.254  Mercurial's <command role="hg-cmd">hg import</command> command or the system's <command>patch</command>
   1.255  command.
   1.256  </para>
   1.257  
   1.258 -<para>If you want to generate a diff of a binary file that is safe to use as
   1.259 +<para id="x_67b">If you want to generate a diff of a binary file that is safe to use as
   1.260  input for <command role="hg-cmd">hg import</command>, use the <command role="hg-cmd">hg diff</command>{--git} option when you
   1.261  generate the patch.  The system <command>patch</command> command cannot handle
   1.262  binary patches at all.