From 0a91f0356904e95e049d4a92d6cd7116a90a3e59 Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Tue, 27 Feb 2018 15:37:59 +0100 Subject: Better comments on TeX preambles The comments in the preambles were made more clear and elaborate. --- tex/preamble-biblatex.tex | 13 +++++++------ tex/preamble-necessary.tex | 6 +++--- tex/preamble-pgfplots.tex | 38 ++++++++++++++++++++++++++++++++++---- 3 files changed, 44 insertions(+), 13 deletions(-) (limited to 'tex') 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. -- cgit v1.2.1