showoff 0.20.1 → 0.20.2

data/lib/showoff/compiler/glossary.rb

@@ -0,0 +1,164 @@
+# adds glossary processing to the compiler
+class Showoff::Compiler::Glossary
+
+  # Scan for glossary links and add definitions. This does not create the
+  # glossary page at the end.
+  #
+  # @param doc [Nokogiri::HTML::DocumentFragment]
+  #     The slide document
+  #
+  # @return [Nokogiri::HTML::DocumentFragment]
+  #     The slide DOM with all glossary entries rendered.
+  #
+  # @see
+  #     https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L650-L706
+  def self.render!(doc)
+
+    # Find all callout style definitions on the slide and add links to the glossary page
+    doc.search('.callout.glossary').each do |item|
+      next unless item.content =~ /^([^|]+)\|([^:]+):(.*)$/
+      item['data-term']   = $1
+      item['data-target'] = $2
+      item['data-text']   = $3.strip
+      item.content        = $3.strip
+
+      glossary = (item.attr('class').split - ['callout', 'glossary']).first
+      address  = glossary ? "#{glossary}/#{$2}" : $2
+
+      link = Nokogiri::XML::Node.new('a', doc)
+      link.add_class('processed label')
+      link.set_attribute('href', "glossary://#{address}")
+      link.content = $1
+
+      item.prepend_child(link)
+    end
+
+    # Find glossary links and add definitions to the notes
+    doc.search('a').each do |link|
+      next unless link['href']
+      next unless link['href'].start_with? 'glossary://'
+      next if link.classes.include? 'processed'
+
+      link.add_class('term')
+
+      term = link.content
+      text = link['title']
+      href = link['href']
+
+      parts  = href.split('/')
+      target = parts.pop
+      name   = parts.pop # either the glossary name or nil
+
+      label = link.clone
+      label.add_class('label processed')
+
+      definition = Nokogiri::XML::Node.new('p', doc)
+      definition.add_class("callout glossary #{name}")
+      definition.set_attribute('data-term', term)
+      definition.set_attribute('data-text', text)
+      definition.set_attribute('data-target', target)
+      definition.content = text
+      definition.prepend_child(label)
+
+      # @todo this duplication is annoying but it makes it less order dependent
+      doc.add_child '<div class="notes-section notes"></div>' if doc.search('div.notes-section.notes').empty?
+      doc.add_child '<div class="notes-section handouts"></div>' if doc.search('div.notes-section.handouts').empty?
+
+      [doc.css('div.notes-section.notes'), doc.css('div.notes-section.handouts')].each do |section|
+        section.first.add_child(definition.clone)
+      end
+
+    end
+
+    doc
+  end
+
+  # Generate and add the glossary page
+  #
+  # @param doc [Nokogiri::HTML::DocumentFragment]
+  #     The presentation document
+  #
+  # @return [Nokogiri::HTML::DocumentFragment]
+  #     The presentation DOM with the glossary page rendered.
+  #
+  # @see
+  #     https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L770-L810
+  def self.generatePage!(doc)
+      doc.search('.slide.glossary .content').each do |glossary|
+        name = (glossary.attr('class').split - ['content', 'glossary']).first
+        list = Nokogiri::XML::Node.new('ul', doc)
+        list.add_class('glossary terms')
+        seen = []
+
+        doc.search('.callout.glossary').each do |item|
+          target = (item.attr('class').split - ['callout', 'glossary']).first
+
+          # if the name matches or if we didn't name it to begin with.
+          next unless target == name
+
+          # the definition can exist in multiple places, so de-dup it here
+          term = item.attr('data-term')
+          next if seen.include? term
+          seen << term
+
+          # excrutiatingly find the parent slide content and grab the ref
+          # in a library less shitty, this would be something like
+          # $(this).parent().siblings('.content').attr('ref')
+          href = nil
+          item.ancestors('.slide').first.traverse do |element|
+            next if element['class'].nil?
+            next unless element['class'].split.include? 'content'
+
+            href = element.attr('ref').gsub('/', '_')
+          end
+
+          text   = item.attr('data-text')
+          link   = item.attr('data-target')
+          page   = glossary.attr('ref')
+          anchor = "#{page}+#{link}"
+          next if href.nil? or text.nil? or link.nil?
+
+          entry = Nokogiri::XML::Node.new('li', doc)
+
+          label = Nokogiri::XML::Node.new('a', doc)
+          label.add_class('label')
+          label.set_attribute('id', anchor)
+          label.content = term
+
+          link = Nokogiri::XML::Node.new('a', doc)
+          label.add_class('return')
+          link.set_attribute('href', "##{href}")
+          link.content = '↩'
+
+          entry.add_child(label)
+          entry.add_child(Nokogiri::XML::Text.new(text, doc))
+          entry.add_child(link)
+
+          list.add_child(entry)
+        end
+
+        glossary.add_child(list)
+      end
+
+      # now fix all the links to point to the glossary page
+      doc.search('a').each do |link|
+        next if link['href'].nil?
+        next unless link['href'].start_with? 'glossary://'
+
+        href = link['href']
+        href.slice!('glossary://')
+
+        parts  = href.split('/')
+        target = parts.pop
+        name   = parts.pop # either the glossary name or nil
+
+        classes = name.nil? ? ".slide.glossary" : ".slide.glossary.#{name}"
+        href    = doc.at("#{classes} .content").attr('ref') rescue nil
+
+        link['href'] = "##{href}+#{target}"
+      end
+
+      doc
+  end
+
+end

