= bookingit

A basic publishing system that takes Mardown and Git repositories and produces a readable "book" in the following forms:

* Website
* PDF
* EBook

The idea is that you can show the evolution of code by referencing particular versions or diffs beteween verions.  Further, you can show the actual output of commands run from particular verisons of the repo.


== Example

Let's say we have a Rails app locally in a git repo called "foobar".  We coudl write the following:

    Here is how our controller looks currently:

        git://foobar.git/app/controlleres/users_controller.rb#initial-version

    We'd like to change the mailer call to use Resque

        git://foobar.git/app/controllers/users_controller.rb#initial-version..add-resque-to-controller

Instead of interpreting the code blocks as verbatim text, bookingit notices the single-line URL and will read the file or diff based on it, and substitute that into the output.  It would be the same as if we wrote our Markdown like so:

    Here is how our controller looks currently:

    ```ruby
    class UsersController < ApplicationController::Base
      def create
        @user = User.new(params.require(:user))
        if @user.save
          UserMailer.welcome_email(user).deliver
          redirect_to root_path
        else
          render 'new'
        end
      end
    end
    ```

    We'd like to change the mailer call to use Resque

    ```diff
    --- a/app/controllers/users_controller.rb
    +++ b/app/controllers/users_controller.rb
      def create
        @user = User.new(params.require(:user))
        if @user.save
    -     UserMailer.welcome_email(user).deliver
    +     Resque.enqueue(WelcomeEmailJob,user.id)
          redirect_to root_path
        else
    ```

Here is what is currently supported:

* <code>git://some_repo.git/path/in/repo.rb#sha1_or_tag</code> - show the contents of the file from the git repo at the given version (either SHA1 or tag)
* <code>git://some_repo.git/path/in/repo.rb#sha1_or_tag..other_sha1_or_tag</code> - show a diff of the contents of the file between the two versions.
* <code>git://some_repo.git/path/in/repo.rb#..other_sha1_or_tag</code> - shortcut for showing a diff between the given SHA1 or tag and the previous revision.
* <code>git://some_repo.git/#sha1_or_tag!rake test</code> - check out the repo at the given SHA1 or tag, then run the command after the bang, and include the output of that command in the text
* <code>sh:///some/filesystem/path#ls -l</code> - cd to the given path, run the command, and include its output in the text.

The paths used can be relative (e.g. <code>git://some_repo.git</code>) or absolute (e.g. <code>git:///some/other/repo.git</code>).  Relative paths are relative to the directory where ran +bookingit+.  You can change where the git repos are located by setting +git_repos_basedir+ in your config (see below).

For URLs that contain shell commands, +bookingit+ will fail if the shell command fails, because the assumption is that your embedded commands are expected to succeed (exit 0).  If you need to run a shell command that is expected to fail (e.g. demonstrate a failing test case), append <code>!nonzero</code> to the URL, e.g. <code>git://some_repo.git/!rake test!nonzero</code>.  In this form, +bookingit+ will fail if the command _succeeds_.

=== Configuration

The book's configuration is driven by +config.json+, which looks like so:

    {
      "front_matter": [
        "intro.md"
      ],
      "main_matter": [
        "chapter1.md",
        "chapter2.md"
      ],
      "back_matter": [
        "appendix.md"
      ],
      "rendering": {
        "stylesheets": "styles.css",
        "git_repos_basedir": "./git_repos",
        "languages" : {
          ".super": "superscript",
          "/Makefile": "make"
        }
      },
      "templates": {
        "index": "/full/path/to/index/html"
      }
    }

The book's contents are described in +front_matter+, +main_matter+, and +back_matter+.  The values of these can be a single file or an array of files.  The likely pattern is that you would have a single entry for +front_matter+, an array in +main_matter+ for each chapter, and an optional +back_matter+ for things like appendeces or a colophon.

Example:

    {
      "front_matter": "intro.md"
      "main_matter": [
        "chapter1.md",
        "chapter2.md",
        "chapter3.md",
        "chapter4.md"
      ],
      "back_matter": "appendix.md"
    }


The +rendering+ section allows some control over the rendering process.  It supports three keys:

+git_repos_basedir+:: path to where your git repos are, for bringing in code.  For example, if you specify the value "./repos", then a url like <code>git://my_repo.git/foo/bar.rb#version-1</code> would look in <code>./repos/my_repo/foo/bar.rb</code> for the file contents.  This path should be relative to where you run +bookingit+.
+languages+:: A map of file extensions or regexps to language names for syntax detection.  If the key starts and ends with a +/+, it will be interpreted as a regexp, otherwise as a file extension
+stylesheets+:: An array of stylesheets that will be copied and linked to each HTML page
+syntax_theme+:: A highlight.js name for the syntax highlighting theme to use.

The +templates+ section allows you to specify a Mustache template for various bits of the generated markup.  The files listed must be full-qualified paths and must omit the <code>.mustache</code> extension, which must be present on the file (e.g. if you specify <code>/tmp/foo.html</code>, the file should be located in <code>/tmp/foo.html.mustache</code>.

Current templates are:

+index+:: The template of the main home page or splash page.  See the built-in one for values you have access to.

In addition to values provided by bookingit, you can specify any values you want in your <code>config.json</code> file and they will be available in your templates under the +config+ namespace, e.g.:


    {
      "front_matter": "intro.md"
      "main_matter": [
        "chapter1.md",
        "chapter2.md",
        "chapter3.md",
        "chapter4.md"
      ],
      "back_matter": "appendix.md",
      "templates": {
        "index": "/tmp/foo.html"
      },
      "title": "My Great Book!",
      "subtitle": "A long journey from Milan to Minsk"
    }

Then, in <code>/tmp/foo.html</code>

    <html>
      <body>
        <h1>{{#config}}{{title}}{{/config}}</h1>
        <h2>{{#config}}{{subtitle}}{{/config}}</h2>
      </body>
    </html>

There are a few other options that control content:

+clicky+:: If present, the +id+ attribute will be used to set up Clicky tracking
+typekit+:: If present, the +id+ attribute will be used to insert the TypeKit boilerplate
+favicon+:: If set to +true+, will include <code>/favicon.ico</code> meta tag in your output
+applie-mobile-web+:: If set to +true+, will include a few meta tags that help the app work in "bookmarked to the homescreen" mode