Formatted chapter 5

.travis.yml

@@ -7,4 +7,6 @@ install: pip install sphinx
 script:
   - python misc/lint.py
   - make html
-sudo: false
+sudo: false
+notifications:
+  email: false

chapters/chap07-industry.rst

@@ -4,15 +4,16 @@ An Industrial Revolution
 
 You have come a long way, young jedi! Your dwarf herding skills are
 strong! You now know the basics of building, production, trading and
-managing your dwarfs. But we still have work to do, so lets get back to
-our fortress!
+managing your dwarves.
+
+This is probably a good time to go read the tutorial on trading -
+it ties in pretty well with a large industrial base.  Tutorials are
+designed be skippable though, so if the thought of heavy industry
+excites you, we can dive right in!
 
 More Production!
 ================
-We took a bit of a detour earlier by getting into managing dwarfs and
-trading and whatnot, but I think you’ll agree those were important
-lessons. But what really gets us going is building awesome new stuff in
-our fortress, right? Lets start with some new workshops you should get
+Lets start with some new workshops you should get
 to grips with. I won’t list the keys you need to use for every task,
 you should be able to remember the basic stuff from earlier lessons, so
 lets just get building these workshops around our four big production
@@ -25,22 +26,22 @@ rooms:
 * Butchers
 * Metalsmith’s Forge
 
-In addition, go to the Furnaces menu (from “b” and then “e” for
-“Furnaces”) and build:
+In addition, go to the Furnaces menu (from :kbd:`b` and then :kbd:`e` for
+:guilabel:`Furnaces`) and build:
 
 * Wood Furnace
 * Smelter
 
 While those places get built lets look at expanding a bit. In the
 middle of our four room area we have three stairs going down. Right now
-they go nowhere, so lets go down about 5 levels. Remember, “d” and then
-“i” for “Up/Down Stairs”, set to the level below, will get that
+they go nowhere, so lets go down about 5 levels. Remember, :kbd:`d` and then
+:kbd:`i` for :guilabel:`Up/Down Stairs`, set to the level below, will get that
 construction going.
 
 We also have room to expand between our production floor and our
 entrance, so lets go up a level and put some storage there. I suggest
-the easiest way to do this will be to “b”, “build” a “C”
-“construction”, that is, an up-stair. So chose the space I highlight
+the easiest way to do this will be to :kbd:`b`, build a :kbd:`C`
+constructed up-stair. So chose the space I highlight
 below, and then follow along!
 
 .. image:: images/dftutorial79.png
@@ -48,9 +49,9 @@ below, and then follow along!
 
 Find the spot in the picture above, just below those down stairs.
 
-* Hit “b”.
-* Hit “C” (capital ‘c’).
-* Hit “u” for “Up Stair”.
+* Hit :kbd:`b`
+* Hit :kbd:`C` (:kbd:`Shift`-:kbd:`c`)
+* Hit :kbd:`u` for :guilabel:`Up Stair`.
 * Chose some stone.
 * Repeat to set three up stairs to be built.
 
@@ -59,19 +60,19 @@ Once the job is done you’ll have some stairs like this:
 .. image:: images/dftutorial80.png
    :align: center
 
-Now we want to “connect” this level to the one above. If you go up a
+Now we want to connect this level to the one above. If you go up a
 level you won’t see anything but dirt, but we know the stairs are
 leading up to this level, so it’s a matter of constructing some, right?
 WRONG! We want to designate some stairs, because our miners will carve
-out some matching stairs! We only use “construct” when we’ve got an
+out some matching stairs! We only use :guilabel:`Construct` when we’ve got an
 empty space to deal with.
 
 One challenge you’ll face is working out where on the floor above the
 spot is you need to dig out. So try this technique:
 
-* Hit “d”.
-* Hit “i” for “Up/Down Stair” (we want a series of stairs almost back
-  up to the surface).
+* Hit :kbd:`d`
+* Hit :kbd:`i` for :guilabel:`Up/Down Stair`
+  (we want a series of stairs almost back up to the surface).
 * Put your X over the top stair in the line, like the screenshot
 
 .. image:: images/dftutorial81.png
