showoff 0.7.0 → 0.9.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5b74b0bccf334e9ec1cc0d1f63e78920dbb09ac7
+  data.tar.gz: 6821752697b1c41013d5723ac3be01b4e6d8a30b
+SHA512:
+  metadata.gz: 4fe62f61ad47dcf4718b1c33229d2c10b9367d9ed2f823338876279924506bf441296308f8b8f382823764747d1dfb0121baf6b9fc5307424728a199655b0779
+  data.tar.gz: 3756465ce5712780bd916c1eff7f54bcfe47928f6f67bbcaa93fc5c38ff712a392e4997936dd8549efde0ac718d6cb8171226bfd627056f9c22315493dc2f845

data/README.rdoc

@@ -5,462 +5,48 @@ presentation.  It is sort of like a Keynote web app engine - think S5 +
 Slidedown.  I am using it to do all my talks in 2010, because I have a deep
 hatred in my heart for Keynote and yet it is by far the best in the field.
 
-The idea is that you setup your markdown slide files in section subdirectories
-and then startup the showoff server in that directory.  It will read in your
-<tt>showoff.json</tt> file for which sections go in which order and then will give
-you a URL to present from.
-
-It can:
-
-* show simple text
-* show images
-* show syntax highlighted code
-* bullets with incremental advancing
-* re-enact command line interactions
-* call up a menu of sections/slides at any time to jump around
-* execute Javascript, Coffeescript or Ruby live and display results
-* do simple transitions (instant, fade, slide in)
-* show a pre-show slideshow while you wait to start
-
-It might will can:
-
-* show a timer - elapsed / remaining
-* perform simple animations of images moving between keyframes
-* show synchronized, hidden notes on another browser (like an iphone)
-* show audience questions / comments (twitter or direct)
-* let audience members go back / catch up as you talk
-* let audience members vote on sections (?)
-* broadcast itself on Bonjour
-* let audience members download slides, code samples or other supplementary material
-* let you write on the slide with your mouse, madden-style via canvas
-* automatically resize text to fit screen [see Alex's shrink.js]
-
-Some of the nice things are that you can easily version control it, you
-can easily move sections between presentations, and you can rearrange or
-remove sections easily.
-
-= Usage
-
-ShowOff is meant to be run in a ShowOff formatted repository - that means that
-it has a <tt>showoff.json</tt> file and a number of sections (subdirectories) with
-markdown files for the slides you're presenting.
-
-    $ gem install showoff
-    $ git clone (showoff-repo)
-    $ cd (showoff-repo)
-    $ showoff serve
-
-If you run 'showoff' in the example subdirectory of ShowOff itself, it will
-show an example presentation, so you can see what it's like.
-
-You can also run 'showoff serve' inside a section subdirectory. If there is no
-<tt>showoff.json</tt> file then it will make its best guess, creating a presentation
-from all `.md` files in alphabetical order in the given (or current)
-directory.
-
-= Slide Format
-
-You can break your slides up into sections of however many subdirectories deep
-you need.  ShowOff will recursively check all the directories mentioned in
-your <tt>showoff.json</tt> file for any markdown files (.md).  Each markdown file can
-have any number of slides in it, separating each slide with the '!SLIDE'
-keyword and optional slide styles.
-
-For example, if you run 'showoff create my_new_pres' it will create a new
-starter presentation for you with one .md file at one/slide.md which will have
-the following contents:
-
-    !SLIDE
-
-    # My Presentation #
-
-    !SLIDE bullets incremental transition=fade
-
-    # Bullet Points #
-
-    * first point
-    * second point
-    * third point
-
-That represents two slides, the first contains just a large title, and the
-second is faded into view showing the title and three bullets that are then
-incrementally shown. In order for ShowOff to see those slides, your
-<tt>showoff.json</tt> file needs to look something like this:
-
-    {
-      "name": "Something",
-      "description": "Example Presentation",
-      "sections": [
-        {"section":"one"}
-      ]
-    }
-
-If you have multiple sections in your talk, you can make this json array
-include all the sections you want to show in which order you want to show
-them.
-
-Instead of a hash, you can use a plain string as an entry in the `sections`
-section of `showoff.json`.
-
-And if that plain string starts with '#' then it is interpreted not as a
-filename, but as markdown. This is used for inserting interstitial slides
-or notes -- for instance, Alex Chaffee's
-[Ruby Notes](http://github.com/alexch/ruby_notes)
-uses it to insert lab instructions between lecture slide sections, which may
-vary from venue to venue.
-
-If you want to keep the ability to emit an HTML document from your
-Markdown source file -- say, for a TextMate preview or a GitHub rendering
--- you can use angle brackets around the `!SLIDE` keyword and styles, e.g.
-
-    <!SLIDE bullets incremental transition=fade>
-
-Some useful styles for each slide are:
-
-* center - centers images on a slide
-* full-page - allows an image to take up the whole slide
-* bullets - sizes and separates bullets properly (fits up to 5, generally)
-* smbullets - sizes and separates more bullets (smaller, closer together)
-* subsection - creates a different background for titles
-* command - monospaces h1 title slides
-* commandline - for pasted commandline sections (needs leading '$' for commands, then output on subsequent lines)
-* code - monospaces everything on the slide
-* incremental - can be used with 'bullets' and 'commandline' styles, will incrementally update elements on arrow key rather than switch slides
-* small - make all slide text 80%
-* smaller - make all slide text 70%
-* execute - on Javascript, Coffeescript and Ruby highlighted code slides, you can click on the code to execute it and display the results on the slide
-
-Check out the example directory included to see examples of most of these.
-
-Transitions can be supplied through the use of transition=tname on the !SLIDE
-definition, where tname is one of the following supported transitions:
-
-* blindX
-* blindY
-* blindZ
-* cover
-* curtainX
-* curtainY
-* fade
-* fadeZoom
-* growX
-* growY
-* none (this is the default)
-* scrollUp
-* scrollDown
-* scrollLeft
-* scrollRight
-* scrollHorz
-* scrollVert
-* shuffle
-* slideX
-* slideY
-* toss
-* turnUp
-* turnDown
-* turnLeft
-* turnRight
-* uncover
-* wipe
-* zoom
-
-The transitions are provided by jQuery Cycle plugin. See http://www.malsup.com/jquery/cycle/browser.html to view the effects and http://www.malsup.com/jquery/cycle/adv2.html for how to add custom effects.
-
-You can manage the presentation with the following keys:
-
-* space, cursor right: next slide
-* shift-space, cursor left: previous slide
-* d: debug mode
-* c, t: table of contents (vi)
-* f: toggle footer
-* z, ?: toggle help
-* p: toggle preshow
-
-= Showing plain old markdown
-
-If a markdown file has no !SLIDE keywords, then showoff will treat every line
-beginning with a single hash -- i.e. every H1 -- as a new slide in "bullets"
-style. Remember that you can't specify classes or transitions in this mode,
-and as soon as you add one !SLIDE you need them everywhere.
-
-= Preshow
-
-If you want to show a slideshow while you wait to speak, you can run a preshow.  Add a +_preshow+ directory
-to your project (I use a symlink, so I don't have to add all the images into Git), put a bunch of images in the +_preshow+ directory and optionally add a +preshow+.+json+ file that provides descriptions for any of the images.
-If you then press 'p' at the beginning of your presentation, it will prompt you for a number of minutes until
-you start.  Then it will count down the time until then, flipping through your pictures to entertain the
-audience in the meantime.  Press 'p' again to stop, or wait until the timer runs out.
-
-= Custom JavaScript
-
-To insert custom JavaScript into your presentation you can either place it into
-a file (with extension .js) into the root directory of your presentation or you
-can embed a <+script+> element directly into your slides. This JavaScript will be
-executed—as usually—as soon as it is loaded.
-
-If you want to trigger some JavaScript as soon as a certain page is shown or
-when you switch to the next or previous slide, you can bind a callback to a
-custom event:
-
-* *showoff:show* will be triggered as soon as you enter a page
-* *showoff:next* will be triggered when you switch to the next page
-* *showoff:prev* will be triggered when you switch to the previous page
-
-These events are triggered on the "div.content" child of the slide, so you must
-add a custom and unique class to your SLIDE to identify it:
-
-    !SLIDE custom_and_unique_class
-    # 1st Example h1
-    <script>
-    // bind to custom event
-    $(".custom_and_unique_class").bind("showoff:show", function (event) {
-      // animate the h1
-      var h1 = $(event.target).find("h1");
-      h1.delay(500)
-        .slideUp(300, function () { $(this).css({textDecoration: "line-through"}); })
-        .slideDown(300);
-    });
-    </script>
-
-This will bind an event handler for *showoff:show* to your slide. The
-h1-element will be animated, as soon as this event is triggered on that slide.
-
-If you bind an event handler to the custom events *showoff:next* or
-*showoff:prev*, you can prevent the default action (that is switching to the
-appropriate slide) by calling *event.preventDefault()*:
-
-    !SLIDE prevent_default
-    # 2nd Example h1
-    <script>
-    $(".prevent_default").bind("showoff:next", function (event) {
-      var h1 = $(event.target).find("h1");
-      if (h1.css("text-decoration") === "none") {
-        event.preventDefault();
-        h1.css({textDecoration: "line-through"})
-      }
-    });
-    </script>
-
-This will bind an event handler for *showoff:next* to your slide. When you press
-the right arrow key the first time, the h1-element will be decorated. When you
-press the right array key another time, you will switch to the next slide.
-
-The same applies to the *showoff:prev* event, of course.
-
-
-= Custom Stylesheets
-
-To insert custom Stylesheets into your presentation you can either place it into
-a file (with extension .css) into the root directory of your presentation or
-you can embed a <+link+> element directly into your slides. This stylesheet will
-be applied as soon as it is loaded.
-
-The content generated by the slide is wrapped with a +div+ with the class .+content+ like this.
-
-    <div ref="intro/01_slide/1" class="content" style="margin-top: 210px;">
-    <h1>jQuery &amp; Sinatra</h1>
-    <h2>A Classy Combination</h2>
-    </div>
-
-This makes the .+content+ tag a perfect place to add additional styling if that
-is your preference. An example of adding some styling is here.
-
-    .content {
-      color: black;
-      font-family: helvetica, arial;
-    }
-    h1, h2 {
-      color: rgb(79, 180, 226);
-      font-family: Georgia;
-    }
-    .content::after {
-      position: absolute;
-      right: 120px;
-      bottom: 120px;
-      content: url(jay_small.png);
-    }
-
-Note that the example above uses CSS3 styling with ::+after+ and the +content+
--attribute to add an image to the slides.
-
-= Language highlighting
-
-Showoff uses {shjs}[http://shjs.sourceforge.net/] to highlight code blocks.
-If you begin a code block with three @-signs followed by a
-{programming language name}[http://shjs.sourceforge.net/doc/documentation.html],
-that line will be stripped and the rest of the block will become sparkly
-and colorful.
-
-    @@@ ruby
-    10.times { puts "Whee!" }
-
-= Custom Ruby Files
-
-If you want to have executable Ruby code on your slides you must set the
-environment variable ENV['SHOWOFF_EVAL_RUBY']. This can be done with
-
-    export SHOWOFF_EVAL_RUBY=1
-
-or
-
-    # On Heroku
-    heroku config:add SHOWOFF_EVAL_RUBY=1
-
-
-If you need supporting libraries when you evaluate the code. You can do this by
-putting Ruby files (*.rb) into the root directory of the presentation then they
-will be required when the presentation loads.
-
-= Editor integration
-
-The "add slide" feature can allow you to add the necessary boilerplate from your editor.  If you are using vim, you can
-
-    !showoff add -t code Check This Code
-
-And your buffer will get
-
-    !SLIDE
-    # Check This Code #
-        @@@ Ruby
-        code_here()
-
-added where your cursor was.  Binding this to a keybinding can allow you to add new slides quickly.
-
-= Command Line Interface
-
-    showoff command_name [command-specific options] [--] arguments...
-
-* Use the command +help+ to get a summary of commands
-* Use the command <tt>help command_name</tt> to get a help for +command_name+
-* Use <tt>--</tt> to stop command line argument processing; useful if your arguments have dashes in them
-
-== Commands
-[<tt>add</tt>] Add a new slide at the end in a given dir
-[<tt>create</tt>] Create new showoff presentation
-[<tt>help</tt>] Shows list of commands or help for one command
-[<tt>heroku</tt>] Setup your presentation to serve on Heroku
-[<tt>github</tt>] Setup your presentation to serve on GitHub Pages
-[<tt>serve</tt>] Serves the showoff presentation in the current directory (or a given dir)
-[<tt>static</tt>] Generate static version of presentation
-
-
-== <tt>showoff add [title]</tt>
-
-Add a new slide at the end in a given dir
-
-*Aliases*
-* <tt><b>new</b></tt>
-
-Outputs or creates a new slide. With -d and -n, a new slide is created in the given dir, numbered to appear
-as the last slide in that dir (use -u to avoid numbering). Without those, outputs the slide markdown to
-stdout (useful for shelling out from your editor). You may also specify a source file to use for a code
-slide.
-
-=== options for add
-
-These options are specified *after* the command.
-
-[<tt>-d, --dir=dir</tt>] Slide dir (where to put a new slide file)
-[<tt>-n, --name=basename</tt>] Slide name (name of the new slide file)
-[<tt>-s, --source=path to file</tt>] Include code from the given file as the slide body
-[<tt>-t, --style, --type=valid showoff style/type</tt>] Slide Type/Style <i>( default: <tt>title</tt>)</i>
-[<tt>-u, --nonumber</tt>] Dont number the slide, use the given name verbatim
-
-
-== <tt>showoff create dir_name</tt>
-
-Create new showoff presentation
-
-*Aliases*
-* <tt><b>init</b></tt>
-
-This command helps start a new showoff presentation by setting up the proper directory structure for you.  It takes the directory name you would like showoff to create for you.
-
-=== options for create
-
-These options are specified *after* the command.
-
-[<tt>-d, --slidedir=arg</tt>] sample slide directory name <i>( default: <tt>one</tt>)</i>
-[<tt>-n, --nosamples</tt>] Dont create sample slides
-
-
-== <tt>showoff help [command]</tt>
-
-Shows list of commands or help for one command
-
-
-== <tt>showoff heroku heroku_name</tt>
-
-Setup your presentation to serve on Heroku
-
-Creates the Gemfile and config.ru file needed to push a showoff pres to heroku.  It will then run heroku create for you to register the new project on heroku and add the remote for you.  Then all you need to do is commit the new created files and run git push heroku to deploy.
-
-
-== <tt>showoff github</tt>
-
-Generates a static version of your site and puts it in a gh-pages branch for static serving on GitHub.
-
-=== options for github
-These options are specified *after* the command.
-
-[<tt>-f, --force</tt>] force overwrite of existing Gemfile/.gems and config.ru files if they exist
-[<tt>-g, --dotgems</tt>] Use older-style .gems file instead of bundler-style Gemfile
-[<tt>-p, --password=arg</tt>] add password protection to your heroku site
-
-
-== <tt>showoff serve </tt>
-
-Serves the showoff presentation in the current directory
-
-==== options for serve
-These options are specified *after* the command.
-
-[<tt>-f, --pres_file=arg</tt>] Presentation file <i>(default: <tt>showoff.json</tt>)</i>
-[<tt>-h, --host=arg</tt>] Host or ip to run on <i>( default: <tt>localhost</tt>)</i>
-[<tt>-p, --port=arg</tt>] Port on which to run <i>( default: <tt>9090</tt>)</i>
-
-
-== <tt>showoff static name</tt>
-
-Generate static version of presentation
-
-= PDF Output
-
-Showoff can produce a PDF version of your presentation.  To do this, you must install a few things first:
-
-    gem install pdfkit
-
-You'll then need to install a version of wkhtmltopdf available at the {wkhtmltopdf repo}[http://code.google.com/p/wkhtmltopdf/wiki/compilation] (or brew install wkhtmltopdf on a mac) and make sure that +wkhtmltopdf+ is in your path:
-
-    export $PATH="/location/to/my/wkhtmltopdf/0.9.9:$PATH"
-
-
-
-Then restart showoff, and navigate to <tt>/pdf</tt> (e.g. http://localhost/pdf) of your presentation and a PDF will be generated with the browser.
-
-= Completion
-
-== ZSH completion
-You can complete commands and options in ZSH, by installing a script:
-
-    mkdir -p $HOME/.zsh/Completion
-    cp script/_showoff $HOME/.zsh/Completion
-    echo 'fpath=(~/.zsh/Completion $fpath)' >> $HOME/.zshrc
-
-== <tt>bash</tt> completion
-
-You can complete commands for showoff by putting the following in your <tt>.bashrc</tt> (or whatever
-you use when starting <tt>bash</tt>):
-
-    complete -F get_showoff_commands
-    function get_showoff_commands()
-    {
-        if [ -z $2 ] ; then
-            COMPREPLY=(`showoff help -c`)
-        else
-            COMPREPLY=(`showoff help -c $2`)
-        fi
-    }
+Showoff allows you to author your presentation slides in Markdown, then organize
+them with a <tt>showoff.json</tt> file. This file also contains metadata about
+the presentation, such as the title, any password protection, etc.
+
+Then you just run <tt>showoff serve</tt> in the presentation directory and open
+a browser window.
+
+Showoff's capabilities include:
+
+* Display content on slides including:
+  * formatted text and images
+  * syntax highlighted code
+  * bullets with incremental advancing
+  * simple slide transitions (instant, fade, slide in)
+  * replayed command line interactions
+
+* Live presenter tools:
+  * presenter view that display notes, tree representation of presentation, and other tools
+  * execute Javascript, Coffeescript or Ruby live and display results
+  * show a pre-show slideshow while you wait to start
+  * let audience members download slides, code samples or other supplementary material
+  * show a timer - elapsed / remaining
+  * show synchronized, hidden notes on another browser (like an iphone)
+
+* Live audience tools:
+  * audience can pull up the presentation on their own browsers
+  * call up a menu of sections/slides at any time to jump around
+  * independent navigation so that audience members can go back / catch up as you talk
+  * allow viewers to set their view of the presentation to track the presenter's
+  * allow the audience to provide pace feedback and ask questions of the presenter
+  * allow the audience to provide contend feedback on the material
+
+* Content creation and distribution functionality:
+  * generate supplemental material based on slide tags
+  * generate printed versions of the presentation including handout notes
+  * password protect any URL path to keep control over different views of content
+  * Automatically generate a Table of Contents
+
+Due to it being plain text, you can easily version control it, you can easily move
+sections between presentations, and you can rearrange or remove sections easily.
+
+Please see the documentation in <tt>./documentation</tt> for further information.
 
 = Real World Usage
 
@@ -501,18 +87,13 @@ So far, ShowOff has been used in the following presentations (and many others):
   http://github.com/alexch/workshop
 * SDRuby Lightning Talk - Readable Regexps - Ian Young
   https://github.com/iangreenleaf/sdruby-lightningtalk-tregexp
+* Disney HTML5 Summit 2011 - Polyfills: Shims and Shivs - Josh Dzielak
+  https://github.com/dzello/shims_and_shivs
+* All PuppetLabs training from Summer 2012 on and many internal & external presentations
 
 
 If you use it for something, please let me know so I can add it.
 
-= Editor Support
-
-* TextMate Bundle - Showoff.tmdbundle - Dr Nic Williams
-  http://github.com/drnic/Showoff.tmbundle
-
-* Emacs major-mode - showoff-mode - Nick Parker
-  http://github.com/developernotes/showoff-mode
-
 = Future Plans
 
 I really want this to evolve into a dynamic presentation software server,
@@ -524,6 +105,14 @@ talk that was given, or all the available slides, plus supplementary
 material. And I want the presenter (me) to be able to push each
 presentation to Heroku or GitHub pages for archiving super easily.
 
+Potential future capabilities might include:
+
+* perform simple animations of images moving between keyframes
+* let audience members vote on sections (?)
+* broadcast itself on Bonjour
+* let you write on the slide with your mouse, madden-style via canvas
+* automatically resize text to fit screen [see Alex's shrink.js]
+
 = Why Not S5 or Slidy or Slidedown?
 
 S5 and Slidy are really cool, and I was going to use them, but mainly I wanted
@@ -534,17 +123,6 @@ also like the idea of having interactive presentation system and didn't need
 half the features of S5/Slidy (style based print view, auto-scaling, themes,
 etc).
 
-= Requirements
-
-* Ruby (duh)
-* Sinatra (and thus Rack)
-* BlueCloth
-* Nokogiri
-* json
-* GLI gem
-* Firefox or Chrome to present
-* PDFKit (optional, for generating PDF of presentation) https://github.com/jdpace/PDFKit
-
 = Contributing
 
 See the CONTRIB.txt file for how to contribute to this project

data/Rakefile

@@ -1,27 +1,26 @@
-require 'rake/testtask'
-
-begin
-  require 'mg'
-rescue LoadError
-  abort "Please `gem install mg`"
+desc "Build HTML documentation"
+task :doc do
+  system("rdoc --main README.rdoc README.rdoc documentation/*.rdoc")
 end
 
-MG.new("showoff.gemspec")
-
-#
-# Tests
-#
+desc "Run tests"
+task :test do
+  require 'rake/testtask'
 
-task :default => :test
+  Rake::TestTask.new do |t|
+    t.libs << 'lib'
+    t.pattern = 'test/**/*_test.rb'
+    t.verbose = false
+  end
 
-desc "Run tests"
-task :turn do
   suffix = "-n #{ENV['TEST']}" if ENV['TEST']
   sh "turn test/*_test.rb #{suffix}"
 end
 
-Rake::TestTask.new do |t|
-  t.libs << 'lib'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = false
+begin
+  require 'mg'
+  MG.new("showoff.gemspec")
+rescue LoadError
+  puts "'gem install mg' to get helper gem publishing tasks. (optional)"
 end
+

data/bin/showoff

@@ -2,12 +2,18 @@
 
 $LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
 require 'showoff'
+require 'showoff/version'
 require 'rubygems'
 require 'gli'
 
-include GLI
+# Support GLI and GLI2
+if GLI::VERSION.to_f > 1
+  include GLI::App
+else
+  include GLI
+end
 
-version ShowOff::Version 
+version SHOWOFF_VERSION
 
 desc 'Create new showoff presentation'
 arg_name 'dir_name'
@@ -98,8 +104,8 @@ command :serve do |c|
   c.flag [:p,:port]
 
   c.desc 'Host or ip to run on'
-  c.default_value "localhost"
-  c.flag [:h,:host]  
+  c.default_value "0.0.0.0"
+  c.flag [:h,:host]
 
   c.desc 'JSON file used to describe presentation'
   c.default_value "showoff.json"
@@ -107,7 +113,14 @@ command :serve do |c|
 
   c.action do |global_options,options,args|
 
-    url = "http://#{options[:h]}:#{options[:p].to_i}"
+    # This is gross. A serious revamp in config file parsing is due.
+    config = JSON.parse(File.read(options[:f]))
+    if Gem::Version.new(config['version']) > Gem::Version.new(SHOWOFF_VERSION) then
+      raise "This presentation requires Showoff version #{config['version']} or greater."
+    end
+
+    host = options[:h] == '0.0.0.0' ? 'localhost' : options[:h]
+    url  = "http://#{host}:#{options[:p].to_i}"
     puts "
 -------------------------
 
@@ -120,7 +133,12 @@ To run it from presenter view, go to: [ #{url}/presenter ]
 -------------------------
 
 "
-    ShowOff.run! :host => options[:h], :port => options[:p].to_i, :pres_file => options[:f], :pres_dir => args[0], :verbose => options[:verbose]
+    ShowOff.run!  :host      => options[:h],
+                  :port      => options[:p].to_i,
+                  :pres_file => options[:f],
+                  :pres_dir  => args[0],
+                  :verbose   => options[:verbose],
+                  :bind      => options[:h]
   end
 end
 
@@ -185,4 +203,8 @@ on_error do |exception|
   true
 end
 
-exit GLI.run(ARGV)
+if GLI::VERSION.to_f > 1
+  exit run(ARGV)
+else
+  exit GLI.run(ARGV)
+end