From d0ae27215b8d51f6e8f37e4e29cb5cbfd2a8d73c Mon Sep 17 00:00:00 2001 From: Brian Campbell Date: Mon, 9 Jan 2012 16:03:29 -0500 Subject: [PATCH 1/3] Display output even if there are no comments Rocco should display the code even if there are no comments. When there are no comments, it produces a single section with an empty docs string. However, to pass it through Markdown, it joins the sections with a delimiter, munges that, and split the result. Joining a list continaing the empty string and splitting it again produces an empty list, not a list containting the empty string: > [""].join("delim").split("delim") => [] In Ruby 1.9, this causes us lose the associated code when when try to zip these lists back together again: > [].zip(["something"]) => [] To fix this, just make sure `docs_html` contains at least a single empty string if it winds up being empty. Fixes: https://github.com/rtomayko/rocco/issues/71 (fix rtomayko/rocco#71) --- lib/rocco.rb | 1 + test/test_reported_issues.rb | 8 ++++++++ 2 files changed, 9 insertions(+) diff --git a/lib/rocco.rb b/lib/rocco.rb index 92c2c23..06504ea 100644 --- a/lib/rocco.rb +++ b/lib/rocco.rb @@ -380,6 +380,7 @@ def highlight(blocks) # into separate sections. markdown = docs_blocks.join("\n\n##### DIVIDER\n\n") docs_html = process_markdown(markdown).split(/\n*
DIVIDER<\/h5>\n*/m) + docs_html << "" if docs_html.empty? # Combine all code blocks into a single big stream with section dividers and # run through either `pygmentize(1)` or diff --git a/test/test_reported_issues.rb b/test/test_reported_issues.rb index 64085ca..7397243 100644 --- a/test/test_reported_issues.rb +++ b/test/test_reported_issues.rb @@ -83,4 +83,12 @@ def test_issue15_extra_space_after_comment_character_remains ) assert_equal("

Comment 1

\n", r.sections[0][0]) end + + def test_issue71_empty_comment + r = roccoize( "filename.rb", "def codeblock\nend\n" ) + assert_equal 1, r.sections.length + assert_equal 2, r.sections[ 0 ].length + assert_match /\s*/, r.sections[ 0 ][ 0 ] + assert_equal "def codeblock\nend", r.sections[ 0 ][ 1 ] + end end From b39f8216d630509d2f77ebf48d4e81309f4d7ea6 Mon Sep 17 00:00:00 2001 From: Brian Campbell Date: Mon, 9 Jan 2012 15:56:53 -0500 Subject: [PATCH 2/3] Allow user to set encoding of files, transcoding to UTF-8 Ruby 1.9 is much more strict about encodings; instead of just reading bytes into the string and hoping you know how to interpret it, it actually keeps track of what encoding it expects the file and the string to be and transcodes between them. This means that we can no longer just read in the ISO-8859-1 as binary, and kind of hope that everything later on ignores it or knows how to cope. Instead, we need to explicitly choose to read the file as ISO-8859-1, and explicitly choose the encoding that we want the string to be in. We use UTF-8, because that's what Pygments and at least some of the Markdown libraries are expecting. Fixes: https://github.com/rtomayko/rocco/issues/73 (fix rtomayko/rocco#73) --- lib/rocco.rb | 32 +++++++++++++++++++++++++------- test/test_reported_issues.rb | 6 ++---- 2 files changed, 27 insertions(+), 11 deletions(-) diff --git a/lib/rocco.rb b/lib/rocco.rb index 06504ea..f1f4a6c 100644 --- a/lib/rocco.rb +++ b/lib/rocco.rb @@ -73,7 +73,10 @@ # # * `:stylesheet`, which specifies the css stylesheet to use for each # rendered template. _Defaults to `http://jashkenas.github.com/docco/resources/docco.css` -# (the original docco stylesheet) +# (the original docco stylesheet)._ +# +# * `:encoding`: specifies the encoding that input files are written in. +# _Defaults to `UTF-8`_. class Rocco VERSION = '0.8.2' @@ -81,18 +84,19 @@ def initialize(filename, sources=[], options={}) @file = filename @sources = sources - # When `block` is given, it must read the contents of the file using - # whatever means necessary and return it as a string. With no `block`, - # the file is read to retrieve data. - @data = if block_given? then yield else File.read(filename) end - @options = { :language => 'ruby', :comment_chars => '#', :template_file => nil, - :stylesheet => 'http://jashkenas.github.com/docco/resources/docco.css' + :stylesheet => 'http://jashkenas.github.com/docco/resources/docco.css', + :encoding => 'UTF-8' }.merge(options) + # When `block` is given, it must read the contents of the file using + # whatever means necessary and return it as a string. With no `block`, + # the file is read to retrieve data. + @data = if block_given? then yield else read_with_encoding(filename) end + # If we detect a language if "text" != detect_language # then assign the detected language to `:language`, and look for @@ -148,6 +152,20 @@ def to_html # Helper Functions # ---------------- + # Read *file* encoded `@options[:encoding]` into a string encoded in UTF-8. + def read_with_encoding filename + # This works differently in Ruby 1.8 and Ruby 1.9, which are + # distinguished by checking if `IO#external_encoding` exists. + if IO.method_defined?("external_encoding") + File.read(filename, :external_encoding => @options[:encoding], + :internal_encoding => "UTF-8") + else + require 'iconv' + data = File.read(filename) + Iconv.conv("UTF-8", @options[:encoding], data) + end + end + # Returns `true` if `pygmentize` is available locally, `false` otherwise. def pygmentize? @_pygmentize ||= ENV['PATH'].split(':'). diff --git a/test/test_reported_issues.rb b/test/test_reported_issues.rb index 7397243..0899fa7 100644 --- a/test/test_reported_issues.rb +++ b/test/test_reported_issues.rb @@ -28,11 +28,9 @@ def test_issue10_utf8_processing "UTF-8 input files ought behave correctly." ) # and, just for grins, ensure that iso-8859-1 works too. - # @TODO: Is this really the correct behavior? Converting text - # to UTF-8 on the way out is probably preferable. - r = Rocco.new( File.dirname(__FILE__) + "/fixtures/issue10.iso-8859-1.rb" ) + r = Rocco.new( File.dirname(__FILE__) + "/fixtures/issue10.iso-8859-1.rb", [], :encoding => 'ISO-8859-1' ) assert_equal( - "

hello w\366rld

\n", + "

hello wörld

\n", r.sections[0][0], "ISO-8859-1 input should probably also behave correctly." ) From e2efb22bd2260d7d6d6a64de429afa35ccd84754 Mon Sep 17 00:00:00 2001 From: Brian Campbell Date: Mon, 9 Jan 2012 17:14:30 -0500 Subject: [PATCH 3/3] Add back missing /docs to .gitignore Commit 854f62c (The default gitignore provided by `bundler gem`) replaced .gitignore with a generated one, but that blew away the .gitignore line for /docs. Add it back in. --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index d87d4be..86db56e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +/docs *.gem *.rbc .bundle