@@ -85,10 +86,10 @@ spot is you need to dig out. So try this technique:
    :align: center
 
 You’ll note I wasn’t quick enough when I took this picture and two of
-my three stairs are already dug out. Good dwarfs!
+my three stairs are already dug out. Good dwarves!
 
 With the new stairs dug out (providing easy access to all the space
-we’re going to create for our production dwarfs) lets make a massive
+we’re going to create for our production dwarves) lets make a massive
 space for them to stockpile goods. Here’s how much I dug out:
 
 .. image:: images/dftutorial83.png
@@ -100,7 +101,7 @@ this layer is), is that it doesn’t leave any messy rock around to
 clutter up our nice stockpiles!
 
 While that’s completing, lets start an important job, making our dining
-room awesome! You see, dwarfs love to spend time in an attractive
+room awesome! You see, dwarves love to spend time in an attractive
 meeting hall. Right now mine is packed with loafers. They clearly need
 a bit more room! A bit of digging will sort that:
 
@@ -110,23 +111,23 @@ a bit more room! A bit of digging will sort that:
 Once the room is expanded, fit doors and some more tables and chairs.
 Once that’s done you’ll need to do something important, and that’s
 resize the room. As you may remember we set the room up from one of the
-tables. But if you “q” over the dining room table now you’ll see it
+tables. But if you :guilabel:`q` over the dining room table now you’ll see it
 doesn’t fill the space:
 
 .. image:: images/dftutorial85.png
    :align: center
 
-The room will be more “valuable” and widely used if it’s set to be
+The room will be more valuable and widely used if it’s set to be
 bigger, to fill this space. Lets do that now:
 
-* Hit “q” and move the X over the table which is setting the room up…
-* Hit “r” for “Resize Room”.
-* Using “alt”+”down arrow” expand the room size till you fill the space:
+* Hit :kbd:`q` and move the X over the table which is setting the room up…
+* Hit :kbd:`r` for :guilabel:`Resize Room`.
+* Using :kbd:`=` expand the room size till you fill the space:
 
 .. image:: images/dftutorial86.png
    :align: center
 
-* Hit “enter”
+* Hit :kbd:`Enter`
 
 Job done! The room is resized and better. But we want to make it MUCH
 better because I noticed a dwarf with a red down arrow flashing and
@@ -136,10 +137,10 @@ surroundings. Lets get to impressing him!
 How do we do that? Simple! We smooth the walls and then engrave them
 with fine carvings all about our fortress! To do this:
 
-* Hit “d”.
-* Hit “s” for “Smooth Stone”.
-* Select the entire dining room and walls using “enter”, move cursor,
-  “enter”.
+* Hit :kbd:`d`.
+* Hit :kbd:`s` for :guilabel:`Smooth Stone`.
+* Select the entire dining room and walls using :kbd:`Enter`, move cursor,
+  :kbd:`Enter`.
 
 The room will now look all flashy like this (until you back out of the
 menu, anyway):
@@ -147,13 +148,13 @@ menu, anyway):
 .. image:: images/dftutorial87.png
    :align: center
 
-Any dwarf with the “Stone detailing” labour on will now set about
+Any dwarf with the :guilabel:`Stone detailing` labour on will now set about
 smoothing the walls and floors. The next step, once the space is
-smooth, is to designate the room to be engraved using “d” and “e”.
-Engraved walls make dwarfs happy and increase the value of your
-fortress. You can even look at them by using “k” and hitting enter with
+smooth, is to designate the room to be engraved using :kbd:`d`, :kbd:`e`.
+Engraved walls make dwarves happy and increase the value of your
+fortress. You can even look at them by using :kbd:`k` and hitting enter with
 the engraving highlighted. Some walls have some quite amusing
