Editing Tutorial (section)

=Authors=
The Authors tutorials demonstrate how one can create reproducible documents using the Madagascar processing package and L<sup>A</sup>TEX together.  By the end of the Authors tutorials, you should be able to:
  
*build papers, including: SEG and EAGE abstracts, manuscripts for Geophysics, and handouts, 
*build a CSM thesis, 
*build a CWP report, 
*build slides, 
*and add/modify Latex class files to add your custom document formats to Madagascar. 
After completing this tutorial series, you will be able to maximize your research productivity using Madagascar.

==Getting started==
Before you can get started writing reproducible documents, you need to ensure that your system is properly setup.  This section of the tutorial will walk you through the setup process, which can be somewhat difficult and laborious depending on which operating system you are on, as you will need a full installation of L<sup>A</sup>TEX and additional L<sup>A</sup>TEX class files that Madagascar makes available to you. The good news is that this configuration only happens once.
===Downloading L<sup>A</sup>TEX===
To begin, you need to download a full installation of L<sup>A</sup>TEX for your operating system.  To do so, you may need to contact your system administrator.  If you have administrative rights, then you can download a full install for your platform from the following locations:
  
*Linux - use your package management software to install a full texlive (you may need additional packages depending on your distribution). 
*Mac - install MacTex http://www.tug.org/mactex/2011/. 
*Windows - install MikTex http://miktex.org/. 
The respective downloads typically are quite large and take a substantial amount of time to complete, so start the download and come back later.  Once your download is done, test your installation by executing '''pdflatex'''  at the command line.  If everything works fine then continue onwards. For Mac users, you may need "sudo port install texlive-latex-extra".

===Downloading SEGTeX===
The next step is to download the SEG\TeX class files, which tells L<sup>A</sup>TEX how to build certain documents that we commonly use.  To download SEG\TeX first '''cd'''  to a directory where L<sup>A</sup>TEX can find additional class files.  This directory is typically operating system dependent, and may be distribution dependent for Linux.  Typically, you can place these files in '''&#36;HOME/texmf''' .  Otherwise, you will need to place them in the root installation for Latex which can be found by searching for the basic class files, such as article.cls.  On a Mac the typical place to put these files is '''&#36;HOME/Library/texmf''' .  In any case, once you are in the proper location, then use the following command to download the class files (using subversion):
<pre>
svn co https://segtex.svn.sourceforge.net/svnroot/segtex/trunk texmf 
</pre>
or download a stable release from http://sourceforge.net/projects/segtex/files/ and unpack it into the <tt>texmf</tt> directory.
===Updating your L<sup>A</sup>TEX install===
Once the class files are successfully downloaded, you will need to run '''texhash'''  or '''texconfig rehash'''  to update L<sup>A</sup>TEX about the new class files.  For reference, a successful run of '''texhash'''  produces the following output:
<pre>
jgodwin&#36; texhash
texhash: Updating /usr/local/texlive/2010/../texmf-local/ls-R... 
texhash: Updating /usr/local/texlive/2010/texmf/ls-R... 
texhash: Updating /usr/local/texlive/2010/texmf-config/ls-R... 
texhash: Updating /usr/local/texlive/2010/texmf-dist/ls-R... 
texhash: Updating /usr/local/texlive/2010/texmf-var/ls-R... 
texhash: Done.
</pre>
To determine if these files are found successfully, go into &#36;RSFROOT/book/rsf/manual and run '''scons manual.read''' .  If L<sup>A</sup>TEX complains about being unable to find the class files then you should re-run texhash, or make sure that your class files are in the proper location.  If you are still having difficulties, then contact the [[SEGTeX|SEGTeX webpage]] or the user mailing list for further information.

