From 4360fbd36203022fde68b12f90548ca3a39085ce Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Tue, 27 Feb 2018 10:42:20 +0100 Subject: Copyrights and TeX management made more clear Until now, the copyright statement was left empty for the users of the pipeline to fill. However, the files have already been created and have an author (or contributing authors) before the user starts using the pipeline. So the original authors of the files are added along with the year. The user can add their own name to the existing files under the "Contributing author" when they start and they will be the "Original author" of the new files they create. Several changes were also made to the TeX management: - LaTeX is run within a `reproduce/build/tex/build' directory now. Not in the top reproduction pipeline directory. This helps keep all the auxiliary TeX files and directories in that directory and keep the top reproduction pipeline directory clean. After the final PDF is built, a copy is put in the top reproduction pipeline directory for easy viewing. - The PGFPlots preamble was also made more useful, allowing the name of the `.tex' file to also be the name of the final plot that is produced. This is a GREAT feature, because without it, the TiKZ externalization would be based on order of the plots within the paper. But now, order is irrelevant and we can even delete the TiKZ files within the processing workhorse-Makefiles so the plots are definitly rebuilt on the next run. - The paper is now in a two-column format to be more similar to published papers. A tip on debugging Make was added to `README.md'. --- Makefile | 5 +-- README.md | 17 +++++++--- configure | 5 +-- paper.tex | 20 +++++++++++- reproduce/src/make/download.mk | 5 +-- reproduce/src/make/initialize.mk | 13 ++++++-- reproduce/src/make/paper.mk | 17 +++++++--- tex/preamble-pgfplots.tex | 68 +++++++++++++++++++++++++++++++--------- tex/preamble-style.tex | 39 ++++++++++++++++++++++- 9 files changed, 156 insertions(+), 33 deletions(-) diff --git a/Makefile b/Makefile index 669b022..d409acf 100644 --- a/Makefile +++ b/Makefile @@ -1,9 +1,10 @@ # A ONE-LINE DESCRIPTION OF THE WHOLE PIPELINE # # Original author: -# Your name +# Mohammad Akhlaghi # Contributing author(s): -# Copyright (C) YYYY, Your Name. +# Your name +# Copyright (C) 2018, Your Name. # # This Makefile is free software: you can redistribute it and/or modify it # under the terms of the GNU General Public License as published by the diff --git a/README.md b/README.md index b2694ad..546b4b4 100644 --- a/README.md +++ b/README.md @@ -314,10 +314,10 @@ been explained here), please let us know to correct it. ``` - **Copyright**, **name** and **date**: Go over the following files and - correct the copyright, names and dates in their first few lines: - `configure`, `Makefile` and `reproduce/src/make/*.mk`. When making new - files, always remember to add a similar copyright statement at the top - of the tile. + add your name and email to the copyright notice: `configure`, + `Makefile` and `reproduce/src/make/*.mk`. When making new files, + always remember to add a similar copyright statement at the top of the + file. - **Title**, **short description** and **author** of project: In this raw skeleton, the title or short description of your project should be @@ -551,6 +551,15 @@ us. In this way, we can add it here for the benefit of others. $ info make "automatic variables ``` + - *Debug*: Since Make doesn't follow the common top-down paradigm, it + can be a little hard to get accustomed to why you get an error or + un-expected behavior. In such cases, run Make with the `-d` + option. With this option, Make prints a full list of exactly which + prerequisites are being checked for which targets. Looking + (patiently) through this output and searching for the faulty + file/step will clearly show you any mistake you might have made in + defining the targets or prerequisites. + - *Large files*: If you are dealing with very large files (thus having multiple copies of them for intermediate steps is not possible), one solution is the following strategy. Set a small plain text file as diff --git a/configure b/configure index cfc724e..b9548eb 100755 --- a/configure +++ b/configure @@ -3,9 +3,10 @@ # Necessary preparations/configurations for the reproduction pipeline. # # Original author: -# Your name +# Mohammad Akhlaghi # Contributing author(s): -# Copyright (C) YYYY, Your Name. +# Your name +# Copyright (C) 2018, Your Name. # # This script is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by diff --git a/paper.tex b/paper.tex index d0e14bb..d42cd7c 100644 --- a/paper.tex +++ b/paper.tex @@ -1,14 +1,32 @@ \documentclass{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 +%% not build them with TikZ in LaTeX), then comment the next line. To use +%% PDF files, they have to be in a `tikz' directory. To MAKE PDF files with +%% TikZ and PGFPlots, it is assumed that the texfile containing the source +%% are in a `tex' subdirectory relative to the directory which latex is run +%% in. +\newcommand{\makepdf}{} + %% Necessary LaTeX preambles to include for relevant functionality. We want %% to start this file as fast as possible with the actual body of the %% report, while keeping modularity in the preambles. \input{tex/pipeline.tex} \input{tex/preamble-style.tex} %\input{tex/preamble-biblatex.tex} -%\input{tex/preamble-pgfplots.tex} +\input{tex/preamble-pgfplots.tex} \input{tex/preamble-necessary.tex} + + + + + + + + + %% Start writing. \begin{document} diff --git a/reproduce/src/make/download.mk b/reproduce/src/make/download.mk index 378e5eb..9617a45 100644 --- a/reproduce/src/make/download.mk +++ b/reproduce/src/make/download.mk @@ -6,9 +6,10 @@ # script running at every instant. # # Original author: -# Your name +# Mohammad Akhlaghi # Contributing author(s): -# Copyright (C) YYYY, Your Name. +# Your name +# Copyright (C) 2018, Your Name. # # This Makefile is free software: you can redistribute it and/or modify it # under the terms of the GNU General Public License as published by the diff --git a/reproduce/src/make/initialize.mk b/reproduce/src/make/initialize.mk index 7854c2f..70d77ed 100644 --- a/reproduce/src/make/initialize.mk +++ b/reproduce/src/make/initialize.mk @@ -1,9 +1,10 @@ # Initialize the reproduction pipeline. # # Original author: -# Your name +# Mohammad Akhlaghi # Contributing author(s): -# Copyright (C) YYYY, Your Name. +# Your name +# Copyright (C) 2018, Your Name. # # This Makefile is free software: you can redistribute it and/or modify it # under the terms of the GNU General Public License as published by the @@ -91,6 +92,14 @@ $(pconfdir)/LOCAL.mk: # changes within that file and if they don't affect the pipeline. For # example a change of the top $(BDIR) name, while the contents are the same # as before. +# +# The `.SUFFIXES' rule with no prerequisite is defined to eliminate all the +# default implicit rules. The default implicit rules are to do with +# programming (for example converting `.c' files to `.o' files). The +# problem they cause is when you want to debug the make command with `-d' +# option: they add too many extra checks that make it hard to find what you +# are looking for in this pipeline. +.SUFFIXES: $(mtexdir): | $(texdir); mkdir $@ $(BDIR): | $(pconfdir)/LOCAL.mk; mkdir $@ $(texdir) $(lockdir): | $(BDIR); mkdir $@ diff --git a/reproduce/src/make/paper.mk b/reproduce/src/make/paper.mk index 0725ec8..db20279 100644 --- a/reproduce/src/make/paper.mk +++ b/reproduce/src/make/paper.mk @@ -1,9 +1,9 @@ # Build the final PDF paper/report. # # Original author: -# Your name +# Mohammad Akhlaghi # Contributing author(s): -# Copyright (C) YYYY, Your Name. +# Copyright (C) 2018, Mohammad Akhlaghi. # # This script is free software: you can redistribute it and/or modify it # under the terms of the GNU General Public License as published by the @@ -27,8 +27,15 @@ # # The commands to build the final report. We want the pipeline version to # be checked everytime the final PDF is to be built. -paper.pdf: tex/pipeline.tex paper.tex +texbdir=$(texdir)/build +tikzdir=$(texbdir)/tikz +$(texbdir): | $(texdir); mkdir $@ +$(tikzdir): | $(texbdir); mkdir $@ +paper.pdf: tex/pipeline.tex paper.tex | $(tikzdir) $(texbdir) # Make the report. - @pdflatex -shell-escape -halt-on-error paper.tex - @rm -f *.auxlock *.aux *.out *.log + p=$$(pwd); \ + export TEXINPUTS=$$p:$$TEXINPUTS; \ + cd $(texbdir); \ + pdflatex -shell-escape -halt-on-error $$p/paper.tex + cp $(texbdir)/$@ $@ diff --git a/tex/preamble-pgfplots.tex b/tex/preamble-pgfplots.tex index 13570e9..c2a7f14 100644 --- a/tex/preamble-pgfplots.tex +++ b/tex/preamble-pgfplots.tex @@ -1,33 +1,73 @@ -%% PGFPlots settings. -%% -%% PGFPlots is a package in (La)TeX for making plots internally. It fits +%% 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'). +%% 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. + -% For a tikz environment: +%% Very general TiKZ settings. In particular, to allow faster processing +%% (not having to re-build the plots on every run), we are using the +%% externalization feature of TiKZ. With this option, TiKZ will build every +%% figure independently in a special directory afterwards it will include +%% the built figure in the final file. This has many advantages: 1) if the +%% code for the plot hasn't changed, then the plot won't be re-made (can be +%% slow with detailed plots). 2) You can use the PDFs of the individual +%% plots for other purposes (for example to include in slides) cleanly. \usepackage{tikz} \usetikzlibrary{external} \tikzexternalize +\tikzsetexternalprefix{tikz/} + + + + + +%% The following rule will cause the name of the files keeping a figure's +%% external PDF to be set based on the file that the TiKZ commands are +%% from. Without this, TiKZ will use numbers based on the order of +%% figures. These numbers can be hard to manage and they will also depend +%% on order in the final PDF, so it will be very buggy to manage them. +\newcommand{\includetikz}[1]{% + \tikzsetnextfilename{#1}% + \input{tex/#1.tex}% +} -\tikzsetexternalprefix{\bdir/tex/tikz/} -%% Uncomment the following lines for EPS and PS images. Note that you -%% still have to use pdflatex and also add a `[dvips]' option to + + + +%% Uncomment the following lines for EPS and PS images. Note that you still +%% have to use the `pdflatex' executable and also add a `[dvips]' option to %% graphicx. -%\tikzset{external/system call={rm -f "\image".eps "\image".ps -%"\image".dvi; latex \tikzexternalcheckshellescape -halt-on-error -%-interaction=batchmode -jobname "\image" "\texsource"; -%dvips -o "\image".ps "\image".dvi; -%ps2eps "\image.ps"}} +%% \tikzset{external/system call={rm -f "\image".eps "\image".ps +%% "\image".dvi; latex \tikzexternalcheckshellescape -halt-on-error +%% -interaction=batchmode -jobname "\image" "\texsource"; +%% dvips -o "\image".ps "\image".dvi; +%% ps2eps "\image.ps"}} + + + + -%For drawing plots: +%% Inport and configure PGFPlots. \usepackage{pgfplots} \pgfplotsset{compat=newest} \usepgfplotslibrary{groupplots} -\pgfplotsset{axis line style={thick}, tick style={semithick}} +\pgfplotsset{ + axis line style={thick}, + tick style={semithick}, + tick label style = {font=\footnotesize}, + every axis label = {font=\footnotesize}, + legend style = {font=\footnotesize}, + label style = {font=\footnotesize} + } diff --git a/tex/preamble-style.tex b/tex/preamble-style.tex index d22354d..d794ac1 100644 --- a/tex/preamble-style.tex +++ b/tex/preamble-style.tex @@ -8,12 +8,31 @@ + + %% Print size \usepackage[a4paper, includeheadfoot, body={18.7cm, 24.5cm}]{geometry} + +%% Page using multiple columns +\usepackage{multicol} + + + + + +%% Allow using figures within the `multi-col' environment. +\newenvironment{Figure} + {\par\medskip\noindent\minipage{\linewidth}} + {\endminipage\par\medskip} + + + + + %% Set the distance between the columns if two columns: \setlength{\columnsep}{0.75cm} @@ -35,38 +54,52 @@ + + %% Color related settings: \usepackage{xcolor} \color{black} % Text color \definecolor{DarkBlue}{RGB}{0,0,90} + + + + % figure and figure* ordering correction: \usepackage{fixltx2e} + + %% For editing the caption appearence. The `setspace' package defines %% the `stretch' variable. `abovecaptionskip' is the distance between %% the figure and the caption. \usepackage{setspace, caption} -\captionsetup{font=small, labelfont={color=DarkBlue,bf}, skip=1pt} +\captionsetup{font=footnotesize, labelfont={color=DarkBlue,bf}, skip=1pt} \captionsetup[figure]{font={stretch=1, small}} \setlength{\abovecaptionskip}{3pt plus 1pt minus 1pt} + + %% To make the footnotes align: \usepackage[hang]{footmisc} \setlength\footnotemargin{10pt} + + %For including time in the title: \usepackage{datetime} + + %To make links to webpages and include document information in the %properties of the PDF \usepackage[ @@ -79,6 +112,8 @@ + + % Basic Document information that goes into the PDF meta-data. \hypersetup { @@ -90,6 +125,8 @@ + + % Title, author, pipeline info and date as they appear on the output PDF. \title{THE TITLE OF THIS PROJECT} \author{YOUR NAME, COLLEAGE1 NAME, ETC} -- cgit v1.2.1