-engravings (randomly generated and based on the history of your dwarfs
+engravings (randomly generated and based on the history of your dwarves
 and your fortress), so it’s worth looking around and finding the good
 ones. The better the quality of the engraving the more text there is to
 read, so keep an eye out for the engravings with the metal-bars icon
@@ -171,7 +172,7 @@ Pretty complete huh? Well, almost, I’m sort of tempted to make a stone
 pile and using custom settings have it as metal ores only. It would
 make things a bit tidier, but on the other hand probably doesn’t gain
 me that much efficiency right now. Be very careful with stone
-stockpiles, hauling stone can consume a heap of your dwarfs’ time,
+stockpiles, hauling stone can consume a heap of your dwarves’ time,
 which is a bit pointless.
 
 Hotel Califortress!
@@ -182,11 +183,11 @@ fortunately?) you’ve probably had a bunch of immigrants arrive over the
 course of the past couple of tutorials and they haven’t been assigned
 anywhere to live. We also don’t have any space dug out for the
 inevitable arrival of nobles, and these boys and girls are one set of
-dwarfs that need hard work to keep happy!
+dwarves that need hard work to keep happy!
 
 Fortunately we’ve dug down a few levels and we have a lot of nice rock
 down there. So lets go take some time to lay out some great bedrooms
-for our dwarfs. The majority of your rooms should be 2×2, but lets make
+for our dwarves. The majority of your rooms should be 2×2, but lets make
 some space for nobles too.
 
 Nobles usually want two-to-four rooms. So lets make things easy and
@@ -202,7 +203,7 @@ connect it up later once we’ve got the left side done. Second, my
 layout is pretty boring, go and check out some of the bedroom designs
 on the wiki. I love the fractal pattern! Very efficient! Finally,
 you’ll notice the big wide corridors for the main arterial routes.
-Dwarfs need space to move around, remember!
+dwarves need space to move around, remember!
 
 Also, remember that you will need a lot of new doors and beds for our
 beautiful hotel. While you’re at it, build a ton of tables and chairs
@@ -213,75 +214,17 @@ built way back in tutorial 1 or 2) with this level as well. Construct
 down stairs from the workshop floor and then designate Up/Down stairs
 till we’re all connected up.
 
-While that is being built (oh, we’re going to find some jems too,
-cool!) lets continue with…
+While that is being built (oh, we’re going to find some gems too,
+cool!) lets continue with-
 
-The Joy of Traps!
-=================
-Traps form the majority of many people’s defences, so it’s best we get
-sorted and make some. First up, we will need a lot of mechanisms, so go
-find that mechanic’s workshop and fill it’s job queue with mechanisms.
-They’ll end up in a finished goods pile when done.
+Dwarves and their strange moods!
+================================
+Oh dear! Something is going down in dwarf land!
 
-Next, go to the Carpenter’s workshop and add a ton of cages (“j” is the
-shortcut from the “Add Task” menu). Try and get ten built. Add another
-carpenter’s workshop to your workshop floor if you fancy, makes it
-easier to queue up more than a few of any item and get things made
-faster.
+    :guilabel:`Endok Oltarisos, Tanner, withdraws from society...`
 
