Bookchef

A library to convert bookchef.xml file tree into an actual book (currently HTML and PDF are supported). bookchef.xml is A VERY SIMPLE xml format that I designed to write books. Yes, I've actually written and successfully published a book with it.

Installation

1. Install wkhtmltopdf as explained in this Wiki. It's a utility that converts html to pdf that Bookchef is going to need.

2. gem install bookchef

Now a bookchef command is available on your system. Type it to see a short summary on how to use it. You will be able to do everything from the command line, but, of course, you may load necessary classes in your ruby program.

Bookchef XML basics

Once I decided to write a book. I didn't want to use any propritary software -- I wanted to use git, my text-editor and a simple xml format (and I mean, really simple) that you can write by hand, so that later I could maybe build some kind of gui-editor around it. In order to make git useful, I realized that each chapter and each section of the chapter should be in a separate file and a seperate directory. Thus we have <chapter> and <section> tags, each may or may not have an src= attribute. Here's an example:

<book>
  <chapter>
      <section src="section1.xml"/>
      <section src="section2.xml"/>
      <section>And this one doesn't have a seperate file</section>
  </chapter>

  <!-- Automatically loads chapter2/index.xml
  if file name is not specified, e.g. doesn't end on .xml -->
  <chapter src="chapter2"></chapter>
</book>

Because chapters and sections may be in seperate files, it will be much easier to parse git diffs in the future, when and if this gui editor arrives. Also, it makes it easy to to manually navigate through the book with just your text editor. Assuming this file is called index.xml (and for now it is a requirement for a file which contains a <book> tag) I don't recommend using any kind of internal links (like footnotes and references, see below) in this file, because for now they will be broken. index.xml in the root book directory should source all the parts from other files.

Within the book, you may use various elements, listed below:

• <title> may appear once within a chapter or a section, but doesn't have to. While compiling, each chapter automatically gets a number before its title
• <code-inline> allows you to include an inline code
• <code> allow a multi-line block of code. Remember that within it other tags don't work.
• <p> is self-exlpanatory
• <term> - wrap a term with it, with standard styles used by compiler the text will appear in italics.
• <filename> is used to indicate either a filename or a url (when it's not supposed to be clicked, for example in the case of http://localhost:3000)

Then we also have two special blocks that may appear at the bottom of each section, which are called <references> and <footnotes>. Here's how it may look:

  
  
Minimum wage doesn't work because people getting jobs for this wage are doing so at the expense of all others who didn't get the same job, when employers were either unable to pay for that many employees or simply went out of business. Or, they may indeed comply with the law and hire just the same number of employees, in which case they simply redistribute these costs on their customers, who then redistribute these costs on their employers demanding more pay and the circle continues. This circle inevitably causes either inflation or loss of demand. Thus, minimum wage always has its costs, but those costs are not payed by people who are expected to pay.
  
  
    By raising prices
    People either start demanding more pay, causing businesses to borrow more from banks or, if it's government employees, causing government to print more money.
  
  
  
    Article about minimum wage on Wikipedia
  
  


As you can see, we referenced both footnotes and references by wrapping some text in `` tags and using either a `footnote=` or `reference=` attributes. In fact, you can add those attributes to other tags, not just ``, but also `` or ``. It will look like this when compiled:

![bookchef_compiled_example](https://github.com/snitko/frontend_notifier/raw/master/bookchef_compiled_example.png)

Of course, readers are able to click the links and go straight to the footnote or the reference they chose.

You can also link to other chapters and sections which are placed in a separate file, for example:

we discussed this in the chapter on supply and demand

or you can even say this

we discussed this in the chapter on 
  
in which case the content in the `