README.md in reveal-ck-0.1.1 vs README.md in reveal-ck-0.1.2
- old
+ new
@@ -1,68 +1,85 @@
# reveal-ck: a [reveal.js](http://lab.hakim.se/reveal-js/) construction kit
+[](https://travis-ci.org/jedcn/reveal-ck)
+
## Overview
-The goal of this project is let you quickly author
-[reveal.js](http://lab.hakim.se/reveal-js/) presentations.
+This project is the home of a gem named `reveal-ck` that lets you
+quickly author [reveal.js](http://lab.hakim.se/reveal-js/)
+presentations.
-It enables you to author reveal.js-aware-[haml](http://haml.info/) that
-can conveniently be transformed into slides.
+The gem provides an executable of the same name, `reveal-ck`, that can
+take a single file as input and generate a set of slides from it.
+Here's a starter repository that contains everything you need to get
+going with reveal-ck: https://github.com/jedcn/reveal-ck-template in
+less than 5 minutes.
+
The hope is that you will be able to leverage all of the power,
beauty, and functionality that comes from reveal.js while focusing
entirely on the actual content and ideas you are trying to get across.
-This content will usually take the form of:
+As with all [reveal.js](http://lab.hakim.se/reveal-js/) presentations,
+you can show these to other people on an iPhone, iPad, or present them
+in your browser.
-* A file containing your slides (```slides.haml```)
-* A directory containing any images you'd like to reference relatively
- (```images```).
+### What You Provide
-And, in return for this, you will be able to create slides that can be
-placed anywhere on the web (or kept locally). As with all
-[reveal.js](http://lab.hakim.se/reveal-js/) presentations, you can
-show these to other people on an iPhone, iPad, or present them in your
-browser.
+You provide:
-Here's an example of the inputs you'd provide:
-https://github.com/jedcn/talk-learning-with-tools
+* A file containing your slide content in HAML (`slides.haml`)
-Here's an example of the output you'd get: Coming Soon
+* (optional) If you have any images that are not already on the web,
+ you can save these into a directory named `images` and the contents
+ will be bundled up into your generated slides. This will allow you
+ to relatively reference the images.
-For a full sampling of everything
-[reveal.js](http://lab.hakim.se/reveal-js/) can do, take a look at the
-[live demo](http://lab.hakim.se/reveal-js/).
-
## Getting Started
At present, we assume you've got a functional Ruby 1.9.x environment
-up and running.
+up and running one way or another and bundler.
If that's the case, try the following:
-* clone this project
-* run a ```bundle```
-* run ```reveal-ck```
+```
+$ git clone git@github.com:jedcn/reveal-ck-template.git
+Cloning into 'reveal-ck-template'...
+remote: Counting objects: 12, done.
+remote: Compressing objects: 100% (7/7), done.
+remote: Total 12 (delta 2), reused 12 (delta 2)
+Receiving objects: 100% (12/12), done.
+Resolving deltas: 100% (2/2), done.
+$ cd reveal-ck-template
+$ bundle
+Fetching gem metadata from https://rubygems.org/......
+Installing rake (10.0.4)
+Installing gli (2.5.6)
+Installing tilt (1.3.6)
+Installing haml (4.0.1)
+Installing reveal-ck (0.1.1)
+Using bundler (1.2.3)
+Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
+$ reveal-ck generate
+$ open slides/index.html
+```
-At this point, the sample ```slides.haml``` that came with the project
-will be transformed into a set of slides. You can see the result by
-opening up ```slides/index.html``` in your browser.
+If all has gone well, you should now have a `slides/` directory and if
+you open up `slides/index.html` in a browser, you should see a
+reveal.js presentation that was generated from the `slides.haml`
-If you've made it this far, you've got the basic basic functionality
-up and running.
-
## Authoring Slides
Now that you are assured of basic functionality, start making changes
-and customizing ```slides.haml```. Once you've made a change you'd
-like to see, re-run ```reveal-ck``` and then re-open (or refresh) ```slides/index.html```
+and customizing `slides.haml`. Once you've made a change you'd like to
+see, re-run `reveal-ck generate` and then re-open (or refresh)
+`slides/index.html`
[reveal.js](http://lab.hakim.se/reveal-js/) has a great
[live demo](http://lab.hakim.se/reveal-js/), and if you take a look at
-the source in the demo, you can get up and running quickly with things
-that can be placed into your ```slides.haml```.
+the source in the demo, you can quickly see the HTML and CSS that has
+good support by default when placed into your `slides.haml`.
## Why not just clone reveal.js?
Or why not use http://www.rvl.io/ which offers a WYSIWYG experience?
@@ -81,12 +98,12 @@
For me, focusing becomes easier and my thoughts clearer when I reduce
the list of slides to a single file (```slides.haml```). It only
contains the slide content I am presenting and there's minimal markup.
HAML isn't the most readable thing (say, compared to markdown), but it
-is decent and sharing or reviewing something like ```slides.haml``` is
-easier than reviewing the final presentation:
+is decent, and sharing or reviewing something like ```slides.haml```
+is easier than reviewing the final presentation:
* If you look at the presentation in a browser, you can't scan all of
the slides at once. You need to visit them. If you're looking at
```slides.haml``` you can quickly scan through 30+ slides.
@@ -99,5 +116,38 @@
slightly easier than if you track the generated presentation.
In the end, the presentation framework,
[reveal.js](http://lab.hakim.se/reveal-js/), can make things pretty,
but only you can make a presentation that is worthwhile.
+
+[talk-learning-with-tools-source]: https://github.com/jedcn/talk-learning-with-tools
+[talk-learning-with-tools-result]: http://www.jednorthridge.com/talks/learning-with-tools
+
+## Development
+
+If you want to make changes to reveal-ck, you should first try the
+following:
+
+```
+git submodule init
+git submodule update
+rake
+```
+
+The gem, reveal-ck, relies on having a copy of reveal.js (the original
+JavaScript based project) via a git submodule.
+
+The commands above get things online and verify basic functionality.
+
+### Testing
+
+The testing strategy blends rspec and cucumber. There's not much going
+on here (at a code level) so RSpec is straight forward. The
+executable, reveal-ck, is verified as a command line tool with Aruba.
+
+As you might expect, `rake spec` runs specs, `rake cucumber` runs
+features, and `rake` runs both `spec` and `cucumber`.
+
+### Travis
+
+This project is setup within Travis. Here is the
+[project page](https://travis-ci.org/jedcn/reveal-ck).