==Papers==
With L<sup>A</sup>TEX installed, we can now create reproducible documents using Madagascar.  First, we will demonstrate how to build shorter, less complicated documents using Madagascar, such as SEG/EAGE abstracts, Geophysics articles, and handouts.  All of these papers have similar build styles, so the rules for building each respective paper have only slight differences from one another.  Instead of talking in detail about each of these documents, we illustrate the basic idea for each of the documents, and provide examples that demonstrate the particulars for each type of document.  
===Paper organization===
All Madagascar papers expect a specific organization to your directories.  In particular, you are expected to have a paper-level directory where your '''tex'''  files and main SConstruct will exist.  These files will tell Madagascar how to build your documents for a particular project.  You can have multiple documents built from the same location, using the same SConstruct as we will demonstrate later.  
Below the paper directory, are the individual "chapters" that contain the processing flows used to generate the plots or process the data that you wish to use in your reproducible documents.  Ideally, each "chapter" directory correlates to the processing flows or examples in each chapter or section for your paper.  Additionally, each "chapter" contains its own SConstruct that operates independently of the paper SConstruct one level above it.  Furthermore, inside the "chapter" folder, Madagascar needs to have a '''Fig'''  folder that contains all of the VPLOT files that were created using Result commands during processing.    This folder is automatically created during processing using SCons, so you don't need to manually create it.  It is important to note that Madagascar can only locate VPLOT files that are in this file hierarchy for use in your papers.  The figure below illustrates the folder hierarchy as well.
Note: "chapter" folders may be symbolic links that point to folders elsewhere on the file system.  This trick can be useful to reuse figures without copying files and folders around to various folders.  If you use symlinks, make sure to avoid editing files that are symbolically linked, as your changes may propagate in unintended ways to other projects and papers.
[[Image:dir.png|frame|center|The organizational hierarchy for Madagascar paper directories.]]

