voloko-sdoc 0.1.2 → 0.1.3

data/rdoc/lib/rdoc/markup/to_html_crossref.rb

@@ -0,0 +1,140 @@
+require 'rdoc/markup/to_html'
+
+##
+# Subclass of the RDoc::Markup::ToHtml class that supports looking up words
+# from a context.  Those that are found will be hyperlinked.
+
+class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
+
+  ##
+  # Regular expressions to match class and method references.
+  #
+  # 1) There can be a '\' in front of text to suppress any cross-references
+  # 2) There can be a '::' in front of class names to reference from the
+  #    top-level namespace.
+  # 3) The method can be followed by parenthesis which may
+
+  CLASS_REGEXP_STR = '\\\\?((?:\:{2})?[A-Z]\w*(?:\:\:\w+)*)'
+  METHOD_REGEXP_STR = '(\w+[!?=]?)(?:\([\.\w+\*\/\+\-\=\<\>]*\))?'
+
+  ##
+  # Regular expressions matching text that should potentially have
+  # cross-reference links generated are passed to add_special.  Note that
+  # these expressions are meant to pick up text for which cross-references
+  # have been suppressed, since the suppression characters are removed by the
+  # code that is triggered.
+
+  CROSSREF_REGEXP = /(
+                      # A::B::C.meth
+                      #{CLASS_REGEXP_STR}[\.\#]#{METHOD_REGEXP_STR}
+
+                      # Stand-alone method (proceeded by a #)
+                      | \\?\##{METHOD_REGEXP_STR}
+
+                      # A::B::C
+                      # The stuff after CLASS_REGEXP_STR is a
+                      # nasty hack.  CLASS_REGEXP_STR unfortunately matches
+                      # words like dog and cat (these are legal "class"
+                      # names in Fortran 95).  When a word is flagged as a
+                      # potential cross-reference, limitations in the markup
+                      # engine suppress other processing, such as typesetting.
+                      # This is particularly noticeable for contractions.
+                      # In order that words like "can't" not
+                      # be flagged as potential cross-references, only
+                      # flag potential class cross-references if the character
+                      # after the cross-referece is a space or sentence
+                      # punctuation.
+                      | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;]|\z)
+
+                      # Things that look like filenames
+                      # The key thing is that there must be at least
+                      # one special character (period, slash, or
+                      # underscore).
+                      | [\/\w]+[_\/\.][\w\/\.]+
+
+                      # Things that have markup suppressed
+                      | \\[^\s]
+                      )/x
+
+  ##
+  # RDoc::CodeObject for generating references
+
+  attr_accessor :context
+
+  ##
+  # Creates a new crossref resolver that generates links relative to +context+
+  # which lives at +from_path+ in the generated files.  '#' characters on
+  # references are removed unless +show_hash+ is true.
+
+  def initialize(from_path, context, show_hash)
+    raise ArgumentError, 'from_path cannot be nil' if from_path.nil?
+    super()
+
+    @markup.add_special(CROSSREF_REGEXP, :CROSSREF)
+
+    @from_path = from_path
+    @context = context
+    @show_hash = show_hash
+
+    @seen = {}
+  end
+
+  ##
+  # We're invoked when any text matches the CROSSREF pattern (defined in
+  # MarkUp).  If we find the corresponding reference, generate a hyperlink.
+  # If the name we're looking for contains no punctuation, we look for it up
+  # the module/class chain.  For example, HyperlinkHtml is found, even without
+  # the Generator:: prefix, because we look for it in module Generator first.
+
+  def handle_special_CROSSREF(special)
+    name = special.text
+
+    # This ensures that words entirely consisting of lowercase letters will
+    # not have cross-references generated (to suppress lots of erroneous
+    # cross-references to "new" in text, for instance)
+    return name if name =~ /\A[a-z]*\z/
+
+    return @seen[name] if @seen.include? name
+
+    if name[0, 1] == '#' then
+      lookup = name[1..-1]
+      name = lookup unless @show_hash
+    else
+      lookup = name
+    end
+
+    # Find class, module, or method in class or module.
+    #
+    # Do not, however, use an if/elsif/else chain to do so.  Instead, test
+    # each possible pattern until one matches.  The reason for this is that a
+    # string like "YAML.txt" could be the txt() class method of class YAML (in
+    # which case it would match the first pattern, which splits the string
+    # into container and method components and looks up both) or a filename
+    # (in which case it would match the last pattern, which just checks
+    # whether the string as a whole is a known symbol).
+
+    if /#{CLASS_REGEXP_STR}[\.\#]#{METHOD_REGEXP_STR}/ =~ lookup then
+      container = $1
+      method = $2
+      ref = @context.find_symbol container, method
+    end
+
+    ref = @context.find_symbol lookup unless ref
+
+    out = if lookup == '\\' then
+            lookup
+          elsif lookup =~ /^\\/ then
+            $'
+          elsif ref and ref.document_self then
+            "<a href=\"#{ref.as_href(@from_path)}\">#{name}</a>"
+          else
+            name
+          end
+
+    @seen[name] = out
+
+    out
+  end
+
+end
+

