runemadsen / magic-book-project

DEPRECATED: We are reviving the Magic Book project as a node package: https://github.com/magicbookproject/magicbook

What is this project?

The Magic Book Project is an open-source framework that facilitates the design and production of electronic and print books for authors.

Here’s a circa-2008 scenario for you. An author is excited to hear that a big company has decided to publish his or her book. The author sits down and types a lot of text into Microsoft Word. The publisher takes that text and “typesets” it using Adobe InDesign, painstakingly laying out each individual page by hand. To market the book, the author decides to post an excerpt from the book online as HTML and performs an elaborate contortion of copying/pasting and reformatting. The book is published and is offered for sale for fifty dollars. An ebook is also for sale for fifty dollars. The author receives a few dollars when a book is sold. Anyone on the internet, however, can easily download a free, illegal PDF version of the book.

See any problems with this scenario?

This is is the impetus behind the Magic Book Project, developed by a small team of ITP faculty, researchers, and students. The Magic Book Project seeks to help authors self-publish in variety of formats, making books available to the widest audience possible at the cheapest prices.

Rather than type into a word processor, the Magic Book Project allows an author to write a book once (using ASCIIDOC, a simple text document format) and procedurally generate the layout for a variety of formats using modern code-based design tools, such as CSS, the stylesheet standard. Write your book once, press a magic button, and out come multiple versions: printed hardcopy, digital PDF, HTML, MOBI, and EPUB.

Installing the App

1. Clone this repository

    $ git clone https://github.com/runemadsen/Magic-Book-Project.git
    $ cd Magic-Book-Project
   

2. Use Ruby 1.9.3. To manage multiple rubies, install either RVM, rbenv, or chruby.

