showoff 0.19.4 → 0.20.3

data/lib/showoff/compiler.rb

@@ -0,0 +1,106 @@
+require 'tilt'
+require 'tilt/erb'
+require 'nokogiri'
+
+class Showoff::Compiler
+  require 'showoff/compiler/form'
+  require 'showoff/compiler/variables'
+  require 'showoff/compiler/fixups'
+  require 'showoff/compiler/i18n'
+  require 'showoff/compiler/notes'
+  require 'showoff/compiler/glossary'
+  require 'showoff/compiler/downloads'
+  require 'showoff/compiler/table_of_contents'
+
+  def initialize(options)
+    @options = options
+    @profile = profile
+  end
+
+  # Configures Tilt with the selected engine and options.
+  #
+  # Returns render options profile hash
+  #
+  # Source:
+  #  https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff_utils.rb#L671-L720
+  # TODO: per slide profiles of render options
+  def profile
+    renderer = Showoff::Config.get('markdown')
+    profile  = Showoff::Config.get(renderer)
+
+    begin
+      # Load markdown configuration
+      case renderer
+      when 'rdiscount'
+        Tilt.prefer Tilt::RDiscountTemplate, "markdown"
+
+      when 'maruku'
+        Tilt.prefer Tilt::MarukuTemplate, "markdown"
+        # Now check if we can go for latex mode
+        require 'maruku'
+        require 'maruku/ext/math'
+
+        if profile[:use_tex]
+          MaRuKu::Globals[:html_math_output_mathml] = false
+          MaRuKu::Globals[:html_math_output_png]    = true
+          MaRuKu::Globals[:html_math_engine]        = 'none'
+          MaRuKu::Globals[:html_png_engine]         = 'blahtex'
+          MaRuKu::Globals[:html_png_dir]            = profile[:png_dir]
+          MaRuKu::Globals[:html_png_url]            = profile[:html_png_url]
+        end
+
+      when 'bluecloth'
+        Tilt.prefer Tilt::BlueClothTemplate, "markdown"
+
+      when 'kramdown'
+        Tilt.prefer Tilt::KramdownTemplate, "markdown"
+
+      when 'commonmarker', 'commonmark'
+        Tilt.prefer Tilt::CommonMarkerTemplate, "markdown"
+
+      when 'redcarpet', :default
+        Tilt.prefer Tilt::RedcarpetTemplate, "markdown"
+
+      else
+        raise 'Unsupported markdown renderer'
+
+      end
+    rescue LoadError
+      puts "ERROR: The #{renderer} markdown rendering engine does not appear to be installed correctly."
+      exit! 1
+    end
+
+    profile
+  end
+
+  # Compiles markdown and all Showoff extensions into the final HTML output and notes.
+  #
+  # @param content [String] markdown content.
+  # @return [[String, Array<String>]] A tuple of (html content, array of notes contents)
+  #
+  # @todo I think the update_image_paths() malarky is redundant. Verify that.
+  def render(content)
+    Variables::interpolate!(content)
+    I18n.selectLanguage!(content)
+
+    html = Tilt[:markdown].new(nil, nil, @profile) { content }.render
+    doc  = Nokogiri::HTML::DocumentFragment.parse(html)
+
+    Form.render!(doc, @options)
+    Fixups.updateClasses!(doc)
+    Fixups.updateLinks!(doc)
+    Fixups.updateSyntaxHighlighting!(doc)
+    Fixups.updateCommandlineBlocks!(doc)
+    Fixups.updateImagePaths!(doc, @options)
+    Glossary.render!(doc)
+    Downloads.scanForFiles!(doc, @options)
+
+    # This call must be last in the chain because it separates notes from the
+    # content and returns them separately. If it's not last, then the notes
+    # won't have all the compilation steps applied to them.
+    #
+    # must pass in extra context because this will render markdown itself
+    Notes.render!(doc, @profile, @options)
+  end
+
+end

data/lib/showoff/compiler/downloads.rb

