showoff 0.20.1 → 0.20.2

data/lib/showoff/locale.rb

@@ -0,0 +1,132 @@
+require 'i18n'
+require 'i18n/backend/fallbacks'
+require 'iso-639'
+
+I18n::Backend::Simple.send(:include, I18n::Backend::Fallbacks)
+I18n.load_path += Dir[File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'locales', '*.yml'))]
+I18n.backend.load_translations
+I18n.enforce_available_locales = false
+
+class Showoff::Locale
+  @@contentLocale = nil
+
+  # Set the minimized canonical version of the specified content locale, selecting
+  # the nearest match to whatever exists in the presentation's locales directory.
+  # If the locale doesn't exist on disk, it will just default to no translation
+  #
+  # @todo: I don't think this is right at all -- it doesn't autoselect content
+  #   languages, just built in Showoff languages. It only worked by accident before
+  #
+  # @param user_locale [String, Symbol] The locale to select.
+  #
+  # @returns [Symbol] The selected and saved locale.
+  def self.setContentLocale(user_locale = nil)
+    if [nil, '', 'auto'].include? user_locale
+      languages = I18n.available_locales
+      @@contentLocale = I18n.fallbacks[I18n.locale].select { |f| languages.include? f }.first
+    else
+      locales = Dir.glob("#{Showoff::Config.root}/locales/*").map {|e| File.basename e }
+      locales.delete 'strings.json'
+
+      @@contentLocale = with_locale(user_locale) do |str|
+        str.to_sym if locales.include? str
+      end
+    end
+  end
+
+  def self.contentLocale
+    @@contentLocale
+  end
+
+  # Find the closest match to current locale in an array of possibilities
+  #
+  # @param items [Array] An array of possibilities to check
+  # @return [Symbol] The closest match to the current locale.
+  def self.resolve(items)
+    with_locale(contentLocale) do |str|
+      str.to_sym if items.include? str
+    end
+  end
+
+  # Turns a locale code into a string name
+  #
+  # @param locale [String, Symbol] The code of the locale to translate
+  # @returns [String] The name of the locale.
+  def self.languageName(locale = contentLocale)
+    with_locale(locale) do |str|
+      result = ISO_639.find(str)
+      result[3] unless result.nil?
+    end
+  end
+
+  # This function returns the directory containing translated *content*, defaulting
+  # to the presentation root. This works similarly to I18n fallback, but we cannot
+  # reuse that as it's a different translation mechanism.
+
+  # @returns [String] Path to the translated content.
+  def self.contentPath
+    root = Showoff::Config.root
+
+    with_locale(contentLocale) do |str|
+      path = "#{root}/locales/#{str}"
+      return path if File.directory?(path)
+    end || root
+  end
+
+  # Generates a hash of all language codes available and the long name description of each
+  #
+  # @returns [Hash] The language code/name hash.
+  def self.contentLanguages
+    root = Showoff::Config.root
+
+    strings = JSON.parse(File.read("#{root}/locales/strings.json")) rescue {}
+    locales = Dir.glob("#{root}/locales/*")
+                 .select {|f| File.directory?(f) }
+                 .map    {|f| File.basename(f)   }
+
+    (strings.keys + locales).inject({}) do |memo, locale|
+      memo.update(locale => languageName(locale))
+    end
+  end
+
+
+  # Generates a hash of all translations for the current language. This is used
+  # for the javascript half of the UI translations
+  #
+  # @returns [Hash] The locale code/strings hash.
+  def self.translations
+    languages = I18n.backend.send(:translations)
+    fallback  = I18n.fallbacks[I18n.locale].select { |f| languages.keys.include? f }.first
+    languages[fallback]
+  end
+
+  # Finds the language key from strings.json and returns the strings hash. This is
+  # used for user translations in the presentation content, e.g. SVG translations.
+  #
+  # @returns [Hash] The user translation code/strings hash.
+  def self.userTranslations
+    path = "#{Showoff::Config.root}/locales/strings.json"
+    return {} unless File.file? path
+    strings = JSON.parse(File.read(path)) rescue {}
+
+    with_locale(contentLocale) do |key|
+      return strings[key] if strings.include? key
+    end
+    {}
+  end
+
+  # This is just a unified lookup method that takes a full locale name
+  # and then resolves it to an available version of the name
+  def self.with_locale(locale)
+    locale = locale.to_s
+    until (locale.empty?) do
+      result = yield(locale)
+      return result unless result.nil?
+
+      # if not found, chop off a section and try again
+      locale = locale.rpartition(/[-_]/).first
+    end
+  end
+  private_class_method :with_locale
+
+end

data/lib/showoff/logger.rb

