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 a rakefile template with:
require 'rake4latex' puts Rake4LaTeX.build_rakefile( basename, :pdf, :dependecies )
The method will print a rakefile definition.
Supported options:
When you think, your project is too small to create a rakefile, then try call_rake4latex.rb.
call_rake4latex.rb is a small programm where you can control rake4latex from your shell.
Example:
call_rake4latex.rb my_file call_rake4latex.rb -e my_file
Windows users can pick up a stand alone executable of call_rake4latex at CTAN: http://ctan.org/tex-archive/support/rake4latex
You can use rake4latex as a lib inside your application.
Example:
require 'rake4latex' task :touch => 'testdocument.tex' task :runtex => [:touch, 'testdocument.pdf', :clean] Rake.application[:runtex].invoke #~ task :basefile => 'testdocument.pdf' #~ Rake.application[:clean].invoke
rake4latex defines the tasks and rules to build documents with LaTeX.
pdf can be created in different ways. rake4latex uses pdflatex, but there are other rake-profile to create your pdf in different ways:
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).
*) Forget the \nofiles-command
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.
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']
You can automatically compute dependencies for the latex task: Rake4LaTeX::TeXfile.new(filename).includes( [options] )
You can use it already direct in your dependecies definition:
file 'testdocument.dvi' => Rake4LaTeX::TeXfile.new('testdocument.tex').includes(:recursive, :uniq )
Alternative you can generate your rakefile:
Rake4LaTeX.build_rakefile( filename, :dependecies )
BibTeX depends on two files:
You can define the dependecies of bib-file in your rakefile:
file 'testdocument.pdf' => 'testdocument.bib' file 'testdocument.bbl' => 'testdocument.bib'
You need both definitions. The pdf-dependecy is needed to start a new TeX-run, The bbl-dependecy is needed to start a new BibTeX-run.
The following tools are supported by rake4latex:
The rake process to generate the document is independent of any package. But some packages requires additional actions.
For the following packages exist special solutions:
There are some tasks in Rake4LaTeX who needs a connected TeX-file. The task basefile defines such a connection.
From rakes view, it's just a dummy-task to define prerequisites for other tasks.
Tasks using basefile are:
If you build a pdf (or dvi), basefile-actions are done in background.
It is recommended to define your main-file as basefile. Without this, clean... may not work correct.
The touch task changes the modification data for the touched file. In the result you can force a new TeX-run.
Usage:
task :touch => 'myfile.tex' task :default => touch
With
task :basefile => 'myfile'
touch is also connected with your sourcefile.
Get a very short overview on the log-content. Errors and warnings are counted for each log (TeX, bibTeX, makeindex...)
Usage:
task :basefile => 'myfile' task :statistic task :default => [ 'myfile.pdf', :statistic ]
A log-file is created with a log-summary (TeX_Statistic#stat_summary), all errors and warnings from TeX and the tools and a detailed analyse for the TeX-log.
You should do this task always _before_ a clean-task.
Usage:
task :basefile => 'myfile' task :log_overview task :default => [ 'myfile.pdf', :log_overview ]
TeX and the related tools build a lot of auxiliary files. When you have them, you can delete the auxiliary files.
The task _clean_ does exactly this.
If you also want to delete the results (pdf...) you can use the task _clobber_.
Usage:
task :basefile => 'myfile' task :default => [ 'myfile.pdf', :clean ]
When may also add a parameter with the basename of a file to delete the auxiliary files:
rake clean[myfile.tx]
With _clean_ you loose all logs. With _log_archive_ you create a zip-file with all logs.
_log_archive_ makes only sense in combination with _clean_. First archive the logs, then delete them with _clean_. After this you have _one_ file with all your logs and in case of errors you can make analyses in the archived logs.
You should do this task always _before_ a clean-task.
Usage:
task :basefile => 'myfile' task :default => [ 'myfile.pdf', :log_archive, :clean ]
Task to generate pictures or other stuff needed to build your LaTeX project can be added like normal rake-tasks.
Some task must be executed after a TeX-run. This tasks must be created with tex_postrule instead of the rake-method rule.
The tasks for makeindex and bibTeX are already defined.
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.
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'
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.
There are additional packages requiring additonal runs.
0.0.1 2010-01-03
0.1.0 2010-01-07
0.1.1 2010-01-21
0.1.2 2010-09-15
0.1.3 2011-08-19
0.1.4
wait_thr.value.exitstatus
0.1.5