edit intro

Author: ocha-

intro.textile

@@ -432,17 +432,20 @@ considered as "one set goal", but apparently it will not be useful for reading t
 actually. It will not be a trigger of any concrete action. Therefore, your first job will be to
 drag down the vague goal to the level of a concrete thing. 
 
-Then, what will the method be? Firstly, it's good if you pretend that you are the composer of
+Then how can we do it? The first way is thinking as if you are the person who wrote
 the program. You can utilize your knowledge in writing a program, in this case. For example,
 when you are reading a traditional "structured" programming by somebody, you will analyze it
 hiring the strategies of structured programming too. That is, you will divide the target into
-pieces, little by little. For another example, suppose you are reading a GUI program that walks
-around in an event loop, you can just start looking at the event loop before studying the roles
-of the event handlers. In another case, you will look up what "M" is for in MVC (Model View Controller). 
+pieces, little by little.
+If it is something circulating in a event loop such as a GUI program,
+first roughly browse the event loop then try to find out the role of each event
+handler. Or, try to investigate the "M" of MVC (Model View Controller) first.
 
-Secondly, keep in mind the methods of analysis. Everybody might have certain analysis methods,
-but they are often done based on experience and relying inspiration. It's crucially important
-to give it to the notion how to read source code well. 
+Second, it's good to be aware of the method to analyze.
+Everybody might have certain analysis methods,
+but they are often done relying on experience or intuition.
+In what way can we read source codes well?
+Thinking about the way itself and being aware of it are crucially important.
 
 Well, what are such methods like? I will explain it in the next section. 
 
@@ -464,20 +467,22 @@ should at least be closer to the fact than dynamic analysis.
 
 h3. Dynamic analysis
 
-h4. Use the target program
+h4. Using the target program
 
 You can't start without the target program. First of all, you need to know in advance what
 the program is like, and what are expected behaviors. 
 
-h4. Follow the behavior using the debugger
+h4. Following the behavior using the debugger
 
 If you want to see the paths of code execution and the data structure produced as a result,
 it's quicker to look at the result by running the program actually than to emulate the behavior
 in your brain. In order to do so easily, use the debugger. 
 
-However, there is not adequate tools unfortunately, especially in free software,
-that can generate the picture of the data structure at execution. A snapshot of the comparatively
-simpler structure may be obtained by converting text data obtained instantly into a picture using
+I would be more happy if the data structure at runtime can be seen as a picture,
+but unfortunately we can nearly scarcely find a tool for that purpose
+(especially few tools are available for free).
+If it is about a snapshot of the comparatively simpler structure,
+we might be able to write it out as a text and convert it to a picture by using a tool like
 graphviz\footnote{graphviz……See doc/graphviz.html in the attached CD-ROM}.
 But it's very difficult to find a way for general purpose and real time analysis. 
 
@@ -492,85 +497,96 @@ If you are watching the history of one variable, for example, it may be easier t
 to look at the dump of the result of the print statements embed, than to track the variable
 with a debugger.
 
-h4. Understanding code by modifying it
+h4. Modifying the code and running it
 
-Say for example, you do not understand some part of the code or a particular parameter,
-just make a small change and then re-run the program.
-By trying out small changes and seeing how they affect the code you will understand how it works.
+Say for example, in the place where it's not easy to understand its behavior,
+just make a small change in some part of the code or a particular parameter
+and then re-run the program.
+Naturally it would change the behavior, thus you would be able to infer the
+meaning of the code from it.
 
-It goes without saying, you should have an original binary to compare your changes to.
+It goes without saying, you should also have an original binary
+and do the same thing on both of them.
 
 h3. Static analysis
 
 h4. The importance of names
 
-Static analysis is simply source code analysis. Therefore, source code analysis is
+Static analysis is simply source code analysis. And source code analysis is
 really an analysis of names. File names, function names, variable names, type names,
-member names -- A program is just a bunch of names.
+member names -- A program is a bunch of names.
 
-One of the most powerful tools for creating abstractions in programming is naming.
-This may seem obvious but keeping this in mind will make reading much more efficient.
+This may seem obvious because
+one of the most powerful tools for creating abstractions in programming is naming,
+but keeping this in mind will make reading much more efficient.
 
