rake4latex: TeX-Build-Tool ------------------------------
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 a rakefile template with:
require 'rake4latex'
puts Rake4LaTeX.build_rakefile( basename, :pdf, :dependecies )
The method will print a rakefile definition.
Supported options:
call_rake4latex.rb ------------------------------
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
rake4latex as lib in your application ------------------------------
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
Document creation ------------------------------
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:
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).
*) 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.
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: 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 )
Dependecies for BibTeX ------------------------------
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.
Supported tools and packages ------------------------------
Supported tools ------------------------------
The following tools are supported by rake4latex:
Supported (checked) packages ------------------------------
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:
Special Tasks ------------------------------
basefile ------------------------------
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.
touch ------------------------------
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.
statistic ------------------------------
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 ]
log_overview ------------------------------
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 ]
clean ------------------------------
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]
log_archive ------------------------------
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 ]
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 tex_postrule instead of the rake-method rule.
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 ------------------------------
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.
Packages with problems ------------------------------
There are additional packages requiring additonal runs.
Version History ------------------------------
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
FAQs
Unknown package
We found that rake4latex demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
