imatix/zguide — pull request #432 by Byron (2014-04-19 12:35:48+00:00)
Title: some typo fixes

While reading the book online, I kept track of some typos I noticed in order to fix them.

First of all, thanks for the book ! It was a great read, and it's my pleasure to invest additional time to give something back.

The result of this work can be found in various commits. Unless it's a most trivial case, I have provided additional explanation the commit message.

After a little work (see _Additional Notes_) I could verify that my only change to formatting came out as intended, using the ePub version of the book for review.

What really makes this worth the overhead is that I now own a copy of the book for use on my various devices, which will help me to manage my notes on it much more nicely.

Thanks :) !

@hintjens In your book you mention that pull request comments comments seem somewhat redundant, and they very well might be in trivial cases. On the other hand, they are great to provide an overview about the workflow used to create the patch, which should help to assert a certain level of quality. For instance, it's great to read that the user has successfully run all tests to assure it doesn't break anything (even if no new test was added).

### Additional Notes

The following is some information I collected during my journey, maybe they are useful for someone. They are not at all relevant for merging this patch.

My conclusions in condensed form for OSX:

* don't do it unless you really, really want it. At least using macports, there is a fix you will have to do yourself related to a sgml catalog file. Maybe use homebrew right away, just to see if it works better.
* You will end up having to install dbtoepub , the ruby script, not the python script called db2epub.py

Here are my conclusions for Ubuntu:

* Use is right away, all you have to do is to install `docbook-utils`.
* Be aware though that my installation might not have been clean, and I might miss something here.

#### Building the zguide on OSX [FAIL]

To be sure I didn't break anything, I tried to build the book on OSX 10.9, but even after setting up the required dependencies using [macports](http://www.macports.org) and overcoming some bugs and issues, I was unable to get _reviewable material_. The latter could have been PDF or Epub. PDF only ended up being 2kb in size and showed up as an empty page.
Maybe it was related to the various warnings I saw earlier:
```
Using catalogs: /opt/local/share/sgml/catalog, /opt/local/share/sgml/iso8879/catalog, /opt/local/share/sgml/openjade/catalog
Using stylesheet: /opt/local/share/sgml/docbook/utils-0.6.14/docbook-utils.dsl#print
[...]
openjade:http://www.oasis-open.org/docbook/xml/4.5/ent/isogrk4.ent:42:30:E: "1D6C2" is not a character number in the document character set
[...]
```

Epub was more of a problem on the level of the toolchain, as I managed to install _db2epub.py_ (making it available under _dbtoepub_), just to see it failing due to some XSL requirements that weren't mentioned in the postface.
Just for a second I thought the author was mean and evil, keeping this apparently vital file hidden somewhere to prevent others from building the epub version.
On a second thought, I realised that maybe, I was taking an unexplored route, as the only platform ever mentioned to be working was ubuntu.
Walking back a few miles, I took the road clearly saying 'go here if you like to build the zguide painlessly', and could only wonder why I ignored it before.

#### About building the zguide on ubuntu [SUCCESS]

Using an ubuntu 14 VM, I started out installing the most basic tools, which required a whopping 390MB on disk:

```
apt-get install docbook-utils
```

For some reason, I was extremely certain that it would just work now, and it did for the ePub format. That's something. PDF however, didn't work due to an issue with openjade, which seemed to be unable to understand all characters used in the document.

```
Using catalogs: /etc/sgml/catalog
Using stylesheet: /usr/share/docbook-utils/docbook-utils.dsl#print
Working on: /media/psf/Home/Documents/dev/ext/zmq/zguide/book.xml
openjade:/media/psf/Home/Documents/dev/ext/zmq/zguide/book.xml:11565:325:E: non SGML character number 144
Error: /undefinedfilename in (book.ps)
Operand stack:

Execution stack:
%interp_exit .runexec2 --nostringval-- --nostringval-- --nostringval-- 2 %stopped_push --nostringval-- --nostringval-- --nostringval-- false 1 %stopped_push
Dictionary stack:
--dict:1164/1684(ro)(G)-- --dict:0/20(G)-- --dict:77/200(L)--
```
Could it be related to the japanese symbols I have seen in some chapters - [SublimeText](http://www.sublimetext.com/) could deal with them nicely.

Looking closer, it became apparent that the `docbook2pdf book.xml` fails, and considering that the osx tool failed with similar issues (which where warnings there), it should have something to do with a missing catalog.

Poking around, I installed `wc3-sgml-lib`, which seemed to confuse openjade even more, and didn't fix anything.

As giving up is not my thing, I decided to see if it might truly be related to the text itself, and not my toolchain. It turned out, that the line and character it was referring to contained the problematic character.

After all, I was able to put in another commit to fix the issue for good.