-Also, I'd like to mention something about coding rules.
+Also, we'd like to know about coding rules beforehand to some extent.
 For example, in C language, @extern@ function often uses prefix to distinguish the type of functions.
-And in object-oriented programs, the name of member fields in a function often includes prefix,
-which is really important information (e.g. @rb_str_length@).
+And in object-oriented programs, function names sometimes contain the
+information about where they belong to in prefixes,
+and it becomes valuable information (e.g. @rb_str_length@).
 
-h4. Read documents
+h4. Reading documents
 
 Sometimes a document describes the internal structure is included.
 Especially be careful of a file named @HACKING@ etc.
 
-h4. Read the directory structure
+h4. Reading the directory structure
 
-You should read in what policy the directories are devided.
-You can grasp the overview about how the program is structured, and what the parts are.
+Looking at in what policy the directories are divided.
+Grasping the overview such as how the program is structured, and what the parts are.
 
-h4. Read the configuration of the files
+h4. Reading the file structure
 
-While browsing the name of the functions, see how the file files are divided.
+While browsing (the names of) the functions,
+also looking at the policy of how the files are divided.
 You should pay attention to the file names because they are like comments
 whose lifetime is very long.
 
-Another important viewpoint is to locate a module in the file.
-Functions for the module are thought to be located in a series.
-So, you can understand the module's structure from the order of functions.
+Additionally, if a file contains some modules in it,
+for each module the functions to compose it should be grouped together,
+so you can find out the module structure from the order of the functions.
 
-h4. Investigate abbreviations
+
+h4. Investigating abbreviations
 
 As you encounter ambiguous abbreviations, make a list of them and investigate
-each of them as early as possible. For example, suppose @GC@ is short for Garbage Collection.
-But the context will be very different if it's actually short for Graphic Context.
+each of them as early as possible. For example, when it is written "GC",
+things will be very different depending on whether it means "Garbage Collection"
+or "Graphic Context".
 
 Abbreviations for a program are generally made by the methods like taking
-the initial letters or dropping the vowels. Note especially the fact that
-popular abbreviations in the fields of the program's target are used without notice.
-You should be familiar with them at an early stage.
+the initial letters or dropping the vowels. Especially,
+popular abbreviations in the fields of the target program are used
+unconditionally, thus you should be familiar with them at an early stage.
+
 
-h4. Understand data structure
+h4. Understanding data structure
 
 If you find both data and code, you should first investigate the data structure.
-In other words, when exploring code in C, it's better to start with the header file.
-When reading filenames, you should use your imagination as much as possible.
+In other words, when exploring code in C, it's better to start with header files.
+And in this case, let's make the most of our imagination from their filenames.
 For example, if you find @frame.h@, it would probably be the stack frame definition.
 
-Also, you can understand many things from the type and member name in a structure.
+Also, you can understand many things from the member names of a struct and their types.
 For example, if you find the member @next@, which points to its own type, then it
 will be a linked list. Similarly, when you find members such as @parent@, @children@,
 and @sibling@, then it must be a tree structure. When @prev@, it will be a stack.
 
-h4. Understanding the relationship between functions
+h4. Understanding the calling relationship between functions
 
 After names, the next most important thing to understand is the relationships between
-functions. It's very useful to visualize the relationship between functions and
-their callers with a tool called a "call graph". I highly recommend you use one.
+functions. A tool to visualize the calling relationships is especially called a
+"call graph", and this is very useful. For this, we'd like to utilize tools.
 
-A text-based tool is sufficient, but call graph tool that generates an actual graph is even better.
-There are not so many tools that generate these graphs, though and most are shareware, not OSS or freeware.
-I often use graphviz to generate these graphs.
-I also implemented a small Ruby parser to generate output for graphviz, then graphviz generates the graph.
+A text-based tool is sufficient,
+but it's even better if a tool can generate diagrams.
+However such tool is seldom available (especially few tools are for free).
+When I analyzed @ruby@ to write this book,
+I wrote a small command language and a parser in Ruby and
+generated diagrams half-automatically by passing the results to the tool named @graphviz@.
 
-h4. Read functions
+h4. Reading functions
 
 動作を読んで、関数のやることを一言で説明できるようにする。関数関連図を
 見ながらパートごとに読んでいくのがいい。