awhyte-rtex 2.1.2

data/CHANGELOG

@@ -0,0 +1,48 @@
+v2.1.0
+
+  Merge in rails-2.2.2 branch, modify to make sure Prawn isn't trampled and
+  2.3.0 is supported.
+  Simplify tagging of templates for later processing (+ ensure it works
+  with compiled templates).
+  Update README_RAILS 
+
+v2.0.5
+
+  Fix issue with Echoe being ultra-sensitive on RubyGems versions (v2.0.4
+  was RubyGems 1.2 only, and 1.3 just came out)
+  
+v2.0.4
+
+  Support for TeX escaping (via l()) calling to_s on the argument.
+  This should handle nils.
+
+v2.0.3
+
+  Rails 2.0 compat:
+  Fix issue with init.rb not requiring rails/init.rb
+
+v1.99.0 2008-04-20
+
+  Released RTeX v1.99.0 as a Rubygem, with a standalone executable for PDF generation
+  and support for plugin installation from the executable.
+
+  This release requires Rails >= 2.0.1
+
+  Thanks to:
+  * Jonas Bähr for a patch with additional LaTeX escaping
+  * Fouad Mardini for a TemplateHandler patch
+
+v1.0.0+
+
+  Added quite a few *long* overdue fixes & enhancements sent in by various people.
+
+  * Added latex escaping 'l' method (Thanks, Benjamin Quorning)
+  * Added support for @options_for_rtex hash for configuration:
+    * Added :tempdir option, and changed default temporary directory
+      (Thanks, Francesco Levorato)
+    * Added :preprocess option to support running through latex before pdflatex
+      (Thanks Charles Lesburg, Benjamin Quorning)
+    * Moved old @filename setting to :filename option in this hash
+
+  If you're using the same settings for @options_for_rtex often, you might want to 
+  put your assignment in a before_filter (perhaps overriding :filename, etc in your actions).

data/Manifest

@@ -0,0 +1,25 @@
+bin/rtex
+CHANGELOG
+init.rb
+lib/rtex/document.rb
+lib/rtex/escaping.rb
+lib/rtex/framework/merb.rb
+lib/rtex/framework/rails.rb
+lib/rtex/tempdir.rb
+lib/rtex/version.rb
+lib/rtex.rb
+Manifest
+rails/init.rb
+Rakefile
+README.rdoc
+README_RAILS.rdoc
+test/document_test.rb
+test/filter_test.rb
+test/fixtures/first.tex
+test/fixtures/first.tex.erb
+test/fixtures/fragment.tex.erb
+test/fixtures/text.textile
+test/tempdir_test.rb
+test/test_helper.rb
+vendor/instiki/LICENSE
+vendor/instiki/redcloth_for_tex.rb

data/README.rdoc

