Ticket #215: book_cage_clean.patch

docs/book/ch02_getting_started.pod

@@ -142 +142 @@
 
 =head1 Building Parrot
 
-Z<CHP-9-SECT-1>
+Z<CHP-2-SECT-2.2.2>
 
 X<Parrot;source code>
 The first step before you start playing with Parrot's PASM and PIR
@@ -192 +192 @@
 
 =head3 Patch submission
 
-Z<CHP-2-SECT-2.2.2>
+Z<CHP-2-SECT-2.2.3>
 
 X<Parrot;patch submission>
 Parrot development proceeds through a continuous stream of patches.
@@ -324 +324 @@
 
 =head3 Bug tracking
 
-Z<CHP-2-SECT-2.2.3>
+Z<CHP-2-SECT-2.2.4>
 
 X<Parrot;bug tracking>
 Bug reports go to the same address as patch submissions

docs/book/ch08_architecture.pod

@@ -2 +2 @@
 
 =head0 Parrot Internals
 
-Z<CHP-7>
+Z<CHP-8>
 
 This chapter details the architecture and internal workings of Parrot,
 and attempts to explain how Parrot has been designed and how it operates.
@@ -13 +13 @@
 
 =head1 Core Design Principles
 
-Z<CHP-7-SECT-1>
+Z<CHP-8-SECT-1>
 
 X<Parrot;internals>
 Three main principles drive the design of
@@ -72 +72 @@
 
 =head1 Parrot's Architecture
 
-Z<CHP-7-SECT-2>
+Z<CHP-8-SECT-2>
 
 The X<architecture;Parrot>
 X<Parrot;architecture>
@@ -85 +85 @@
 
 =begin figure Parrot's flow
 
-Z<CHP-7-FIG-1>
+Z<CHP-8-FIG-1>
 F<figs/p6e_0801.png>
 
 =end figure
@@ -113 +113 @@
 
 =head2 Parser
 
-Z<CHP-7-SECT-2.1>
+Z<CHP-8-SECT-2.1>
 
 X<parser, Parrot>
 X<Parrot;parser module>
@@ -171 +171 @@
 
 =head2 Compiler
 
-Z<CHP-7-SECT-2.2>
+Z<CHP-8-SECT-2.2>
 
 
 X<Parrot;compiler module>
@@ -194 +194 @@
 
 =head2 Optimizer
 
-Z<CHP-7-SECT-2.3>
+Z<CHP-8-SECT-2.3>
 
 X<Parrot;optimizer module>
 X<optimizer>
@@ -316 +316 @@
 
 =head1 The Interpreter
 
-Z<CHP-7-SECT-3>
+Z<CHP-8-SECT-3>
 
 The X<interpreter, Parrot>
 interpreter is the engine that actually runs the code emitted by the
@@ -360 +360 @@
 
 =head2 Registers
 
-Z<CHP-7-SECT-3.1>
+Z<CHP-8-SECT-3.1>
 
 X<interpreter, Parrot;registers>
 As we've seen in previous chapers, Parrot has four basic types of
@@ -375 +375 @@
 
 =head2 Strings
 
-Z<CHP-7-SECT-3.3>
+Z<CHP-8-SECT-3.3>
 
 X<strings;Parrot>
 X<interpreter, Parrot;strings>
@@ -455 +455 @@
 
 =head2 Variables
 
-Z<CHP-7-SECT-3.4>
+Z<CHP-8-SECT-3.4>
 
 X<variables;Parrot interpreter and>
 X<interpreter, Parrot;variables>
@@ -506 +506 @@
 
 =head2 Bytecode
 
-Z<CHP-7-SECT-3.5>
+Z<CHP-8-SECT-3.5>
 
 Like any CPU, software, or hardware, Parrot needs a set of
 instructions to tell it what to do. For hardware, this is a stream of
@@ -560 +560 @@
 
 =head1 I/O, Events, and Threads
 
-Z<CHP-7-SECT-4>
+Z<CHP-8-SECT-4>
 
 Parrot has comprehensive support for I/O, threads, and events. These
 three systems are interrelated, so we'll treat them together. The
@@ -570 +570 @@
 
 =head2 I/O
 
-Z<CHP-7-SECT-4.1>
+Z<CHP-8-SECT-4.1>
 
 Parrot's base X<I/O;Parrot> I/O system is fully X<asynchronous I/O>
 asynchronous with callbacks and per-request private data. Since this
@@ -637 +637 @@
 
 =head2 Events
 
-Z<CHP-7-SECT-4.2>
+Z<CHP-8-SECT-4.2>
 
 An X<events, Parrot> event is a notification that something has
 happened: the user has manipulated a GUI element, an I/O request has