-While you’re at it, queue up a bunch of booze at the still too, we
-don’t want to run out, ok!
-
-Now would be a good time to go fiddle with Dwarf Manager. Sort out your
-profession groups, make sure your diggers have no job other than
-diggers and your masons and stone details are doing nothing but those
-jobs, after all, we want them to stay on task and not get distracted,
-right? Set all the peasants to haul jobs only, remove all hauling jobs
-but food hauling from your farmers, you get the picture!
-
-Here’s how I’ve got my lads and ladies sorted:
-
-.. image:: images/dftutorial90.png
-   :align: center
-
-Couple of interesting points. First up, I’ve got 14 dwarfs assigned to
-the “Pleb” profession: All they do is haul stuff. The others are
-grouped around certain jobs – farming, crafting, digging, masonry/stone
-detailing, etc. In a few situations, for example, my “Foody” class, I
-have a dwarf who is good at cooking and another who is good at brewing,
-and to make life easier I’ve turned on both jobs for both dwarfs.
-Eventually they’ll be great at both, and it saves me a little admin
-with dozens of production classes. I engage in this sort of
-rationalisation frequently in my dwarf management.
-
-I’ve also got four dwarfs set to farm, and they only farm and haul
-food, nothing else. With nothing to distract them they will fill the
-fields with crops! I’ve also got at least one dwarf in there who has no
-farming skill, it’s never to soon to start training them up though!
-
-With so many dedicated haulers I can afford to leave some dwarfs to
-specialise in these various production tasks. But be careful of having
-to many dwarfs who aren’t doing anything, idle hands are the devil’s
-plaything, after all! Dwarfs with no jobs will eventually get bored and
-throw parties that tie up lots of time and dwarfs. If your dwarfs have
-little to do, set a few making stone blocks (blocks make any item made
-out of them more valuable and can also be stacked in bins, a great way
-to remove stone clutter) or have them out their harvesting plants,
-smoothing stone or whathaveyou. No need to have them lazing about!
-
-Hang on a second.. weren’t we meant to be talking about traps? Yes! I
-think we were! So, with cages and mechanisms built lets get on and make
-some cage traps…
-
-Dwarfs and their strange moods!
-===============================
-…or not! Oh dear! Something is going down in dwarf land!
-
-.. image:: images/dftutorial91.png
-   :align: center
-
-If you get a dwarf in a strange mood, find them using “u”, looking for
-their name, and then “c”. You will see the dwarf flashing with a grey
+If you get a dwarf in a strange mood, find them using :kbd:`u`, looking for
+their name, and then :kbd:`c`. You will see the dwarf flashing with a grey
 exclamation mark (red is very bad, by the way). Follow this dwarf
 closesly. This dwarf has got a strange mood and is off to claim a
 workshop to start building some amazing object based on their whim and
@@ -294,12 +237,12 @@ sooner or later.
 
 Right, my dwarf, Endok Oltarisos has rushed off to claim a leather
 workshop. No surprise, he’s a tanner after all. Once he claims the
-workshop you can “q” and see the status of the workshop, and if you
+workshop you can :kbd:`q` and see the status of the workshop, and if you
 wait, it will scroll through what items the dwarf is looking for. Endok
-is looking for “stacked leather” and “skeletons”. I’m not sure if I’ve
-got any. I’ll find out pretty quickly though, the dwarf will either run
-off and start fetching stuff, or sit in the workshop, seemingly doing
-nothing…
+is looking for :guilabel:`stacked leather` and :guilabel:`skeletons`.
+I’m not sure if I’ve got any. I’ll find out pretty quickly though,
+the dwarf will either run off and start fetching stuff, or sit in
+the workshop, seemingly doing nothing…
 
 .. image:: images/dftutorial92.png
    :align: center
@@ -309,36 +252,30 @@ and the bones, I think he’s grabbed some from the refuse pile.
 Thankfully, my worries about the dwarf not getting stuff are put to
 rest when I get this message:
 
-.. image:: images/dftutorial93.png
-   :align: center
+    :guilabel:`Endok Oltarisos has begun a mysterious construction!`
 
 Endok has begun a mysterious construction! Great! Now we just wait and
 see what crazy object the dwarf produces. With luck it will be useful!
 
-.. image:: images/dftutorial94.png
-   :align: center
+    :guilabel:`Endok Oltarisos, Tanner, has created Modonnokoi, a dog
+    leather cap!`
 
 ..or maybe not! Our dwarf has made a cap, a simple hat, out of dog
 leather! Damn! On the plus side though the dwarf has become a legendary
 tanner. If they gain skill from a mood it often leaves them
-“Legendary”, which is pretty neat. With legendary skill I could use
-Endok to make leather armour and it would be as good as metal armour,
-handy.
+Legendary, which is pretty neat. With legendary skill I could use
+Endok to make leather armour and it would be almost as good as metal armour.
 