@@ -0,0 +1,15 @@
+require 'logger'
+class Showoff::Logger
+  @@logger = Logger.new(STDERR)
+  @@logger.progname = 'Showoff'
+  @@logger.formatter = proc { |severity,datetime,progname,msg| "(#{progname}) #{severity}: #{msg}\n" }
+  @@logger.level = Showoff::State.get(:verbose) ? Logger::DEBUG : Logger::WARN
+  @@logger.level = Logger::WARN
+
+  [:debug, :info, :warn, :error, :fatal].each do |meth|
+    define_singleton_method(meth) do |msg|
+      @@logger.send(meth, msg)
+    end
+  end
+
+end

data/lib/showoff/monkeypatches.rb

@@ -0,0 +1,28 @@
+# Yay for Ruby 2.0!
+class Hash
+  unless Hash.method_defined? :dig
+    def dig(*args)
+      args.reduce(self) do |iter, arg|
+        break nil unless iter.is_a? Enumerable
+        break nil unless iter.include? arg
+        iter[arg]
+      end
+    end
+  end
+
+end
+
+class Nokogiri::XML::Element
+  unless Nokogiri::XML::Element.method_defined? :add_class
+    def add_class(classlist)
+      self[:class] = [self[:class], classlist].join(' ')
+    end
+  end
+
+  unless Nokogiri::XML::Element.method_defined? :classes
+    def classes
+      self[:class] ? self[:class].split(' ') : []
+    end
+  end
+
+end

data/lib/showoff/presentation.rb