@@ -0,0 +1,46 @@
+= RTeX: TeX/PDF Generation for Ruby
+
+Project homepage (FAQ, manual, documentation, contact info): http://rtex.rubyforge.org
+
+Source repository at: http://github.com/bruce/rtex
+
+== Dependencies
+
+* pdflatex executable, available in modern teTeX distributions
+* Requires Rails >= 2.0.1 if used as a plugin.
+
+== Usage
+
+For use as a standalone executable, see `rtex --help'
+
+For use as a Rails plugin, see README_RAILS.rdoc
+
+== More Information
+
+Additional help may be available at the project homepage,
+http://rtex.rubyforge.org
+
+== License
+
+  (The MIT License)
+
+  Copyright (c) 2006-2008 Bruce Williams, Wiebe Cazemier
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  'Software'), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be
+  included in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README_RAILS.rdoc

@@ -0,0 +1,58 @@
+= RTeX for Rails
+
+== Installation
+
+  sudo gem install rtex
+  
+Rails 2.0.X, 2.1+ in vendor/plugins (not recommended):
+  rtex --install /path/to/rails/app
+  
+Or, as a Rails 2.1+ gem dependency, just add the following
+to your config/environment.rb:
+  config.gem 'rtex'
+  
+== Dependencies
+
+* Rails >= 2.0.1
+  
+== Usage
+
+Create files pdf.rtex extensions (eg, index.pdf.rtex) using standard LaTeX markup.
+
+* Layouts are supported, eg: application.pdf.rtex
+* Partials are supported, eg: _item.pdf.rtex
+
+=== Example
+
+With the following:
+
+  # In config/initializers/mime_types.rb (or environment.rb in older Rails)
+  Mime::Type.register "application/pdf", :pdf
+
+  # app/controllers/items_controller.rb
+  def index
+    @items = Item.find(:all)
+    respond_to do |format|
+      format.html # We support the normal HTML view as well
+      format.pdf
+    end
+  end
+  
+  # app/views/items/index.pdf.rtex
+  \section*{Items}
+  \begin{itemize}
+    <%= render :partial => @items %>
+  \end{itemize}
+  
+  # app/views/items/_item.pdf.rtex
+  \item <%=l item.name %> \\
+  
+  # app/layouts/application.pdf.rtex
+  \documentclass[12pt]{article}
+  \begin{document}
+    <%= yield %>
+  \end{document}
+
+If you hit /items.pdf, you end up with a nice PDF listing of items.
+
+Obviously a simplistic example.

data/Rakefile

@@ -0,0 +1,22 @@
+require 'rubygems'
+require 'echoe'
+
+require File.dirname(__FILE__) << "/lib/rtex/version"
+
+Echoe.new 'rtex' do |p|
+  p.version = RTeX::Version::STRING
+  p.author = ['Bruce Williams', 'Wiebe Cazemier']
+  p.email  = 'bruce@codefluency.com'
+  p.project = 'rtex'
+  p.summary = "LaTeX preprocessor for PDF generation; Rails plugin"
+  p.url = "http://rtex.rubyforge.org"
+  p.include_rakefile = true
+  p.development_dependencies = %w(Shoulda echoe)
+  p.rcov_options = '--exclude gems --exclude version.rb --sort coverage --text-summary --html -o coverage'
+  p.ignore_pattern = /^(pkg|doc|site)|\.svn|CVS|\.bzr|\.DS|\.git/
+  p.rubygems_version = nil
+end
+
+task :coverage do
+  system "open coverage/index.html" if PLATFORM['darwin']
+end

data/bin/rtex

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'fileutils'
+
+require File.dirname(__FILE__) << '/../lib/rtex'
+
+options = {}
+
+opts = OptionParser.new do |opts|
+  
+  opts.banner = [
+    "RTeX v#{RTeX::Version::STRING} (c) 2006-2007 Bruce Williams, Wiebe Cazemier",
+    "Usage: rtex [OPTION...] FILE...\n\n"
+  ].join("\n")
+    
+  opts.on('-l LAYOUT', '--layout LAYOUT', 'Path to layout file (use <%= yield %>)') do |layout|
+    if File.exists?(layout)
+      options[:layout] = File.read(layout)
+    else
+      STDERR.puts "Layout file not found: #{layout}"
+      exit 1
+    end
+  end
+  
+  opts.on('-o OUTFILE', '--output OUTFILE', "Output to file (defaults to STDOUT)") do |path|
+    options[:outfile] = path
+  end
+  
+  filters = RTeX.filters.keys.map { |k| k.to_s }.sort.join(', ')
+  opts.on('-f FILTER', '--filter FILTER', "Filter input (supported: #{filters})", "(Wraps in a basic `article' document; use --layout to customize)") do |filter|
+    options[:filter] = filter
+  end
+  
+  opts.on('--no-pdf', "Don't generate PDF (just output TeX)") do
+    options[:tex] = true
+  end
+  
+  opts.on('-i PATH', '--install PATH', "Install as plugin into Rails app at PATH") do |path|
+    unless Dir[plugins = File.join(path, 'vendor/plugins')].any?
+      STDERR.puts "Could not find application at #{path}"
+      exit 1
+    end
+    plugin_path = File.join(plugins, 'rtex')
+    FileUtils.cp_r(File.dirname(__FILE__) << '/..', plugin_path)
+    %w(Rakefile Manifest.txt bin tasks).each do |prune|
+      FileUtils.rm_rf(File.join(plugin_path, prune)) rescue nil
+    end
+    STDERR.puts "Installed at #{plugin_path}"
+    exit
+  end
+  
+  opts.on('-p PROCESSOR', '--processor PROCESSOR', "Specify the LaTeX processor (default: #{RTeX::Document.options[:processor]})") do |processor|
+    options[:processor] = processor
+  end
+  
+  opts.on('-h', '--help', "Show this message\n")
+  opts.separator "With no FILEs, or when FILE is -, read from standard input."
+  
+  opts.on_tail do
+    STDERR.puts opts
+    exit
+  end
+end
+opts.parse!(ARGV)
+
+if options[:filter] && !options[:layout]
+  STDERR.puts "Warning: Using default `article' layout (see --help on '--layout')"
+  options[:layout] = RTeX.basic_layout
+end
+
+RTeX::Document.create(ARGF.read, options) do |document|
+  document.to_pdf do |filename|
+    begin
+      location = File.expand_path options[:outfile]
+      FileUtils.move filename, location
+    rescue
+      STDOUT.print File.read(filename)
+    end
+  end
+end
+

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) << "/rails/init"