3. Run bundler to install gems (if you don't have bundler do $ gem install bundler).

    $ bundle install
   

   One of the gems we use, Nokogiri, has some system pre-requirements. Under Ubuntu 12.04, before you run bundle install you need to install the development libraries for xml and xslt with

    $ sudo apt-get install libxml2-dev libxslt1-dev
   

   On Mac OS X Mountain Lion with XCode 4.5.2 Developer tools, in order to get Nokogiri to work, I had to do the following before bundle install:

    $ sudo ln -s /usr/bin/gcc /usr/bin/gcc-4.2
    $ brew install libxml2 --with-xml2-config
    $ brew link libxml2
    $ gem install nokogiri -- --with-xml2-include=/usr/local/Cellar/libxml2/2.8.0/include/libxml2/ --with-xml2-lib=/usr/local/Cellar/libxml2/2.8.0/lib/ --with-xslt-dir=/usr/local/Cellar/libxslt/1.1.26/
   

4. We are using a custom build of the asciidoc gem. To keep track of changes to this gem use git submodules. From the root of the repository run the following two commands to initialize the submodule and then get any updates.

    $ git submodule init
    $ git submodule update
   

5. Now you need the asciidoc program. We recommend installing asciidoc with homebrew. Once you have homebrew installed get the asciidoc keg like so

    $ brew install asciidoc
   

   Under Ubuntu, you'll need to install asciidoc with

    $ sudo apt-get install asciidoc
   

Notes

If your book will include code blocks you'll need to install pygments for syntax highlighting.

    $ sudo easy_install Pygments

Under Ubuntu, it's probably better to install it as a system package:

    $ sudo apt-get install python-pygments

To run the app

1. cd Magic-Book-Project
2. shotgun config.ru
3. Then visit in your browser one of these urls:

• localhost:9393/create_html/:filename

• localhost:9393/create_html_chapters/:filename

• localhost:9393/create_pdf/:filename

  where :filename is the path to an .asc, .asciidoc or .txt file.

  Note: For the time being, the asciidoc gem uses Prince XML for PDF rendering (we are using this until we find a good, open-source HTML to PDF renderer). If you want to produce PDF output, you'l need to download and install it from http://www.princexml.com/download/.

If it's been a while since you've used this app, update the asciidoc gem by running $ git submodule update.

magic-book-project's Issues

PDF: letter-spacing doesn't work

Letter are too close, and the css letter-spacing property doesn't make an effect.

code comment formatting loss of line breaks

we are losing some line breaks when the code gets formatted, i.e.

background(255);

// Move the ball according to its speed.
x = x + xspeed;

turns into

background(255);
x = x + xspeed;   ---------- Move the ball according to its speed.

instead of

background(255);

x = x + xspeed;   ---------- Move the ball according to its speed.

Wrap book sections in DIVs

Multiple parameters for image/canvas

Some images will need to have multiple parameters, i.e. class for styling as well as JS files for canvas version, etc. Something like:

image::imgs/chapter01_2-01.png[canvas="processingjs/bouncingball_novectors.pde"][classname="half-width"]

Are illustrations the right size?

The illustrations were made for print.

6 inches for full-width and 2.875 for half-width. (300 DPI) All fonts 12 point.

However, we are also using them for HTML: 800 pixels for full-width etc. A test render:

http://www.learningprocessing.com/noc/tests/chp1/index.html

Do we need to deal with resizing the type for these pixel dimensions?

@runemadsen @stevenklise @evanemolo @luisaph

Fix breakout box

ability to override CSS

use HTML css as basis for PDF etc

"Fill in the blanks"

I have a couple exercises which are "fill in the blanks", i.e. write this function that limits the length of a vector:

[source,java]
----
  void limit(float max) {
    if (_______ > _______) {
      _________();
      ____(max);
    }
  }
----

There are only a couple of these so it's not worth going crazy to accomodate them. But something to consider regarding specific style for these (maybe just code block with larger font size).

Implement internal links and figure out page stuff

Implement headers

show raw button hide or modify design?

the show raw button is fantastically amazing! but sometimes it seems unnecessary (one line of code) and causes the code block to take up a lot of additional space. so maybe we play around with different css design or add an option to hide it for some blocks of code.

add background and padding to code blocks

The following CSS rule looks nice but messes up the comment layouts.

.code-block code {
    background-color: #fafafa;
    padding: 2em;
}

We need to find a way to add those two styles but not conflict with current styling and layout...

Implement include files

Illustration/Image/Canvas captions

We need support for captions

Move Magic Book cheatsheet to github wiki

Reset button for canvas elements

Implementing lazy loading (Issue #29) should help, but would be nice to have a little reset button for every canvas that would allow the user to restart the sketch.

Subsection Heading doesn't seem to work

A section heading looks like:

==Section 1.1: Vector Math

But I also have subsection headings

===Vector subtraction

This doesn't seem to work at the moment? (See Chapter 1, ===Vector Subtraction) in shiffman branch (haven't pushed yet)

Need class for image not container?

Not sure about this one, but let's say I want a border around the image only, not the container (i.e. the border does not encompass the caption). Right now the HTML output is:

<div class="image-container screenshot">
    <img src="imgs/intro/intro_08.png" alt="Noise vs. Random">
    <p class="caption">Noise vs. Random</p>
</div>

I think what I need is:

<div class="image-container">
    <img src="imgs/intro/intro_08.png" alt="Noise vs. Random" class="screenshot">
    <p class="caption">Noise vs. Random</p>
</div>

Unbulleted list with tight vertical spacing

This is probably a simple CSS thing, but just making a note of it. Also, not sure how we should do ASCIIDOC markup for this. ASCIIDOC currently looks like:

translates to:

- [var]*w*~x~ = [var]*u~x~* + [var]*v~x~*
- [var]*w*~y~ = [var]*u~y~* + [var]*v~y~*

The output looks like:

translates to:

  * wx = ux + vx

  * wy = uy + vy

I want it to look more like:

translates to:

    wx = ux + vx
    wy = uy + vy

All boxes same class type --> example?

I was playing around with styling the exercises and breakout boxes differently and they look like they are all contained in the same div type called "example". Maybe we should refactor and have these be different? I like the convention of "exercise", "note", "tip" as three different options. The name "example" is confusing b/c the examples are something different, in nature of code at least.

Vector notation

Need to figure out a way to deal with math / vector notation in ASCIIDOC

Code block formatting

Can we have support for custom formatting some lines of code, i.e. making them bold, etc. This might be something that would only happen for b&w print when there is no syntax highlighting?

Code info bubbles

Table of Contents

Move all ASCIIDOC files to repo from dropbox

Spacing issue if canvas follow code block

horizontal scrollbars with code (sometimes)

i have no idea why but sometimes horizontal scrollbars show up with the code blocks (when there are comments). can't figure out why.

Integrate Illustrations, Chapters 1-10

@evanemolo or @luisaph I have PNG / illlustrator versions of all the illustrations for chapters 1-4 and the intro. I integrated a the first 7 or 8 into 01_vectors.asc but we can start pulling in more for further tests. Let me know if either of you have time/interest to try working on this and I can share the files.

JavaScript Lazy Loading

See: http://processingjs.nihongoresources.com/bezierinfo/ for an example

Check all lists

weird things not working (formatting) in lists and blockquotes, also not working with tabbed items

Copy/paste code blocks

With the way we are reformatting the code to have the comments along the side, it is not easy to copy/paste a block of code directly into Processing. We should integrate a "copy to clipboard" (or something) button that copies the code before the comments are parsed out?

Create Magic Book Site

We'll need a basic site with:

• project info
• tutorial
• sample templates

this can come later, but just putting it here now to remind ourselves.

Canvas with multiple PDE files

It'll be easier to add examples running in canvas if we can support multiple PDE files with Processing.js

syntax highlighting makes rendering super slow

is it going to network for pygments?

Option for specifying image layout

When an image (or canvas) is added, we need to specify some parameters for its styling (i.e. full width or half width).

Box2D and Toxiclibs JS

get canvas working for box2d and toxiclibs examples

Table Markup?

I was playing around with reformatting a section of Chapter 1 as a table and used the markup from the cheatsheet

Table "[options=""header,footer""]
|=======================
|heading |heading | heading
|field   |field   |field
|field   |field   |field
|=======================

Am just getting:

<p>Table "[options=""header,footer""]</p>
<p>heading</p>
<p>heading</p>
<p>heading</p>
<p>field</p>
<p>field</p>
<p>field</p>
<p>field</p>
<p>field</p>
<p>field</p>

output though. do we have it wrong?

cc @evanemolo

tables require heading

tables don't work unless they have a heading. which is fine with me as long as we can hide the heading?

.need a header
[options="header,footer"]
|=======================
|Flip 1 |Flip 2 |Result.
|Heads  |Heads  |Step forward.
|Heads  |Tails  |Step right.
|Tails  |Heads  |Step left.
|Tails  |Tails  |Step backward.
|=======================

Support underlined text

How do we support underlined text with ASCIIDOC markup? (doesn't seem to be an option in the cheatsheet)

code comment placement in PDF render

The code comment placement is a little off in the PDF render, too low and spacing is weird. this will be a challenge as 6 inches is not a lot of room to work with.

Support strikethrough text

How do we support strikethrough text with ASCIIDOC markup, doesn't seem to be an option in the ASCIIDOC cheatsheet?

Implement self-referencing in chapter 1 and test it

PDF dimensions

@runemadsen i know you fixed this yesterday, but is it checked in? My PDF is rendering to 8.26x11.69

Custom formatting for "kinds" of text (function, variables, etc.)

Can we support a view for text labeled in a custom way, i.e.

[function]#setup()#
[var]#x#

Even though all functions might be, say, bold, we don't want to mark them up as bold in case we later decide all functions should be italicized or monospaced font, etc.

Implement tables

Should be able to have code in them

Implement footers

Add Class to Block Level element in ASCIIDOC

In response to wanting to have bulleted lists with different styling (Issue #51).

I actually don't know if this is already possible, but if it is, we get to close another issue.

GUI for Canvas Elements or DatGUI

figure out how to get datgui working with JS sketches (or some other interface)

Make Processing.js work

Implement page-break attribute