@@ -710 +710 @@
 
 =head2 Signals
 
-Z<CHP-7-SECT-4.3>
+Z<CHP-8-SECT-4.3>
 
 X<signals, Parrot>
 Signals are a special form of event, based on the standard Unix signal
@@ -771 +771 @@
 
 =head2 Threads
 
-Z<CHP-7-SECT-4.4>
+Z<CHP-8-SECT-4.4>
 
 X<threads, Parrot>
 Threads are a means of splitting a process into multiple pieces that
@@ -884 +884 @@
 
 =head1 Objects
 
-Z<CHP-7-SECT-5>
+Z<CHP-8-SECT-5>
 
 X<objects;Parrot>
 Perl 5, Perl 6, Python, and Ruby are all object-oriented languages in
@@ -899 +899 @@
 
 =head2 Generic Object Interfacing
 
-Z<CHP-7-SECT-5.1>
+Z<CHP-8-SECT-5.1>
 
 X<PMCs (Parrot Magic Cookies);handling method calls>
 Parrot's object system is very simple--in fact, a PMC only has to handle
@@ -924 +924 @@
 
 =head2 Parrot Objects
 
-Z<CHP-7-SECT-5.2>
+Z<CHP-8-SECT-5.2>
 
 X<objects;Parrot>
 X<Parrot;objects>
@@ -986 +986 @@
 
 =head2 Mixed Class-Type Support
 
-Z<CHP-7-SECT-5.3>
+Z<CHP-8-SECT-5.3>
 
 X<mixed class-type support in Parrot>
 X<classes;Parrot;mixed class support>
@@ -1015 +1015 @@
 
 =head1 Advanced Features
 
-Z<CHP-7-SECT-6>
+Z<CHP-8-SECT-6>
 
 Since the languages Parrot targets (like Perl and Ruby) have
 sophisticated concepts as core features, it's in Parrot's best
@@ -1024 +1024 @@
 
 =head2 Garbage Collection
 
-Z<CHP-7-SECT-6.1>
+Z<CHP-8-SECT-6.1>
 
 X<garbage collection;Parrot>
 It's expected that modern languages have garbage collection built in.
@@ -1099 +1099 @@
 
 =head2 Multimethod Dispatching
 
-Z<CHP-7-SECT-6.2>
+Z<CHP-8-SECT-6.2>
 
 X<multimethod;dispatching>
 Multimethod dispatching (also known as signature-based dispatching) is
@@ -1162 +1162 @@
 
 =head2 Continuations
 
-Z<CHP-7-SECT-6.3>
+Z<CHP-8-SECT-6.3>
 
 X<continuations>
 Continuations are possibly the most powerful high-level flow control
@@ -1234 +1234 @@
 
 =head2 Coroutines
 
-Z<CHP-7-SECT-6.4>
+Z<CHP-8-SECT-6.4>
 
 X<coroutines>
 A coroutine is a subroutine or method that can suspend itself partway
@@ -1256 +1256 @@
 
 =head1 Conclusion
 
-Z<CHP-7-SECT-7>
+Z<CHP-8-SECT-7>
 
 We've touched on much of Parrot's core functionality, but certainly
 not all. Hopefully we've given you enough of a feel for how Parrot

docs/book/ch12_opcodes.pod

@@ -2 +2 @@
 
 =head1 Opcodes and Runcores
 
-Z<CHP-11>
+Z<CHP-12>
 
 The smallest executable component is not the compilation unit or even
 the subroutine, but is actually the opcode. Opcodes in PASM, like opcodes
@@ -50 +50 @@
 
 =over 4
 
-=item* Slow Core
+=item * Slow Core
 
 The slow core is a basic runcore design that treats each opcode as a
 separate function at the C level. Each function is called, and returns
@@ -71 +71 @@
           UPDATE_INTERPRETER();
   }
 
-=item* Fast Core
+=item * Fast Core
 
 The fast core is a bare-bones core that doesn't do any of the
 bounds-checking or context updating that the slow core does. The fast
@@ -86 +86 @@
           DISPATCH_OPCODE(pc);
   }
 
-=item* Switch Core
+=item * Switch Core
 
 As its name implies, the switch core uses a gigantic C C<switch / case>
 structure to execute opcodes. Here's a brief example of how this
@@ -109 +109 @@
 pointer, dereferencing the opcode pointer, and then a jump to the C<case>
 statement for the next opcode.
 
-=item* Computed Goto Core
+=item * Computed Goto Core
 
 I<Computed Goto> is a feature of some C compilers where a label is
 treated as a piece of data that can be stored as a C<void *> pointer. Each
@@ -167 +167 @@
 presented here. However, as we shall see with the precomputed goto core,
 it isn't optimized as aggressively as is possible.
 