===Locking figures===
Once you have created the necessary folder hierarchy with your "chapters" and processing flows, then go ahead and run your processing SConstructs.  After those are finished, you need to lock your figures using '''scons lock''' .  '''scons lock'''  tells Madagascar that the figures you have generated are ready to go into a publication, and will store them in a subfolder of the '''&#36;RSFFIGS'''  directory for safe keeping.  Locked figures are used for document figures instead of the figures in your local directory, because they are locked and not still changing.  If you change your plots but do not lock your figures, you will not see your figures change.  Always make sure to lock your figures before building a document.
===TeX files===
Now that your figures are locked, you can create your first reproducible document in Madagascar.  To do so, you will need to:
*make your TeX files, and  
*make a paper SConstruct,  
Before making a document, you need to create your TeX files in the paper level directory.   For example, to create an EAGE abstract, you would create a main TeX file called: '''eageabs.tex'''  which contains the content and TeX commands to build your abstract.  Your TeX file can use all of the standard and expanded L<sup>A</sup>TEX commands provided by any available packages on your system. It's important to remember that you should try and break apart your TeX files into manageable chunks, so that you can modify them independently, or reuse the content in other documents.  For example, instead of having a single TeX file for your EAGE abstract, you could have a separate TeX file that contains: '''\input{...}'''  statements that include additional TeX files for each section, such as the abstract, theory, discussion, conclusions, etc.
Additionally, Madagascar provides some convenience commands for often used L<sup>A</sup>TEX functions.  Here is a short description of some of those convenience commands that you may run across.  Here's a brief list of these convenience functions:
*<font color="#cd4b19">\plot</font>, 
*<font color="#cd4b19">\multiplot</font>, 
*<font color="#cd4b19">\sideplot</font>, 
*and more. 
These convenience functions are not available for every type of document, but are demonstrated in documents where they are available.  The definition for the convenience functions may be found in the L<sup>A</sup>TEX class definitions listed at the end of this tutorial.

===Paper SConstructs===
One of Madagascar's aims is to make TeX files as layout-agnostic as possible.  To do so, Madagascar automatically adds the TeX document preamble (including the L<sup>A</sup>TEX document class information), the L<sup>A</sup>TEX package inclusions, and end of document information at runtime.  This allows you to generate multiple documents from a single TeX file by simply changing the SConstruct, instead of the TeX file.  
Note: the paper SConstruct is only used to build papers.  It contains no other information, and cannot be used to process data in the same SConstruct.  This is why the paper SConstruct must exist in a separate directory from any processing SConstructs.
The paper SConstruct is very simple compared to most processing SConstructs, in that it contains only a few lines as shown below (in an example for an EAGE abstract):
<syntaxhighlight lang="python">
from rsf.tex import *
Paper('eageabs',
      lclass='eageabs',
      options='11pt',
      use='times,natbib,color,amssymb,amsmath,amsbsy,graphicx,fancyhdr')
</syntaxhighlight>
The first section, '''from rsf.tex import *'''  tells Madagascar to import Python packages for processing TeX files instead of the usual processing packages.  Next, we call a '''Paper'''  object, which takes the following parameters:
<pre>
Paper(name,lclass,options,use)
name - name of the root tex file to build.
lclass - name of the LaTeX class file to use.
options - document options for LaTeX class file.
use - names of LaTeX packages to import during compilation.
</pre>
All of the parameters are passed as strings to the Paper object.  Parameters with more that one possible value (e.g. options and use) accept comma delimited strings as shown above.  
To generate different types of documents, you simply change the '''lclass'''  and options sent to the Paper object in the SConstruct for the respective document type.  Since the documents that we are creating use custom L<sup>A</sup>TEX document classes that require additional TeX commands to function properly, it is easier for us to provide you with a template instead of discussing the details of each document class.  The templates for the documents can be found in the following directory: '''$RSFSRC/book/tutorial/authors'''.

===Templates===
To run the templates, you first need to generate the data used for them in the '''data'''  directory inside of the '''$RSFSRC/book/tutorial/authors''' .  To do so, run '''scons lock'''  which will produce and lock the figures necessary.  Then go into the template directory that you are interested in, and make a symbolic link to the data directory: '''ln -s ../data'''  and a symbolic link to the BibTeX file: '''ln -s ../demobib.bib'''  in the template directory.  After those steps are made you can build and view the paper using '''scons'''  or '''scons paper.read'''  where paper is the name of the root tex file.  Of course, if you want to remove all the generated files, then you can use '''scons -c'''  to clean the directory.

===Handouts===
Handouts are informal documents that are loosely formatted, and very flexible.  The handout example is located in: '''$RSFSRC/book/tutorial/authors/handout''' .  Handouts do not require many additional arguments and are the most flexible of the documents discussed here.

===EAGE abstracts===
EAGE abstracts are short documents, with a few particular formatting tricks. In particular, EAGE requires the logo of the current year's convention to appear in the abstract.  A template is available in: '''$RSFSRC/book/tutorial/authors/eage''' .

===SEG abstracts===
SEG abstracts are different from EAGE abstracts in that they require two-column formatting and are strictly limited to four pages not including references.  To build an SEG abstract, we first build the abstract, and then build another document using the segcut.tex file that removes the references from the final pdf.  An example is found in: '''$RSFSRC/book/tutorial/authors/seg''' .

===Geophysics manuscripts===
Geophysics manuscripts come in two flavors: the first is the manuscript prepared for peer review, and the second is the final document that would appear in a print version of Geophysics.  The example shows how to build both from the same TeX files, which makes it painless to transition the formatting between the two documents.  An example is located in: '''$RSFSRC/book/tutorial/authors/geophys''' .  Make sure to use the template as there are quite a few additional TeX commands that have to be used to get the correct formatting.

===CWP reports===
CWP reports are slightly more complicated then most documents in that they require substantial modification to get the proper formatting.  The CWP template is available in '''$RSFSRC/book/tutorial/authors/cwp''' .

==Slides==
Additionally, one can create presentation slides using L<sup>A</sup>TEX  and Madagascar together.  To create slides, we use the Beamer class files that have been customized for the CWP.  Slides have distinctly different commands then regular documents, so be sure to examine the template before diving in.  The template is in: '''$RSFSRC/book/tutorial/authors/slides''' .

==Theses==
One can also create very complex documents using Madagascar in a reproducible way.  To iillustrate this point we provide a template for building a thesis for the Colorado School of Mines.  This template is quite heavily modified, and requires substantial modification due to all the formatting requirements.  If you want to include a thesis template for another institution then you can do so by examining this template along with the CSM class files.  The template is located in: '''$RSFSRC/book/tutorial/authors/thesis''' .

==Books==
You can make whole books using Madagascar.  The advantage to doing so, is that you can make individual chapters with examples of processing or workflows that can be run independently of one another.  Then Madagascar will stitch the chapters together into a cohesive package seamlessly.  The example for a book is this document itself, which is located in: '''$RSFSRC/book/tutorial/''' .  Note: creating a book is significantly different from creating a paper.

==Adding/modifying L<sup>A</sup>TEX class files==
The L<sup>A</sup>TEX class files made available from SEGtex are found in '''texmf/tex/latex''' .  You can modify these files locally by changing the files inside this location.  
To add your own L<sup>A</sup>TEX class files, place them in this same directory, and then request SEG\TeX access to commit them to the main repository.
==Using the default L<sup>A</sup>TEX class files==
Lastly, you can use any of the default L<sup>A</sup>TEX class files just by changing the options to the Paper object to the appropriate lclass and options. For example:
<syntaxhighlight lang="python">
Paper('article',
lclass='article',
options='11pt',
use='times,natbib,color,amssymb,amsmath,amsbsy,graphicx,fancyhdr')
</syntaxhighlight>