Mercurial > hgbook
annotate ja/preface.tex @ 290:b0db5adf11c1 ja_root
fork Japanese translation.
author | Yoshiki Yazawa <yaz@cc.rim.or.jp> |
---|---|
date | Wed, 06 Feb 2008 17:43:11 +0900 |
parents | en/preface.tex@9bba958be4c6 |
children | 3b1291f24c0d |
rev | line source |
---|---|
26 | 1 \chapter*{Preface} |
2 \addcontentsline{toc}{chapter}{Preface} | |
3 \label{chap:preface} | |
4 | |
5 Distributed revision control is a relatively new territory, and has | |
6 thus far grown due to people's willingness to strike out into | |
7 ill-charted territory. | |
8 | |
9 I am writing a book about distributed revision control because I | |
10 believe that it is an important subject that deserves a field guide. | |
11 I chose to write about Mercurial because it is the easiest tool to | |
12 learn the terrain with, and yet it scales to the demands of real, | |
13 challenging environments where many other revision control tools fail. | |
14 | |
15 \section{This book is a work in progress} | |
16 | |
17 I am releasing this book while I am still writing it, in the hope that | |
18 it will prove useful to others. I also hope that readers will | |
19 contribute as they see fit. | |
20 | |
200
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
21 \section{About the examples in this book} |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
22 |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
23 This book takes an unusual approach to code samples. Every example is |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
24 ``live''---each one is actually the result of a shell script that |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
25 executes the Mercurial commands you see. Every time an image of the |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
26 book is built from its sources, all the example scripts are |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
27 automatically run, and their current results compared against their |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
28 expected results. |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
29 |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
30 The advantage of this approach is that the examples are always |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
31 accurate; they describe \emph{exactly} the behaviour of the version of |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
32 Mercurial that's mentioned at the front of the book. If I update the |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
33 version of Mercurial that I'm documenting, and the output of some |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
34 command changes, the build fails. |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
35 |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
36 There is a small disadvantage to this approach, which is that the |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
37 dates and times you'll see in examples tend to be ``squashed'' |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
38 together in a way that they wouldn't be if the same commands were |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
39 being typed by a human. Where a human can issue no more than one |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
40 command every few seconds, with any resulting timestamps |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
41 correspondingly spread out, my automated example scripts run many |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
42 commands in one second. |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
43 |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
44 As an instance of this, several consecutive commits in an example can |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
45 show up as having occurred during the same second. You can see this |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
46 occur in the \hgext{bisect} example in section~\ref{sec:undo:bisect}, |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
47 for instance. |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
48 |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
49 So when you're reading examples, don't place too much weight on the |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
50 dates or times you see in the output of commands. But \emph{do} be |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
51 confident that the behaviour you're seeing is consistent and |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
52 reproducible. |
9bba958be4c6
Mention automatic example generation.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
53 |
26 | 54 \section{Colophon---this book is Free} |
55 | |
56 This book is licensed under the Open Publication License, and is | |
57 produced entirely using Free Software tools. It is typeset with | |
58 \LaTeX{}; illustrations are drawn and rendered with | |
59 \href{http://www.inkscape.org/}{Inkscape}. | |
60 | |
61 The complete source code for this book is published as a Mercurial | |
62 repository, at \url{http://hg.serpentine.com/mercurial/book}. | |
63 | |
64 %%% Local Variables: | |
65 %%% mode: latex | |
66 %%% TeX-master: "00book" | |
67 %%% End: |