Better comments for the top macros of paper.tex

The default 'paper.tex' starts by defining some macros and comments
describing them. Until now, the text was not too clear and could be
confusing for someone that is not at all familiar with Maneage.

With this commit, the comments have been edited to be more clear for a
first-time reader. For example they all start with FULL CAPS
summaries.

Two other small things were corrected in 'tex/src/preamble-necessary.tex':

 - Until now 'project.tex' was included in this preamble. However, because
   of its importance in Maneage, and prominent place in the demonstration
   plot of the paper introducing Maneage, it is now included directly in
   'paper.tex'. This also allows users to safely ignore/delete this
   preamble file if their LaTeX style is different.

 - I noticed that some macros for some astronomical software names from the
   very first commits in Maneage were still present here! They are no
   longer used, so they have been removed.

2 files changed, 50 insertions, 46 deletions

diff --git a/paper.tex b/paper.tex
index f1ca48f..24cadf0 100644
--- a/paper.tex
+++ b/paper.tex
@@ -2,43 +2,67 @@
 %% See the end of the file for license conditions.
 \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 figures directly, you
-%% can use the standard `\includegraphics' command. See the definition of
-%% `\includetikz' in `tex/preamble-pgfplots.tex' for where the files are
-%% assumed to be if you use `\includetikz' when `\makepdf' is not defined.
+%% (OPTIONAL) CONVENIENCE VARIABLE: Only relevant when you use Maneage's
+%% '\includetikz' macro to build plots/figures within LaTeX using TikZ or
+%% PGFPlots. If so, when the Figure files (PDFs) are already built, you can
+%% avoid TikZ or PGFPlots completely by commenting/removing the definition
+%% of '\makepdf' below. This is useful when you don't want to slow-down a
+%% LaTeX-only build of the project (for example this happens when you run
+%% './project make dist'). See the definition of '\includetikz' in
+%% `tex/preamble-pgfplots.tex' for more.
 \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.
+%% (OPTIONAL) CONVENIENCE VARIABLE: Only relevant when
+%% 'tex/src/preamble-necessary.tex' is included (in particular the small
+%% patch relating to '\highlightchanges'). In there, Maneage defines two
+%% macros: `\tonote' and `\new'. When '\highlightchanges' is defined (value
+%% is irrelevant), the text in those two macros becomes colored (in the
+%% former, the text becomes dark red, in the latter it becomes dark
+%% green). When not defined, text in the former isn't printed in the output
+%% at all, and text in the latter becomes the same color as the rest of the
+%% text. This is useful in cases that you need to distribute drafts and you
+%% want to hightlight the new parts and add notes in the middle of the text
+%% only for discussion, and build a clean PDF without any such highlights
+%% without modifying the text.
 \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.
+%% VALUES FROM ANALYSIS (NUMBERS AND STRINGS): these are automatically
+%% generated by the analysis phase of the project. The files loaded by
+%% 'project.tex' only contain macro definitions (with '\newcommand') and
+%% nothing else. So they won't interfere with any LaTeX style and can be
+%% safely used in any pre-defined style.
+\input{tex/build/macros/project.tex}
+
+%% CUSTOM PREAMBLES FOR DEMO: You can remove them if you are using a
+%% specific journal style, or don't need features like BibLaTeX (advanced
+%% bibliography management) or PGFPlots (for drawing plots within LaTeX
+%% directly from tables of data). If you don't need them, you can also
+%% delete their files from your branch to keep the 'tex/src' directory on
+%% your branch clean.
 \input{tex/src/preamble-style.tex}
 \input{tex/src/preamble-header.tex}
 \input{tex/src/preamble-biblatex.tex}
 \input{tex/src/preamble-pgfplots.tex}
 \input{tex/src/preamble-necessary.tex}
 
-%% Title and author information. For a more fine-grained control of the
-%% headers including author name, or paper info, see
-%% `tex/src/preamble-header.tex'. Note that if you plan to use a journal's
-%% LaTeX style file, you will probably not need to set them, and can also
-%% replace this "Title and author information" section with the journal's
-%% preferred format.
-%
-%% NOTE ON TITLE: The title of the project should also be printed as
-%% metadata in all output files. So it is defined with other core project
-%% metadata in 'reproduce/analysis/config/metadata.conf'. That value is
-%% then written in the '\projectitle' LaTeX macro and directly used
-%% here. So please set your project's title in that Makefile with other
-%% basic information.
+%% PROJECT TITLE: The project title should also be printed as metadata in
+%% all output files. To avoid inconsistancy caused by manually typing it,
+%% the title is defined with other core project metadata in
+%% 'reproduce/analysis/config/metadata.conf'. That value is then written in
+%% the '\projectitle' LaTeX macro by
+%% 'reproduce/analysis/make/initialize.mk' and is directly used here. So
+%% please set your project's title in 'metadata.conf' (ideally with other
+%% basic project information) and re-run the project to have your new
+%% title. If you later use a different LaTeX style, please use the same
+%% '\projectitle' in it (after importing 'tex/build/macros/project.tex'
+%% like above), don't type it by hand.
 \title{\large \uppercase{\projecttitle}}
+
+%% AUTHOR INFORMATION: For a more fine-grained control of the headers
+%% including author name, or paper info, see
+%% `tex/src/preamble-header.tex'. Note that if you plan to use a journal's
+%% LaTeX style file, you will probably set the authors in a different way,
+%% feel free to change them here, this part is not related to the analysis.
 \author[1]{Your name}
 \author[2]{Coauthor one}
 \author[1,3]{Coauthor two}
diff --git a/tex/src/preamble-necessary.tex b/tex/src/preamble-necessary.tex
index 47a178e..bf74c8b 100644
--- a/tex/src/preamble-necessary.tex
+++ b/tex/src/preamble-necessary.tex
@@ -23,26 +23,6 @@
 
 
 
-%% Values from the analysis.
-\input{tex/build/macros/project.tex}
-
-
-
-
-
-% Macros for to help in typing, remove them if you don't need them, but
-% this can help as a demo on how you can simply writing of commonly used
-% words that need special formatting (like software names).
-\newcommand{\snsign}{{\small S}/{\small N}}
-\newcommand{\originsoft}{\textsf{ORIGIN}}
-\newcommand{\sextractor}{\textsf{SE\-xtractor}}
-\newcommand{\noisechisel}{\textsf{Noise\-Chisel}}
-\newcommand{\makecatalog}{\textsf{Make\-Catalog}}
-
-
-
-
-
 %% For highlighting updates. When this is set, text marked as \new
 %% will be colored in dark green and text that is marked wtih \tonote
 %% will be marked in dark red.