@@ -0,0 +1,91 @@
+# adds file download link processing
+class Showoff::Compiler::Downloads
+
+  # Scan for file download links and move them to the state storage.
+  #
+  # @param doc [Nokogiri::HTML::DocumentFragment]
+  #     The slide document
+  #
+  # @return [Nokogiri::HTML::DocumentFragment]
+  #     The slide DOM with download links removed.
+  #
+  # @todo Should .download change meaning to 'make available on this slide'?
+  #
+  # @see
+  #     https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L1056-L1073
+  def self.scanForFiles!(doc, options)
+    current = Showoff::State.get(:slide_count)
+    doc.search('p.download').each do |container|
+      links = container.text.gsub(/^\.download ?/, '')
+      links.split("\n").each do |line|
+        file, modifier = line.split
+        modifier ||= 'next' # @todo Is this still the proper default?
+
+        case modifier
+        when 'a', 'all', 'always', 'now'
+          self.pushFile(0, current, options[:name], file)
+        when 'p', 'prev', 'previous'
+          self.pushFile(current-1, current, options[:name], file)
+        when 'c', 'curr', 'current'
+          self.pushFile(current, current, options[:name], file)
+        when 'n', 'next'
+          self.pushFile(current+1, current, options[:name], file)
+        end
+      end
+
+      container.remove
+    end
+
+    doc
+  end
+
+
+# Convention that index 0 represents files that are always available and every
+# other index represents files whose visibility will be triggered on that slide.
+#
+#   [
+#     {
+#       :enabled => false,
+#       :slides  => [
+#                     {:slidenum => num, :source => name, :file => file},
+#                     {:slidenum => num, :source => name, :file => file},
+#                   ],
+#     },
+#     {
+#       :enabled => false,
+#       :slides  => [
+#                     {:slidenum => num, :source => name, :file => file},
+#                     {:slidenum => num, :source => name, :file => file},
+#                   ],
+#     },
+#   ]
+
+
+  def self.pushFile(index, current, source, file)
+    record = Showoff::State.getAtIndex(:downloads, index) || {}
+    record[:enabled] ||= false
+    record[:slides]  ||= []
+    record[:slides] << {:slidenum => current, :source => source, :file => file}
+
+    Showoff::State.setAtIndex(:downloads, index, record)
+  end
+
+  def self.enableFiles(index)
+    record = Showoff::State.getAtIndex(:downloads, index)
+    return unless record
+
+    record[:enabled] = true
+    Showoff::State.setAtIndex(:downloads, index, record)
+  end
+
+  def self.getFiles(index)
+    record = Showoff::State.getAtIndex(:downloads, index)
+
+    if (record and record[:enabled])
+      record[:slides]
+    else
+      []
+    end
+  end
+
+end

data/lib/showoff/compiler/fixups.rb