-=item* Precomputed Goto Core
+=item * Precomputed Goto Core
 
 The precomputed goto core is an amazingly fast optimized core that uses
 the same computed goto feature, but performs the array dereferencing
@@ -208 +208 @@
 available with compilers that support computed goto, such as GCC. Parrot
 will not have access to this core if it is built with a different compiler.
 
-=item* Tracing Core
+=item * Tracing Core
 
-=item* Profiling Core
+=item * Profiling Core
 
 The profiling core analyzes the performance of Parrot, and helps to
 determine where bottlenecks and trouble spots are in the programs that
@@ -227 +227 @@
 number of calls to each subroutine made. All this information is helpfully
 printed to the STDERR output for later analysis.
 
-=item* GC Debug Core
+=item * GC Debug Core
 
 Parrot's garbage collector has been known as a weakness in the system
 for several years. In fact, the garbage collector and memory management
@@ -243 +243 @@
 performance is terrible, but that's not the point: it's almost guaranteed
 to find problems in the memory system if they exist.
 
-=item* Debug Core
+=item * Debug Core
 
 The debug core works like a normal software debugger, such as GDB. The
 debug core executes each opcode, and then prompts the user to enter a
@@ -361 +361 @@
 
 =head2 Dynops
 
+=cut
 
 ##########################################################################
 #                              PSEUDOPOD LEGEND

docs/book/ch09_pct.pod

@@ -55 +55 @@
 
 =over 4
 
-=item* A main file
+=item * A main file
 
 The main file should contain the C<:main> function that is the driver
 program for the compiler. Here, a new C<PCT::HLLCompiler> object is
@@ -64 +64 @@
 although thankfully they tend to be very short. Most of the action
 happens elsewhere.
 
-=item* A parser file
+=item * A parser file
 
 The grammar for the high level language is specified using the Perl 6
 grammar engine (PGE) and is stored in a C<.pg> file. This file should
 subclass the C<PCT::Grammar> class and implement all the necessary
 rules to successfully parse the language.
 
-=item* An actions file
+=item * An actions file
 
 Actions files are written in NQP. They take match objects generated by
 the grammar file and convert them into an Abstract Syntax Tree (AST)
@@ -196 +196 @@
 
 =over 4
 
-=item* Rules
+=item * Rules
 
 Rules are the most basic grammar element. Rules may call subrules and
 may also contain arbitrary whitespace, which is ignored.
 