@@ -0,0 +1,181 @@
+class Showoff::Presentation
+  require 'showoff/presentation/section'
+  require 'showoff/presentation/slide'
+  require 'showoff/compiler'
+  require 'keymap'
+
+  attr_reader :sections
+
+  def initialize(options)
+    @options  = options
+    @sections = Showoff::Config.sections.map do |name, files|
+      Showoff::Presentation::Section.new(name, files)
+    end
+
+    # weird magic variables the presentation expects
+    @baseurl   = nil # this doesn't appear to have ever been used
+    @title     = Showoff::Config.get('name')    || I18n.t('name')
+    @favicon   = Showoff::Config.get('favicon') || 'favicon.ico'
+    @feedback  = Showoff::Config.get('feedback') # note: the params check is obsolete
+    @pause_msg = Showoff::Config.get('pause_msg')
+    @language  = Showoff::Locale.translations
+    @edit      = Showoff::Config.get('edit') if options[:review]
+
+    # invert the logic to maintain backwards compatibility of interactivity on by default
+    @interactive = ! options[:standalone]
+
+    # Load up the default keymap, then merge in any customizations
+    keymapfile   = File.expand_path(File.join('~', '.showoff', 'keymap.json'))
+    @keymap      = Keymap.default
+    @keymap.merge! JSON.parse(File.read(keymapfile)) rescue {}
+
+    # map keys to the labels we're using
+    @keycode_dictionary   = Keymap.keycodeDictionary
+    @keycode_shifted_keys = Keymap.shiftedKeyDictionary
+
+    @highlightStyle = Showoff::Config.get('highlight') || 'default'
+
+    if Showoff::State.get(:supplemental)
+      @wrapper_classes = ['supplemental']
+    end
+  end
+
+  def compile
+    Showoff::State.reset([:slide_count, :section_major, :section_minor])
+
+    # @todo For now, we reparse the html so that we can generate content via slide
+    #       templates. This adds a bit of extra time, but not too much. Perhaps
+    #       we'll change that at some point.
+    html = @sections.map(&:render).join("\n")
+    doc  = Nokogiri::HTML::DocumentFragment.parse(html)
+
+    Showoff::Compiler::TableOfContents.generate!(doc)
+    Showoff::Compiler::Glossary.generatePage!(doc)
+
+    doc
+  end
+
+  # The index page does not contain content; just a placeholder div that's
+  # dynamically loaded after the page is displayed. This increases perceived
+  # responsiveness.
+  def index
+    ERB.new(File.read(File.join(Showoff::GEMROOT, 'views','index.erb')), nil, '-').result(binding)
+  end
+
+  def slides
+    compile.to_html
+  end
+
+  def static
+    # This singleton guard removes ordering coupling between assets() & static()
+    @doc  ||= compile
+    @slides = @doc.to_html
+
+    # All static snapshots should be non-interactive by definition
+    @interactive = false
+
+    case Showoff::State.get(:format)
+    when 'web'
+      template = 'index.erb'
+    when 'print', 'supplemental', 'pdf'
+      template = 'onepage.erb'
+    end
+
+    ERB.new(File.read(File.join(Showoff::GEMROOT, 'views', template)), nil, '-').result(binding)
+  end
+
+  # Generates a list of all image/font/etc files used by the presentation. This
+  # will only identify the sources of <img> tags and files referenced by the
+  # CSS url() function.
+  #
+  # @see
+  #     https://github.com/puppetlabs/showoff/blob/220d6eef4c5942eda625dd6edc5370c7490eced7/lib/showoff.rb#L1509-L1573
+  # @returns [Array]
+  #     List of assets, such as images or fonts, used by the presentation.
+  def assets
+    # This singleton guard removes ordering coupling between assets() & static()
+    @doc ||= compile
+
+    # matches url(<path>) and returns the path as a capture group
+    urlsrc = /url\([\"\']?(.*?)(?:[#\?].*)?[\"\']?\)/
+
+    # get all image and url() sources
+    files = @doc.search('img').map {|img| img[:src] }
+    @doc.search('*').each do |node|
+      next unless node[:style]
+      next unless matches = node[:style].match(urlsrc)
+      files << matches[1]
+    end
+
+    # add in images from css files too
+    css_files.each do |css_path|
+      data = File.read(File.join(Showoff::Config.root, css_path))
+
+      # @todo: This isn't perfect. It will match commented out styles. But its
+      # worst case behavior is displaying a warning message, so that's ok for now.
+      data.scan(urlsrc).flatten.each do |path|
+        # resolve relative paths in the stylesheet
+        path = File.join(File.dirname(css_path), path) unless path.start_with? '/'
+        files << path
+      end
+    end
+
+    # also all user-defined styles and javascript files
+    files.concat css_files
+    files.concat js_files
+    files.uniq
+  end
+
+  def erb(template)
+    ERB.new(File.read(File.join(Showoff::GEMROOT, 'views', "#{template}.erb")), nil, '-').result(binding)
+  end
+
+  def css_files
+    base  = Dir.glob("#{Showoff::Config.root}/*.css").map { |path| File.basename(path) }
+    extra = Array(Showoff::Config.get('styles'))
+    base + extra
+  end
+
+  def js_files
+    base  = Dir.glob("#{Showoff::Config.root}/*.js").map { |path| File.basename(path) }
+    extra = Array(Showoff::Config.get('scripts'))
+    base + extra
+  end
+
+  # return a list of keys associated with a given action in the keymap
+  def mapped_keys(action, klass='key')
+    list = @keymap.select { |key,value| value == action }.keys
+
+    if klass
+      list.map { |val| "<span class=\"#{klass}\">#{val}</span>" }.join
+    else
+      list.join ', '
+    end
+  end
+
+
+
+
+  # @todo: backwards compatibility shim
+  def user_translations
+    Showoff::Locale.userTranslations
+  end
+
+  # @todo: backwards compatibility shim
+  def language_names
+    Showoff::Locale.contentLanguages
+  end
+
+
+  # @todo: this should be part of the server. Move there with the least disruption.
+  def master_presenter?
+    false
+  end
+
+  # @todo: this should be part of the server. Move there with the least disruption.
+  def valid_presenter_cookie?
+    false
+  end
+
+
+end

data/lib/showoff/presentation/section.rb

@@ -0,0 +1,70 @@
+class Showoff::Presentation::Section
+  attr_reader :slides, :name
+
+  def initialize(name, files)
+    @name   = name
+    @slides = []
+    files.each { |filename| loadSlides(filename) }
+
+    # merged output means that we just want to generate *everything*. This is used by internal,
+    # methods such as content validation, where we want all content represented.
+    # https://github.com/puppetlabs/showoff/blob/220d6eef4c5942eda625dd6edc5370c7490eced7/lib/showoff.rb#L429-L453
+    unless Showoff::State.get(:merged)
+      if Showoff::State.get(:supplemental)
+        # if we're looking for supplemental material, only include the content we want
+        @slides.select! {|slide| slide.classes.include? 'supplemental' }
+        @slides.select! {|slide| slide.classes.include? Showoff::State.get(:supplemental) }
+      else
+        # otherwise just skip all supplemental material completely
+        @slides.reject! {|slide| slide.classes.include? 'supplemental' }
+      end
+
+      case Showoff::State.get(:format)
+      when 'web'
+        @slides.reject! {|slide| slide.classes.include? 'toc' }
+        @slides.reject! {|slide| slide.classes.include? 'printonly' }
+      when 'print', 'supplemental'
+        @slides.reject! {|slide| slide.classes.include? 'noprint' }
+      end
+    end
+
+  end
+
+  def render
+    @slides.map(&:render).join("\n")
+  end
+
+  # Gets the raw file content from disk and partitions it by slide markers into
+  # content for each slide.
+  #
+  # Returns an array of Slide objects
+  #
+  # Source:
+  #  https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L396-L414
+  def loadSlides(filename)
+    return unless filename.end_with? '.md'
+
+    content = File.read(File.join(Showoff::Locale.contentPath, filename))
+
+    # if there are no !SLIDE markers, then make every H1 define a new slide
+    unless content =~ /^\<?!SLIDE/m
+      content = content.gsub(/^# /m, "<!SLIDE>\n# ")
+    end
+
+    slides = content.split(/^<?!SLIDE\s?([^>]*)>?/)
+    slides.shift # has an extra empty string because the regex matches the entire source string.
+
+    # this is a counter keeping track of how many slides came from the file.
+    # It kicks in at 2 because at this point, slides are a tuple of (options, content)
+    seq = slides.size > 2 ? 1 : nil
+
+    # iterate each slide tuple and add slide objects to the array
+    slides.each_slice(2) do |data|
+      options, content = data
+      @slides << Showoff::Presentation::Slide.new(options, content, :section => @name, :name => filename, :seq => seq)
+      seq +=1 if seq
+    end
+
+  end
+
+end

data/lib/showoff/presentation/slide.rb

@@ -0,0 +1,113 @@
+require 'erb'
+
+class Showoff::Presentation::Slide
+  attr_reader :section, :section_title, :name, :seq, :id, :ref, :background, :transition, :form, :markdown, :classes
+
+  def initialize(options, content, context={})
+    @markdown   = content
+    @transition = 'none'
+    @classes    = []
+    setOptions!(options)
+    setContext!(context)
+  end
+
+  def render
+    Showoff::State.increment(:slide_count)
+    options = { :form => @form,
+                :name => @name,
+                :seq  => @seq,
+              }
+
+    content, notes = Showoff::Compiler.new(options).render(@markdown)
+
+    # if a template file has been specified for this slide, load from disk and render it
+    # @todo How many people are actually using these limited templates?!
+    if tpl_file = Showoff::Config.get('template', @template)
+      template = File.read(tpl_file)
+      content  = template.gsub(/~~~CONTENT~~~/, content)
+    end
+
+    ERB.new(File.read(File.join(Showoff::GEMROOT, 'views','slide.erb')), nil, '-').result(binding)
+  end
+
+  # This is a list of classes that we want applied *only* to content, and not to the slide,
+  # typically so that overly aggressive selectors don't match more than they should.
+  #
+  # @see
+  #     https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L734-L737
+  def slideClasses
+    blacklist = ['bigtext']
+    @classes.reject { |klass| blacklist.include? klass }
+  end
+
+  # options are key=value elements within the [] brackets
+  def setOptions!(options)
+    return unless options
+    return unless matches = options.match(/(\[(.*?)\])?(.*)/)
+
+    if matches[2]
+      matches[2].split(",").each do |element|
+        key, val = element.split("=")
+        case key
+        when 'tpl', 'template'
+          @template = val
+        when 'bg', 'background'
+          @background = val
+        # For legacy reasons, the options below may also be specified in classes.
+        # Currently that takes priority.
+        # @todo: better define the difference between options and classes.
+        when 'form'
+          @form = val
+        when 'id'
+          @id = val
+        when 'transition'
+          @transition = val
+        else
+          Showoff::Logger.warn "Unknown slide option: #{key}=#{val}"
+        end
+      end
+    end
+
+    if matches[3]
+      @classes = matches[3].split
+    end
+  end
+
+  # currently a mishmash of passed in context and calculated valued extracted from classes
+  def setContext!(context)
+    @section = context[:section] || 'main'
+    @name    = context[:name].chomp('.md')
+    @seq     = context[:seq]
+
+    #TODO: this should be in options
+    # extract id from classes if set, or default to the HTML sanitized name
+    @classes.delete_if { |x| x =~ /^#([\w-]+)/ && @id = $1 }
+    @id ||= @name.dup.gsub(/[^-A-Za-z0-9_]/, '_')
+    @id << seq.to_s if @seq
+
+    # provide an href for the slide. If we've got multiple slides in this file, we'll have a sequence number
+    # include that sequence number to index directly into that content
+    @ref = @seq ? "#{@name}:#{@seq.to_s}" : @name
+
+    #TODO: this should be in options
+    # extract transition from classes, or default to 'none'
+    @classes.delete_if { |x| x =~ /^transition=(.+)/ && @transition = $1 }
+
+    #TODO: this should be in options
+    # extract form id from classes, or default to nil
+    @classes.delete_if { |x| x =~ /^form=(.+)/ && @form = $1 }
+
+    # Extract a section title from subsection slides and add it to state so that it
+    # can be carried forward to subsequent slides until a new section title is discovered.
+    # @see
+    #     https://github.com/puppetlabs/showoff/blob/3f43754c84f97be4284bb34f9bc7c42175d45226/lib/showoff.rb#L499-L508
+    if @classes.include? 'subsection'
+      matches = @markdown.match(/#+ *(.*?)#*$/)
+      @section_title = matches[1] || @section
+      Showoff::State.set(:section_title, @section_title)
+    else
+      @section_title = Showoff::State.get(:section_title) || @section
+    end
+  end
+
+end