data/lib/showoff/compiler/i18n.rb

@@ -0,0 +1,24 @@
+# Adds slide language selection to the compiler
+class Showoff::Compiler::I18n
+
+  def self.selectLanguage!(content)
+    translations = {}
+    content.scan(/^((~~~LANG:([\w-]+)~~~\n)(.+?)(\n~~~ENDLANG~~~))/m).each do |match|
+      markup, opentag, code, text, closetag = match
+      translations[code] = {:markup => markup, :content => text}
+    end
+
+    lang = Showoff::Locale.resolve(translations.keys).to_s
+
+    translations.each do |code, translation|
+      if code == lang
+        content.sub!(translation[:markup], translation[:content])
+      else
+        content.sub!(translation[:markup], "\n")
+      end
+    end
+
+    content
+  end
+
+end

data/lib/showoff/compiler/notes.rb

@@ -0,0 +1,73 @@
+# adds presenter notes processing to the compiler
+class Showoff::Compiler::Notes
+
+  # Generate the presenter notes sections, including personal notes
+  #
+  # @param doc [Nokogiri::HTML::DocumentFragment]
+  #     The slide document
+  #
+  # @param profile [String]
+  #     The markdown engine profile to use when rendering
+  #
+  # @param options [Hash] Options used for rendering any embedded markdown
+  # @option options [String] :name The markdown slide name
+  # @option options [String] :seq The sequence number for multiple slides in one file
+  #
+  # @return [Nokogiri::HTML::DocumentFragment]
+  #     The slide DOM with all notes sections rendered.
+  #
+  # @see
+  #     https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L616-L716
+  # @note
+  #     A ton of the functionality in the original method got refactored to its logical location
+  def self.render!(doc, profile, options = {})
+    # Turn tags into classed divs.
+    doc.search('p').select {|p| p.text.start_with?('~~~SECTION:') }.each do |p|
+      klass = p.text.match(/~~~SECTION:([^~]*)~~~/)[1]
+
+      # Don't bother creating this if we don't want to use it
+      next unless Showoff::Config.includeNotes?(klass)
+
+      notes = Nokogiri::XML::Node.new('div', doc)
+      notes.add_class("notes-section #{klass}")
+      nodes = []
+      iter = p.next_sibling
+      until iter.text == '~~~ENDSECTION~~~' do
+        nodes << iter
+        iter = iter.next_sibling
+
+        # if the author forgot the closing tag, let's not crash, eh?
+        break unless iter
+      end
+      iter.remove if iter # remove the extraneous closing ~~~ENDSECTION~~~ tag
+
+      # We need to collect the list before moving or the iteration crashes since the iterator no longer has a sibling
+      nodes.each {|n| n.parent = notes }
+
+      p.replace(notes)
+    end
+
+    filename = [
+      File.join(Showoff::Config.root, '_notes', "#{options[:name]}.#{options[:seq]}.md"),
+      File.join(Showoff::Config.root, '_notes', "#{options[:name]}.md"),
+    ].find {|path| File.file?(path) }
+
+    if filename and Showoff::Config.includeNotes?('notes')
+      # Make sure we've got a notes div to hang personal notes from
+      doc.add_child '<div class="notes-section notes"></div>' if doc.search('div.notes-section.notes').empty?
+      doc.search('div.notes-section.notes').each do |section|
+        text = Tilt[:markdown].new(nil, nil, options[:profile]) { File.read(filename) }.render
+        frag = "<div class=\"personal\"><h1>#{I18n.t('presenter.notes.personal')}</h1>#{text}</div>"
+        section.prepend_child(frag)
+      end
+    end
+
+    # return notes separately from content so that it can be rendered outside the slide
+    # @see https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L726-L732
+    notes = doc.search('div.notes-section')
+    doc.search('div.notes-section').each {|n| n.remove }
+
+    [doc, notes]
+  end
+
+end

