rake4latex 0.0.1

data/lib/call_rake4latex.rb

@@ -0,0 +1,156 @@
+=begin rdoc
+call_rake4latex.rb offers an easy and fast interface
+to rake4latex.
+
+Just call it from the shell:
+  call_rake4latex.rb my_file
+
+my_file.tex will be compiled to my_file.pdf.
+
+For details, please use the help:
+  call_rake4latex.rb -h
+
+For complex documents you may want define your own rakefile
+and use rake.
+
+It is recommended to copy this file to a location in your 
+search path for executable files.
+=end
+
+require 'rake4latex'
+require 'optparse'
+
+#Anlegen des Parsers
+opts = OptionParser.new()
+opts.banner = "Usage: call_rake4latex.rb [options] filename"	#Usage-zeile
+opts.separator "Call LaTeX as often as needed."
+opts.separator ""
+opts.separator "Examples:"
+opts.separator "call_rake4latex testdocument.pdf"
+opts.separator "  Create testdocument.pdf via pdflatex"
+opts.separator "  Starts only if testdocument.tex is newer then testdocument.pdf."
+opts.separator ""
+opts.separator "call_rake4latex -f testdocument"
+opts.separator "  Touch 'testdocument.tex' (set the modification date)"
+opts.separator "  Create testdocument.pdf via pdflatex"
+opts.separator ""
+opts.separator "Specific options:"
+
+#
+#List of task to be done after the TeX-call.
+#
+TASK_BEFORE_TeX = []  #only task where we need the filenem
+TASK_AFTER_TeX = []
+PARSE_MESSAGES = true
+
+
+=begin
+Shortcuts
+=end
+opts.on('-f', "--force", "Force an initial TeX-run") { |v|
+  TASK_BEFORE_TeX << :force
+}
+
+#
+#fixme:
+#Warum gibt es immer einen TeX-Lauf mit dieser Option?
+#
+opts.on('-d', '--dep', "--dependecies", "Build dependecies") { |v|
+  TASK_BEFORE_TeX << :dependecies
+}
+opts.on("-i", "--ignore", "--ignore-error", "Allow LaTeX errors") { |v|
+  puts "Allow LaTeX errors"  if PARSE_MESSAGES
+  Rake.application.set_latexrunner_default(:texerrors_allowed, true)
+}
+
+opts.on("-s", "--statistic", "Show the statistic after TeX-run") { |v|
+  puts "Show the statistic after TeX-run"  if PARSE_MESSAGES
+  TASK_BEFORE_TeX  << :statistic  #Set filename
+  TASK_AFTER_TeX  << :statistic
+}
+opts.on("-c", "--clean", "Clean after TeX-run (delete auxiliary files)") { |v|
+  puts "Clean after TeX-run"  if PARSE_MESSAGES
+  TASK_AFTER_TeX  << :clean
+}
+
+=begin
+Main options
+=end
+# Soll der Parameter Optional sein, kann [] verwendet werden.
+opts.on("--touch FILE", "Touch FILE") { |v|
+  puts "Touch #{v.inspect}" if PARSE_MESSAGES
+  task :touch => v
+  task :default => :touch
+}
+
+
+#
+opts.on("--task TASK", "Define a rake-task") { |v|
+  puts "Set task #{v.inspect}" if PARSE_MESSAGES
+  task :default => v
+}
+
+#
+opts.on("--task_after TASK", "Define a rake-task after the TeX-run") { |v|
+  puts "Set task #{v.inspect} after LaTeX" if PARSE_MESSAGES
+  TASK_AFTER_TeX  << v
+}
+
+=begin
+LaTeXRunner-options
+=end
+#
+opts.on("--maxrun MAXRUN", "Maximum MAXRUN TeX calls") { |v|
+  puts "Set maximum TeX-Runs #{v.inspect}"  if PARSE_MESSAGES
+  Rake.application.set_latexrunner_default(:maxruns, v.to_i)
+  #~ LaTeXRunner::DEFAULT_SETTINGS[:maxruns] = 
+}
+
+opts.on("-l", "--loglevel LEVEL", "Log Level for the logger (1=debug, 2=info(default), 3=warn 4=error)") { |v|
+  puts "Set loglevel to #{v.inspect}"  if PARSE_MESSAGES
+  Rake.application.set_latexrunner_default(:loglevel, v.to_i)
+}
+
+
+
+#Parsen der Parameter mit Exception bei ung�ltigen Parametern
+begin
+	opts.parse!
+  ARGV.each{|arg|
+    target = arg.ext('pdf')
+    puts "Define target #{target}"
+    set4clean(arg)
+    TASK_BEFORE_TeX.each{|task|
+    case task
+      when :force
+        puts "Force an initial TeX-run (touch #{target.ext('tex')})" if PARSE_MESSAGES
+        task (:touch => target.ext('tex'))
+        task (:default => :touch)
+      when :dependecies
+        puts "Build dependecies for #{target.ext('tex')}" if PARSE_MESSAGES
+        LaTeXDependencies.get_dependecies(target.ext('tex'), :inputs, :flat).each{|dep|
+          puts "     => #{dep.inspect}" if PARSE_MESSAGES
+          task (target => dep)
+        }
+      when :statistic
+        task (:statistic => target.ext('tex'))
+      else
+        raise ArgumentError, "Undefined option #{task.inspect}"
+      end
+    }
+    task( :default => target )
+  }  
+rescue OptionParser::MissingArgument, OptionParser::InvalidOption => err
+	puts "Error:\t#{err}"
+	#Ausgabe der Schnittstelle
+	puts opts
+end
+
+#
+#Set tasks after the LaTeX-call
+TASK_AFTER_TeX.each{|task|
+  task (:default => task)
+}
+
+app = Rake.application
+app[:default].invoke

