|
|
| (10 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.
| |
| * Optionally runs configure on your latex files to replace <tt>@''VARIABLE''@</tt> with the equivalent CMake variable.
| |
| * Automatically finds png, jpeg, 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)
| |
| | |
| The <tt>ADD_LATEX_DOCUMENT</tt> adds the following targets to create a readable document from MyDoc.tex:
| |
| | |
| ;dvi:Creates MyDoc.dvi.
| |
| ;pdf:Creates MyDoc.pdf using pdflatex. Requires the PDFLATEX_COMPILER CMake variable to be set.
| |
| ;ps:Creates MyDoc.ps. Requires the DVIPS_CONVERTER CMake variable to be set.
| |
| ;safepdf:Creates MyDoc.pdf from MyDoc.ps using ps2pdf. Many publishers prefer pdfs are created this way. Requires the PS2PDF_CONVERTER CMake variable to be set.
| |
| ;html:Creates html pages. Requires the LATEX2HTML_CONVERTER CMake variable to be set.
| |
| | |
| One caveat about using [[CMakeUserUseLATEX_UseLATEX.cmake|UseLATEX.cmake]] is that you are required to do an out-of-source build. That is, CMake must be run in a directory other than the source directory. This is necessary as latex is very picky about file locations, and the relative locations of some generated or copied files can only be maintained if everything is copied to a separate directory structure.
| |
| | |
| ===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 or jpeg 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>IMAGE_DIRS</tt> option to the <tt>ADD_LATEX_DOCUMENT</tt> macro to point to them. [[CMakeUserUseLATEX_UseLATEX.cmake|UseLATEX.cmake]] will take care of the rest.
| |
| | |
| ADD_LATEX_DOCUMENT(MyDoc.tex BIBFILES MyDoc.bib IMAGE_DIRS images)
| |
| | |
| If you want to break up your image files in several different directories, you can do that, too. Simply provide multiple directories after the IMAGE_DIRS command.
| |
| | |
| ADD_LATEX_DOCUMENT(MyDoc.tex BIBFILES MyDoc.bib IMAGE_DIRS icons figures)
| |
| | |
| Alternatively, you could list all of your image files separatly with the <tt>IMAGES</tt> option.
| |
| | |
| SET(MyDocImages
| |
| logo.eps
| |
| icons/next.png
| |
| icons/previous.png
| |
| figures/flowchart.eps
| |
| figures/team.jpeg
| |
| )
| |
| ADD_LATEX_DOCUMENT(MyDoc.tex IMAGES ${MyDocImages})
| |
| | |
| Both the <tt>IMAGE_DIRS</tt> and <tt>IMAGES</tt> can be used together. The combined set of image files will be processed. 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]
| |
| | |
| ===Create a PDF by Default===
| |
| | |
| By default, when you use <code>ADD_LATEX_DOCUMENT</code> and then run <code>make</code> with no arguments, the dvi file will be created. You have to specifically build the pdf target to use <code>pdflatex</code> to create a pdf file. However, oftentimes we want the pdf to be generated by default. To do that, simply use the <code>DEFAULT_PDF</code> option to <code>ADD_LATEX_DOCUMENT</code>:
| |
| | |
| ADD_LATEX_DOCUMENT(MyDoc.tex BIBFILES MyDoc.bib IMAGE_DIRS images DEFAULT_PDF)
| |
| | |
| ===Building Multiple LaTeX Documents===
| |
| | |
| The most comment use for [[CMakeUserUseLATEX_UseLATEX.cmake| UseLATEX.cmake]] is to build a single document, such as a paper you are working on. However, some use cases involve building several documents at one time. To do this, you must call <code>ADD_LATEX_DOCUMENT</code> multiple times. However, if you do this, the dvi, pdf, etc. targets will be generated multiple times, and that is illegal in the current version of CMake. To get around this, you need to mangle the names of the targets that <code>ADD_LATEX_DOCUMENT</code> creates. To do this, use the <code>MANGLE_TARGET_NAMES</code> option.
| |
| | |
| ADD_LATEX_DOCUMENT(MyDoc1.tex MANGLE_TARGET_NAMES)
| |
| ADD_LATEX_DOCUMENT(MyDoc2.tex MANGLE_TARGET_NAMES)
| |
| | |
| In the example above, the first call to <code>ADD_LATEX_DOCUMENT</code> will create targets named <tt>MyDoc1_dvi</tt>, <tt>MyDoc1_pdf</tt>, <tt>MyDoc1_ps</tt>, etc. whereas the second call will create targets named <tt>MyDoc2_*</tt>.
| |
| | |
| If you still want the simple, short targets to build all of the documents, you can add them yourself with custom targets that depend on the targets created by <code>ADD_LATEX_DOCUMENT</code>
| |
| | |
| ADD_CUSTOM_TARGET(dvi)
| |
| ADD_DEPENDENCIES(MyDoc1_dvi MyDoc2_dvi)
| |
| ADD_CUSTOM_TARGET(pdf)
| |
| ADD_DEPENDENCIES(MyDoc1_pdf MyDoc2_pdf)
| |
| ADD_CUSTOM_TARGET(ps)
| |
| ADD_DEPENDENCIES(MyDoc1_ps MyDoc2_ps)
| |
| | |
| ===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 <code>USE_INDEX</code> option anywhere in the <code>ADD_LATEX_DOCUMENT</code> arguments, and makeidx will automatically be added to the build.
| |
| | |
| ADD_LATEX_DOCUMENT(MyDoc.tex BIBFILES MyDoc.bib IMAGE_DIRS images 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 these files along with the target tex file. Build dependencies to these files is also established.
| |
| | |
| ADD_LATEX_DOCUMENT(MyDoc.tex
| |
| INPUTS Chapter1.tex Chapter2.tex Chapter3.tex Chapter4.tex
| |
| BIBFILES MyDoc.bib
| |
| IMAGE_DIRS images
| |
| USE_INDEX
| |
| )
| |
| | |
| ===Configuring LaTeX Files===
| |
| | |
| Sometimes it is convenient to control the build options of your tex file with CMake variables. You can achieve this by using the <tt>CONFIGURE</tt> argument to <tt>ADD_LATEX_DOCUMENT</tt>.
| |
| | |
| ADD_LATEX_DOCUMENT(MyDoc.tex
| |
| INPUTS Chapter1.tex Chapter2.tex Chapter3.tex Chapter4.tex
| |
| CONFIGURE MyDoc.tex
| |
| BIBFILES MyDoc.bib
| |
| IMAGE_DIRS images
| |
| USE_INDEX
| |
| )
| |
| | |
| In the above example, in addition to copying MyDoc.tex to the binary directory, [[CMakeUserUseLATEX_UseLATEX.cmake|UseLATEX.cmake]] will configure MyDoc.tex. That is, it will find all occurrences of @''VARIABLE''@ and replace that string with the current CMake variable ''VARIABLE''.
| |
| | |
| With the <tt>CONFIGURE</tt> argument you can list the target tex file (as shown above) as well as any other tex file listed in the <tt>INPUTS</tt> argument.
| |
| | |
| ADD_LATEX_DOCUMENT(MyDoc.tex
| |
| INPUTS Ch1Config.tex Ch1.tex Ch2Config.tex Ch2.tex Ch3Config Ch3.tex
| |
| CONFIGURE Ch1Config.tex Ch2Config.tex Ch3Config.tex
| |
| BIBFILES MyDoc.bib
| |
| IMAGE_DIRS images
| |
| USE_INDEX
| |
| )
| |
| | |
| Be careful when using the <tt>CONFIGURE</tt> option. 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). This can be particularly troublesome to debug as LaTeX will give an error in a place that, in the original document, is legal. Hence, it is best to only configure tex files that contain very little text of the actual document and instead are mostly setup and options.
| |
| | |
| == Frequently Asked Questions ==
| |
| | |
| This section includes resolutions to common questions and issues concerning use of [[CMakeUserUseLATEX_UseLATEX.cmake| UseLATEX.cmake]] and with LaTeX in general.
| |
| | |
| === How do I process LaTeX files on Windows? ===
| |
| | |
| I have successfully used two different ports of LaTeX for windows: the [http://www.cygwin.com/ cygwin] port and the [http://www.miktex.org/ MiKTeX] port.
| |
| | |
| If you use the [http://www.cygwin.com/ cygwin] port of LaTeX, you must also use the [http://www.cygwin.com/ cygwin] port of CMake, make, and ImageMagick. If you use the [http://www.miktex.org/ MiKTeX] port of LaTex, you must use the CMake from http://www.cmake.org/HTML/Download.html, the ImageMagick port from http://www.imagemagick.org/script/index.php, and a native build tool like MSVC or the GNU make port at http://unxutils.sourceforge.net/. '''Do not use the "native" CMake program with any cygwin programs or the cygwin CMake program with any non-cygwin programs.''' This issue at hand is that the cygwin ports create and treat filenames differently then other windows programs.
| |
| | |
| Also be aware that if you have images in your document, there are numerous problems that can occur on Windows with the ImageMagick convert program. See the [[#Why is convert failing on Windows?]] entry for more information.
| |
| | |
| === How do I process LaTeX files on Mac OS X? ===
| |
| | |
| I highly recommend using the port of LaTeX that is available from the [http://fink.sourceforge.net fink project]. The easiest way to get files from [http://fink.sourceforge.net fink] is to use [http://finkcommander.sourceforge.net FinkCommander].
| |
| | |
| The ImageMagick convert program is also available from the [http://fink.sourceforge.net fink project].
| |
| | |
| === Why is convert failing on Windows? ===
| |
| | |
| Assuming that you have correctly downloaded and installed an appropriate version of ImageMagick (as specified by [[#How do I process LaTeX files on Windows?]]), there are several other problems that users can run into the created build files attempt to run the convert program.
| |
| | |
| A common error seen is
| |
| Invalid Parameter - ''filename''
| |
| This is probably because CMake has found the wrong convert program. Windows is installed with a program named convert in %SYSTEMROOT%\system32. This convert program is used to change the filesystem type on a hard drive. Since the windows convert is in a system binary directory, it is usually found in the path before the installed ImageMagick convert program. (Don't get me started about the logic behind this.) Make sure that the <code>IMAGEMAGICK_CONVERT</code> CMake variable is pointing to the correct convert program.
| |
| | |
| Another common error is that convert not finding a file that is clearly there.
| |
| convert: unable to open image `''filename'''
| |
| If you notice that the drive letter is stripped off of the filename (i.e. C:), then you are probably mixing the Cygwin version of convert with the non-cygwin CMake. The cygwin version of convert uses the colon (<tt>:</tt>), as a directory separator for inputs. Thus, it assumes the output file name is really two input files separated by the colon. Switch to the non-cygwin port of ImageMagick to fix this.
| |
| | |
| If you are using nmake, you may also see the following error:
| |
| convert.exe: unable to open image `C:': Permission denied.
| |
| I don't know what causes this error, but it appears to have something to do with some strange behavior of nmake when quoting the convert executable. The easiest solution is to use a different build program (such as make or MSVC's IDE). If anyone finds away around this problem, please contribute back.
| |
| | |
| | |
| [[CMake_User_Contributed_Macros|Back]]
| |
| | |
| {{CMake/Template/Footer}}
| |