data/lib/showoff/compiler/table_of_contents.rb

@@ -0,0 +1,51 @@
+# adds table of content generation to the compiler
+class Showoff::Compiler::TableOfContents
+
+  # Render a table of contents
+  #
+  # @param doc [Nokogiri::HTML::DocumentFragment]
+  #     The presentation document
+  #
+  # @return [Nokogiri::HTML::DocumentFragment]
+  #     The presentation DOM with the table of contents rendered.
+  #
+  # @see
+  #     https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L747-L768
+  def self.generate!(doc)
+    container = doc.search('p').find {|p| p.text == '~~~TOC~~~' }
+    return doc unless container
+
+    section = nil
+    toc = Nokogiri::XML::Node.new('ol', doc)
+    toc.set_attribute('id', 'toc')
+
+    doc.search('div.slide:not(.toc)').each do |slide|
+      next if slide.search('.content').first.classes.include? 'cover'
+
+      heads = slide.search('div.content h1:not(.section_title)')
+      title = heads.empty? ? slide['data-title'] : heads.first.text
+      href  = "##{slide['id']}"
+
+      entry = Nokogiri::XML::Node.new('li', doc)
+      entry.add_class('tocentry')
+      link  = Nokogiri::XML::Node.new('a', doc)
+      link.set_attribute('href', href)
+      link.content = title
+      entry.add_child(link)
+
+      if (section and slide['data-section'] == section['data-section'])
+        section.add_child(entry)
+      else
+        section = Nokogiri::XML::Node.new('ol', doc)
+        section.add_class('major')
+        section.set_attribute('data-section', slide['data-section'])
+        entry.add_child(section)
+        toc.add_child(entry)
+      end
+
+    end
+    container.replace(toc)
+
+    doc
+  end
+end

data/lib/showoff/compiler/variables.rb

