Editing Manual (section)

==Exploring existing reproducible papers==
===Papers and books included in the Madagascar distribution===
[[Reproducible Documents]] and more.

===How to reproduce specific figures in existing papers===
A frequently encountered case is when a researcher wants to reproduce only one or several figures from an entire paper, but not the entire paper. This can happen because on that system LaTeX dependencies of Madagascar are missing or not working properly, or simply because the researcher is interested only in that result.
# '''Finding the paper directory:''' If the interesting article has been found by browsing/hyperlink to [[Reproducible Documents]], then the reproducibility package corresponding to <pre>http://www.reproducibility.org/RSF/book/&lt;bookname&gt;/&lt;papername&gt;/paper_html/</pre> can be found in <pre>RSFSRC/book/&lt;bookname&gt;/&lt;papername&gt;/</pre>
# '''Finding result names:''' Use the html version of the paper, or grep in all <tt>.tex</tt> files in the directory for a text string that occurs in the figure legend. Multiple-panel figures may have individual names for each panel. [Note: In pdf versions obtained with scons pdf in paper directory, neither the book name nor paper directory name nor figure names are given. LaTeX options to have figure names as well as a Geophysics-style header/footer with more details on the first page may be in order]
# '''Finding where to launch the re-build''': In some cases, rules for creating a result are specified in SConstruct files in subdirectories of the main paper directory. If step 4 fails in the main paper directory, then you will have to find where the figure is built. Because result names may be generated automatically, a simple grep may not be enough and you may need to read the SConstruct and python modules imported by it to figure out if the result is generated there.
# '''Re-build''' and display the figure by typing <tt>scons resultname.view</tt> in the appropriate directory.

SConstructs containing a <tt>Fetch</tt> instruction will attempt to download public-domain input data from a communal server when the "scons" command is run. A fast internet connection is necessary in this case.

===How to reproduce entire papers using stored figures===
# See the previous section for how to find the paper directory
# Pointer to how to download stored figures ([[Download#Reproducible figures]])
*<tt>scons pdf</tt>
*<tt>scons read</tt>

Troubleshooting:
* In case of failure with this kind of messages (details here), you miss TeX system dependencies. Install a TeX system. [http://www.tug.org/texlive/ Tex Live] should have it all. Note: It's a 1 Gb download. Too large for many individual users to bother with it and for most IT departments of companies to review for security. We should implement individual dependency checking, like we do in the installation. 
* In case of failure with <tt>LaTeX Error: File `geophysics.cls' not found</tt> you have LaTeX, but you are missing [[SEGTeX]]
* If <tt>scons pdf</tt> in the paper directory requires pdf figures already in place in order to work, run <tt>sftour scons lock</tt> (?).

===How to reproduce entire papers and all their figures===
# See an earlier section for how to find the paper directory
# The relevant SCons command (<tt>scons lock</tt>, or <tt>sftour scons lock</tt>, as in [[Download#Reproducible figures]] to force reproducing the figures in the paper even when the reference figures repository is present

Tell the user to expect conditional reproducibility: If Matlab is not present, rsftex will not try to build the figures but will use the stored PDF files (same goes for Mathematica, xfig, etc.)

===How to reproduce whole books===
The [http://sourceforge.net/mailarchive/forum.php?thread_name=20061222142849.9688.qmail%40web34215.mail.mud.yahoo.com&forum_name=rsf-user 2006-12-22 rsf-user thread], [http://reproducibility.org/rsflog/index.php?/archives/142-Assembling-reports-from-papers.html the 2007-04-08 blog entry] and more.

From Jim's 2009-03-7 rsf-devel message:
Here is a way to generate all the targets in the subdirectories of $RSFSRC/book/geostats/spatial_stats:
<syntaxhighlight lang="bash">
cd $RSFSRC/book/geostats/spatial_stats
sftour scons
</syntaxhighlight>
That works pretty nice.  It generates all the targets in each of the 4 subdirectories of book/geostats/spatial_stats.

Now suppose I want to capture the output and errors in a log file (tcsh):
<syntaxhighlight lang="bash">
sftour scons >& scons.log
</syntaxhighlight>
That's nice, except all the output goes into one log file in book/geostats/spatial_stats.  Suppose I want 4 separate log files, one in each of the subdirectories.  This will do the trick:
<syntaxhighlight lang="bash">
sftour 'scons >& scons.log'
</syntaxhighlight>
The quotes make the entire string go to sftour as the command to run in each directory, instead of just 'scons'.

So far so good.  Now suppose I want to go up one directory level and do the process recursively:
<syntaxhighlight lang="bash">
cd $RSFSRC/book/geostats
sftour sftour 'scons >& scons.log'
</syntaxhighlight>
Well, that runs scons in each of the book/geostats/*/* directories, but it only makes 3 log files in the 3 subdirectories of book/geostats, not 14 log files in the 14 book/geostats/*/* directories.  I can get 14 separate log files like this:
<syntaxhighlight lang="bash">
sftour "sftour 'scons >& scons.log'"
</syntaxhighlight>
That does what I want.  Now suppose I want to go up one more level to $RSFSRC/book and run the process recursively three levels deep:
<syntaxhighlight lang="bash">
sftour sftour "sftour 'scons >& scons.log'"
</syntaxhighlight>
This works, but it doesn't put the log files in the bottom level, it puts them one level up.  I can't fix it the same way I did before because I've run out of quotes :-)  Here is one way to do it (tcsh):
<pre>
foreach i (*)
    if ( -d $i) then
        echo ++++++ $i
        cd $i
        sftour "sftour '/usr/bin/time -p scons >& scons.log'"
        cd ..
    endif
end
</pre>

From Sergey's 2009-03-10 rsf-devel message: A more elegant solution is
<syntaxhighlight lang="bash">
sftour sftour scons >& ../../%/%/scons.log
</syntaxhighlight>