Editing Tutorial (section)

==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''' .