-=item* Tokens
+=item * Tokens
 
 Tokens represent basic regular expressions. They may not call subrules
 and whitespace is treated literally. {{I don't think this is right, but
 I'm adding it here anyway as a placeholder -- Whiteknight}}
 
-=item* Protoregex
+=item * Protoregex
 
 A protoregex is like a rule or a token, except it can be overloaded
 dynamically.

docs/book/ch04_pir_subroutines.pod

@@ -1 +1 @@
 =pod
 
-Z<CHP-4>
-
 =head1 Subroutines
 
 Z<CHP-4>
@@ -454 +452 @@
 
 =head2 Compilation Units Revisited
 
-Z<CHP-4-SECT-1.2>
+Z<CHP-4-SECT-1.1>
 
 The term "compilation unit" is one that's been bandied about throughout the
 chapter and it's worth some amount of explanation here. A compilation unit
@@ -499 +497 @@
 
 =head3 PASM Subroutines
 
-Z<CHP-4-SECT-1.1>
+Z<CHP-4-SECT-1.2>
 
 X<subroutines;PASM>
 X<PASM (Parrot assembly language);subroutines>
@@ -537 +535 @@
 
 =head3 Namespaces
 
-Z<CHP-4-SECT-2>
+Z<CHP-4-SECT-2.1>
 
 X<Namespaces>
 X<.namespace>
@@ -586 +584 @@
 
 =head3 Calling Methods
 
-Z<CHP-4-SECT-2>
+Z<CHP-4-SECT-2.2>
 
 Now that we've discussed namespaces, we can start to discuss all the
 interesting things that namespaces enable, like object-oriented
@@ -793 +791 @@
 
 =over 4
 
-=item* Identifies coroutines
+=item * Identifies coroutines
 
 When Parrot sees a yield, it knows to create a coroutine PMC object
 instead of a Subroutine one.
 
-=item* Creates a continuation
+=item * Creates a continuation
 
 Continuations, as we have already seen, allow us to continue
 execution at the point of the continuation later. It's like a snapshot of
@@ -806 +804 @@
 the coroutine and stores the continuation object in the coroutine object
 or later resuming from the point of the C<.yield>.
 
-=item* Returns a value
+=item * Returns a value
 
 C<.yield> can return a value N<or many values, or no values> to the caller.
 It is basically the same as a C<.return> in this regard.

docs/book/ch13_reference.pod

@@ -2 +2 @@
 
 =head1 Parrot Reference
 
-Z<CHP-10>
+Z<CHP-13>
 
 This chapter contains a condensed list of PASM opcodes, PIR directives
 and instructions, and Parrot command-line options, sorted alphabetically
@@ -13 +13 @@
 
 =head2 PASM Opcodes
 
-Z<CHP-10-SECT-1>
+Z<CHP-13-SECT-1>
 
 X<PASM (Parrot assembly language);opcodes, quick reference>
 For complete details on each opcode and the latest changes, read the
@@ -1245 +1245 @@
 
 =begin table picture Interpinfo flags
 
-Z<CHP-10-TABLE-1>
+Z<CHP-13-TABLE-1>
 
 =headrow
 
@@ -2415 +2415 @@
 
 =begin table picture Stringinfo arguments
 
-Z<CHP-10-TABLE-2>
+Z<CHP-13-TABLE-2>
 
 =headrow
 
@@ -2812 +2812 @@
 
 =head2 PIR Directives
 
-Z<CHP-10-SECT-2>
+Z<CHP-13-SECT-2>
 
 X<PIR (Parrot intermediate representation);quick reference;directives>
 This is a summary of PIR directives. Directives are preprocessed by the
@@ -3031 +3031 @@
 
 =head2 PIR Instructions
 
-Z<CHP-10-SECT-3>
+Z<CHP-13-SECT-3>
 
 X<PIR (Parrot intermediate representation);quick reference;instructions>
 This section is a quick reference to PIR instructions. For more details
@@ -3323 +3323 @@
 
 =head2 Parrot Command-Line Options
 
-Z<CHP-10-SECT-4>
+Z<CHP-13-SECT-4>
 
 X<command-line options (Parrot)>
 X<Parrot;command-line options>
@@ -3336 +3336 @@
 
 =head3 General Usage
 
-Z<CHP-10-SECT-4.1>
+Z<CHP-13-SECT-4.1>
 
   parrot [options] file [arguments]
 
@@ -3346 +3346 @@
 
 =head3 Assembler Options
 
-Z<CHP-10-SECT-4.2>
+Z<CHP-13-SECT-4.2>
 
 =over 4
 
@@ -3374 +3374 @@
 
 =begin table picture Debug bits
 
-Z<CHP-10-TABLE-3>
+Z<CHP-13-TABLE-3>
 
 =headrow
 
@@ -3513 +3513 @@
 
 =begin table picture Optimizations
 
-Z<CHP-10-TABLE-4>
+Z<CHP-13-TABLE-4>
 
 =headrow
 
@@ -3561 +3561 @@
 
 =head3 Bytecode Interpreter Options
 
-Z<CHP-10-SECT-4.3>
+Z<CHP-13-SECT-4.3>
 
 X<Parrot;bytecode interpreter options>
 X<bytecode interpreter options (Parrot)>

docs/book/ch10_hlls.pod

@@ -165 +165 @@
 
 =over 4
 
-=item* VTable methods
+=item * VTable methods
 
 VTable methods are the standard interface for PMC data types, and all PMCs
 have them. If the PMCs were written properly to satisfy this interface
 all the necessary information from those PMCs. Operate on the PMCs at the
 VTable level, and we can safely ignore the implementation details of them.
 
-=item* Class Methods
+=item * Class Methods
 
 If a library returns data in a particular format, the library reuser should
 know, understand, and make use of that format. Classes written in other

docs/book/ch11_pmcs.pod

@@ -2 +2 @@
 
 =head1 PMCs
 
-Z<CHP-10>
+Z<CHP-11>
 
 PMCs are one of the four fundamental data types in Parrot, and definitely one
 of the most useful. A PMC can contain a single scalar value (integer, floating
@@ -229 +229 @@
 =head3 Loading dynpmcs
 
 
+=cut
 
-
 ##########################################################################
 #                              PSEUDOPOD LEGEND
 #

docs/book/ch07_testing_and_debugging.pod

@@ -2 +2 @@
 
 =head0 Testing and Debugging
 
-Z<CHP-6>
+Z<CHP-7>
 
 Programming languages and the virtual machines on which they run are just
 one small part of the total programming ecosystem. Programmers require not
@@ -15 +15 @@
 
 =head1 Writing Tests
 
-Z<CHP-6-SECT-1>
+Z<CHP-7-SECT-1>
 
 X<testing Parrot>
 Parrot is volunteer-driven, and contributions from new users are always
@@ -118 +118 @@
 
 =head1 The Parrot Debugger
 
-Z<CHP-6-SECT-2>
+Z<CHP-7-SECT-2>
 
 =cut