This is a starter project for people looking to make a "Learn X The Hard Way" book. If you want to have a book for your favorite language, and you like the style of "Learn Python The Hard Way" and "Learn Ruby The Hard Way", then this kit will get you started quickest for the best results. I've developed this kit after using various publishing and authoring systems over the years, and I've found this to be the best for producing high quality self-published text. It does require you to learn LaTeX, but I'll be including a crash course in LaTeX that uses the features of this book kit. Getting Started =============== First thing is, you should install both tex-live and dexy. To install tex-live, follow the quick instructions [here](http://www.tug.org/texlive/quickinstall.html). As for dexy, make sure you have python installed, and then simply $ easy_install dexy You may or may not need sudo. If this doesn't work for you, check the instructions on [Dexy's site](http://dexy.it). Once you have those, try this: $ dexy --setup $ make This will produce all the gear for dexy, and then build the sample starter book into output/book-final.pdf. Go look at that book and see what is produced. Setting Up Your Book ==================== You should now probably setup whatever revision control tool you need to use. If you want to keep using git, then I suggest doing: $ rm -rf .git $ make clean $ git init . $ git add . $ git commit -am "first commit" That will make sure you get a clean git setup that is just for your book. Feel free to change the above to fit whatever system and workflow you need. Once you have this setup, you then want to edit the kit to fit your book. Here's what you need to change: 1. book.tex -- Set your own author and title settings at the top. 2. preamble.tex -- Do the same for author and title in the PDF specifics here. 3. Makefile -- Change the target host for rsyncing it to your server if you use one. Make the book again and check the resulting book-final.pdf to see your title. Structure And Initial Content ============================= Now you can lay down your structure and introduction. Here's what I suggest. 1. Write a quick introduction in the introduction.tex to get your feeling down. 2. Write your preface.tex to give some personal stuff about you, why you're writing. 3. Edit ex0.tex such that it teaches a total nobody how to install the needed gear. 4. Edit ex1.tex such that it teaches a total nobody how to print out a bunch of stuff. 5. Edit next.tex to explain where the student should go after finishing your book. Once you have this you should have a basic feel for the book, and enough content to show it to some people. Show it to a few folks and watch them try your exercises. This will tell you if you've got it simple enough. Recommended Contents ==================== I recommend for your ex0.tex install instructions you focus on the following: 1. Use just a simple editor like gedit, notepad+, or Textwrangler. NO vim! NO emacs! 2. Do *not* have them use git or other RCS tools. They're here to learn code, not git. 3. Make it work for Windows, OSX, and Linux if you can. 4. The install of your language should not involve tons of steps. For your introduction, and for the whole rest of the book, remember these points: 1. Your book should *educate* people, not *indoctrinate* them. If you find yourself talking constantly about how awesome your language is and how it will change their life, then you're not educating, you're just making another cult follower. Leave the decision of whether the language is good to the reader. 2. Read through my Introduction and give advice for learning, especially persistence and how the book is *supposed* to be hard and tedious at first. 3. Be honest about flaws and problems in your language so the reader is not discouraged when they encounter them. 4. Lightly make fun of programmers and inoculate your student against religious wars over syntax, idioms, editors, tools, and anything else that gets in the way of them learning. Remember, you are writing this book for *them*, not your fellow coder friends. 5. Make it clear that programmers are not scary geniuses. This goes a long way to encourage your readers to try to learn as it will reduce their "code anxiety". Working With Dexy ================= Dexy is fairly new, but a very good tool for this kind of work. What it does is take code for your exercises and then injects it into your .tex files in a nice pretty printed format that's publication ready. You use it like this: 1. Edit the .dexy file and put your language extension in there like I've got. The syntax is FILENAME_PATTERN|FILTER1|FILTER2, etc. For mine, I'm mostly using the pyg(pygmentize) filter. For python, it looks like this: "*.py|pyg|l": {}. *.py is the pattern of files to convert, pyg is the pygmentize filter for highlting code and "l" is the filter for converting to LaTex. 2. Put your code for each exercise in code/ named after each exercise. 3. Look at the ex0.tex that I've written which shows you how to include this code. 4. Finally, if you want to show the output of your programs, there are two ways to do this. If you want to use dexy, you can create another entry in .dexy like this: "*.py|py|pyg|l". This means, run the code through python (py), then pass the result to pyg (if you are generating HTML or xml or whatever it will be highlighted), and finally, pass to the LaTeX filter. The other low tech way is simply to put the output for each program into code as ex#.txt and include that as well. ex0.tex has both. Refer to http://dexy.it for more information on how to use it. Working With Tex ================ TeX (or actually LaTeX) may seem daunting compared to markdown or textile, but it's actually fairly easy. Get yourself one of the many LaTeX cheat-sheets out there and sit down with it to write. The things to remember are: 1. TeX assumes anything not marked up is just a paragraph of text. Write like normal. 2. Block style things, like lists and code blocks, are bounded by \begin{thing} and \end{thing}. 3. Look in commands.tex for a list of available blocks and helpers I've already written. 4. Write your own helpers for things you seem to write over and over again. The power of TeX, apart from its awesome typesetting and structure, is that you can extend it to include your own macros and time saving tricks. Steal anything you can find about it. Last Steps ========== Once you've got your voice and initial setup, I recommend that you go through and setup all the titles and the big structure of your book. Look at LPTHW to get a general idea of a good structure. Here it is in a short form: 1. Two sections split at 26 exercises. 2. First half is repetitive interactions with the computer that are immediate, with heavy focus on functions and no objects, complex data structures, algorithms, or math. 3. Second half is a sudden ramp-up in difficulty that teaches logic, OOP, data structures, and the more complex things your language features. 4. Focus on simple text adventure games as the main kind of program they make. These are fun, easy to create, immediate, and don't require any special geometry skills or graphics systems. The way to think of the book's structure is the first half gets them strong, the second half gets them skills. In the first half they're just doing push-ups and sit-ups and getting used to your language's basic syntax and symbols. In the second half they use this strength and grounding in the basics to start learning more advanced techniques and concepts, then apply them to real problems. I recommend that you create a single text file and make a basic outline of all your chapter titles to get an idea of your structure. Once you've got that kind of thought out, go through and fill in each of the ex#.tex files with the titles and a short note on what you plan to teach there. This will turn the book into an easy to follow TODO list of what to write. Then, just go through and write each one in order and change later ones as you go in new directions. Don't be a slave to your structure, but having one helps keep you motivated and organized. Publishing Your Book ==================== If you want help publishing or promoting your book, then contact me at zedshaw-AT-zedshaw.com.