-Lets look at the item. If we hit “l” we get a “list” of artefacts. With
+Lets look at the item. If we hit :kbd:`l` we get a list of artefacts. With
 only one artefact there’s no list, so we can go straight in to hitting
-“v” to “View”.
-
-Behold! Triberiddle, the dog leather cap (click on the picture here if
-you can’t read the text)!
+:kbd:`v` to :guilabel`View`. Behold! Triberiddle, the dog leather cap!
 
 .. image:: images/dftutorial95.png
    :align: center
 
 A nice hat depicting when one of the trade caravan guards shot a
-goblin. No one will wear it though, it’s an :wiki:`artifact`, only
-champions consider themselves important enough to grab artifacts from
-stock piles.
+goblin. No one will wear it though, it’s an :wiki:`artifact`, and only
+champions are important enough to grab artifacts from stockpiles.
 
 We were lucky this time with our moody dwarf. He was able to get
 everything he needed to make his artifact. If he couldn’t find it he
@@ -348,14 +285,13 @@ available, in his room. When you see the dwarf start to go crazy
 sign) it’s time to either assign the dwarf some war dogs (more on that
 later) or to construct some walls and wall them in to their workshop,
 or to lock the door on their quarters. At some point the dwarf will go
-beserk and either get attacked by nearby military dwarfs or war dogs,
+beserk and either get attacked by nearby military dwarves or war dogs,
 or if locked inside, slowly starve to death.
 
 If the crazy dwarf is ignored they will destroy stuff and attack
-dwarfs, probably killing a couple before they are put down, so watch
+dwarves, probably killing a couple before they are put down, so watch
 those moody stunties closely!
 
-…Hang on a second, weren’t we supposed to be doing something about
-traps? Bugger! We’re out of time. How about next time? OK? Seriously? I
-really promise we’ll get to traps, ok!
+In the next chapter, we'll cover traps - which are used to 'mine' a
+kind of iron ore the community calls "goblinite".  See you then!
 

chapters/chap08-defences-traps.rst

@@ -3,10 +3,16 @@ It's a trap!
 ############
 
 
-I promised traps, and damn traps we will have! And not of the Star Wars
-or Thai kind, but of the Dwarf Fortress kind! I’m two bottles of beer
-and a glass of absinthe into the evening, so lets get on with it before
-things get worse!
+Traps form the majority of many people’s defences, so it’s best we get
+sorted and make some. First up, we will need a lot of mechanisms, so go
+find that mechanic’s workshop and fill it’s job queue with mechanisms.
+They’ll end up in a finished goods pile when done.
+
+Next, go to the Carpenter’s workshop and add a ton of cages (:kbd:`j` is the
+shortcut from the “Add Task” menu). Try and get ten built. Add another
+carpenter’s workshop to your workshop floor if you fancy, makes it
+easier to queue up more than a few of any item and get things made
+faster.
 
 Defence and Traps!
 ==================

misc/contributing.rst

@@ -81,7 +81,7 @@ Style
 -----
 Use clear, direct, and simple language.  Avoid jargon or the passive voice.
 I find the `hemmingway editor <http://www.hemingwayapp.com>`_ useful;
-I often ignore but always conside it's suggestions.
+I often ignore but always consider it's suggestions.
 
 Keep all lines to 80 characters or less.  Sphinx will automatically join
 everything between blank lines into one paragraph, and short lines
@@ -134,7 +134,7 @@ TODO list
 items may be done in other orders for whatever reason.*
 
 #. Update all content for DF2014.  Preferably *before* the next DF release
-#. Use ``:kbd:`` and ``:guilabel`` roles everywhere; see chapter one and two
+#. Use ``:kbd:`` and ``:guilabel:`` roles everywhere; see chapter one and two
 #. Update all images and make sure descriptions match
 #. Run everything through Hemmingway
 #. Make usage / reading a nicer experience for new players