CMakeUserUseLATEX: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
No edit summary
 
(27 intermediate revisions by 4 users not shown)
Line 1: Line 1:
[[CMake_User_Contributed_Macros|Back]]
{{CMake/Template/Moved}}


==Description==
This page has moved [https://gitlab.kitware.com/kmorel/UseLATEX here].
 
Compiling LaTeX files into readable documents is actually a very involved process.  Although CMake comes with FindLATEX.cmake, it does nothing for you other than find the commands associated with LaTeX.  I like using CMake to build my LaTeX documents, but creating targets to do it is actually a pain.  Thus, I've compiled a bunch of macros that help me create targets in CMake into a file I call "[[CMakeUserUseLATEX_UseLATEX.cmake| UseLATEX.cmake]]".  Here are some of the things UseLATEX.cmake handles:
 
* Runs LaTeX multiple times to resolve links.
* Can run bibtex and makeindex to make bibliographies and/or indexes.
* Runs configure on your latex files to replace @VARIABLE@ with the equivalent CMake variable.
* Automatically finds png, eps, and pdf files and converts them to formats latex and pdflatex understand.
 
==Download==
 
Click here to get a copy of [[CMakeUserUseLATEX_UseLATEX.cmake| UseLATEX.cmake]].
 
==Usage==
 
Using [[CMakeUserUseLATEX_UseLATEX.cmake| UseLATEX.cmake]] is easy.  For a basic LaTeX file, simply include the file in your CMakeLists.txt and use the <tt>ADD_LATEX_DOCUMENT</tt> command to make targets to build your document.  For an example document in the file MyDoc.tex, you could establish a build with the following simple CMakeLists.txt.
 
PROJECT(MyDoc NONE)
INCLUDE(UseLATEX.cmake)
ADD_LATEX_DOCUMENT(MyDoc.tex)
 
In addition to adding all the necessary build targets to create MyDoc.dvi, MyDoc.ps, and MyDoc.pdf, <tt>ADD_LATEX_DOCUMENT</tt> also configures MyDoc.tex, replacing any occurrence of <tt>@VARIABLE@</tt> with the CMake variable named <tt>VARIABLE</tt>.
 
===Using a Bibliography===
 
For any technical document, you will probably want to maintain a bibtex database of papers you are referencing in the paper.  You can incorporate your .bib files by adding them after the BIBFILES argument to the <tt>ADD_LATEX_DOCUMENT</tt> command.
 
ADD_LATEX_DOCUMENT(MyDoc.tex BIBFILES MyDoc.bib)
 
This will automatically add targets to build your bib file and link it into your document.  To use the bibtex file in your LaTeX file, just do as you normally would with <tt>\cite</tt> commands and bibliography commands:
 
\bibliographystyle{plain}
\bibliography{ParallelVolumeRenderingInParaView}
 
You can list as many bibliography files as you like.
 
===Incorporating Images===
 
To be honest, incorporating images into LaTeX documents can be a real pain.  This is mostly because the format of the images needs to depend on the version of latex you are running (latex vs. pdflatex).  With these CMake macros, you only need to convert your raster graphics to png format and your vector graphics to eps or pdf format.  Place them all in a common directory (e.g. images) and then use the <tt>ADD_LATEX_IMAGES</tt> and <tt>ADD_LATEX_DOCUMENT</tt> macros to point to them.  [[CMakeUserUseLATEX_UseLATEX.cmake|UseLATEX.cmake]] will take care of the rest.
 
ADD_LATEX_IMAGES(images)
ADD_LATEX_DOCUMENT(MyDoc.tex . BIBFILES MyDoc.bib)
 
Alternatively, you could add a CMakeLists.txt file to the images directory and call <tt>ADD_LATEX_IMAGES(.)</tt> to that directory.  In that case, in the root directory you would add a <tt>SUBDIRS</tt> command to the root CMakeLists.txt and change the second argument of the <tt>ADD_LATEX_DOCUMENT</tt> command to <tt>images</tt>.
 
If you wish to provide a separate eps file and pdf or png file, that is OK, too.  [[CMakeUserUseLATEX_UseLATEX.cmake|UseLATEX.cmake]] will handle that by copying over the correct file instead of converting.
 
Once you establish the images directory, CMake will automatically find all png and eps files in it and add makefile targets to use ImageMagick's convert to convert the file times to those appropriate for the build.  If you do not have ImageMagick, you can get it for free from http://www.imagemagick.org.  CMake will also give you a LATEX_SMALL_IMAGES option that, when on, will downsample raster images.  This can help speed up building and viewing documents.  It will also make the output image sizes smaller.
 
One more note about vector graphics.  Encapsulated postscript (eps) files have a bounding box that is often lost when converting to pdf types.  When using eps files, it is best to search for a line starting with <tt>%%BoundingBox:</tt> such as
 
%%BoundingBox: 58 77 734 536
 
and then copy these numbers to the <tt>bb</tt> option of the LaTeX <tt>\includegraphics</tt> command:
 
\includegraphics[width=\linewidth,bb=58 77 734 536]
 
===Making an Index===
 
You can make an index in a LaTeX document by using the makeidx package.  However, this package requires you to run the makeindex command.  Simply add the <tt>USE_INDEX</tt> option anywhere in the <tt>ADD_LATEX_DOCUMENT</tt> arguments, and makeidx will automatically be added to the build.
 
ADD_LATEX_IMAGES(images)
ADD_LATEX_DOCUMENT(MyDoc.tex . BIBFILES MyDoc.bib USE_INDEX)
 
===Multipart LaTeX Files===
 
Often, it is convenient to split a LaTeX document into multiple files and use the LaTeX <tt>\input</tt> or <tt>\include</tt> command to put them back together.  To do this, all the files have to be together.  [[CMakeUserUseLATEX_UseLATEX.cmake|UseLATEX.cmake]] can take care of that, too.  Simply add the <tt>INPUTS</tt> argument to <tt>ADD_LATEX_DOCUMENT</tt> to copy (and configure) these files along with the target tex file.
 
ADD_LATEX_DOCUMENT(MyDoc.tex .
  INPUTS Chapter1.tex Chapter2.tex Chapter3.tex Chapter4.tex
  BIBFILES MyDoc.bib
  USE_INDEX
  )
 
===Suppressing Configure===
 
As mentioned previously, [[CMakeUserUseLATEX_UseLATEX.cmake|UseLATEX.cmake]] will configure all of your .tex files.  That is, it will find all occurrences of @''MACRONAME''@ and replace that string with the current CMake variable ''MACRONAME''.
 
Unfortunately, the @ symbol is used by LaTeX in some places.  For example, when establishing a tabular environment, an @ is used to define the space between columns.  If you use it more than once, then [[CMakeUserUseLATEX_UseLATEX.cmake|UseLATEX.cmake]] will erroneously replace part of the definition of your columns for a macro (which is probably an empty string).
 
To suppress this behavior, add the <tt>NO_CONFIGURE</tt> option to <tt>ADD_LATEX_DOCUMENT</tt>.
 
ADD_LATEX_DOCUMENT(MyDoc.tex . BIBFILES MyDoc.bib NO_CONFIGURE)
 
[[CMake_User_Contributed_Macros|Back]]
 
{{CMake/Template/Footer}}

Latest revision as of 16:46, 1 May 2018


The CMake community Wiki has moved to the Kitware GitLab Instance.

This page has moved here.