.. latex-makefile:
   
Advanced ways to build LaTeX documents
===============================================
There is an advanced way to build your LaTeX documents using a
``Makefile``. A ``Makefile`` build is in particular very convenient
and saves lots of efforts if you need to deal with multiple source
files.

In general, ``Makefile`` is a way to build/compile source files/codes
in scientific computing. To see more, please take a look at
Prof. Dongwook Lee's
`AMS 209 class notes
<https://users.soe.ucsc.edu/~dongwook/wp-content/uploads/2017/ams209/lectureNote/_build/html/chapters/chapt02/ch02_fortran_makefiles.html>`_
on ``Makefile``.


Let's take a look at a case study where you now want to merge the
previous two LaTeX files into one, plus, want to add a new section.
What you can do is to make a new master file (or caller, or driver),
say, ``master.tex`` from which you ``include`` those two existing LaTeX files,
``first_latex.tex`` (line 28) and ``linuxCommands.tex`` (line 30):

  
  .. literalinclude:: ./examples2/master.tex
     :language: latex
     :linenos:


  .. note::
     What is the difference between ``input`` and ``include``? Check
     out this link:
     `input vs. include: <https://tex.stackexchange.com/questions/246/when-should-i-use-input-vs-include>`_

	
You also see that in lines 22 and 26, we included two new files,
``macros.tex`` and ``useMacros.tex``. The first is analogous to the
style file ``ams200.sty``, but including a bunch of definitions only
that a user would wish to use frequently in documents.
In the below, you see many user-defined macro definitions
``newcommands`` that provide shorthand notations
for their standard (and longer) command lines:

  .. literalinclude:: ./examples2/macros.tex
     :language: latex
     :linenos:

With this, we can conviently call these macros from any other places
in documents, for instance, in ``useMacros.tex``:

  .. literalinclude:: ./examples2/useMacros.tex
     :language: latex
     :linenos:

Note here that, when including ``first_latex.tex`` and
``linuxCommands.tex``, you now need to comment out
the first couple of lines which define the begining and end of the
documents because you now define them in ``master.tex``.
Therefore the two files now should look like:

  .. literalinclude:: ./examples2/first_latex.tex
     :language: latex
     :linenos:

  .. literalinclude:: ./examples2/linuxCommands.tex
     :language: latex
     :linenos:

Finally, we use a ``Makefile`` to build multiple LaTeX source files as
follow:

  .. literalinclude:: ./examples2/Makefile
     :language: makefile
     :linenos:

To build, you simply type in ``make`` in your terminal::

  $ make

In order to rebuild you type in::

  $ make clean

When there is a ``master.pdf`` file already built from a
previous ``make``, you won't be able to ``make`` it again.
In this case you need to build it from fresh by typing in::

  $ make cleanall

You can download all of the files in this section as a tarball:

 * :download:`master.tar <./examples2/master.tar>`

To untar it, run a command::

  $ tar xvf master.tar