Migrate pdf format

.gitignore

@@ -13,6 +13,7 @@ git-log.xml
 book-revhistory.xml
 beam-book-from-ab.xml
 beam-book.pdf
+beam-book2.pdf
 opcodes_doc.asciidoc
 .#.gitignore
 genop.tab
@@ -22,4 +23,4 @@ xml/*.png
 xml/*.png.md5
 site
 .asciidoctor
-.DS_Store
+.DS_Store

Makefile

@@ -13,8 +13,14 @@ xml/beam-book-from-ab.xml:  chapters/opcodes_doc.asciidoc
 beam-book.pdf: xml/beam-book-from-ab.xml
 	dblatex $(DBLATEX_OPTS) xml/beam-book-from-ab.xml -o $@
 
+### Experimental pdf command
+beam-book2.pdf:  chapters/opcodes_doc.asciidoc book.asciidoc  chapters/*.asciidoc chapters/contributors.txt
+	cp -r images/*.png site/images
+	asciidoctor-pdf  -r ./style/custom-pdf-converter.rb -r asciidoctor-diagram -r ./style/custom-admonition-block.rb  -a config=./style/ditaa.cfg --doctype book -a media=prepress -a pdf-style=./style/pdf-theme.yml book.asciidoc -o $@
+
 index.html:
-	asciidoctor -r asciidoctor-diagram --backend=html5 --doctype=book -o site/index.html book.asciidoc
+	asciidoctor -r asciidoctor-diagram  -r ./style/custom-admonition-block.rb -a config=style/ditaa.cfg --backend=html5 --doctype=book -o site/index.html book.asciidoc --trace
+	cp -r images/*.png site/images
 
 code/book/ebin/generate_op_doc.beam: code/book/src/generate_op_doc.erl
 	erlc -o $(dir $@) $<
@@ -28,3 +34,4 @@ genop.tab:
 
 clean:
 	rm -f beam-book.pdf site/index.html site/*.png site/*.md5 xml/*.png xml/*.md5 xml/beam-book-from-ab.xml
+	rm -f beam-book2.pdf site/images/*.png

README.md

@@ -107,10 +107,14 @@ free to contribute by fixing tags in the current version.
 Chapter tags should start with 'CH-'. Words in a tag are separated by
 underscores '_'.
 
+Part tags should start with 'P-'.
+
 Section tags should start with 'SEC-'.
 
 Figure tags should start with 'FIG-'.
 
+Appendix tags should start with 'AP-'.
+
 Code listing tags (in the appendix) should start with 'LISTING-'.
 
 ### Process
@@ -157,24 +161,25 @@ make
    need to _full_ MacTex rather than just BasicTex.
 1. Add `/Library/TeX/texbin` to your `PATH`.
 1. `easy_install dblatex`
-1. Install [asciidoc](http://asciidoc.org/INSTALL.html)
+1. Install [asciidoc](https://github.com/asciidoctor/asciidoctor)
+1. Install [asciidoctor-pdf](https://github.com/asciidoctor/asciidoctor-pdf)
 1. Install [asciidoctor-diagram](http://asciidoctor.org/docs/asciidoctor-diagram/)
-1. Install [shaape](https://github.com/christiangoltz/shaape)
+1. Install [ditaa](https://github.com/stathissideris/ditaa)
 1. Install [source-highlight](https://www.gnu.org/software/src-highlite/)
 1. Install [wget](https://www.gnu.org/software/wget/)
 1. `make`
 
-### Mac OSX (using brew)
+### Mac OSX (using brew etc)
 
 1. `brew install Caskroom/cask/mactex`
 1. Add `/Library/TeX/texbin` to your `PATH`.
 1. `sudo easy_install dblatex`
-1. `brew install asciidoc`
-1. `brew install pygtk py2cairo pango`
-1. `pip install shaape`
+1. `brew install asciidoctor`
+1. `gem install asciidoctor-pdf`
+1. `gem install asciidoctor-diagram`
+1. `brew install ditaa`
 1. `brew install source-highlight`
 1. `brew install wget`
-1. `gem install asciidoctor-diagram`
 1. `make`
 
 ## License

book.asciidoc

@@ -6,6 +6,14 @@
 :toclevels: 3
 :experimental:
 :icons: font
+:partnums:
+:sectnums:
+:sectlinks:
+:!compat-mode:
+:source-highlighter: rouge
+:imagesdir: site/images
+:ditaa-shadows: false
+:ditaa-transparent: true
 
 include::chapters/preface.asciidoc[]
 
@@ -60,11 +68,12 @@ include::chapters/ops.asciidoc[]
 include::chapters/tweak.asciidoc[]
 
 [[appendix]]
-= Appendices
-// include::chapters/index.asciidoc[]
-
 include::chapters/building.asciidoc[]
 
 include::chapters/ap-beam_instructions.asciidoc[]
 
 include::chapters/ap-code_listings.asciidoc[]
+
+
+//[index]
+//include::chapters/index.asciidoc[]

chapters/ap-beam_instructions.asciidoc

@@ -1,5 +1,6 @@
 [[AP-Instructions]]
-== BEAM Instructions
+[appendix]
+= BEAM Instructions
 
 Here we will go through most of the instructions in the BEAM generic instruction set in detail. In the next section we list all instructions with a brief explanation generated from the documentaion in the code (see `lib/compiler/src/genop.tab`).
 

chapters/ap-code_listings.asciidoc

@@ -1,5 +1,6 @@
 [[AP-listings]]
-== Full Code Listings
+[appendix]
+= Full Code Listings
 
 [source,erlang]
 ----

chapters/beam.asciidoc

@@ -1,7 +1,7 @@
 [[CH-BEAM]]
 == The Erlang Virtual Machine: BEAM
 
-BEAM (Bogumil's/Björn's Abstract Machine) is the machine that executes
+BEAM (Bogumil's/Björn’s Abstract Machine) is the machine that executes
 the code in the Erlang Runtime System. It is a garbage collecting,
 reduction counting, virtual, non-preemptive, directly threaded,
 register machine. If that doesn't tell you much, don't worry, in the
@@ -119,7 +119,7 @@ then moves the value to a Y register.
 
 [[x_and_y_regs_in_memory]]
 .X and Y Registers in Memory
-[shaape]
+[ditaa]
 ----
   hend ->  +----+    -
            |....|
@@ -142,10 +142,6 @@ then moves the value to a Y register.
       X1   |    |
      (X0)  |    |
            +----+
-
-options:
- - ".*": {fill: [[0.7, 0.7, 0.7], no-shadow], frame: [[0.9, 0.9, 0.9], line]}
- - ".*": {text : ["Monospace 10", no-shadow]}
 ----
 
 Let us compile the following program with the _'S'_ flag:
@@ -265,7 +261,7 @@ integer(I) ->
 -------------------------------------------
 
 Now lets write a simple virtual machine in C. The full code can
-be found in [appendix].
+be found in xref:AP-listings[].
 
 [source, C]
 -------------------------------------------
@@ -429,7 +425,7 @@ We will look closer at the BEAM emulator later but we will take a
 quick look at how the add instruction is implemented. The code is
 somewhat hard to follow due to the heavy usage of macros. The
 STORE_ARITH_RESULT macro actually hides the dispatch function which
-looks something like: _I += 4; Goto(*I);_.
+looks something like: `I += 4; Goto(*I);`.
 
 [source, C]
 -------------------------------------------
@@ -539,16 +535,16 @@ in the BEAM we just use them to illustrate this example):
 
 -------------------------------------------
 
-Note that the star in "+goto+ +*+" does not mean dereference, the
+Note that the star in `+goto *+` does not mean dereference, the
 expression means jump to an address pointer, we should really write it
-as "+goto*+".
+as `+goto*+`.
 
 Now imagine that the compiled C code for these instructions end up at
 memory addresses 0x3000, 0x3100, and 0x3200. When the BEAM code is
 loaded the three move instructions in the code will be replaced by the
 memory addresses of the implementation of the instructions. Imagine
-that the code (+{move,{x,0},{x,1}}, {move,{y,0},{x,0}},
-{move,{x,1},{y,0}}+) is loaded at address 0x1000:
+that the code (`+{move,{x,0},{x,1}}, {move,{y,0},{x,0}},
+{move,{x,1},{y,0}}+`) is loaded at address 0x1000:
 
 
 -------------------------------------------
@@ -564,9 +560,9 @@ that the code (+{move,{x,0},{x,1}}, {move,{y,0},{x,0}},
 -------------------------------------------
 
 The word at address 0x1000 points to the implementation of
-the move_xx instruction. If the register +I+ contains the instruction
-pointer, pointing to 0x1000 then the dispatch will be to fetch +*I+
-(i.e. 0x3000) and jump to that address. ("+goto*+ +*I+")
+the move_xx instruction. If the register `I` contains the instruction
+pointer, pointing to 0x1000 then the dispatch will be to fetch `+*I+`
+(i.e. 0x3000) and jump to that address. (`+goto* *I+`)
 
 In xref:CH-Instructions[] we will look more closely at some real
 BEAM instructions and how they are implemented.

chapters/beam_instructions.asciidoc

@@ -283,7 +283,7 @@ registers. E.g. if +Live+ is 2 then registers X0 and X1 are saved.
 When allocating on the stack, the stack pointer (E) is decreased.
 
 .Allocate 1 0
-[shaape]
+[ditaa]
 ----
        Before           After
          | xxx |            | xxx |
@@ -293,10 +293,6 @@ When allocating on the stack, the stack pointer (E) is decreased.
            ...                ...
  HTOP -> |     |    HTOP -> |     |
          | xxx |            | xxx |
-
-options:
- - ".*": {fill: [[0.7, 0.7, 0.7], no-shadow], frame: [[0.9, 0.9, 0.9], line]}
- - ".*": {text : ["Monospace 10", no-shadow]}
 ----
 
 For a full listing of all types of allocate and deallocate

chapters/beam_modules.asciidoc

@@ -15,11 +15,11 @@ NOTE: What is a module. How is code loaded. How does hot code loading work. How
 
 The definite source of information about the beam file format is obviously the source code of beam_lib.erl (see link:$$https://github.com/erlang/otp/blob/maint/lib/stdlib/src/beam_lib.erl$$[]). There is actually also a more readable but slightly dated description of the format written by the main developer and maintainer of Beam (see link:$$http://www.erlang.se/~bjorn/beam_file_format.html$$[]).
 
-The beam file format is based on the interchange file format (EA IFF)#, with two small changes. We will get to those shortly. An IFF file starts with a header followed by a number of “chunks”. There are a number of standard chunk types in the IFF specification dealing mainly with images and music. But the IFF standard also lets you specify your own named chunks, and this is what BEAM does.
+The beam file format is based on the interchange file format (EA IFF)#, with two small changes. We will get to those shortly. An IFF file starts with a header followed by a number of “chunks”. There are a number of standard chunk types in the IFF specification dealing mainly with images and music. But the IFF standard also lets you specify your own named chunks, and this is what BEAM does.
 
-NOTE: Beam files differ from standard IFF files, in that each chunk is aligned on 4-byte boundary (i.e. 32 bit word) instead of on a 2-byte boundary as in the IFF standard. To indicate that this is not a standard IFF file the IFF header is tagged with “FOR1” instead of “FORM”. The IFF specification suggests this tag for future extensions.
+NOTE: Beam files differ from standard IFF files, in that each chunk is aligned on 4-byte boundary (i.e. 32 bit word) instead of on a 2-byte boundary as in the IFF standard. To indicate that this is not a standard IFF file the IFF header is tagged with “FOR1” instead of “FOR”. The IFF specification suggests this tag for future extensions.
 
-Beam uses form type “BEAM”. A beam file header has the following layout:
+Beam uses form type “BEAM”. A beam file header has the following layout:
 
 [source,erlang]
 ----
@@ -265,7 +265,7 @@ parse_code_info(<<Instructionset:32/integer,
 
 
 
-We will learn how to decode the beam instructions in a later chapter, aptly named &ldquo;BEAM Instructions&rdquo;.
+We will learn how to decode the beam instructions in a later chapter, aptly named “BEAM Instructions”.
 
 
 ==== String table chunk
@@ -496,7 +496,7 @@ TIP: `Beam_asm` is a module in the `compiler` application, part of the Erlang di
 
 The reason behind this complicated design is to try and fit as much type and value data into the first byte as possible to make the code section more compact. After decoding, all encoded values become full size machine words or terms.
 
-[shaape]
+[ditaa]
 ----
 7 6 5 4 3 | 2 1 0
 ----------+-------+
@@ -521,7 +521,7 @@ It uses the first 3 bits of a first byte to store the tag which defines the type
 
 For values under 16, the value is placed entirely into bits 4-5-6-7 having bit 3 set to 0:
 
-[shaape]
+[ditaa]
 ----
 7 6 5 4 | 3 | 2 1 0
 --------+---+------
@@ -530,7 +530,7 @@ Value   | 0 | Tag
 
 For values under 2048 (16#800) bit 3 is set to 1, marks that 1 continuation byte will be used and 3 most significant bits of the value will extend into this byte’s bits 5-6-7:
 
-[shaape]
+[ditaa]
 ----
 7 6 5 | 4 3 | 2 1 0
 ------+-----+------
@@ -539,7 +539,7 @@ Value | 0 1 | Tag
 
 Larger and negative values are first converted to bytes. Then if the value takes 2..8 bytes, bits 3-4 will be set to 1, and bits 5-6-7 will contain the (Bytes-2) size for the value, which follows:
 
-[shaape]
+[ditaa]
 ----
 7  6  5 | 4 3 | 2 1 0
 --------+-----+------
@@ -548,7 +548,7 @@ Bytes-2 | 1 1 | Tag
 
 If the following value is greater than 8 bytes, then all bits 3-4-5-6-7 will be set to 1, followed by a nested encoded unsigned literal (macro `?tag_u` in `beam_opcodes.hrl`) value of (Bytes-9):8, and then the data:
 
-[shaape]
+[ditaa]
 ----
 7 6 5 4 3 | 2 1 0  ||  Followed by a          ||
 ----------+------  ||  nested encoded literal || Data . . .

chapters/building.asciidoc

@@ -1,5 +1,6 @@
-[[CH-BuildingERTS]]
-== Building the Erlang Runtime System
+[[AP-BuildingERTS]]
+[appendix]
+= Building the Erlang Runtime System
 
 In this chapter we will look at different way to configure and build
 Erlang/OTP to suite your needs. We will use an Ubuntu Linux for most

chapters/compiler.asciidoc

@@ -61,7 +61,7 @@ xref:fig_compiler_passes[].
 
 [[fig_compiler_passes]]
 .Compiler Passes
-[shaape]
+[ditaa, scale=0.6]
 ----
 [] = Compiler options, () = files, {} = erlang terms, boxes = passes
          (.erl)
@@ -174,9 +174,6 @@ xref:fig_compiler_passes[].
             v
          (.beam)</pre>
 
-options:
- - ".*": {fill: [[0.7, 0.7, 0.7], no-shadow], frame: [[0.9, 0.9, 0.9], line]}
- - ".*": {text : ["Monospace 10", no-shadow]}
 ----
 
 If you want to see a complete and up to date list of compiler passes
@@ -511,7 +508,7 @@ The compilation of +json_test+ fails since the module contains invalid
 Erlang syntax, but you get to see what the AST looks like. Now we can
 just write some functions to traverse the AST and rewrite the json
 code into Erlang code.footnote:[The translation here is done in
-accordance with link:http://www.erlang.org/eeps/eep-0018.html[EEP 18] 
+accordance with link:http://www.erlang.org/eeps/eep-0018.html[EEP 18] 
 (Erlang Enhancement Proposal 18: "JSON bifs")]
 
 [source,erlang]
@@ -778,7 +775,7 @@ the string/1 function that leex generates to tokenize the test file.
 ----
 2> c(json_tokens).
 {ok,json_tokens}.
-3> f(File), f(L), {ok, File} = file:read_file("test.json"), L = binary_to_list(File), ok.
+3> f(File), f(L), {ok, File} = file:read_file("test.json"), L = binary_to_list(File), ok.
 ok
 4> f(Tokens), {ok, Tokens,_} = json_tokens:string(L), hd(Tokens).
 {'{',1}