From 7a989feae06c46f57d31fc434f940561a4199669 Mon Sep 17 00:00:00 2001
From: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Date: Tue, 27 Feb 2018 20:00:07 +0100
Subject: Abstract added to final PDF along with better explanation

An abstract is also something most research reports will need, so a simple
macro was defined to make it easy (not too many code lines within the text
of the main body) to implement an abstract.

The title was also moved up a little to better use the extra white space at
the top of the page.

Finally, the `\highlightchanges' along with its explanation (both as
comments and within the text with examples) was added in `paper.tex' to
demonstrate how useful the `\new' and `\tonote' macros are.
---
 paper.tex | 83 +++++++++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 59 insertions(+), 24 deletions(-)

(limited to 'paper.tex')

diff --git a/paper.tex b/paper.tex
index 049bc18..4dd644a 100644
--- a/paper.tex
+++ b/paper.tex
@@ -1,4 +1,4 @@
-\documentclass[twocolumn]{article}
+\documentclass[10pt, twocolumn]{article}
 
 %% This is a convenience variable if you are using PGFPlots to build plots
 %% within LaTeX. If you want to import PDF files for plots directly (and
@@ -9,6 +9,13 @@
 %% in.
 \newcommand{\makepdf}{}
 
+%% When defined (value is irrelevant), `\highlightchanges' will cause text
+%% in `\tonote' and `\new' to become colored. This is useful in cases that
+%% you need to distribute drafts that is undergoing revision and you want
+%% to hightlight to your colleagues which parts are new and which parts are
+%% only for discussion.
+\newcommand{\highlightchanges}{}
+
 %% Necessary LaTeX preambles to include for relevant functionality. We want
 %% to start this file as fast as possible with the actual body of the
 %% paper, while keeping modularity in the preambles.
@@ -31,7 +38,21 @@
 \begin{document}
 
 %% Write the title, authors and date.
-\maketitle
+\includeabstract{
+  %% -------- Delete this ---------
+
+  You have completed the reproduction pipeline and are ready to configure
+  and implement it for your own research. This template reproduction
+  pipeline and document contains almost all the elements that you will need
+  in a research project containing the downloading of raw data, processing
+  it, including them in plots and report, including this abstract, figures
+  and bibliography. If you use this pipeline in your work, don't forget to
+  add a notice to clearly let the readers know that your work is
+  reproducible. If this pipeline proves useful in your research, please
+  cite \citet{ai15}.
+
+  %% ------------------------------
+}
 
 %% -------- Delete this ---------
 \section{Congratulations!}
@@ -54,40 +75,54 @@ in this way, will let you focus clearly on your science and not have to
 worry about fixing this or that number/name in the text.
 
 Just as a demonstration of creating plots within \LaTeX{} (using the
-PGFPlots package), in Figure \ref{deleteme} we show a plot of
+{\small PGFP}lots package), in Figure \ref{deleteme} we show a plot of
 \deletemenum{} random points that were generated by this pipeline using the
 text manipulation program {\small AWK} (which is not the best random number
 generator, but just used here to generate some values). The minimum value
 in this distribution is $\deletememin$ and $\deletememax$ is the maximum.
 
 The {\small PDF} file of Figure \ref{deleteme} is available in the
-directory \texttt{\bdir/tex/build/tikz} and can be used in other contexts
-(for example slides). If you want to directly use the PDF file in the
-figure without having to let TiKZ decide if it should be remade or not, you
-can also comment the \texttt{makepdf} macro at the top of this \LaTeX{}
-source file.
-
-PGFPlots is a great tool to build the plots within \LaTeX{} and removes the
-necessity to add further dependencies (to create the plots) to your
-reproduction pipeline. High-level language libraries like Matplotlib do
-exist to also generate plots. However, bare in mind that they require many
-dependencies (Python, Numpy and etc). Installing these dependencies from
-source (after several years when the binaries are no longer available in
-common repositories), is not easy and will harm the reproducibility of your
-paper.
-
-\begin{Figure}
+directory \texttt{\bdir/tex/build/tikz/} and can be used in other contexts
+(for example slides). If you want to directly use the {\small PDF} file in
+the figure without having to let {\small T}i{\small KZ} decide if it should
+be remade or not, you can also comment the \texttt{makepdf} macro at the
+top of this \LaTeX{} source file.
+
+{\small PGFP}lots is a great tool to build the plots within \LaTeX{} and
+removes the necessity to add further dependencies (to create the plots) to
+your reproduction pipeline. High-level language libraries like Matplotlib
+do exist to also generate plots. However, bare in mind that they require
+many dependencies (Python, Numpy and etc). Installing these dependencies
+from source (after several years when the binaries are no longer available
+in common repositories), is not easy and will harm the reproducibility of
+your paper.
+
+\begin{figure}[t]
   \includetikz{delete-me}
 
   \captionof{figure}{\label{deleteme} A random set of values plotted as a
     demonstration of how to generate plots within LaTeX.}
-\end{Figure}
+\end{figure}
 
-Furthermore, since PGFPlots is built by \LaTeX{} it respects all the
-properties of your text (for example line width and fonts and etc), so the
-final plot blends in your paper much more nicely. It also has a wonderful
+Furthermore, since {\small PGFP}lots is built by \LaTeX{} it respects all
+the properties of your text (for example line width and fonts and etc), so
+the final plot blends in your paper much more nicely. It also has a
+wonderful
 manual\footnote{\url{http://mirrors.ctan.org/graphics/pgf/contrib/pgfplots/doc/pgfplots.pdf}}.
 
+This pipeline also defines two \LaTeX{} macros that allow you to mark text
+within your document as \emph{new} and \emph{notes}. For example, \new{this
+  text has been marked as \texttt{new}.} \tonote{While this one is marked
+  as \texttt{tonote}.} If you comment the line (by adding a `\texttt{\%}'
+at the start of the line or simply deleting the line) that defines
+\texttt{highlightchanges}, then the one that was marked \texttt{new} will
+become black (totally blend in with the rest of the text) and the one
+marked \texttt{tonote} will not be in the final PDF. You can thus use
+\texttt{highlightchanges} to easily make copies of your research for
+existing coauthors (who are just interested in the new parts or notes) and
+new co-authors (who don't want to be distracted by these issues in their
+first time reading).
+
 
 \section{Notice and citations}
 To encourage other scientists to publish similarly reproducible papers,
@@ -101,7 +136,7 @@ cite the first paper that used the first version of this pipeline:
 
 After publication, don't forget to upload all the necessary data, software
 source code and the reproduction pipeline to a long-lasting host like
-Zenodo (\url{https://zenodo.org/}).
+Zenodo (\url{https://zenodo.org}).
 %% ------------------------------
 
 
-- 
cgit v1.2.1