@@ -0,0 +1,142 @@
+require 'commandline_parser'
+
+# adds misc fixup methods to the compiler
+class Showoff::Compiler::Fixups
+
+    # Find any <p> or <img> tags with classes defined via the prefixed dot syntax.
+    # Remove .break and .comment paragraphs and apply classes/alt to the rest.
+    #
+    # @param doc [Nokogiri::HTML::DocumentFragment]
+    #     The slide document
+    # @return [Nokogiri::HTML::DocumentFragment]
+    #     The document with classes applied.
+    def self.updateClasses!(doc)
+      doc.search('p').select {|p| p.text.start_with? '.'}.each do |p|
+        # The first string of plain text in the paragraph
+        node = p.children.first
+        classes, sep, text = node.content.partition(' ')
+        classes = classes.split('.')
+        classes.shift
+
+        if ['break', 'comment'].include? classes.first
+          p.remove
+        else
+          p.add_class(classes.join(' '))
+          node.content = text
+        end
+      end
+
+      doc.search('img').select {|img| img.attr('alt').start_with? '.'}.each do |img|
+        classes, sep, text = img.attr('alt').partition(' ')
+        classes = classes.split('.')
+        classes.shift
+
+        img.add_class(classes.join(' '))
+        img.set_attribute('alt', text)
+      end
+
+      doc
+    end
+
+    # Ensure that all links open in a new window. Perhaps move some of this to glossary.rb
+    def self.updateLinks!(doc)
+      doc.search('a').each do |link|
+        next unless link['href']
+        next if link['href'].start_with? '#'
+        next if link['href'].start_with? 'glossary://'
+        # Add a target so we open all external links from notes in a new window
+        link.set_attribute('target', '_blank')
+      end
+
+      doc
+    end
+
+    # This munges code blocks to ensure the proper syntax highlighting
+    # @see
+    #     https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L1105-L1133
+    def self.updateSyntaxHighlighting!(doc)
+      doc.search('pre').each do |pre|
+        pre.search('code').each do |code|
+          out  = code.text
+          lang = code.get_attribute('class')
+
+          # Skip this if we've got an empty code block
+          next if out.empty?
+
+          # catch fenced code blocks from commonmarker
+          if (lang and lang.start_with? 'language-' )
+            pre.set_attribute('class', 'highlight')
+            # turn the colon separated name back into classes
+            code.set_attribute('class', lang.gsub(':', ' '))
+
+          # or we've started a code block with a Showoff language tag
+          elsif out.strip[0, 3] == '@@@'
+            lines = out.split("\n")
+            lang  = lines.shift.gsub('@@@', '').strip
+            pre.set_attribute('class', 'highlight')
+            code.set_attribute('class', 'language-' + lang.downcase) if !lang.empty?
+            code.content = lines.join("\n")
+          end
+
+        end
+      end
+
+      doc
+    end
+
+    # This munges commandline code blocks for the proper classing
+    # @see
+    #     https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L1107
+    #     https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L1135-L1163
+    def self.updateCommandlineBlocks!(doc)
+      parser = CommandlineParser.new
+      doc.search('.commandline > pre > code').each do |code|
+        out = code.text
+        code.content = ''
+        tree = parser.parse(out)
+        transform = Parslet::Transform.new do
+          rule(:prompt => simple(:prompt), :input => simple(:input), :output => simple(:output)) do
+            command = Nokogiri::XML::Node.new('code', doc)
+            command.set_attribute('class', 'command')
+            command.content = "#{prompt} #{input}"
+            code << command
+
+            # Add newline after the input so that users can
+            # advance faster than the typewriter effect
+            # and still keep inputs on separate lines.
+            code << "\n"
+
+            unless output.to_s.empty?
+
+              result = Nokogiri::XML::Node.new('code', doc)
+              result.set_attribute('class', 'result')
+              result.content = output
+              code << result
+            end
+          end
+        end
+        transform.apply(tree)
+      end
+
+      doc
+    end
+
+    # Because source slide files can be nested in arbitrarily deep directories we
+    # need to simplify paths to images when we flatten it out to a single HTML file.
+    # @see
+    #     https://github.com/puppetlabs/showoff/blob/220d6eef4c5942eda625dd6edc5370c7490eced7/lib/showoff.rb#L1076-L1103
+    def self.updateImagePaths!(doc, options={})
+      doc.search('img').each do |img|
+        slide_dir = File.dirname(options[:name])
+
+        # We need to turn all URLs into relative from the root. If it starts with '/'
+        # then we can assume the author meant to start the path at the presentation root.
+        if img[:src].start_with? '/'
+          img[:src] = img[:src][1..-1]
+        else
+          # clean up the path and remove some of the relative nonsense
+          img[:src] = Pathname.new(File.join(slide_dir, img[:src])).cleanpath.to_path
+        end
+      end
+    end
+end

data/lib/showoff/compiler/form.rb

