diff options
author | drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2011-02-05 06:20:57 +0000 |
---|---|---|
committer | drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2011-02-05 06:20:57 +0000 |
commit | 8aa895294b8d696489b51a5e69b2986f452da905 (patch) | |
tree | 085fe578ab276ff3be423448a4b9407c60a6dc51 /lib/rdoc | |
parent | d8ebf3829f24fcb05ff47a12a9bb83e8b993aeae (diff) |
Import RDoc 3.5.2
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@30795 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/rdoc')
-rw-r--r-- | lib/rdoc/any_method.rb | 4 | ||||
-rw-r--r-- | lib/rdoc/context.rb | 143 | ||||
-rw-r--r-- | lib/rdoc/generator/markup.rb | 29 | ||||
-rw-r--r-- | lib/rdoc/generator/template/darkfish/classpage.rhtml | 253 | ||||
-rw-r--r-- | lib/rdoc/generator/template/darkfish/rdoc.css | 51 | ||||
-rw-r--r-- | lib/rdoc/markup.rb | 14 | ||||
-rw-r--r-- | lib/rdoc/markup/to_html.rb | 144 | ||||
-rw-r--r-- | lib/rdoc/options.rb | 2 | ||||
-rw-r--r-- | lib/rdoc/text.rb | 32 |
9 files changed, 401 insertions, 271 deletions
diff --git a/lib/rdoc/any_method.rb b/lib/rdoc/any_method.rb index 5877ec9662..f691598910 100644 --- a/lib/rdoc/any_method.rb +++ b/lib/rdoc/any_method.rb @@ -44,7 +44,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr ## # Adds +an_alias+ as an alias for this method in +context+. - def add_alias(an_alias, context) + def add_alias(an_alias, context = nil ) method = self.class.new an_alias.text, an_alias.new_name method.record_location an_alias.file @@ -54,7 +54,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr method.comment = an_alias.comment method.is_alias_for = self @aliases << method - context.add_method method + context.add_method( method ) if context method end diff --git a/lib/rdoc/context.rb b/lib/rdoc/context.rb index 3c12d10058..3f2856db05 100644 --- a/lib/rdoc/context.rb +++ b/lib/rdoc/context.rb @@ -60,11 +60,6 @@ class RDoc::Context < RDoc::CodeObject attr_reader :requires ## - # Sections in this context - - attr_reader :sections - - ## # Hash <tt>old_name => [aliases]</tt>, for aliases # that haven't (yet) been resolved to a method/attribute. # (Not to be confused with the aliases of the context.) @@ -93,13 +88,18 @@ class RDoc::Context < RDoc::CodeObject attr_reader :constants_hash ## - # A per-comment section of documentation like: + # A section of documentation like: # # # :section: The title # # The body + # + # Sections can be referenced multiple times and will be collapsed into a + # single section. class Section + include RDoc::Text + ## # Section comment @@ -111,11 +111,6 @@ class RDoc::Context < RDoc::CodeObject attr_reader :parent ## - # Section sequence number (for linking) - - attr_reader :sequence - - ## # Section title attr_reader :title @@ -125,56 +120,84 @@ class RDoc::Context < RDoc::CodeObject ## # Creates a new section with +title+ and +comment+ - def initialize(parent, title, comment) + def initialize parent, title, comment @parent = parent - @title = title + @title = title ? title.strip : title @@sequence.succ! @sequence = @@sequence.dup - set_comment comment + @comment = extract_comment comment end ## - # Sections are equal when they have the same #sequence + # Sections are equal when they have the same #title - def ==(other) - self.class === other and @sequence == other.sequence + def == other + self.class === other and @title == other.title end - def inspect # :nodoc: - "#<%s:0x%x %s %p>" % [ - self.class, object_id, - @sequence, title - ] + ## + # Anchor reference for linking to this section + + def aref + title = @title || '[untitled]' + + CGI.escape(title).gsub('%', '-').sub(/^-/, '') + end + + ## + # Appends +comment+ to the current comment separated by a rule. + + def comment= comment + comment = extract_comment comment + + return if comment.empty? + + if @comment then + @comment += "\n# ---\n#{comment}" + else + @comment = comment + end end ## - # Set the comment for this section from the original comment block. If - # the first line contains :section:, strip it and use the rest. + # Extracts the comment for this section from the original comment block. + # If the first line contains :section:, strip it and use the rest. # Otherwise remove lines up to the line containing :section:, and look # for those lines again at the end and remove them. This lets us write # # # :section: The title # # The body - def set_comment(comment) - return unless comment - + def extract_comment comment if comment =~ /^#[ \t]*:section:.*\n/ then start = $` rest = $' - if start.empty? - @comment = rest + if start.empty? then + rest else - @comment = rest.sub(/#{start.chomp}\Z/, '') + rest.sub(/#{start.chomp}\Z/, '') end else - @comment = comment + comment end + end - @comment = nil if @comment.empty? + def inspect # :nodoc: + "#<%s:0x%x %s %p>" % [ + self.class, object_id, + @sequence, title + ] + end + + ## + # Section sequence number (deprecated) + + def sequence + warn "RDoc::Context::Section#sequence is deprecated, use #aref" + @sequence end end @@ -192,7 +215,7 @@ class RDoc::Context < RDoc::CodeObject @visibility = :public @current_section = Section.new self, nil, nil - @sections = [@current_section] + @sections = { nil => @current_section } @classes = {} @modules = {} @@ -670,6 +693,28 @@ class RDoc::Context < RDoc::CodeObject end ## + # Iterator for each section's contents sorted by title. The +section+, the + # section's +constants+ and the sections +attributes+ are yielded. The + # +constants+ and +attributes+ collections are sorted. + # + # To retrieve methods in a section use #methods_by_type with the optional + # +section+ parameter. + # + # NOTE: Do not edit collections yielded by this method + + def each_section # :yields: section, constants, attributes + constants = @constants.group_by do |constant| constant.section end + constants.default = [] + + attributes = @attributes.group_by do |attribute| attribute.section end + attributes.default = [] + + @sections.sort_by { |title, _| title.to_s }.each do |_, section| + yield section, constants[section].sort, attributes[section].sort + end + end + + ## # Finds an attribute +name+ with singleton value +singleton+. def find_attribute(name, singleton) @@ -876,10 +921,13 @@ class RDoc::Context < RDoc::CodeObject end ## - # Breaks method_list into a nested hash by type (class or instance) and - # visibility (public, protected, private) + # Breaks method_list into a nested hash by type (<tt>'class'</tt> or + # <tt>'instance'</tt>) and visibility (+:public+, +:protected+, +:private+). + # + # If +section+ is provided only methods in that RDoc::Context::Section will + # be returned. - def methods_by_type + def methods_by_type section = nil methods = {} TYPES.each do |type| @@ -892,6 +940,7 @@ class RDoc::Context < RDoc::CodeObject end each_method do |method| + next if section and not method.section == section methods[method.type][method.visibility] << method end @@ -997,11 +1046,29 @@ class RDoc::Context < RDoc::CodeObject end ## + # Sections in this context + + def sections + @sections.values + end + + def sections_hash # :nodoc: + @sections + end + + ## # Creates a new section with +title+ and +comment+ def set_current_section(title, comment) - @current_section = Section.new self, title, comment - @sections << @current_section + if @sections.key? title then + @current_section = @sections[title] + @current_section.comment = comment + else + @current_section = Section.new self, title, comment + @sections[title] = @current_section + end + + @current_section end ## diff --git a/lib/rdoc/generator/markup.rb b/lib/rdoc/generator/markup.rb index dd7c73044d..1919a62ec8 100644 --- a/lib/rdoc/generator/markup.rb +++ b/lib/rdoc/generator/markup.rb @@ -62,22 +62,6 @@ end class RDoc::AnyMethod - ## - # Maps RDoc::RubyToken classes to CSS class names - - STYLE_MAP = { - RDoc::RubyToken::TkCONSTANT => 'ruby-constant', - RDoc::RubyToken::TkKW => 'ruby-keyword', - RDoc::RubyToken::TkIVAR => 'ruby-ivar', - RDoc::RubyToken::TkOp => 'ruby-operator', - RDoc::RubyToken::TkId => 'ruby-identifier', - RDoc::RubyToken::TkNode => 'ruby-node', - RDoc::RubyToken::TkCOMMENT => 'ruby-comment', - RDoc::RubyToken::TkREGEXP => 'ruby-regexp', - RDoc::RubyToken::TkSTRING => 'ruby-string', - RDoc::RubyToken::TkVal => 'ruby-value', - } - include RDoc::Generator::Markup @add_line_numbers = false @@ -130,7 +114,18 @@ class RDoc::AnyMethod @token_stream.each do |t| next unless t - style = STYLE_MAP[t.class] + style = case t + when RDoc::RubyToken::TkCONSTANT then 'ruby-constant' + when RDoc::RubyToken::TkKW then 'ruby-keyword' + when RDoc::RubyToken::TkIVAR then 'ruby-ivar' + when RDoc::RubyToken::TkOp then 'ruby-operator' + when RDoc::RubyToken::TkId then 'ruby-identifier' + when RDoc::RubyToken::TkNode then 'ruby-node' + when RDoc::RubyToken::TkCOMMENT then 'ruby-comment' + when RDoc::RubyToken::TkREGEXP then 'ruby-regexp' + when RDoc::RubyToken::TkSTRING then 'ruby-string' + when RDoc::RubyToken::TkVal then 'ruby-value' + end text = CGI.escapeHTML t.text diff --git a/lib/rdoc/generator/template/darkfish/classpage.rhtml b/lib/rdoc/generator/template/darkfish/classpage.rhtml index 4a1bdcdea9..856321532b 100644 --- a/lib/rdoc/generator/template/darkfish/classpage.rhtml +++ b/lib/rdoc/generator/template/darkfish/classpage.rhtml @@ -9,17 +9,13 @@ <link rel="stylesheet" href="<%= rel_prefix %>/rdoc.css" type="text/css" media="screen" /> - <script src="<%= rel_prefix %>/js/jquery.js" type="text/javascript" - charset="utf-8"></script> - <script src="<%= rel_prefix %>/js/thickbox-compressed.js" type="text/javascript" - charset="utf-8"></script> - <script src="<%= rel_prefix %>/js/quicksearch.js" type="text/javascript" - charset="utf-8"></script> - <script src="<%= rel_prefix %>/js/darkfish.js" type="text/javascript" - charset="utf-8"></script> + <script src="<%= rel_prefix %>/js/jquery.js" type="text/javascript" charset="utf-8"></script> + <script src="<%= rel_prefix %>/js/thickbox-compressed.js" type="text/javascript" charset="utf-8"></script> + <script src="<%= rel_prefix %>/js/quicksearch.js" type="text/javascript" charset="utf-8"></script> + <script src="<%= rel_prefix %>/js/darkfish.js" type="text/javascript" charset="utf-8"></script> </head> -<body class="<%= klass.type %>"> +<body id="top" class="<%= klass.type %>"> <div id="metadata"> <div id="home-metadata"> @@ -45,7 +41,7 @@ </div> </div> - <% if !svninfo.empty? %> + <% if !svninfo.empty? then %> <div id="file-svninfo-section" class="section"> <h3 class="section-header">Subversion Info</h3> <div class="section-body"> @@ -66,9 +62,8 @@ </div> <div id="class-metadata"> - + <% if klass.type == 'class' then %> <!-- Parent Class --> - <% if klass.type == 'class' %> <div id="parent-class-section" class="section"> <h3 class="section-header">Parent</h3> <% if klass.superclass and not String === klass.superclass then %> @@ -79,8 +74,20 @@ </div> <% end %> + <% unless klass.sections.length == 1 then %> + <!-- Sections --> + <div id="sections-section" class="section"> + <h3 class="section-header">Sections</h3> + <ul class="link-list"> + <% klass.sections.sort_by { |s| s.title.to_s }.each do |section| %> + <li><a href="#<%= section.aref %>"><%= h section.title %></a></li> + <% end %> + </ul> + </div> + <% end %> + + <% unless klass.classes_and_modules.empty? then %> <!-- Namespace Contents --> - <% unless klass.classes_and_modules.empty? %> <div id="namespace-list-section" class="section"> <h3 class="section-header">Namespace</h3> <ul class="link-list"> @@ -91,8 +98,8 @@ </div> <% end %> + <% unless klass.method_list.empty? then %> <!-- Method Quickref --> - <% unless klass.method_list.empty? %> <div id="method-list-section" class="section"> <h3 class="section-header">Methods</h3> <ul class="link-list"> @@ -103,13 +110,13 @@ </div> <% end %> + <% unless klass.includes.empty? then %> <!-- Included Modules --> - <% unless klass.includes.empty? %> <div id="includes-section" class="section"> <h3 class="section-header">Included Modules</h3> <ul class="link-list"> <% klass.each_include do |inc| %> - <% unless String === inc.module %> + <% unless String === inc.module then %> <li><a class="include" href="<%= klass.aref_to inc.module.path %>"><%= inc.module.full_name %></a></li> <% else %> <li><span class="include"><%= inc.name %></span></li> @@ -154,7 +161,7 @@ <div id="no-class-search-results" style="display: none;">No matching classes.</div> </div> - <% if $DEBUG_RDOC %> + <% if $DEBUG_RDOC then %> <div id="debugging-toggle"><img src="<%= rel_prefix %>/images/bug.png" alt="toggle debugging" height="16" width="16" /></div> <% end %> @@ -164,126 +171,142 @@ <div id="documentation"> <h1 class="<%= klass.type %>"><%= klass.full_name %></h1> - <div id="description"> + <div id="description" class="description"> <%= klass.description %> - </div> + </div><!-- description --> + + <% klass.each_section do |section, constants, attributes| %> + <div id="<%= section.aref %>" class="documentation-section"> + <% if section.title then %> + <h2 class="section-header"> + <%= section.title %> + <a href="#top">↑ top</a> + </h2> + <% end %> - <!-- Constants --> - <% unless klass.constants.empty? %> - <div id="constants-list" class="section"> - <h3 class="section-header">Constants</h3> - <dl> - <% klass.each_constant do |const| %> - <dt><a name="<%= const.name %>"><%= const.name %></a></dt> - <% if const.comment %> - <dd class="description"><%= const.description.strip %></dd> - <% else %> - <dd class="description missing-docs">(Not documented)</dd> - <% end %> + <% if section.comment then %> + <div class="description"> + <%= section.description %> + </div> <% end %> - </dl> - </div> - <% end %> - - <!-- Attributes --> - <% unless klass.attributes.empty? %> - <div id="attribute-method-details" class="method-section section"> - <h3 class="section-header">Attributes</h3> - - <% klass.each_attribute do |attrib| %> - <div id="<%= attrib.html_name %>-attribute-method" class="method-detail"> - <a name="<%= h attrib.name %>"></a> - <% if attrib.rw =~ /w/i %> - <a name="<%= h attrib.name %>="></a> - <% end %> - <div class="method-heading attribute-method-heading"> - <span class="method-name"><%= h attrib.name %></span><span - class="attribute-access-type">[<%= attrib.rw %>]</span> - </div> - <div class="method-description"> - <% if attrib.comment %> - <%= attrib.description.strip %> - <% else %> - <p class="missing-docs">(Not documented)</p> + <% unless constants.empty? then %> + <!-- Constants --> + <div id="constants-list" class="section"> + <h3 class="section-header">Constants</h3> + <dl> + <% constants.each do |const| %> + <dt><a name="<%= const.name %>"><%= const.name %></a></dt> + <% if const.comment then %> + <dd class="description"><%= const.description.strip %></dd> + <% else %> + <dd class="description missing-docs">(Not documented)</dd> + <% end %> <% end %> - </div> + </dl> </div> <% end %> - </div> - <% end %> - - <!-- Methods --> - <% klass.methods_by_type.each do |type, visibilities| - next if visibilities.empty? - visibilities.each do |visibility, methods| - next if methods.empty? %> - <div id="<%= visibility %>-<%= type %>-method-details" class="method-section section"> - <h3 class="section-header"><%= visibility.to_s.capitalize %> <%= type.capitalize %> Methods</h3> - - <% methods.each do |method| %> - <div id="<%= method.html_name %>-method" class="method-detail <%= method.is_alias_for ? "method-alias" : '' %>"> - <a name="<%= h method.aref %>"></a> - - <% if method.call_seq %> - <% method.call_seq.strip.split("\n").each_with_index do |call_seq, i| %> - <div class="method-heading"> - <span class="method-callseq"><%= call_seq.strip.gsub(/->/, '→').gsub( /^\w+\./m, '') %></span> - <% if i == 0 %> - <span class="method-click-advice">click to toggle source</span> + + <% unless attributes.empty? then %> + <!-- Attributes --> + <div id="attribute-method-details" class="method-section section"> + <h3 class="section-header">Attributes</h3> + + <% attributes.each do |attrib| %> + <div id="<%= attrib.html_name %>-attribute-method" class="method-detail"> + <a name="<%= h attrib.name %>"></a> + <% if attrib.rw =~ /w/i then %> + <a name="<%= h attrib.name %>="></a> <% end %> + <div class="method-heading attribute-method-heading"> + <span class="method-name"><%= h attrib.name %></span><span + class="attribute-access-type">[<%= attrib.rw %>]</span> + </div> + + <div class="method-description"> + <% if attrib.comment then %> + <%= attrib.description.strip %> + <% else %> + <p class="missing-docs">(Not documented)</p> + <% end %> + </div> </div> <% end %> - <% else %> - <div class="method-heading"> - <span class="method-name"><%= h method.name %></span><span - class="method-args"><%= method.params %></span> - <span class="method-click-advice">click to toggle source</span> - </div> - <% end %> + </div><!-- attribute-method-details --> + <% end %> - <div class="method-description"> - <% if method.comment %> - <%= method.description.strip %> + <!-- Methods --> + <% klass.methods_by_type(section).each do |type, visibilities| + next if visibilities.empty? + visibilities.each do |visibility, methods| + next if methods.empty? %> + <div id="<%= visibility %>-<%= type %>-method-details" class="method-section section"> + <h3 class="section-header"><%= visibility.to_s.capitalize %> <%= type.capitalize %> Methods</h3> + + <% methods.each do |method| %> + <div id="<%= method.html_name %>-method" class="method-detail <%= method.is_alias_for ? "method-alias" : '' %>"> + <a name="<%= h method.aref %>"></a> + + <% if method.call_seq then %> + <% method.call_seq.strip.split("\n").each_with_index do |call_seq, i| %> + <div class="method-heading"> + <span class="method-callseq"><%= call_seq.strip.gsub(/->/, '→').gsub( /^\w+\./m, '') %></span> + <% if i == 0 then %> + <span class="method-click-advice">click to toggle source</span> + <% end %> + </div> + <% end %> <% else %> - <p class="missing-docs">(Not documented)</p> + <div class="method-heading"> + <span class="method-name"><%= h method.name %></span><span + class="method-args"><%= method.params %></span> + <span class="method-click-advice">click to toggle source</span> + </div> <% end %> - <% if method.token_stream %> - <div class="method-source-code" - id="<%= method.html_name %>-source"> + <div class="method-description"> + <% if method.comment then %> + <%= method.description.strip %> + <% else %> + <p class="missing-docs">(Not documented)</p> + <% end %> + + <% if method.token_stream then %> + <div class="method-source-code" id="<%= method.html_name %>-source"> <pre> <%= method.markup_code %> </pre> + </div><!-- <%= method.html_name %>-source --> + <% end %> </div> - <% end %> - </div> - <% unless method.aliases.empty? %> - <div class="aliases"> - Also aliased as: <%= method.aliases.map do |aka| - if aka.parent then # HACK lib/rexml/encodings - %{<a href="#{klass.aref_to aka.path}">#{h aka.name}</a>} - else - h aka.name - end - end.join ", " %> - </div> - <% end %> + <% unless method.aliases.empty? then %> + <div class="aliases"> + Also aliased as: <%= method.aliases.map do |aka| + if aka.parent then # HACK lib/rexml/encodings + %{<a href="#{klass.aref_to aka.path}">#{h aka.name}</a>} + else + h aka.name + end + end.join ", " %> + </div> + <% end %> - <% if method.is_alias_for then %> - <div class="aliases"> - Alias for: <a href="<%= klass.aref_to method.is_alias_for.path %>"><%= h method.is_alias_for.name %></a> - </div> - <% end %> - </div> + <% if method.is_alias_for then %> + <div class="aliases"> + Alias for: <a href="<%= klass.aref_to method.is_alias_for.path %>"><%= h method.is_alias_for.name %></a> + </div> + <% end %> + </div><!-- <%= method.html_name %>-method --> - <% end %> - </div> - <% end - end %> + <% end %> + </div><!-- <%= visibility %>-<%= type %>-method-details --> + <% end + end %> + </div><!-- <%= section.aref %> --> + <% end %> - </div> + </div><!-- documentation --> <div id="validator-badges"> <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p> diff --git a/lib/rdoc/generator/template/darkfish/rdoc.css b/lib/rdoc/generator/template/darkfish/rdoc.css index 59f568ae47..c5a93ff150 100644 --- a/lib/rdoc/generator/template/darkfish/rdoc.css +++ b/lib/rdoc/generator/template/darkfish/rdoc.css @@ -278,46 +278,46 @@ ul.link-list .type { /* @group Documentation Section */ -#description { +.description { font-size: 100%; color: #333; } -#description p { +.description p { margin: 1em 0.4em; } -#description li p { +.description li p { margin: 0; } -#description ul { +.description ul { margin-left: 1.5em; } -#description ul li { +.description ul li { line-height: 1.4em; } -#description dl, +.description dl, #documentation dl { margin: 8px 1.5em; border: 1px solid #ccc; } -#description dl { +.description dl { font-size: 14px; } -#description dt, +.description dt, #documentation dt { padding: 2px 4px; font-weight: bold; background: #ddd; } -#description dd, +.description dd, #documentation dd { padding: 2px 12px; } -#description dd + dt, +.description dd + dt, #documentation dd + dt { margin-top: 0.7em; } @@ -325,9 +325,21 @@ ul.link-list .type { #documentation .section { font-size: 90%; } -#documentation h3.section-header { + +#documentation h2.section-header { margin-top: 2em; padding: 0.75em 0.5em; + background: #ccc; + color: #333; + font-size: 175%; + border: 1px solid #bbb; + -moz-border-radius: 3px; + -webkit-border-radius: 3px; +} + +#documentation h3.section-header { + margin-top: 2em; + padding: 0.25em 0.5em; background-color: #dedede; color: #333; font-size: 150%; @@ -359,6 +371,23 @@ ul.link-list .type { color: #666; } +.documentation-section h2 { + position: relative; +} + +.documentation-section h2 a { + position: absolute; + top: 8px; + right: 10px; + font-size: 12px; + color: #9b9877; + visibility: hidden; +} + +.documentation-section h2:hover a { + visibility: visible; +} + /* @group Method Details */ #documentation .method-source-code { diff --git a/lib/rdoc/markup.rb b/lib/rdoc/markup.rb index 9a2e7f2ca8..73de2d06f8 100644 --- a/lib/rdoc/markup.rb +++ b/lib/rdoc/markup.rb @@ -502,10 +502,11 @@ require 'rdoc' # Starts a new section in the output. The title following +:section:+ is # used as the section heading, and the remainder of the comment containing # the section is used as introductory text. Subsequent methods, aliases, -# attributes, and classes will be documented in this section. A :section: -# comment block may have one or more lines before the :section: directive. -# These will be removed, and any identical lines at the end of the block are -# also removed. This allows you to add visual cues such as: +# attributes, and classes will be documented in this section. +# +# A :section: comment block may have one or more lines before the :section: +# directive. These will be removed, and any identical lines at the end of +# the block are also removed. This allows you to add visual cues such as: # # # ---------------------------------------- # # :section: My Section @@ -513,7 +514,10 @@ require 'rdoc' # # See it glisten in the noon-day sun. # # ---------------------------------------- # -# <i>Note: Current formatters to not take sections into account.</i> +# Sections may be referenced multiple times in a class or module allowing +# methods, attributes and constants to be ordered one way for implementation +# ordering but still grouped together in documentation. If a section has +# multiple comments they will be concatenated with a dividing rule. # # [+:call-seq:+] # Lines up to the next blank line in the comment are treated as the method's diff --git a/lib/rdoc/markup/to_html.rb b/lib/rdoc/markup/to_html.rb index d587a8abbc..599f3713f1 100644 --- a/lib/rdoc/markup/to_html.rb +++ b/lib/rdoc/markup/to_html.rb @@ -10,6 +10,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter include RDoc::Text + # :section: Utilities + ## # Maps RDoc::Markup::Parser::LIST_TOKENS types to HTML tags @@ -55,6 +57,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter File.join(*from) end + # :section: + ## # Creates a new formatter that will output HTML @@ -75,54 +79,21 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter init_tags end - ## - # Maps attributes to HTML tags - - def init_tags - add_tag :BOLD, "<b>", "</b>" - add_tag :TT, "<tt>", "</tt>" - add_tag :EM, "<em>", "</em>" - end + # :section: Special Handling + # + # These methods handle special markup added by RDoc::Markup#add_special. ## - # Generate a hyperlink for +url+, labeled with +text+. Handles the special - # cases for img: and link: described under handle_special_HYPERLINK - - def gen_url(url, text) - if url =~ /([A-Za-z]+):(.*)/ then - type = $1 - path = $2 - else - type = "http" - path = url - url = "http://#{url}" - end - - if type == "link" then - url = if path[0, 1] == '#' then # is this meaningful? - path - else - self.class.gen_relative_url @from_path, path - end - end - - if (type == "http" or type == "link") and - url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then - "<img src=\"#{url}\" />" - else - "<a href=\"#{url}\">#{text.sub(%r{^#{type}:/*}, '')}</a>" - end - end - - # :section: Special handling - - ## - # And we're invoked with a potential external hyperlink. <tt>mailto:</tt> - # just gets inserted. <tt>http:</tt> links are checked to see if they - # reference an image. If so, that image gets inserted using an - # <tt><img></tt> tag. Otherwise a conventional <tt><a href></tt> is used. - # We also support a special type of hyperlink, <tt>link:</tt>, which is a - # reference to a local file whose path is relative to the --op directory. + # +special+ is a potential hyperlink. The following schemes are handled: + # + # <tt>mailto:</tt>:: + # Inserted as-is. + # <tt>http:</tt>:: + # Links are checked to see if they reference an image. If so, that image + # gets inserted using an <tt><img></tt> tag. Otherwise a conventional + # <tt><a href></tt> is used. + # <tt>link:</tt>:: + # Reference to a local file relative to the output directory. def handle_special_HYPERLINK(special) url = special.text @@ -130,8 +101,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter end ## - # Here's a hyperlink where the label is different to the URL - # <label>[url] or {long label}[url] + # This +special+ is a hyperlink where the label is different from the URL + # label[url] or {long label}[url] def handle_special_TIDYLINK(special) text = special.text @@ -143,41 +114,9 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter gen_url url, label end - # :section: Utilities - - ## - # Wraps +txt+ to +line_len+ - - 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.join.strip - end - # :section: Visitor + # + # These methods implement the HTML visitor. ## # Prepares the visitor for HTML generation @@ -283,6 +222,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter @res << raw.parts.join("\n") end + # :section: Utilities + ## # CGI escapes +text+ @@ -291,6 +232,36 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter end ## + # Generate a hyperlink for +url+, labeled with +text+. Handles the special + # cases for img: and link: described under handle_special_HYPERLINK + + def gen_url(url, text) + if url =~ /([A-Za-z]+):(.*)/ then + type = $1 + path = $2 + else + type = "http" + path = url + url = "http://#{url}" + end + + if type == "link" then + url = if path[0, 1] == '#' then # is this meaningful? + path + else + self.class.gen_relative_url @from_path, path + end + end + + if (type == "http" or type == "link") and + url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then + "<img src=\"#{url}\" />" + else + "<a href=\"#{url}\">#{text.sub(%r{^#{type}:/*}, '')}</a>" + end + end + + ## # Determines the HTML list element for +list_type+ and +open_tag+ def html_list_name(list_type, open_tag) @@ -300,6 +271,15 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter end ## + # Maps attributes to HTML tags + + def init_tags + add_tag :BOLD, "<b>", "</b>" + add_tag :TT, "<tt>", "</tt>" + add_tag :EM, "<em>", "</em>" + end + + ## # Returns the HTML tag for +list_type+, possible using a label from # +list_item+ diff --git a/lib/rdoc/options.rb b/lib/rdoc/options.rb index c5f3b36b8d..dd91706638 100644 --- a/lib/rdoc/options.rb +++ b/lib/rdoc/options.rb @@ -747,7 +747,7 @@ Usage: #{opt.program_name} [options] [names...] if @generator.respond_to? :setup_options then @option_parser ||= OptionParser.new - @generator.setup_options self + @generator.setup_options self end end diff --git a/lib/rdoc/text.rb b/lib/rdoc/text.rb index 6dec4217e6..501871c8df 100644 --- a/lib/rdoc/text.rb +++ b/lib/rdoc/text.rb @@ -260,5 +260,37 @@ http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse html end + ## + # Wraps +txt+ to +line_len+ + + 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.join.strip + end + end |