1.1 --- a/en/ch06-filenames.xml	Thu Mar 19 20:54:12 2009 -0700
     1.2 +++ b/en/ch06-filenames.xml	Thu Mar 26 23:05:28 2009 -0700
     1.3 @@ -4,22 +4,22 @@
     1.4    <?dbhtml filename="file-names-and-pattern-matching.html"?>
     1.5    <title>File names and pattern matching</title>
     1.6  
     1.7 -  <para>Mercurial provides mechanisms that let you work with file
     1.8 +  <para id="x_543">Mercurial provides mechanisms that let you work with file
     1.9      names in a consistent and expressive way.</para>
    1.10  
    1.11    <sect1>
    1.12      <title>Simple file naming</title>
    1.13  
    1.14 -    <para>Mercurial uses a unified piece of machinery <quote>under the
    1.15 +    <para id="x_544">Mercurial uses a unified piece of machinery <quote>under the
    1.16  	hood</quote> to handle file names.  Every command behaves
    1.17        uniformly with respect to file names.  The way in which commands
    1.18        work with file names is as follows.</para>
    1.19  
    1.20 -    <para>If you explicitly name real files on the command line,
    1.21 +    <para id="x_545">If you explicitly name real files on the command line,
    1.22        Mercurial works with exactly those files, as you would expect.
    1.23        &interaction.filenames.files;</para>
    1.24  
    1.25 -    <para>When you provide a directory name, Mercurial will interpret
    1.26 +    <para id="x_546">When you provide a directory name, Mercurial will interpret
    1.27        this as <quote>operate on every file in this directory and its
    1.28  	subdirectories</quote>. Mercurial traverses the files and
    1.29        subdirectories in a directory in alphabetical order.  When it
    1.30 @@ -32,18 +32,18 @@
    1.31    <sect1>
    1.32      <title>Running commands without any file names</title>
    1.33  
    1.34 -    <para>Mercurial's commands that work with file names have useful
    1.35 +    <para id="x_547">Mercurial's commands that work with file names have useful
    1.36        default behaviours when you invoke them without providing any
    1.37        file names or patterns.  What kind of behaviour you should
    1.38        expect depends on what the command does.  Here are a few rules
    1.39        of thumb you can use to predict what a command is likely to do
    1.40        if you don't give it any names to work with.</para>
    1.41      <itemizedlist>
    1.42 -      <listitem><para>Most commands will operate on the entire working
    1.43 +      <listitem><para id="x_548">Most commands will operate on the entire working
    1.44  	  directory. This is what the <command role="hg-cmd">hg
    1.45  	    add</command> command does, for example.</para>
    1.46        </listitem>
    1.47 -      <listitem><para>If the command has effects that are difficult or
    1.48 +      <listitem><para id="x_549">If the command has effects that are difficult or
    1.49  	  impossible to reverse, it will force you to explicitly
    1.50  	  provide at least one name or pattern (see below).  This
    1.51  	  protects you from accidentally deleting files by running
    1.52 @@ -51,7 +51,7 @@
    1.53  	  arguments, for example.</para>
    1.54        </listitem></itemizedlist>
    1.55  
    1.56 -    <para>It's easy to work around these default behaviours if they
    1.57 +    <para id="x_54a">It's easy to work around these default behaviours if they
    1.58        don't suit you.  If a command normally operates on the whole
    1.59        working directory, you can invoke it on just the current
    1.60        directory and its subdirectories by giving it the name
    1.61 @@ -59,7 +59,7 @@
    1.62  
    1.63      &interaction.filenames.wdir-subdir;
    1.64  
    1.65 -    <para>Along the same lines, some commands normally print file
    1.66 +    <para id="x_54b">Along the same lines, some commands normally print file
    1.67        names relative to the root of the repository, even if you're
    1.68        invoking them from a subdirectory.  Such a command will print
    1.69        file names relative to your subdirectory if you give it explicit
    1.70 @@ -75,21 +75,21 @@
    1.71    <sect1>
    1.72      <title>Telling you what's going on</title>
    1.73  
    1.74 -    <para>The <command role="hg-cmd">hg add</command> example in the
    1.75 +    <para id="x_54c">The <command role="hg-cmd">hg add</command> example in the
    1.76        preceding section illustrates something else that's helpful
    1.77        about Mercurial commands.  If a command operates on a file that
    1.78        you didn't name explicitly on the command line, it will usually
    1.79        print the name of the file, so that you will not be surprised
    1.80        what's going on.</para>
    1.81  
    1.82 -    <para>The principle here is of <emphasis>least
    1.83 +    <para id="x_54d">The principle here is of <emphasis>least
    1.84  	surprise</emphasis>.  If you've exactly named a file on the
    1.85        command line, there's no point in repeating it back at you.  If
    1.86        Mercurial is acting on a file <emphasis>implicitly</emphasis>,
    1.87        because you provided no names, or a directory, or a pattern (see
    1.88        below), it's safest to tell you what it's doing.</para>
    1.89  
    1.90 -    <para>For commands that behave this way, you can silence them
    1.91 +    <para id="x_54e">For commands that behave this way, you can silence them
    1.92        using the <option role="hg-opt-global">-q</option> option.  You
    1.93        can also get them to print the name of every file, even those
    1.94        you've named explicitly, using the <option
    1.95 @@ -99,39 +99,39 @@
    1.96    <sect1>
    1.97      <title>Using patterns to identify files</title>
    1.98  
    1.99 -    <para>In addition to working with file and directory names,
   1.100 +    <para id="x_54f">In addition to working with file and directory names,
   1.101        Mercurial lets you use <emphasis>patterns</emphasis> to identify
   1.102        files.  Mercurial's pattern handling is expressive.</para>
   1.103  
   1.104 -    <para>On Unix-like systems (Linux, MacOS, etc.), the job of
   1.105 +    <para id="x_550">On Unix-like systems (Linux, MacOS, etc.), the job of
   1.106        matching file names to patterns normally falls to the shell.  On
   1.107        these systems, you must explicitly tell Mercurial that a name is
   1.108        a pattern.  On Windows, the shell does not expand patterns, so
   1.109        Mercurial will automatically identify names that are patterns,
   1.110        and expand them for you.</para>
   1.111  
   1.112 -    <para>To provide a pattern in place of a regular name on the
   1.113 +    <para id="x_551">To provide a pattern in place of a regular name on the
   1.114        command line, the mechanism is simple:</para>
   1.115      <programlisting>syntax:patternbody</programlisting>
   1.116 -    <para>That is, a pattern is identified by a short text string that
   1.117 +    <para id="x_552">That is, a pattern is identified by a short text string that
   1.118        says what kind of pattern this is, followed by a colon, followed
   1.119        by the actual pattern.</para>
   1.120  
   1.121 -    <para>Mercurial supports two kinds of pattern syntax.  The most
   1.122 +    <para id="x_553">Mercurial supports two kinds of pattern syntax.  The most
   1.123        frequently used is called <literal>glob</literal>; this is the
   1.124        same kind of pattern matching used by the Unix shell, and should
   1.125        be familiar to Windows command prompt users, too.</para>
   1.126  
   1.127 -    <para>When Mercurial does automatic pattern matching on Windows,
   1.128 +    <para id="x_554">When Mercurial does automatic pattern matching on Windows,
   1.129        it uses <literal>glob</literal> syntax.  You can thus omit the
   1.130        <quote><literal>glob:</literal></quote> prefix on Windows, but
   1.131        it's safe to use it, too.</para>
   1.132  
   1.133 -    <para>The <literal>re</literal> syntax is more powerful; it lets
   1.134 +    <para id="x_555">The <literal>re</literal> syntax is more powerful; it lets
   1.135        you specify patterns using regular expressions, also known as
   1.136        regexps.</para>
   1.137  
   1.138 -    <para>By the way, in the examples that follow, notice that I'm
   1.139 +    <para id="x_556">By the way, in the examples that follow, notice that I'm
   1.140        careful to wrap all of my patterns in quote characters, so that
   1.141        they won't get expanded by the shell before Mercurial sees
   1.142        them.</para>
   1.143 @@ -139,27 +139,27 @@
   1.144      <sect2>
   1.145        <title>Shell-style <literal>glob</literal> patterns</title>
   1.146  
   1.147 -      <para>This is an overview of the kinds of patterns you can use
   1.148 +      <para id="x_557">This is an overview of the kinds of patterns you can use
   1.149  	when you're matching on glob patterns.</para>
   1.150  
   1.151 -      <para>The <quote><literal>*</literal></quote> character matches
   1.152 +      <para id="x_558">The <quote><literal>*</literal></quote> character matches
   1.153  	any string, within a single directory.</para>
   1.154  
   1.155        &interaction.filenames.glob.star;
   1.156  
   1.157 -      <para>The <quote><literal>**</literal></quote> pattern matches
   1.158 +      <para id="x_559">The <quote><literal>**</literal></quote> pattern matches
   1.159  	any string, and crosses directory boundaries.  It's not a
   1.160  	standard Unix glob token, but it's accepted by several popular
   1.161  	Unix shells, and is very useful.</para>
   1.162  
   1.163        &interaction.filenames.glob.starstar;
   1.164  
   1.165 -      <para>The <quote><literal>?</literal></quote> pattern matches
   1.166 +      <para id="x_55a">The <quote><literal>?</literal></quote> pattern matches
   1.167  	any single character.</para>
   1.168  
   1.169        &interaction.filenames.glob.question;
   1.170  
   1.171 -      <para>The <quote><literal>[</literal></quote> character begins a
   1.172 +      <para id="x_55b">The <quote><literal>[</literal></quote> character begins a
   1.173  	<emphasis>character class</emphasis>.  This matches any single
   1.174  	character within the class.  The class ends with a
   1.175  	<quote><literal>]</literal></quote> character.  A class may
   1.176 @@ -169,13 +169,13 @@
   1.177  
   1.178  	&interaction.filenames.glob.range;
   1.179  
   1.180 -      <para>If the first character after the
   1.181 +      <para id="x_55c">If the first character after the
   1.182  	<quote><literal>[</literal></quote> in a character class is a
   1.183  	<quote><literal>!</literal></quote>, it
   1.184  	<emphasis>negates</emphasis> the class, making it match any
   1.185  	single character not in the class.</para>
   1.186  
   1.187 -      <para>A <quote><literal>{</literal></quote> begins a group of
   1.188 +      <para id="x_55d">A <quote><literal>{</literal></quote> begins a group of
   1.189  	subpatterns, where the whole group matches if any subpattern
   1.190  	in the group matches.  The <quote><literal>,</literal></quote>
   1.191  	character separates subpatterns, and
   1.192 @@ -186,7 +186,7 @@
   1.193        <sect3>
   1.194  	<title>Watch out!</title>
   1.195  
   1.196 -	<para>Don't forget that if you want to match a pattern in any
   1.197 +	<para id="x_55e">Don't forget that if you want to match a pattern in any
   1.198  	  directory, you should not be using the
   1.199  	  <quote><literal>*</literal></quote> match-any token, as this
   1.200  	  will only match within one directory.  Instead, use the
   1.201 @@ -201,27 +201,27 @@
   1.202        <title>Regular expression matching with <literal>re</literal>
   1.203  	patterns</title>
   1.204  
   1.205 -      <para>Mercurial accepts the same regular expression syntax as
   1.206 +      <para id="x_55f">Mercurial accepts the same regular expression syntax as
   1.207  	the Python programming language (it uses Python's regexp
   1.208  	engine internally). This is based on the Perl language's
   1.209  	regexp syntax, which is the most popular dialect in use (it's
   1.210  	also used in Java, for example).</para>
   1.211  
   1.212 -      <para>I won't discuss Mercurial's regexp dialect in any detail
   1.213 +      <para id="x_560">I won't discuss Mercurial's regexp dialect in any detail
   1.214  	here, as regexps are not often used.  Perl-style regexps are
   1.215  	in any case already exhaustively documented on a multitude of
   1.216  	web sites, and in many books.  Instead, I will focus here on a
   1.217  	few things you should know if you find yourself needing to use
   1.218  	regexps with Mercurial.</para>
   1.219  
   1.220 -      <para>A regexp is matched against an entire file name, relative
   1.221 +      <para id="x_561">A regexp is matched against an entire file name, relative
   1.222  	to the root of the repository.  In other words, even if you're
   1.223  	already in subbdirectory <filename
   1.224  	  class="directory">foo</filename>, if you want to match files
   1.225  	under this directory, your pattern must start with
   1.226  	<quote><literal>foo/</literal></quote>.</para>
   1.227  
   1.228 -      <para>One thing to note, if you're familiar with Perl-style
   1.229 +      <para id="x_562">One thing to note, if you're familiar with Perl-style
   1.230  	regexps, is that Mercurial's are <emphasis>rooted</emphasis>.
   1.231  	That is, a regexp starts matching against the beginning of a
   1.232  	string; it doesn't look for a match anywhere within the
   1.233 @@ -233,35 +233,35 @@
   1.234    <sect1>
   1.235      <title>Filtering files</title>
   1.236  
   1.237 -    <para>Not only does Mercurial give you a variety of ways to
   1.238 +    <para id="x_563">Not only does Mercurial give you a variety of ways to
   1.239        specify files; it lets you further winnow those files using
   1.240        <emphasis>filters</emphasis>.  Commands that work with file
   1.241        names accept two filtering options.</para>
   1.242      <itemizedlist>
   1.243 -      <listitem><para><option role="hg-opt-global">-I</option>, or
   1.244 +      <listitem><para id="x_564"><option role="hg-opt-global">-I</option>, or
   1.245  	  <option role="hg-opt-global">--include</option>, lets you
   1.246  	  specify a pattern that file names must match in order to be
   1.247  	  processed.</para>
   1.248        </listitem>
   1.249 -      <listitem><para><option role="hg-opt-global">-X</option>, or
   1.250 +      <listitem><para id="x_565"><option role="hg-opt-global">-X</option>, or
   1.251  	  <option role="hg-opt-global">--exclude</option>, gives you a
   1.252  	  way to <emphasis>avoid</emphasis> processing files, if they
   1.253  	  match this pattern.</para>
   1.254        </listitem></itemizedlist>
   1.255 -    <para>You can provide multiple <option
   1.256 +    <para id="x_566">You can provide multiple <option
   1.257  	role="hg-opt-global">-I</option> and <option
   1.258  	role="hg-opt-global">-X</option> options on the command line,
   1.259        and intermix them as you please.  Mercurial interprets the
   1.260        patterns you provide using glob syntax by default (but you can
   1.261        use regexps if you need to).</para>
   1.262  
   1.263 -    <para>You can read a <option role="hg-opt-global">-I</option>
   1.264 +    <para id="x_567">You can read a <option role="hg-opt-global">-I</option>
   1.265        filter as <quote>process only the files that match this
   1.266  	filter</quote>.</para>
   1.267  
   1.268      &interaction.filenames.filter.include;
   1.269  
   1.270 -    <para>The <option role="hg-opt-global">-X</option> filter is best
   1.271 +    <para id="x_568">The <option role="hg-opt-global">-X</option> filter is best
   1.272        read as <quote>process only the files that don't match this
   1.273  	pattern</quote>.</para>
   1.274  
   1.275 @@ -271,13 +271,13 @@
   1.276    <sect1>
   1.277      <title>Ignoring unwanted files and directories</title>
   1.278  
   1.279 -    <para>XXX.</para>
   1.280 +    <para id="x_569">XXX.</para>
   1.281  
   1.282    </sect1>
   1.283    <sect1 id="sec:names:case">
   1.284      <title>Case sensitivity</title>
   1.285  
   1.286 -    <para>If you're working in a mixed development environment that
   1.287 +    <para id="x_56a">If you're working in a mixed development environment that
   1.288        contains both Linux (or other Unix) systems and Macs or Windows
   1.289        systems, you should keep in the back of your mind the knowledge
   1.290        that they treat the case (<quote>N</quote> versus
   1.291 @@ -286,17 +286,17 @@
   1.292        does, but it could surprise you if you don't know about
   1.293        it.</para>
   1.294  
   1.295 -    <para>Operating systems and filesystems differ in the way they
   1.296 +    <para id="x_56b">Operating systems and filesystems differ in the way they
   1.297        handle the <emphasis>case</emphasis> of characters in file and
   1.298        directory names.  There are three common ways to handle case in
   1.299        names.</para>
   1.300      <itemizedlist>
   1.301 -      <listitem><para>Completely case insensitive.  Uppercase and
   1.302 +      <listitem><para id="x_56c">Completely case insensitive.  Uppercase and
   1.303  	  lowercase versions of a letter are treated as identical,
   1.304  	  both when creating a file and during subsequent accesses.
   1.305  	  This is common on older DOS-based systems.</para>
   1.306        </listitem>
   1.307 -      <listitem><para>Case preserving, but insensitive.  When a file
   1.308 +      <listitem><para id="x_56d">Case preserving, but insensitive.  When a file
   1.309  	  or directory is created, the case of its name is stored, and
   1.310  	  can be retrieved and displayed by the operating system.
   1.311  	  When an existing file is being looked up, its case is
   1.312 @@ -307,13 +307,13 @@
   1.313  	  interchangeable is also referred to as <emphasis>case
   1.314  	    folding</emphasis>.</para>
   1.315        </listitem>
   1.316 -      <listitem><para>Case sensitive.  The case of a name is
   1.317 +      <listitem><para id="x_56e">Case sensitive.  The case of a name is
   1.318  	  significant at all times. The names <filename>foo</filename>
   1.319  	  and {FoO} identify different files.  This is the way Linux
   1.320  	  and Unix systems normally work.</para>
   1.321        </listitem></itemizedlist>
   1.322  
   1.323 -    <para>On Unix-like systems, it is possible to have any or all of
   1.324 +    <para id="x_56f">On Unix-like systems, it is possible to have any or all of
   1.325        the above ways of handling case in action at once.  For example,
   1.326        if you use a USB thumb drive formatted with a FAT32 filesystem
   1.327        on a Linux system, Linux will handle names on that filesystem in
   1.328 @@ -322,7 +322,7 @@
   1.329      <sect2>
   1.330        <title>Safe, portable repository storage</title>
   1.331  
   1.332 -      <para>Mercurial's repository storage mechanism is <emphasis>case
   1.333 +      <para id="x_570">Mercurial's repository storage mechanism is <emphasis>case
   1.334  	  safe</emphasis>.  It translates file names so that they can
   1.335  	be safely stored on both case sensitive and case insensitive
   1.336  	filesystems.  This means that you can use normal file copying
   1.337 @@ -335,13 +335,13 @@
   1.338      <sect2>
   1.339        <title>Detecting case conflicts</title>
   1.340  
   1.341 -      <para>When operating in the working directory, Mercurial honours
   1.342 +      <para id="x_571">When operating in the working directory, Mercurial honours
   1.343  	the naming policy of the filesystem where the working
   1.344  	directory is located.  If the filesystem is case preserving,
   1.345  	but insensitive, Mercurial will treat names that differ only
   1.346  	in case as the same.</para>
   1.347  
   1.348 -      <para>An important aspect of this approach is that it is
   1.349 +      <para id="x_572">An important aspect of this approach is that it is
   1.350  	possible to commit a changeset on a case sensitive (typically
   1.351  	Linux or Unix) filesystem that will cause trouble for users on
   1.352  	case insensitive (usually Windows and MacOS) users.  If a
   1.353 @@ -352,7 +352,7 @@
   1.354  	Linux users, they will be correctly represented as separate
   1.355  	files.</para>
   1.356  
   1.357 -      <para>If a Windows or Mac user pulls this change, they will not
   1.358 +      <para id="x_573">If a Windows or Mac user pulls this change, they will not
   1.359  	initially have a problem, because Mercurial's repository
   1.360  	storage mechanism is case safe.  However, once they try to
   1.361  	<command role="hg-cmd">hg update</command> the working
   1.362 @@ -366,14 +366,14 @@
   1.363      <sect2>
   1.364        <title>Fixing a case conflict</title>
   1.365  
   1.366 -      <para>If you are using Windows or a Mac in a mixed environment
   1.367 +      <para id="x_574">If you are using Windows or a Mac in a mixed environment
   1.368  	where some of your collaborators are using Linux or Unix, and
   1.369  	Mercurial reports a case folding conflict when you try to
   1.370  	<command role="hg-cmd">hg update</command> or <command
   1.371  	  role="hg-cmd">hg merge</command>, the procedure to fix the
   1.372  	problem is simple.</para>
   1.373  
   1.374 -      <para>Just find a nearby Linux or Unix box, clone the problem
   1.375 +      <para id="x_575">Just find a nearby Linux or Unix box, clone the problem
   1.376  	repository onto it, and use Mercurial's <command
   1.377  	  role="hg-cmd">hg rename</command> command to change the
   1.378  	names of any offending files or directories so that they will
   1.379 @@ -383,14 +383,14 @@
   1.380  	MacOS system, and <command role="hg-cmd">hg update</command>
   1.381  	to the revision with the non-conflicting names.</para>
   1.382  
   1.383 -      <para>The changeset with case-conflicting names will remain in
   1.384 +      <para id="x_576">The changeset with case-conflicting names will remain in
   1.385  	your project's history, and you still won't be able to
   1.386  	<command role="hg-cmd">hg update</command> your working
   1.387  	directory to that changeset on a Windows or MacOS system, but
   1.388  	you can continue development unimpeded.</para>
   1.389  
   1.390        <note>
   1.391 -	<para>  Prior to version 0.9.3, Mercurial did not use a case
   1.392 +	<para id="x_577">  Prior to version 0.9.3, Mercurial did not use a case
   1.393  	  safe repository storage mechanism, and did not detect case
   1.394  	  folding conflicts.  If you are using an older version of
   1.395  	  Mercurial on Windows or MacOS, I strongly recommend that you