Skip to content
Browse files

Merge remote branch 'davetron5000/improved-cli'

Conflicts:
	README.txt
	bin/showoff
  • Loading branch information...
2 parents b7a6272 + 39e7ec3 commit 437b81f7d7766267022f14888177b4020606330c @schacon schacon committed Apr 5, 2010
Showing with 550 additions and 66 deletions.
  1. +279 −0 README.rdoc
  2. +98 −15 bin/showoff
  3. +171 −50 lib/showoff_utils.rb
  4. +2 −1 showoff.gemspec
View
279 README.rdoc
@@ -0,0 +1,279 @@
+= ShowOff Presentation Software
+
+ShowOff is a Sinatra web app that reads simple configuration files for a
+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
+showoff.json 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 or ruby live and display results
+* do simple transitions (instant, fade, slide in)
+
+It might will can:
+
+* show a timer - elapsed / remaining
+* perform simple animations of images moving between keyframes
+* show syncronized, 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
+
+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 showoff.json 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 ShowOff directory itself, it will show an example
+presentation from the 'example' subdirectory, so you can see what it's like.
+
+= 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 showoff.json file for any markdown files (.md). Each markdown file can
+have any number of slides in it, seperating 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
+showoff.json file needs to look something like this:
+
+ [
+ {"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.
+
+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 seperates bullets properly (fits up to 5, generally)
+* smbullets - sizes and seperates 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 js 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
+* cursor left: previous slide
+* d: debug mode
+* c: table of contents (vi)
+* f: toggle footer
+* z: toggle help
+
+= 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>serve</tt>] Serves the showoff presentation in the current directory
+
+=== <tt>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
+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>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
+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>help [command]</tt>
+
+Shows list of commands or help for one command
+
+=== <tt>heroku heroku_name</tt>
+
+Setup your presentation to serve on Heroku
+
+=== <tt>serve </tt>
+
+Serves the showoff presentation in the current directory
+
+
+
+==== Options
+These options are specified *after* the command.
+
+[<tt>-p, --port=arg</tt>] Port on which to run <i>( default: <tt>9090</tt>)</i>
+= Real World Usage
+
+So far, ShowOff has been used in the following presentations:
+
+* LinuxConf.au 2010 - Wrangling Git - Scott Chacon
+ http://github.com/schacon/showoff-wrangling-git
+* SF Ruby Meetup - Resque! - Chris Wanstrath
+ http://github.com/defunkt/sfruby-meetup-resque
+* RORO Sydney Talk, Feb 2010 - Beyond Actions - Dave Bolton
+ http://github.com/lightningdb/roro-syd-beyond-actions
+* LRUG's February meeting - Showing Off with Ruby - Joel Chippindale
+ http://github.com/mocoso/showing-off-with-ruby
+* PyCon 2010 - Hg and Git; Can't we all just get along? - Scott Chacon
+ http://github.com/schacon/pycon-hg-git
+* PdxJs Tech Talk - Asynchronous Coding For My Tiny Ruby Brain - Rick Olson
+ http://github.com/technoweenie/pdxjs-twitter-node
+* RORO Perth Talk - Rails 3; A Brief Introduction Darcy Laycock
+ http://github.com/Sutto/roro-perth-rails-3
+* PDXRB Tech Talk - Here's Sinatra - Jesse Cooke
+ http://github.com/jc00ke/pdxrb_sinatra
+
+If you use it for something, please let me know so I can add it.
+
+= Future Plans
+
+I really want this to evolve into a dynamic presentation software server,
+that gives the audience a lot of interaction into the presentation -
+helping them decide dynamically what the content of the presentation is,
+ask questions without interupting the presenter, etc. I want the audience
+to be able to download a dynamically generated PDF of either the actual
+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.
+
+= Why Not S5 or Slidy or Slidedown?
+
+S5 and Slidy are really cool, and I was going to use them, but mainly I wanted
+something more dynamic. I wanted Slidy + Slidedown, where I could write my
+slideshows in a structured format in sections, where the sections could easily
+be moved around and between presentations and could be written in Markdown. I
+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
+* Firefox or Chrome to present
+
View
113 bin/showoff
@@ -2,19 +2,102 @@
$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
require 'showoff'
-command = ARGV.shift
-
-case command
-when 'create'
- ShowOffUtils.create
-when 'add'
- ShowOffUtils.add_slide
-when 'heroku'
- ShowOffUtils.heroku
-when 'serve'
- ShowOff.run! :host => 'localhost', :port => 9090
-when 'static'
- ShowOff.do_static(ARGV)
-else
- ShowOffUtils.help
+require 'rubygems'
+require 'gli'
+
+include GLI
+
+desc 'Create new showoff presentation'
+arg_name 'dir_name'
+long_desc '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.'
+command [:create,:init] do |c|
+
+ c.desc 'Don''t create sample slides'
+ c.switch [:n,:nosamples]
+
+ c.desc 'sample slide directory name'
+ c.default_value 'one'
+ c.flag [:d,:slidedir]
+
+ c.action do |global_options,options,args|
+ raise "dir_name is required" if args.empty?
+ ShowOffUtils.create(args[0],!options[:n],options[:d])
+ end
+end
+
+desc 'Setup your presentation to serve on Heroku'
+arg_name 'heroku_name'
+long_desc 'Creates the .gems file 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.'
+command :heroku do |c|
+ c.action do |global_options,options,args|
+ raise "heroku_name is required" if args.empty?
+ ShowOffUtils.heroku(args[0])
+ end
end
+
+desc 'Serves the showoff presentation in the current directory'
+command :serve do |c|
+
+ c.desc 'Port on which to run'
+ c.default_value "9090"
+ c.flag [:p,:port]
+
+ c.action do |global_options,options,args|
+ ShowOff.run! :host => 'localhost', :port => options[:p].to_i
+ end
+end
+
+desc 'Add a new slide at the end in a given dir'
+arg_name '[title]'
+long_desc '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'
+command [:add,:new] do |c|
+ c.desc 'Don''t number the slide, use the given name verbatim'
+ c.switch [:u,:nonumber]
+
+ c.desc 'Include code from the given file as the slide body'
+ c.arg_name 'path to file'
+ c.flag [:s,:source]
+
+ c.desc 'Slide Type/Style'
+ c.arg_name 'valid showoff style/type'
+ c.default_value 'title'
+ c.flag [:t,:type,:style]
+
+ c.desc 'Slide dir (where to put a new slide file)'
+ c.arg_name 'dir'
+ c.flag [:d,:dir]
+
+ c.desc 'Slide name (name of the new slide file)'
+ c.arg_name 'basename'
+ c.flag [:n,:name]
+
+ c.action do |global_options,options,args|
+ title = args.join(" ")
+ ShowOffUtils.add_slide(:dir => options[:d],
+ :name => options[:n],
+ :title => title,
+ :number => !options[:m],
+ :code => options[:s],
+ :type => options[:t])
+ end
+end
+
+pre do |global,command,options,args|
+ # Pre logic here
+ # Return true to proceed; false to abourt and not call the
+ # chosen command
+ true
+end
+
+post do |global,command,options,args|
+ # Post logic here
+end
+
+on_error do |exception|
+ raise exception
+ # Error logic here
+ # return false to skip default error handling
+ true
+end
+
+GLI.run(ARGV)
View
221 lib/showoff_utils.rb
@@ -1,39 +1,33 @@
class ShowOffUtils
- def self.create
- dirname = ARGV[1]
- return help('create') if !dirname
+ def self.create(dirname,create_samples,dir='one')
Dir.mkdir(dirname) if !File.exists?(dirname)
Dir.chdir(dirname) do
- # create section
- Dir.mkdir('one')
-
- # create markdown file
- File.open('one/slide.md', 'w+') do |f|
- f.puts "!SLIDE"
- f.puts "# My Presentation #"
- f.puts
- f.puts "!SLIDE bullets incremental"
- f.puts "# Bullet Points #"
- f.puts
- f.puts "* first point"
- f.puts "* second point"
- f.puts "* third point"
+ if create_samples
+ # create section
+ Dir.mkdir(dir)
+
+ # create markdown file
+ File.open("#{dir}/01_slide.md", 'w+') do |f|
+ f.puts make_slide("My Presentation")
+ f.puts make_slide("Bullet Points","bullets incremental",["first point","second point","third point"])
+ end
end
# create showoff.json
File.open('showoff.json', 'w+') do |f|
- f.puts '[ {"section":"one"} ]'
+ f.puts '[ {"section":"#{dir}"} ]'
end
- # print help
- puts "done. run 'showoff serve' in #{dirname}/ dir to see slideshow"""
+ if create_samples
+ puts "done. run 'showoff serve' in #{dirname}/ dir to see slideshow"
+ else
+ puts "done. add slides, modify showoff.json and then run 'showoff serve' in #{dirname}/ dir to see slideshow"
+ end
end
end
- def self.heroku
- name = ARGV[1]
- return help('heroku') if !name
+ def self.heroku(name)
if !File.exists?('showoff.json')
puts "fail. not a showoff directory"
return false
@@ -60,38 +54,165 @@ def self.heroku
"
end
- def self.help(verb = nil)
- verb = ARGV[1] if !verb
- case verb
- when 'heroku'
- puts <<-HELP
-usage: showoff heroku (heroku-name)
+ # Makes a slide as a string.
+ # [title] title of the slide
+ # [classes] any "classes" to include, such as 'smaller', 'transition', etc.
+ # [content] slide content. Currently, if this is an array, it will make a bullet list. Otherwise
+ # the string value of this will be put in the slide as-is
+ def self.make_slide(title,classes="",content=nil)
+ slide = "!SLIDE #{classes}\n"
+ slide << "# #{title} #\n"
+ slide << "\n"
+ if content
+ if content.kind_of? Array
+ content.each { |x| slide << "* #{x.to_s}\n" }
+ else
+ slide << content.to_s
+ end
+ end
+ slide
+ end
+
+ TYPES = {
+ :default => lambda { |t,size,source,type| make_slide(t,"#{size} #{type}",source) },
+ 'title' => lambda { |t,size,dontcare| make_slide(t,size) },
+ 'bullets' => lambda { |t,size,dontcare| make_slide(t,"#{size} bullets incremental",["bullets","go","here"])},
+ 'smbullets' => lambda { |t,size,dontcare| make_slide(t,"#{size} smbullets incremental",["bullets","go","here","and","here"])},
+ 'code' => lambda { |t,size,src| make_slide(t,size,blank?(src) ? " @@@ Ruby\n code_here()" : src) },
+ 'commandline' => lambda { |t,size,dontcare| make_slide(t,"#{size} commandline"," $ command here\n output here")},
+ 'full-page' => lambda { |t,size,dontcare| make_slide(t,"#{size} full-page","![Image Description](image/ref.png)")},
+ }
+
+
+ # Adds a new slide to a given dir, giving it a number such that it falls after all slides
+ # in that dir.
+ # Options are:
+ # [:dir] - dir where we put the slide (if omitted, slide is output to $stdout)
+ # [:name] - name of the file, without the number prefix. (if omitted, a default is used)
+ # [:title] - title in the slide. If not specified the source file name is
+ # used. If THAT is not specified, uses the value of +:name+. If THAT is not
+ # specified, a suitable default is used
+ # [:code] - path to a source file to use as content (force :type to be 'code')
+ # [:number] - true if numbering should be done, false if not
+ # [:type] - the type of slide to create
+ def self.add_slide(options)
+
+ raise "No such dir #{options[:dir]}" if options[:dir] && !File.exists?(options[:dir])
+
+ options[:type] = 'code' if options[:code]
-creates the .gems file 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.
+ title = determine_title(options[:title],options[:name],options[:code])
-HELP
- when 'create'
- puts <<-HELP
-usage: showoff create (directory)
+ options[:name] = 'new_slide' if !options[:name]
-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.
+ size,source = determine_size_and_source(options[:code])
+ type = options[:type] || :default
+ slide = TYPES[type].call(title,size,source)
-HELP
+ if options[:dir]
+ filename = determine_filename(options[:dir],options[:name],options[:number])
+ write_file(filename,slide)
else
- puts <<-HELP
-usage: showoff (command)
-
-commands:
- serve serves a showoff presentation from the current directory
- create generates a new showoff presentation layout
- heroku sets up your showoff presentation to push to heroku
-HELP
+ puts slide
+ puts
+ end
+
+ end
+
+ def self.blank?(string)
+ string.nil? || string.strip.length == 0
+ end
+
+ def self.determine_size_and_source(code)
+ size = ""
+ source = ""
+ if code
+ source,lines,width = read_code(code)
+ size = adjust_size(lines,width)
+ end
+ [size,source]
+ end
+
+ def self.write_file(filename,slide)
+ File.open(filename,'w') do |file|
+ file.puts slide
end
+ puts "Wrote #{filename}"
end
-end
+ def self.determine_filename(slide_dir,slide_name,number)
+ filename = "#{slide_dir}/#{slide_name}.md"
+ if number
+ max = find_next_number(slide_dir)
+ filename = "#{slide_dir}/#{max}_#{slide_name}.md"
+ end
+ filename
+ end
+
+ # Finds the next number in the given dir to
+ # name a slide as the last slide in the dir.
+ def self.find_next_number(slide_dir)
+ max = 0
+ Dir.open(slide_dir).each do |file|
+ if file =~ /(\d+).*\.md/
+ num = $1.to_i
+ max = num if num > max
+ end
+ end
+ max += 1
+ max = "0#{max}" if max < 10
+ max
+ end
+
+ def self.determine_title(title,slide_name,code)
+ if blank?(title)
+ title = slide_name
+ title = File.basename(code) if code
+ end
+ title = "Title here" if blank?(title)
+ title
+ end
+
+ # Determines a more optimal value for the size (e.g. small vs. smaller)
+ # based upon the size of the code being formatted.
+ def self.adjust_size(lines,width)
+ size = ""
+ # These values determined empircally
+ size = "small" if width > 50
+ size = "small" if lines > 15
+ size = "smaller" if width > 57
+ size = "smaller" if lines > 19
+ puts "warning, some lines are too long and the code may be cut off" if width > 65
+ puts "warning, your code is too long and the code may be cut off" if lines > 23
+ size
+ end
+
+ # Reads the code from the source file, returning
+ # the code, indented for markdown, as well as the number of lines
+ # and the width of the largest line
+ def self.read_code(source_file)
+ code = " @@@ #{lang(source_file)}\n"
+ lines = 0
+ width = 0
+ File.open(source_file) do |code_file|
+ code_file.readlines.each do |line|
+ code += " #{line}"
+ lines += 1
+ width = line.length if line.length > width
+ end
+ end
+ [code,lines,width]
+ end
+
+ EXTENSIONS = {
+ 'pl' => 'perl',
+ 'rb' => 'ruby',
+ 'erl' => 'erlang',
+ # so not exhaustive, but probably good enough for now
+ }
+
+ def self.lang(source_file)
+ ext = File.extname(source_file).gsub(/^\./,'')
+ EXTENSIONS[ext] || ext
+ end
+end
View
3 showoff.gemspec
@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
s.has_rdoc = false
s.require_path = "lib"
s.executables = %w( showoff )
- s.files = %w( README.txt Rakefile LICENSE )
+ s.files = %w( README.rdoc Rakefile LICENSE )
s.files += Dir.glob("lib/**/*")
s.files += Dir.glob("bin/**/*")
s.files += Dir.glob("views/**/*")
@@ -18,6 +18,7 @@ Gem::Specification.new do |s|
s.add_dependency "bluecloth"
s.add_dependency "nokogiri"
s.add_dependency "json"
+ s.add_dependency ("gli",">= 1.1.0")
s.description = <<-desc
ShowOff is a Sinatra web app that reads simple configuration files for a
presentation. It is sort of like a Keynote web app engine. I am using it

0 comments on commit 437b81f

Please sign in to comment.
Something went wrong with that request. Please try again.