data/lib/rake4latex.rb

@@ -0,0 +1,377 @@
+=begin rdoc
+==Introduction
+This file contains definitions to build a rakefile for LaTeX-documents.
+
+A not-so minimal rakefile looks like this:
+  require 'rake4latex'
+  #Needed for some actions without a previous TeX-call
+  task :basefile => 'testdocument.tex'
+  #We want to build a PDF
+  file 'testdocument.pdf' => 'testdocument.tex'
+  
+  #Force the compilation
+  task :touch => 'testdocument.tex'
+
+  #Define the default tasks
+  task :default => :touch
+  task :default => 'testdocument.pdf'
+  task :default => :statistic
+  task :default => :clean
+
+  #Make the rakefile self-executable
+  if $0 == __FILE__
+    app = Rake.application
+    app[:default].invoke
+  end
+
+You can generate this template with:
+  require 'rake4latex'
+  puts Rake4LaTeX.template( [basename] )
+
+==Multiple runs
+One of the problems with writing a Makefile for LaTeX is that often latex needs
+to be run more than once on the same file, before obtaining the final output.
+Moreover, every LaTeX package may require other runs basing on different conditions
+and maybe even requiring some other program to be run between latex invocations.
+
+Makefile normally expect a defined sequence of prerequisites.
+Prerequisites are known before the action takes care.
+Some dependecies of (La)TeX-documents creates ther prerequisites after the 
+(La)TeX-run (e.g. new index entries).
+
+The approach followed here is to define "Post-Prerequisites".
+The virtual target :latex_dependecies contains all this "Post-Prerequisites".
+After a TeX-run, each Post-Prerequisites is checked.
+For each post-prerequisites you must define a rule (in the following called postprereq.
+
+The prerequisites of postprereq are checked for changes.
+To detect changes, the Hash-Code of the prerequisite-files before and after
+the TeX-run are compared (the comparison of the time stamp makes no sense,
+TeX always(*) recreate the files).
+
+<small>*) Forget the \nofiles-command</small>
+
+See the examples-section hot to define your own custom action.
+
+To avoid problems of endless loops, a there's a maximum number of runs, which is
+5 by default. The user can change it in the runner.
+
+==Dependencies
+You must define your dependencies your own (but there is a help to do so, see next next section)
+
+Example:
+  file 'testdocument.dvi' => ['testdocument.tex', 'testincludes/testinclude1.tex']
+
+
+===Determine Dependecies: LaTeXDependencies.get_dependecies( )
+You can automatically compute dependencies for the latex task:
+  LaTeXDependencies.new(filename).get_dependecies( *options )
+Options may be:
+* :inputs:
+
+  The input file (the one which is passed to latex) is read, and the arguments of the 
+  <tt>\includeonly</tt>, <tt>\include</tt> and <tt>\input</tt> latex commands are
+  extracted. Each of this these files is scanned again for dependecies.
+ 
+  The result is a nested array with all dependecies.
+
+* :flat:
+  The (nested) result is flatted and double entries are deleted.
+
+You can use it already direct in your dependecies definition:
+  file 'testdocument.dvi' => LaTeXDependencies.new('testdocument.tex').get_dependecies( *options )
+
+===Dependecies for BibTeX
+BibTeX depends on two files:
+* aux file with the list of the cites.
+* bib-file(s) with the data of the literature.
+
+You can define the dependecies of bib-file in your rakefile:
+  file 'testdocument.pdf' => 'testdocument.bib'
+  file 'testdocument.bbl' => 'testdocument.bib'
+You need both definietions.
+The pdf-dependecy is needed to start a new TeX-run, 
+The bbl-dependecy is needed to start a new BibTeX-run.
+
+==Supported tools and packages
+
+===Supported tools
+The following tools are supported by rake4latex:
+* Makeindex with makeidx.sty
+* BibTeX
+
+===Supported (checked) packages
+The rake process to generate the document is independent of any 
+package.
+But some packages requires additional TeX-runs.
+The following packages are tested and work fine:
+* minitoc
+* longtable
+* supertabular
+* splitindex (splitindex is replaced by internal routines)
+
+Untested packages:
+* glossary
+* multiind/index (not planned to check, please use splitindex or inform me about your need)
+
+==Adding new tasks
+===Normal tasks
+Task to generate pictures or other stuff needed to
+build your LaTeX project can be added like normal
+rake-tasks.
+
+===TeX-related tasks
+Some task must be executed after a TeX-run.
+This tasks must be created with <tt>tex_postrule</tt>
+instead of the rake-method <tt>rule</tt>.
+
+The tasks for makeindex and bibTeX are already defined.
+
+====Example makeindex
+An example for this tasks is makeindex.
+After a TeX-run you must check, if there are are new or changed
+index entries.
+
+The makeindex-task looks like this:
+  desc "Call Makeindex"
+  tex_postrule '.ind' => '.idx' do |t|
+      sh "makeindex #{t.source}"
+  end
+
+That's it to get an index.
+
+After a TeX-run, the prerequisites of rule '.ind' is checked for changes
+(Hash-Code of the idx-file before and after the TeX-Run).
+If there is a change, the rule is called.
+And if the .ind-file changed, an additional TeX-call is forced.
+
+====Example BibTeX
+BibTeX is a bit more complicated:
+  tex_postrule '.bbl' => '.aux' do |t, args |  
+    sh "bibtex #{t.source}"
+  end
+
+With this rule, BibTeX is called every times the aux-file changed
+(if we use BibTeX or not).
+We need a modified pre-check, if the BibTeX-call is necessary:
+  tex_postrule_check '.bbl' do |args|
+    auxfile = args[:task].name.ext('aux')
+    File.exist?(auxfile) and                        #there is a aux-file
+      ( args[:checksums][auxfile] == :changed ) and #the aux-file changed
+      ( necessary and File.read(auxfile) =~ /bibdata/ )#and we use bibtex
+  end
+
+
+See also section 'Multiple runs'
+
+==Known Bugs and Problems
+*Only pdflatex/xelatex/lualatex/latex to create the target,
+  no ps-files, no ps2pdf.
+**Intended for the next release
+* Two runs for new documents, when only one is needed.\\
+After the first run, the aux-file is created,
+so rake4latex detect a reason to rerun.
+Solution would be to make a log-file analyse.
+** No plan to solve it.
+  Not a big problem, and why you need a rakefile for such simple tex-files?
+* No usage of kpsewhich\\
+  LaTeXDependencies#get_dependecies checks dependecies only relative to 
+  the file location.
+  kpsewhich is not used.
+** Would be nice escpecially for BibTeX and scan for \bibliography{xxx}
+** Low priority
+
+=end
+
+<<weiter
+fixmes
+== weiterer Aufbau rake abh�ngigkeiten
+- glossary
+rule '.glo' => '.aux' '.glo' do |t|
+(glossaries?)
+
+==task statistic/log-analyse
+
+==application::texrunner als array?
+
+Rake.template(basename) erzeugt rakefile
+  app = Rake.application
+  #~ app.set_latexrunner_default(:maxruns, 1)
+  #~ app.set_latexrunner_default(:loglevel, Log4r::DEBUG)
+  #~ app.set_latexrunner_default(:texerrors_allowed, true)
+  app[:default].invoke
+
+rail �berarbeiten
+
+Compilierungswege dvi -> ps -> pdf
+
+prob:
+wie erkennen ob 
+- dvi2ps + ps2pdf
+- dvipdfm
+
+weiter
+
+
+#~ ==Problems
+#~ * the action which checks for changed references causes a second latex invocation
+  #~ every time the .aux file changes. 
+  #~ I don't know enough of the contents of the
+  #~ .aux file to parse it, but I need to base the decision on it, because messages
+  #~ such as "rerun to get cross-references right" in the latex log file aren't
+  #~ reliable (for example, the when the hyperref package is used, they aren't
+  #~ produced)
+
+require 'log4r'
+#Create a dummy-Logger to define the constants Log4r::DEBUG...
+
+Log4r::Logger.new("test")
+#~ gem 'rake', '=0.8.7'
+require 'rake'
+require 'md5'
+
+class Rake::Application
+=begin rdoc
+Sets a default option for the LaTeXRunner.
+
+The options are stored and used for new LaTeXRunners.
+
+Example:
+  app.set_latexrunner_default(:loglevel, Log4r::DEBUG)
+
+You could also access LaTeXRunner::DEFAULT_SETTINGS directly.
+But with this method you get also a check if the option exists.
+=end
+  def set_latexrunner_default( key, option )
+    if ! LaTeXRunner::DEFAULT_SETTINGS.keys.include?(key)
+      raise ArgumentError, "Undefined key #{key.inspect} for LaTeXRunner" unless @latexrunner
+      @latexrunner.logger.warn("Undefined key #{key.inspect} for LaTeXRunner")
+    end
+    LaTeXRunner::DEFAULT_SETTINGS[key] = option
+  end
+=begin rdoc
+Get the related actual LaTeXRunner.
+=end
+  attr_reader :latexrunner
+=begin rdoc
+Define a LaTeXRunner.
+
+This LaTeXRunner may be used via Rake#application#latexrunner to get the logger.
+=end
+  def latexrunner=( latexrunner )
+    raise ArgumentError, "LaTeXRunner is no LaTeXRunner but #{t.class}" unless latexrunner.is_a?(LaTeXRunner)
+    if @latexrunner
+      @latexrunner.logger.warn( "LaTeXRunner replaced by other runner")
+    end
+    @latexrunner = latexrunner
+    @latexrunner.logger.debug( "Set LaTeXRunner #{@latexrunner.main_file} as default runner in Rake::Application")
+  end
+end #Rake::Application
+
+=begin rdoc
+Define the files to be deleted with clean and clobber.
+
+There is no global definition to delete all files, 
+only the help file for the selected basename is taken.
+
+Helpfiles for splitindex are not added. You can do it manual:
+  CLEAN.add("testdocument-*") #splitidx-helpfiles
+
+This method is called by task 'basename'
+=end
+def set4clean( basename )
+  #fixme splitindex-dateien
+  FileList["#{basename.ext('*')}"].each do |file|
+    #Set the cleaning actions      
+    case file
+      when /\.(tex)\Z/
+      when /\.(aux|log|out|toc|lot|lof|nav|snm)\Z/
+        CLEAN.include(file)    
+      when /\.(maf|ptc\d*|mtc\d*|stc\d*)\Z/ #minitoc
+        CLEAN.include(file)    
+      when /\.(ilg|idx|ind)\Z/  #Index-Files
+        CLEAN.include(file)    
+      when /\.(blg|bbl)\Z/  #BibTeX-Files
+        CLEAN.include(file)    
+      when /\.(rai|rao|RAO)\Z/  #Rail-Files
+        CLEAN.include(file)    
+      when /\.(dvi|pdf|ps)\Z/
+        CLOBBER.include(file)              
+      else
+        #~ @logger.warn("Unknown help file #{file}")
+    end
+  end
+  CLEAN.uniq!
+  CLOBBER.uniq!
+end
+
+=begin rdoc
+Define a task to be executed after each TeX run.
+
+The task name is added to LaTeXRunner::Post_Prerequisites.
+LaTeXRunner#run_latex_once will loop on all tasks in LaTeXRunner::Post_Prerequisites.
+=end
+def tex_postrule(*args, &block)
+  #~ rules = rule(*args, &block)
+  Rake::Task.create_rule(*args, &block)  #@rules << [pattern, deps, block]
+  #
+  if args.size == 1 #normal rule without arguments
+    LaTeXRunner::Post_Prerequisites << args.first.keys.first
+  else  #rule with arguments (args.last is a hash with :needs)
+    LaTeXRunner::Post_Prerequisites << args.first
+  end
+end
+=begin rdoc
+Define a procedure to decide, if the post process should be 
+called.
+
+The task name is added to LaTeXRunner::Post_Prerequisites_check.
+LaTeXRunner#run_latex_once will loop on all tasks in LaTeXRunner::Post_Prerequisites_check.
+
+The block will be called with a hash, the block must accept this one parameter.
+
+Inside the block you have access to:
+* :task: The task for which you test.
+* :checksums: the checksums of the files before the TeX-run.
+* :logger: the logger of the related task
+
+The block must return false or the reason for a call (e.g. "testdocument.aux changed")
+
+Example: See BibTeX-definition.
+=end
+def tex_postrule_check(rulename, &block)
+  raise "No block for postrule_check #{rulename}" unless block_given?
+  raise "Wrong number of arguments for postrule_check #{rulename}" unless block.arity == 1
+  LaTeXRunner::Post_Prerequisites_check[rulename] ||= [] << block
+end
+
+#
+#Load the sub-files
+#
+require 'rake4latex/clean'  #modified rake/clean
+require 'rake4latex/latexrunner'
+require 'rake4latex/latexdependencies'
+require 'rake4latex/splitindex'
+require 'rake4latex/rules'
+require 'rake4latex/tex_statistic'
+require 'rake4latex/template'
+
+
+#Do some development tests
+if $0 == __FILE__
+  #~ require 'yaml'
+  #~ puts LaTeXRunner.find_included_files( 'test/testdocument.tex' ).to_yaml
+
+  task :acroread => 'test/testdocument.pdf'
+  #~ task :default => :acroread
+
+  #~ app = Rake.application
+  #~ app[:default].invoke
+
+  #~ LaTeXRunner.new( 
+    #~ :main_file => 'test/testdocument.tex',
+    #~ :maxruns => 1.0/0,  
+    #~ :program => :latex,
+    #~ :dummy => nil
+    #~ )
+end