data/lib/rtex.rb

@@ -0,0 +1,37 @@
+$:.unshift(File.dirname(__FILE__) << '/rtex')
+
+require 'document'
+require 'version'
+
+module RTeX
+  
+  # Load code to initialize RTeX for framework 
+  def self.framework(name)
+    require File.dirname(__FILE__) << "/rtex/framework/#{name}"
+    framework = ::RTeX::Framework.const_get(name.to_s.capitalize)
+    framework.setup
+  end
+  
+  def self.filters #:nodoc:
+    @filters ||= {}
+  end
+  
+  def self.basic_layout #:nodoc:
+    "\\documentclass[12pt]{article}\n\\begin{document}\n<%= yield %>\n\\end{document}"
+  end
+  
+  # Define a processing filter
+  # call-seq:
+  #   filter(:name) { |text_to_transform| ... } # => result
+  def self.filter(name, &block)
+    filters[name.to_s] = block
+  end
+  
+  filter :textile do |source|
+    require File.dirname(__FILE__) << '/../vendor/instiki/redcloth_for_tex'
+    RedClothForTex.new(source).to_tex
+  end
+  
+end
+
+

data/lib/rtex/document.rb

@@ -0,0 +1,245 @@
+require 'erb'
+require 'escaping'
+require 'tempdir'
+
+module RTeX
+  class Document
+    extend Escaping
+    
+    class FilterError < ::StandardError; end
+    class GenerationError < ::StandardError; end
+    class ExecutableNotFoundError < ::StandardError; end
+    
+    # Create a new +RTeX::Document+. A temporary directory will be created
+    # for the lifetime of the document, and then destroyed at the end of the block.
+    #
+    #   RTeX::Document.create(source, :processor => "xelatex") do |document|
+    #     puts "working in #{document.tempdir}"
+    #
+    #     document.to_pdf do |filename|
+    #       # process PDF file
+    #       # ...
+    #     end
+    #   end
+    #
+    # Options passed to +#create+ are the same as those for +#new+.
+    #
+    # To specify which temporary directory should be created for processing the
+    # document, set +:tempdir+.
+    #
+    def self.create(content, options={})
+      Tempdir.open(options[:tempdir]) do |dir|
+        doc = Document.new(content, options.merge(:tempdir => dir))
+        yield doc
+      end
+    end
+    
+    # Create a new +RTeX::Document+ in either the current directory (default) 
+    # or a specified, pre-existing directory.
+    #
+    # The +content+ parameter should contain the document source.
+    #
+    # The +options+ hash may contain:
+    # [+:processor+] Executable with which to output the document 
+    #                (default: 'pdflatex')
+    # [+:preprocessor+] Executable to use during preprocessing (particularly 
+    #                   for longer documents containing a table-of-contents or 
+    #                   bibliography section (default: 'latex')
+    # [+:preprocess+] Either a boolean specifying whether to preprocess the 
+    #                 input file(s), or an integer for the number of times to 
+    #                 preprocess (default: false / 0)
+    # [+:tmpdir+] Location of temporary directory (default: +Dir.getwd+)
+    # [+:shell_redirect+] Option redirection for shell output, 
+    #                     e.g. +"> /dev/null 2>&1"+ (default: +nil+).
+    #
+    def initialize(content, options={})
+      @options = self.class.options.merge(options)
+      if @options[:processed]
+        @source = content
+      else
+        @erb = ERB.new(content)
+      end
+    end
+    
+    # Get the compiled source for the entire document
+    def source(binding=nil) #:nodoc:
+      @source ||= wrap_in_layout do
+        filter @erb.result(binding)
+      end
+    end
+    
+    # Process through defined filter
+    def filter(text) #:nodoc:
+      return text unless @options[:filter]
+      if (process = RTeX.filters[@options[:filter]])
+        process[text]
+      else
+        raise FilterError, "No `#{@options[:filter]}' filter"
+      end
+    end
+    
+    # Wrap content in optional layout
+    def wrap_in_layout #:nodoc:
+      if @options[:layout]
+        ERB.new(@options[:layout]).result(binding)
+      else
+        yield
+      end
+    end
+    
+    # Generate PDF output:
+    #
+    #   to_pdf # => PDF in a String
+    #   to_pdf { |filename| ... }
+    #
+    def to_pdf(binding=nil, &file_handler)
+      process_pdf_from(source(binding), &file_handler)
+    end
+    
+    def processor #:nodoc:
+      @processor ||= check_path_for @options[:processor]
+    end
+    
+    def preprocessor #:nodoc:
+      @preprocessor ||= check_path_for @options[:preprocessor]
+    end
+    
+    def system_path #:nodoc:
+      ENV['PATH']
+    end
+    
+    def self.options #:nodoc:
+      @options ||= {
+        :preprocessor => 'latex',
+        :preprocess => false,
+        :processor => 'pdflatex',
+        :shell_redirect => nil,
+        :tex_inputs => nil,
+        :tempdir => Dir.getwd # Current directory unless otherwise set
+      }
+    end
+    
+  private
+    
+    # Verify existence of executable in search path
+    def check_path_for(command)
+      unless FileTest.executable?(command) || system_path.split(":").any?{ |path| FileTest.executable?(File.join(path, command))}
+        raise ExecutableNotFoundError, command
+      end
+      command
+    end
+    
+    # Basic processing
+    #
+    # The general call sequence is:
+    #   #to_pdf (from user) => #source (ruby compile) => #process_pdf_from => #prepare => #preprocess! => #process! => #verify! => return as string or output filename
+    #
+    def process_pdf_from(input, &file_handler)
+      prepare input
+      if generating?
+        preprocess_count.times { preprocess! }
+        process!
+        verify!
+      end
+      if file_handler
+        yield result_file
+      else
+        result_as_string
+      end
+    end
+    
+    # Save the Ruby-compiled document source to a file
+    # It is then ready for LaTeX to compile it into a PDF
+    #
+    def prepare(input)
+      File.open(source_file, 'wb') { |f| f.puts input }
+    end
+    
+    # Run LaTeX pre-processing step on the source file
+    def preprocess!
+      unless `#{environment_vars}#{preprocessor} --output-directory=#{tempdir} --interaction=nonstopmode '#{File.basename(source_file)}' #{@options[:shell_redirect]}`
+        raise GenerationError, "Could not preprocess using #{preprocessor}"      
+      end
+    end
+    
+    # Run LaTeX output generation step on the source file
+    def process!
+      unless `#{environment_vars}#{tex_inputs} #{processor} --output-directory=#{tempdir} --interaction=nonstopmode '#{File.basename(source_file)}' #{@options[:shell_redirect]}`
+        raise GenerationError, "Could not generate PDF using #{processor}"      
+      end
+    end
+    
+    # Check the output file has been generated correctly
+    def verify!
+      unless File.exists?(result_file)
+        raise GenerationError, "Could not find result PDF #{result_file} after generation.\nCheck #{log_file}"
+      end
+    end
+    
+    # Load the output file and return its contents
+    def result_as_string
+      File.open(result_file, 'rb') { |f| f.read }
+    end
+    
+    # Should we pre-process?
+    def preprocessing?
+      preprocess_count > 0
+    end
+    
+    def preprocess_count
+      case @options[:preprocess]
+        when Numeric
+          @options[:preprocess].to_i
+        when true
+          1
+        else
+          0
+      end
+    end
+    
+    # Compile list of extra directories to search for LaTeX packages, using
+    # the file or array of files held in the :tex_inputs option.
+    #
+    def tex_inputs
+      if inputs = @options[:tex_inputs]
+        inputs = [inputs].flatten.select { |i| File.exists? i }
+        "TEXINPUTS='#{inputs.join(':')}:'"
+      else
+        nil
+      end
+    end
+    
+    # Produce a list of environment variables to prefix the process and 
+    # preprocess commands.
+    #
+    def environment_vars
+      list = [tex_inputs].compact
+      list.empty? ? "" : list.join(" ") + " "
+    end
+    
+    def source_file
+      @source_file ||= file(:tex)
+    end
+    
+    def log_file
+      @log_file ||= file(:log)
+    end
+    
+    def result_file
+      @result_file ||= file(@options[:tex] ? :tex : :pdf)
+    end
+    
+    def tempdir
+      @options[:tempdir]
+    end
+    
+    def file(extension)
+      File.join(tempdir.to_s, "document.#{extension}")
+    end
+    
+    def generating?
+      !@options[:tex]
+    end
+    
+  end
+end