@@ -0,0 +1,236 @@
+# Adds form processing to the compiler
+#
+# @see https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L848-L1022
+class Showoff::Compiler::Form
+
+  # Add the form markup to the slide and then render all elements
+  #
+  # @todo UI elements to translate once i18n is baked in.
+  # @todo Someday this should be rearchitected into the markdown renderer.
+  #
+  # @return [Nokogiri::HTML::DocumentFragment]
+  #     The slide DOM with all form elements rendered.
+  #
+  # @see
+  #     https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L849-L878
+  def self.render!(doc, options={})
+    title = options[:form]
+    return unless title
+
+    begin
+      tools = Nokogiri::XML::Node.new('div', doc)
+        tools.add_class('tools')
+        doc.add_child(tools)
+
+      button = Nokogiri::XML::Node.new('input', doc)
+        button.add_class('display')
+        button.set_attribute('type', 'button')
+        button.set_attribute('value', I18n.t('forms.display'))
+        tools.add_child(button)
+
+      submit = Nokogiri::XML::Node.new('input', doc)
+        submit.add_class('save')
+        submit.set_attribute('type', 'submit')
+        submit.set_attribute('value', I18n.t('forms.save'))
+        submit.set_attribute('disabled', 'disabled')
+        tools.add_child(submit)
+
+      form = Nokogiri::XML::Node.new('form', doc)
+        form.set_attribute('id', title)
+        form.set_attribute('action', "form/#{title}")
+        form.set_attribute('method', 'POST')
+        doc.add_child(form)
+
+      doc.children.each do |elem|
+        next if elem == form
+        elem.parent = form
+      end
+
+      doc.css('p').each do |p|
+        if p.text =~ /^(\w*) ?(?:->)? ?(.*)? (\*?)= ?(.*)?$/
+          code     = $1
+          id       = "#{title}_#{code}"
+          name     = $2.empty? ? code : $2
+          required = ! $3.empty?
+          rhs      = $4
+
+          p.replace self.form_element(id, code, name, required, rhs, p.text)
+        end
+      end
+
+    rescue Exception => e
+      Showoff::Logger.warn "Form parsing failed: #{e.message}"
+      Showoff::Logger.debug "Backtrace:\n\t#{e.backtrace.join("\n\t")}"
+    end
+
+    doc
+  end
+
+  # Generates markup for any supported form element type
+  #
+  # @param id [String]
+  #     The HTML ID for the generated markup
+  # @param code [String]
+  #     The question code; used for indexing
+  # @param name [String]
+  #     The full text of the question
+  # @param required [Boolean]
+  #     Whether the rendered element should be marked as required
+  # @param rhs [String]
+  #     The right hand side of the question specification, if on one line.
+  # @param text [String]
+  #     The full content of the content, used for recursive multiline calls
+  #
+  # @return [String]
+  #     The HTML markup for all the HTML nodes that the full element renders to.
+  #
+  # @see
+  #     https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L880-L903
+  def self.form_element(id, code, name, required, rhs, text)
+    required = required ? 'required' : ''
+    str =  "<div class='form element #{required}' id='#{id}' data-name='#{code}'>"
+    str << "<label class='question' for='#{id}'>#{name}</label>"
+    case rhs
+    when /^\[\s+(\d*)\]$$/             # value = [    5]                                     (textarea)
+      str << self.form_element_textarea(id, code, $1)
+    when /^___+(?:\[(\d+)\])?$/        # value = ___[50]                                     (text)
+      str << self.form_element_text(id, code, $1)
+    when /^\(.?\)/                     # value = (x) option one (=) opt2 () opt3 -> option 3 (radio)
+      str << self.form_element_radio(id, code, rhs.scan(/\((.?)\)\s*([^()]+)\s*/))
+    when /^\[.?\]/                     # value = [x] option one [=] opt2 [] opt3 -> option 3 (checkboxes)
+      str << self.form_element_checkboxes(id, code, rhs.scan(/\[(.?)\] ?([^\[\]]+)/))
+    when /^\{(.*)\}$/                  # value = {BOS, [SFO], (NYC)}                         (select shorthand)
+      str << self.form_element_select(id, code, rhs.scan(/[(\[]?\w+[)\]]?/))
+    when /^\{$/                        # value = {                                           (select)
+      str << self.form_element_select_multiline(id, code, text)
+    when ''                            # value =                                             (radio/checkbox list)
+      str << self.form_element_multiline(id, code, text)
+    else
+      Showoff::Logger.warn "Unmatched form element: #{rhs}"
+    end
+    str << '</div>'
+  end
+
+  def self.form_element_text(id, code, length)
+    "<input type='text' id='#{id}_response' name='#{code}' size='#{length}' />"
+  end
+
+  def self.form_element_textarea(id, code, rows)
+    rows = 3 if rows.empty?
+    "<textarea id='#{id}_response' name='#{code}' rows='#{rows}'></textarea>"
+  end
+
+  def self.form_element_radio(id, code, items)
+    self.form_element_check_or_radio_set('radio', id, code, items)
+  end
+
+  def self.form_element_checkboxes(id, code, items)
+    self.form_element_check_or_radio_set('checkbox', id, code, items)
+  end
+
+  def self.form_element_select(id, code, items)
+    str =  "<select id='#{id}_response' name='#{code}'>"
+    str << '<option value="">----</option>'
+
+    items.each do |item|
+      selected = classes = ''
+      case item
+      when /\((\w+)\)/
+        item     = $1
+        selected = 'selected'
+      when /\[(\w+)\]/
+        item     = $1
+        classes  = 'correct'
+      end
+      str << "<option value='#{item}' class='#{classes}' #{selected}>#{item}</option>"
+    end
+    str << '</select>'
+  end
+
+  def self.form_element_select_multiline(id, code, text)
+    str =  "<select id='#{id}_response' name='#{code}'>"
+    str << '<option value="">----</option>'
+
+    text.split("\n")[1..-1].each do |item|
+      case item
+      when /^   +\((\w+) -> (.+)\),?$/         # (NYC -> New York City)
+        str << "<option value='#{$1}' selected>#{$2}</option>"
+      when /^   +\[(\w+) -> (.+)\],?$/         # [NYC -> New York City]
+        str << "<option value='#{$1}' class='correct'>#{$2}</option>"
+      when /^   +(\w+) -> (.+),?$/             # NYC -> New, York City
+        str << "<option value='#{$1}'>#{$2}</option>"
+      when /^   +\((.+)\)$/                    # (Boston)
+        str << "<option value='#{$1}' selected>#{$1}</option>"
+      when /^   +\[(.+)\]$/                    # [Boston]
+        str << "<option value='#{$1}' class='correct'>#{$1}</option>"
+      when /^   +([^\(].+[^\),]),?$/           # Boston
+        str << "<option value='#{$1}'>#{$1}</option>"
+      end
+    end
+    str << '</select>'
+  end
+
+  def self.form_element_multiline(id, code, text)
+    str = '<ul>'
+
+    text.split("\n")[1..-1].each do |item|
+      case item
+      when /\((.?)\)\s*(\w+)\s*(?:->\s*(.*)?)?/
+        modifier = $1
+        type     = 'radio'
+        value    = $2
+        label    = $3 || $2
+      when /\[(.?)\]\s*(\w+)\s*(?:->\s*(.*)?)?/
+        modifier = $1
+        type     = 'checkbox'
+        value    = $2
+        label    = $3 || $2
+      end
+
+      str << '<li>'
+      str << self.form_element_check_or_radio(type, id, code, value, label, modifier)
+      str << '</li>'
+    end
+    str << '</ul>'
+  end
+
+  def self.form_element_check_or_radio_set(type, id, code, items)
+    str = ''
+    items.each do |item|
+      modifier = item[0]
+
+      if item[1] =~ /^(\w*) -> (.*)$/
+        value = $1
+        label = $2
+      else
+        value = label = item[1].strip
+      end
+
+      str << self.form_element_check_or_radio(type, id, code, value, label, modifier)
+    end
+    str
+  end
+
+  def self.form_element_check_or_radio(type, id, code, value, label, modifier)
+    # yes, value and id are conflated, because this is the id of the parent widget
+    checked = self.form_checked?(modifier)
+    classes = self.form_classes(modifier)
+
+    name = (type == 'checkbox') ? "#{code}[]" : code
+    str  =  "<input type='#{type}' name='#{name}' id='#{id}_#{value}' value='#{value}' class='#{classes}' #{checked} />"
+    str << "<label for='#{id}_#{value}' class='#{classes}'>#{label}</label>"
+  end
+
+  def self.form_classes(modifier)
+    modifier.downcase!
+    classes = ['response']
+    classes << 'correct' if modifier.include?('=')
+
+    classes.join(' ')
+  end
+
+  def self.form_checked?(modifier)
+    modifier.downcase.include?('x') ? "checked='checked'" : ''
+  end
+
+end