aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMohammad Akhlaghi <mohammad@akhlaghi.org>2018-02-27 15:37:59 +0100
committerMohammad Akhlaghi <mohammad@akhlaghi.org>2018-02-27 15:37:59 +0100
commit0a91f0356904e95e049d4a92d6cd7116a90a3e59 (patch)
tree3d34cdfe6b2d90b6bb48f627aa8fb504674f7c6f
parent155d959f45613360c8b986007916ee6f7dd8b318 (diff)
Better comments on TeX preambles
The comments in the preambles were made more clear and elaborate.
-rw-r--r--tex/preamble-biblatex.tex13
-rw-r--r--tex/preamble-necessary.tex6
-rw-r--r--tex/preamble-pgfplots.tex38
3 files changed, 44 insertions, 13 deletions
diff --git a/tex/preamble-biblatex.tex b/tex/preamble-biblatex.tex
index 869d3d5..b0660a9 100644
--- a/tex/preamble-biblatex.tex
+++ b/tex/preamble-biblatex.tex
@@ -1,13 +1,14 @@
%% Biblatex settings.
%%
-%% Since the preamble settings necessary to make the bibliography with
-%% Biblatex is a little long and unclean, and might be used in other places
-%% separately later, it is easier to have it here as a separate file.
+%% Settings necessary to make the bibliography with Biblatex. Keeping all
+%% BibLaTeX settings in a separate preamble was done in the spirit of
+%% modularity to 1) easily managable, 2) If a similar BibLaTeX
+%% configuration is necessary in another LaTeX compilation, this file can
+%% just be copied there and used.
%%
%% USAGE:
-%%
-%% - `tex/ref.tex': the file containing Bibtex source of each
-%% reference. The file suffix doesn't have to be `.bib', this naming
+%% - `tex/references.tex': the file containing Bibtex source of each
+%% reference. The file suffix doesn't have to be `.bib'. This naming
%% helps in clearly identifying the files and avoiding places that
%% complain about `.bib' files.
diff --git a/tex/preamble-necessary.tex b/tex/preamble-necessary.tex
index debcb4b..bef5a2f 100644
--- a/tex/preamble-necessary.tex
+++ b/tex/preamble-necessary.tex
@@ -1,8 +1,8 @@
%% Some (commonly) necessary LaTeX packages.
%%
-%% These are a set of packages that are commonly necessary in most LaTeX
-%% usages. However, if any are not needed in your work, you can remove them
-%% from here.
+%% These are a set of packages that have been commonly necessary in most
+%% LaTeX usages. However, if any are not needed in your work, please feel
+%% free to remove them.
diff --git a/tex/preamble-pgfplots.tex b/tex/preamble-pgfplots.tex
index 78937a7..17ca7b5 100644
--- a/tex/preamble-pgfplots.tex
+++ b/tex/preamble-pgfplots.tex
@@ -1,14 +1,44 @@
%% PGFPlots settings
%% -----------------
-
+%%
%% PGFPLOTS is a package in (La)TeX for making plots internally. It fits
%% nicely with the purpose of a reproduction pipeline. But it isn't
-%% mandatory. Therefore if needed, you can just uncomment the line that
-%% includes this file in the top LaTeX source (`paper.tex').
-
+%% mandatory. Therefore if you don't need it, just comment/delete the line
+%% that includes this file in the top LaTeX source (`paper.tex').
+%%
+%% However, TiKZ and PGFPlots are the recommended way to include figures
+%% and plots in your paper. There are two main reasons: 1) it follows the
+%% same LaTeX settings as the text of the paper, so the figures will be in
+%% the exact same settings (for example font or lines) as the main body of
+%% the papers. 2) It doesn't require any extra dependency (it is
+%% distributed as part of TeX-live). Adding specific programs/libraries for
+%% plots can greatly increase the number of dependencies for the
+%% pipeline. For example Python's Matplotlib library is indeed very good,
+%% but it requires Python and Numpy. The latter is not easy to build from
+%% source, so after a few years, installing the required version can be
+%% very frustrating.
+%%
+%% Keeping all BibLaTeX settings in a separate preamble was done in the
+%% spirit of modularity to 1) easily managable, 2) If a similar BibLaTeX
+%% configuration is necessary in another LaTeX compilation, this file can
+%% just be copied there and used.
+%%
%% PGFPlots uses the (La)TeX TiKZ package to build plots. So we will first
%% do the settings that are necessary in TiKZ, and then go onto the actual
%% PGFPlots package.
+%%
+%% USAGE:
+%%
+%% - All plots are made within a `tikz' directory (that must already be
+%% present in the location LaTeX is run).
+%%
+%% - Use `\includetikz{XXXX}' to make/use the figure. If a `makepdf' LaTeX
+%% macro is not defined, then it will simply assume a `XXXX.pdf' file
+%% exists in the `\bdir/tex/build/tikz' directory and simply import
+%% it. If `makepdf' is defined, then TiKZ/PGFPlot will be called to
+%% (possibly) build the plot based on `tex/XXXX.tex'. Note that if the
+%% contents of `tex/XXXX.tex' hasn't changed since the las
+%% build. TiKZ/PGFPlots won't rebuild the plot.