data/rdoc/lib/rdoc/markup/to_latex.rb

@@ -0,0 +1,328 @@
+require 'rdoc/markup/formatter'
+require 'rdoc/markup/fragments'
+require 'rdoc/markup/inline'
+
+require 'cgi'
+
+##
+# Convert SimpleMarkup to basic LaTeX report format.
+
+class RDoc::Markup::ToLaTeX < RDoc::Markup::Formatter
+
+  BS = "\020"   # \
+  OB = "\021"   # {
+  CB = "\022"   # }
+  DL = "\023"   # Dollar
+
+  BACKSLASH   = "#{BS}symbol#{OB}92#{CB}"
+  HAT         = "#{BS}symbol#{OB}94#{CB}"
+  BACKQUOTE   = "#{BS}symbol#{OB}0#{CB}"
+  TILDE       = "#{DL}#{BS}sim#{DL}"
+  LESSTHAN    = "#{DL}<#{DL}"
+  GREATERTHAN = "#{DL}>#{DL}"
+
+  def self.l(str)
+    str.tr('\\', BS).tr('{', OB).tr('}', CB).tr('$', DL)
+  end
+
+  def l(arg)
+    RDoc::Markup::ToLaTeX.l(arg)
+  end
+
+  LIST_TYPE_TO_LATEX = {
+    :BULLET =>  [ l("\\begin{itemize}"), l("\\end{itemize}") ],
+    :NUMBER =>  [ l("\\begin{enumerate}"), l("\\end{enumerate}"), "\\arabic" ],
+    :UPPERALPHA =>  [ l("\\begin{enumerate}"), l("\\end{enumerate}"), "\\Alph" ],
+    :LOWERALPHA =>  [ l("\\begin{enumerate}"), l("\\end{enumerate}"), "\\alph" ],
+    :LABELED => [ l("\\begin{description}"), l("\\end{description}") ],
+    :NOTE    => [
+      l("\\begin{tabularx}{\\linewidth}{@{} l X @{}}"),
+      l("\\end{tabularx}") ],
+  }
+
+  InlineTag = Struct.new(:bit, :on, :off)
+
+  def initialize
+    init_tags
+    @list_depth = 0
+    @prev_list_types = []
+  end
+
+  ##
+  # Set up the standard mapping of attributes to LaTeX
+
+  def init_tags
+    @attr_tags = [
+      InlineTag.new(RDoc::Markup::Attribute.bitmap_for(:BOLD), l("\\textbf{"), l("}")),
+      InlineTag.new(RDoc::Markup::Attribute.bitmap_for(:TT),   l("\\texttt{"), l("}")),
+      InlineTag.new(RDoc::Markup::Attribute.bitmap_for(:EM),   l("\\emph{"), l("}")),
+    ]
+  end
+
+  ##
+  # Escape a LaTeX string
+
+  def escape(str)
+    $stderr.print "FE: ", str if $DEBUG_RDOC
+    s = str.
+       sub(/\s+$/, '').
+      gsub(/([_\${}&%#])/, "#{BS}\\1").
+      gsub(/\\/, BACKSLASH).
+      gsub(/\^/, HAT).
+      gsub(/~/,  TILDE).
+      gsub(/</,  LESSTHAN).
+      gsub(/>/,  GREATERTHAN).
+      gsub(/,,/, ",{},").
+      gsub(/\`/,  BACKQUOTE)
+    $stderr.print "-> ", s, "\n" if $DEBUG_RDOC
+    s
+  end
+
+  ##
+  # Add a new set of LaTeX tags for an attribute. We allow
+  # separate start and end tags for flexibility
+
+  def add_tag(name, start, stop)
+    @attr_tags << InlineTag.new(RDoc::Markup::Attribute.bitmap_for(name), start, stop)
+  end
+
+  ##
+  # This is a higher speed (if messier) version of wrap
+
+  def wrap(txt, line_len = 76)
+    res = ""
+    sp = 0
+    ep = txt.length
+    while sp < ep
+      # scan back for a space
+      p = sp + line_len - 1
+      if p >= ep
+        p = ep
+      else
+        while p > sp and txt[p] != ?\s
+          p -= 1
+        end
+        if p <= sp
+          p = sp + line_len
+          while p < ep and txt[p] != ?\s
+            p += 1
+          end
+        end
+      end
+      res << txt[sp...p] << "\n"
+      sp = p
+      sp += 1 while sp < ep and txt[sp] == ?\s
+    end
+    res
+  end
+
+  ##
+  # :section: Visitor
+
+  def start_accepting
+    @res = ""
+    @in_list_entry = []
+  end
+
+  def end_accepting
+    @res.tr(BS, '\\').tr(OB, '{').tr(CB, '}').tr(DL, '$')
+  end
+
+  def accept_paragraph(am, fragment)
+    @res << wrap(convert_flow(am.flow(fragment.txt)))
+    @res << "\n"
+  end
+
+  def accept_verbatim(am, fragment)
+    @res << "\n\\begin{code}\n"
+    @res << fragment.txt.sub(/[\n\s]+\Z/, '')
+    @res << "\n\\end{code}\n\n"
+  end
+
+  def accept_rule(am, fragment)
+    size = fragment.param
+    size = 10 if size > 10
+    @res << "\n\n\\rule{\\linewidth}{#{size}pt}\n\n"
+  end
+
+  def accept_list_start(am, fragment)
+    @res << list_name(fragment.type, true) << "\n"
+    @in_list_entry.push false
+  end
+
+  def accept_list_end(am, fragment)
+    if tag = @in_list_entry.pop
+      @res << tag << "\n"
+    end
+    @res << list_name(fragment.type, false) << "\n"
+  end
+
+  def accept_list_item(am, fragment)
+    if tag = @in_list_entry.last
+      @res << tag << "\n"
+    end
+    @res << list_item_start(am, fragment)
+    @res << wrap(convert_flow(am.flow(fragment.txt))) << "\n"
+    @in_list_entry[-1] = list_end_for(fragment.type)
+  end
+
+  def accept_blank_line(am, fragment)
+    # @res << "\n"
+  end
+
+  def accept_heading(am, fragment)
+    @res << convert_heading(fragment.head_level, am.flow(fragment.txt))
+  end
+
+  private
+
+  def on_tags(res, item)
+    attr_mask = item.turn_on
+    return if attr_mask.zero?
+
+    @attr_tags.each do |tag|
+      if attr_mask & tag.bit != 0
+        res << tag.on
+      end
+    end
+  end
+
+  def off_tags(res, item)
+    attr_mask = item.turn_off
+    return if attr_mask.zero?
+
+    @attr_tags.reverse_each do |tag|
+      if attr_mask & tag.bit != 0
+        res << tag.off
+      end
+    end
+  end
+
+  def convert_flow(flow)
+    res = ""
+    flow.each do |item|
+      case item
+      when String
+        $stderr.puts "Converting '#{item}'" if $DEBUG_RDOC
+        res << convert_string(item)
+      when AttrChanger
+        off_tags(res, item)
+        on_tags(res,  item)
+      when Special
+        res << convert_special(item)
+      else
+        raise "Unknown flow element: #{item.inspect}"
+      end
+    end
+    res
+  end
+
+  ##
+  # some of these patterns are taken from SmartyPants...
+
+  def convert_string(item)
+    escape(item).
+
+    # convert ... to elipsis (and make sure .... becomes .<elipsis>)
+      gsub(/\.\.\.\./, '.\ldots{}').gsub(/\.\.\./, '\ldots{}').
+
+    # convert single closing quote
+      gsub(%r{([^ \t\r\n\[\{\(])\'}, '\1\'').
+      gsub(%r{\'(?=\W|s\b)}, "'" ).
+
+    # convert single opening quote
+      gsub(/'/, '`').
+
+    # convert double closing quote
+      gsub(%r{([^ \t\r\n\[\{\(])\"(?=\W)}, "\\1''").
+
+    # convert double opening quote
+      gsub(/"/, "``").
+
+    # convert copyright
+      gsub(/\(c\)/, '\copyright{}')
+
+  end
+
+  def convert_special(special)
+    handled = false
+    Attribute.each_name_of(special.type) do |name|
+      method_name = "handle_special_#{name}"
+      if self.respond_to? method_name
+        special.text = send(method_name, special)
+        handled = true
+      end
+    end
+    raise "Unhandled special: #{special}" unless handled
+    special.text
+  end
+
+  def convert_heading(level, flow)
+    res =
+      case level
+      when 1 then "\\chapter{"
+      when 2 then "\\section{"
+      when 3 then "\\subsection{"
+      when 4 then "\\subsubsection{"
+      else  "\\paragraph{"
+      end +
+      convert_flow(flow) +
+      "}\n"
+  end
+
+  def list_name(list_type, is_open_tag)
+    tags = LIST_TYPE_TO_LATEX[list_type] || raise("Invalid list type: #{list_type.inspect}")
+    if tags[2] # enumerate
+      if is_open_tag
+        @list_depth += 1
+        if @prev_list_types[@list_depth] != tags[2]
+          case @list_depth
+          when 1
+            roman = "i"
+          when 2
+            roman = "ii"
+          when 3
+            roman = "iii"
+          when 4
+            roman = "iv"
+          else
+            raise("Too deep list: level #{@list_depth}")
+          end
+          @prev_list_types[@list_depth] = tags[2]
+          return l("\\renewcommand{\\labelenum#{roman}}{#{tags[2]}{enum#{roman}}}") + "\n" + tags[0]
+        end
+      else
+        @list_depth -= 1
+      end
+    end
+    tags[ is_open_tag ? 0 : 1]
+  end
+
+  def list_item_start(am, fragment)
+    case fragment.type
+    when :BULLET, :NUMBER, :UPPERALPHA, :LOWERALPHA then
+      "\\item "
+
+    when :LABELED then
+      "\\item[" + convert_flow(am.flow(fragment.param)) + "] "
+
+    when :NOTE then
+        convert_flow(am.flow(fragment.param)) + " & "
+    else
+      raise "Invalid list type"
+    end
+  end
+
+  def list_end_for(fragment_type)
+    case fragment_type
+    when :BULLET, :NUMBER, :UPPERALPHA, :LOWERALPHA, :LABELED then
+      ""
+    when :NOTE
+      "\\\\\n"
+    else
+      raise "Invalid list type"
+    end
+  end
+
+end
+

data/rdoc/lib/rdoc/markup/to_test.rb

@@ -0,0 +1,53 @@
+require 'rdoc/markup'
+require 'rdoc/markup/formatter'
+
+##
+# This Markup outputter is used for testing purposes.
+
+class RDoc::Markup::ToTest < RDoc::Markup::Formatter
+
+  ##
+  # :section: Visitor
+
+  def start_accepting
+    @res = []
+  end
+
+  def end_accepting
+    @res
+  end
+
+  def accept_paragraph(am, fragment)
+    @res << fragment.to_s
+  end
+
+  def accept_verbatim(am, fragment)
+    @res << fragment.to_s
+  end
+
+  def accept_list_start(am, fragment)
+    @res << fragment.to_s
+  end
+
+  def accept_list_end(am, fragment)
+    @res << fragment.to_s
+  end
+
+  def accept_list_item(am, fragment)
+    @res << fragment.to_s
+  end
+
+  def accept_blank_line(am, fragment)
+    @res << fragment.to_s
+  end
+
+  def accept_heading(am, fragment)
+    @res << fragment.to_s
+  end
+
+  def accept_rule(am, fragment)
+    @res << fragment.to_s
+  end
+
+end
+

data/rdoc/lib/rdoc/markup/to_texinfo.rb

@@ -0,0 +1,73 @@
+require 'rdoc/markup/formatter'
+require 'rdoc/markup/fragments'
+require 'rdoc/markup/inline'
+
+require 'rdoc/markup'
+require 'rdoc/markup/formatter'
+
+##
+# Convert SimpleMarkup to basic TexInfo format
+#
+# TODO: WTF is AttributeManager for?
+
+class RDoc::Markup::ToTexInfo < RDoc::Markup::Formatter
+
+  def format(text)
+    text.txt.
+      gsub(/@/, "@@").
+      gsub(/\{/, "@{").
+      gsub(/\}/, "@}").
+      # gsub(/,/, "@,"). # technically only required in cross-refs
+      gsub(/\+([\w]+)\+/, "@code{\\1}").
+      gsub(/\<tt\>([^<]+)\<\/tt\>/, "@code{\\1}").
+      gsub(/\*([\w]+)\*/, "@strong{\\1}").
+      gsub(/\<b\>([^<]+)\<\/b\>/, "@strong{\\1}").
+      gsub(/_([\w]+)_/, "@emph{\\1}").
+      gsub(/\<em\>([^<]+)\<\/em\>/, "@emph{\\1}")
+  end
+
+  # :section: Visitor
+
+  def start_accepting
+    @text = []
+  end
+
+  def end_accepting
+    @text.join("\n")
+  end
+
+  def accept_paragraph(attributes, text)
+    @text << format(text)
+  end
+
+  def accept_verbatim(attributes, text)
+    @text << "@verb{|#{format(text)}|}"
+  end
+
+  def accept_heading(attributes, text)
+    heading = ['@majorheading', '@chapheading'][text.head_level - 1] || '@heading'
+    @text << "#{heading} #{format(text)}"
+  end
+
+  def accept_list_start(attributes, text)
+    @text << '@itemize @bullet'
+  end
+
+  def accept_list_end(attributes, text)
+    @text << '@end itemize'
+  end
+
+  def accept_list_item(attributes, text)
+    @text << "@item\n#{format(text)}"
+  end
+
+  def accept_blank_line(attributes, text)
+    @text << "\n"
+  end
+
+  def accept_rule(attributes, text)
+    @text << '-----'
+  end
+
+end
+