@@ -0,0 +1,71 @@
+# Adds variable interpolation to the compiler
+class Showoff::Compiler::Variables
+  #
+  #
+  # @param content [String]
+  #     A string of Markdown content which may contain Showoff variables.
+  # @return [String]
+  #     The content with variables interpolated.
+  # @note
+  #     Had side effects of altering state datastore.
+  # @see
+  #     https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L557-L614
+  def self.interpolate!(content)
+    # update counters, incrementing section:minor if needed
+    content.gsub!("~~~CURRENT_SLIDE~~~", Showoff::State.get(:slide_count).to_s)
+    content.gsub!("~~~SECTION:MAJOR~~~", Showoff::State.get(:section_major).to_s)
+    if content.include? "~~~SECTION:MINOR~~~"
+      Showoff::State.increment(:section_minor)
+      content.gsub!("~~~SECTION:MINOR~~~", Showoff::State.get(:section_minor).to_s)
+    end
+
+    # scan for pagebreak tags. Should really only be used for handout notes or supplemental materials
+    content.gsub!("~~~PAGEBREAK~~~", '<div class="pagebreak">continued...</div>')
+
+    # replace with form rendering placeholder
+    content.gsub!(/~~~FORM:([^~]*)~~~/, '<div class="form wrapper" title="\1"></div>')
+
+    # Now check for any kind of options
+    content.scan(/(~~~CONFIG:(.*?)~~~)/).each do |match|
+      parts = match[1].split('.') # Use dots ('.') to separate Hash keys
+      value = Showoff::Config.get(*parts)
+
+      unless value.is_a?(String)
+        msg = "#{match[0]} refers to a non-String data type (#{value.class})"
+        msg = "#{match[0]}: not found in settings data" if value.nil?
+        Showoff::Logger.warn(msg)
+        next
+      end
+
+      content.gsub!(match[0], value)
+    end
+
+    # Load and replace any file tags
+    content.scan(/(~~~FILE:([^:~]*):?(.*)?~~~)/).each do |match|
+      # make a list of code highlighting classes to include
+      css  = match[2].split.collect {|i| "language-#{i.downcase}" }.join(' ')
+
+      # get the file content and parse out html entities
+      name = match[1]
+      file = File.read(File.join(Showoff::Config.root, '_files', name)) rescue "Nonexistent file: #{name}"
+      file = "Empty file: #{name}" if file.empty?
+      file = HTMLEntities.new.encode(file) rescue "HTML encoding of #{name} failed"
+
+      content.gsub!(match[0], "<pre class=\"highlight\"><code class=\"#{css}\">#{file}</code></pre>")
+    end
+
+    # insert font awesome icons
+    content.gsub!(/\[(fa\w?)-(\S*) ?(.*)\]/, '<i class="\1 fa-\2 \3"></i>')
+
+    # For fenced code blocks, translate the space separated classes into one
+    # colon separated string so Commonmarker doesn't ignore the rest
+    content.gsub!(/^`{3} *(.+)$/) {|s| "``` #{$1.split.join(':')}"}
+
+    # escape any tags left and ensure they're in distinctly separate p tags so
+    # that renderers that accept a string of tildes for fenced code blocks don't blow up.
+    # @todo This is terrible and we need to design a better tag syntax.
+    content.gsub!(/^~~~(.*?)~~~/, "\n\\~~~\\1~~~\n")
+
+    content
+  end
+end

data/lib/showoff/config.rb

@@ -0,0 +1,218 @@
+require 'json'
+
+class Showoff::Config
+
+  def self.keys
+    @@config.keys
+  end
+
+  # Retrieve settings from the config hash.
+  # If multiple arguments are given then it will dig down through data
+  # structures argument by argument.
+  #
+  # Returns the data type & value requested, nil on error.
+  def self.get(*setting)
+    @@config.dig(*setting) rescue nil
+  end
+
+  def self.sections
+    @@sections
+  end
+
+  # Absolute root of presentation
+  def self.root
+    @@root
+  end
+
+  # Relative path to an item in the presentation directory structure
+  def self.path(path)
+    File.expand_path(File.join(@@root, path)).sub(/^#{@@root}\//, '')
+  end
+
+  # Identifies whether we're including a given notes section
+  #
+  # @param section [String] The name of the notes section of interest.
+  # @return [Boolean] Whether to include this section in the output
+  def self.includeNotes?(section)
+    return true # todo make this work
+  end
+
+  def self.load(path = 'showoff.json')
+    raise 'Presentation file does not exist at the specified path' unless File.exist? path
+
+    @@root     = File.dirname(path)
+    @@config   = JSON.parse(File.read(path))
+    @@sections = self.expand_sections
+
+    self.load_defaults!
+  end
+
+  # Expand and normalize all the different variations that the sections structure
+  # can exist in. When finished, this should return an ordered hash of one or more
+  # section titles pointing to an array of filenames, for example:
+  #
+  # {
+  #     "Section name": [ "array.md, "of.md, "files.md"],
+  #     "Another Section": [ "two/array.md, "two/of.md, "two/files.md"],
+  # }
+  #
+  # See valid input forms at
+  #   https://puppetlabs.github.io/showoff/documentation/PRESENTATION_rdoc.html#label-Defining+slides+using+the+sections+setting.
+  # Source:
+  #  https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff_utils.rb#L427-L475
+  def self.expand_sections
+    begin
+      if @@config.is_a?(Hash)
+        # dup so we don't overwrite the original data structure and make it impossible to re-localize
+        sections = @@config['sections'].dup
+      else
+        sections = @@config.dup
+      end
+
+      if sections.is_a? Array
+        sections = self.legacy_sections(sections)
+      elsif sections.is_a? Hash
+        raise "Named sections are unsupported on Ruby versions less than 1.9." if RUBY_VERSION.start_with? '1.8'
+        sections.each do |key, value|
+          next if value.is_a? Array
+          path = File.dirname(value)
+          data = JSON.parse(File.read(File.join(@@root, value)))
+          raise "The section file #{value} must contain an array of filenames." unless data.is_a? Array
+
+          # get relative paths to each slide in the array
+          sections[key] = data.map do |filename|
+            Pathname.new("#{path}/#{filename}").cleanpath.to_path
+          end
+        end
+      else
+        raise "The `sections` key must be an Array or Hash, not a #{sections.class}."
+      end
+
+    rescue => e
+      Showoff::Logger.error "There was a problem with the presentation file #{index}"
+      Showoff::Logger.error e.message
+      Showoff::Logger.debug e.backtrace
+      sections = {}
+    end
+
+    sections
+  end
+
+  # Source:
+  #  https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff_utils.rb#L477-L545
+  def self.legacy_sections(data)
+    # each entry in sections can be:
+    # - "filename.md"
+    # - "directory"
+    # - { "section": "filename.md" }
+    # - { "section": "directory" }
+    # - { "section": [ "array.md, "of.md, "files.md"] }
+    # - { "include": "sections.json" }
+    sections = {}
+    counters = {}
+    lastpath = nil
+
+    data.map do |entry|
+      next entry if entry.is_a? String
+      next nil unless entry.is_a? Hash
+      next entry['section'] if entry.include? 'section'
+
+      section = nil
+      if entry.include? 'include'
+        file = entry['include']
+        path = File.dirname(file)
+        data = JSON.parse(File.read(File.join(@@root, file)))
+        if data.is_a? Array
+          if path == '.'
+            section = data
+          else
+            section = data.map do |source|
+              "#{path}/#{source}"
+            end
+          end
+        end
+      end
+      section
+    end.flatten.compact.each do |entry|
+      # We do this in two passes simply because most of it was already done
+      # and I don't want to waste time on legacy functionality.
+
+      # Normalize to a proper path from presentation root
+      if File.directory? File.join(@@root, entry)
+        sections[entry] = Dir.glob("#{@@root}/#{entry}/**/*.md").map {|e| e.sub(/^#{@@root}\//, '') }
+        lastpath = entry
+      else
+        path = File.dirname(entry)
+
+        # this lastpath business allows us to reference files in a directory that aren't
+        # necessarily contiguous.
+        if path != lastpath
+          counters[path] ||= 0
+          counters[path]  += 1
+        end
+
+        # now record the last path we've seen
+        lastpath = path
+
+        # and if there are more than one disparate occurences of path, add a counter to this string
+        path = "#{path} (#{counters[path]})" unless counters[path] == 1
+
+        sections[path] ||= []
+        sections[path]  << entry
+      end
+    end
+
+    sections
+  end
+
+  def self.load_defaults!
+    # use a symbol which cannot clash with a string key loaded from json
+    @@config['markdown'] ||= :default
+    renderer = @@config['markdown']
+    defaults = case renderer
+      when 'rdiscount'
+        {
+          :autolink          => true,
+        }
+      when 'maruku'
+        {
+          :use_tex           => false,
+          :png_dir           => 'images',
+          :html_png_url      => '/file/images/',
+        }
+      when 'bluecloth'
+        {
+          :auto_links        => true,
+          :definition_lists  => true,
+          :superscript       => true,
+          :tables            => true,
+        }
+      when 'kramdown'
+        {}
+      else
+        {
+          :autolink          => true,
+          :no_intra_emphasis => true,
+          :superscript       => true,
+          :tables            => true,
+          :underline         => true,
+          :escape_html       => false,
+        }
+      end
+
+    @@config[renderer] ||= {}
+    @@config[renderer]   = defaults.merge!(@@config[renderer])
+
+    # run `wkhtmltopdf --extended-help` for a full list of valid options here
+    pdf_defaults = {
+      :page_size        => 'Letter',
+      :orientation      => 'Portrait',
+      :print_media_type => true,
+      :quiet            => false}
+    pdf_options = @@config['pdf_options'] || {}
+    pdf_options = Hash[pdf_options.map {|k, v| [k.to_sym, v]}]
+
+    @@config['pdf_options'] = pdf_defaults.merge!(pdf_options)
+  end
+
+end