Merge pull request #13 from fmilthaler/develop

Improvements on example figures/tables, README, Makefile

Also further separating specific settings for page/text layout from preamble/preamble.tex.

.gitignore

@@ -10,6 +10,10 @@
 *.lot
 *.loa
 *.toc
+*.nlo
+*.nls
+*.ilg
+*.nlo-old
 
 ######################
 # Other files        #

Makefile

@@ -71,13 +71,14 @@ nomtest:
 	    if test -s $(THESIS).nlo-diff; then \
 	      echo "diff in nomenclature found"; \
 	      make nomupdate; \
-	      rm $(THESIS).nlo-diff; \
 	    fi \
 	  else \
 	    echo "$(THESIS).nlo-old not found (or empty)"; \
 	    make nomupdate; \
 	  fi \
 	fi
+	# removing thesis.nlo-diff if it exists
+	test -f $(THESIS).nlo-diff && rm $(THESIS).nlo-diff
 
 nomupdate:index run
 	@cp -p ${THESIS}.nlo ${THESIS}.nlo-old
@@ -87,13 +88,13 @@ nomupdate:index run
 	@echo "------------------------------------------"
 
 warnings:
-	@if fgrep ${LATEXWARNING} ${THESIS}.log; then echo "+++ The following warnings were found +++"; ${FGREP} ${LATEXWARNING} ${THESIS}.log; else echo "+++ No warnings found +++"; fi
-	@if fgrep ${LATEXOFULL} ${THESIS}.log; then echo "+++ The following OVERFULL boxes were found +++"; ${FGREP} -B 1 ${LATEXOFULL} ${THESIS}.log; else echo "+++ No overfull boxes found +++"; fi
-	@if fgrep ${LATEXUFULL} ${THESIS}.log; then echo "+++ The following UNDERFULL boxes were found +++"; ${FGREP} -B 1 ${LATEXUFULL} ${THESIS}.log; else echo "+++ No underfull boxes found +++"; fi
-	@if fgrep ${LATEXBADNESS} ${THESIS}.log; then echo "+++ The following BADNESS warnings were found +++"; ${FGREP} -B 1 ${LATEXBADNESS} ${THESIS}.log; else echo "+++ No badness warnings found +++"; fi
-	@if fgrep ${LATEXMULTIPLELABEL} ${THESIS}.log; then echo "+++ FIX YOUR LABELS! Exiting +++"; ${GREP} ${LATEXMULTIPLYLABELS} ${THESIS}.log; ${FGREP} ${LATEXMULTIPLELABEL} ${THESIS}.log; fi
-	@if fgrep ${LATEXMISSCITATION} ${THESIS}.log; then echo "+++ STILL MISSING CITATIONS, FIX YOUR BIB-FILES +++"; ${FGREP} ${LATEXMISSCITATION} ${THESIS}.log; fi
-	@if fgrep ${LATEXRERUN} ${THESIS}.log; then echo "+++ Rerun ${LATEX} to get rid of some warnings +++"; fi
+	@if fgrep ${LATEXWARNING} ${THESIS}.log > /dev/null; then echo "+++ The following warnings were found +++"; ${FGREP} ${LATEXWARNING} ${THESIS}.log; else echo "+++ No warnings found +++"; fi
+	@if fgrep ${LATEXOFULL} ${THESIS}.log > /dev/null; then echo "+++ The following OVERFULL boxes were found +++"; ${FGREP} -B 1 ${LATEXOFULL} ${THESIS}.log; else echo "+++ No overfull boxes found +++"; fi
+	@if fgrep ${LATEXUFULL} ${THESIS}.log > /dev/null; then echo "+++ The following UNDERFULL boxes were found +++"; ${FGREP} -B 1 ${LATEXUFULL} ${THESIS}.log; else echo "+++ No underfull boxes found +++"; fi
+	@if fgrep ${LATEXBADNESS} ${THESIS}.log > /dev/null; then echo "+++ The following BADNESS warnings were found +++"; ${FGREP} -B 1 ${LATEXBADNESS} ${THESIS}.log; else echo "+++ No badness warnings found +++"; fi
+	@if fgrep ${LATEXMULTIPLELABEL} ${THESIS}.log > /dev/null; then echo "+++ FIX YOUR LABELS! Exiting +++"; ${GREP} ${LATEXMULTIPLYLABELS} ${THESIS}.log; ${FGREP} ${LATEXMULTIPLELABEL} ${THESIS}.log; fi
+	@if fgrep ${LATEXMISSCITATION} ${THESIS}.log > /dev/null; then echo "+++ STILL MISSING CITATIONS, FIX YOUR BIB-FILES +++"; ${FGREP} ${LATEXMISSCITATION} ${THESIS}.log; fi
+	@if fgrep ${LATEXRERUN} ${THESIS}.log > /dev/null; then echo "+++ Rerun ${LATEX} to get rid of some warnings +++"; fi
 
 spellcheck: texdirs
 	@echo "spell check on ${THESIS}.tex"

README.md

@@ -32,20 +32,21 @@ optional.
 
 ## Features
 - Supports PDFLaTeX, LuaLaTeX
-- Customised Page layouts, Header and Footer styles
+- **Customised Page layouts**, Header and Footer styles
 - A Nomenclature with subgroups
-- Examples for fancy figures (using Ti*k*Z) and Tables (using pgfplotstable), as well as support for very large tables that need to be rotated to fit on a page.
+- **Examples** of **fancy figures** (using Ti*k*Z/PGFPlots) and **tables** (using PGFPlotsTable), as well as support for very large tables that need to be rotated to fit on a page.
 - File structure to separate files of different chapters
 - A Bash script automatically includes all your `.bib` files in one file `references/references.tex`, that way you can organise and split your references across several `.bib` files without keeping track of them (without manually updating `\bibliography{...}` in your `.tex` file)
-- Besides having a good file structure, this template provides recursive use of Makefiles. The **Makefiles ensure a minimum number of compilations to resolve all changes** in references/citations, thus the Makefiles offer **similar benefits of the tool `latexmk` and they even go beyond**. **This template stands out from others due to the customised Makefiles**. They allow for (please find a more detailled description of the Makefile's targets and how to use it further below):
+- Besides having a good file structure, this template provides recursive use of Makefiles. The **Makefiles ensure a minimum number of compilations to resolve all changes** in references/citations, thus the Makefiles offer **similar benefits of the tool `latexmk` and they even go beyond**. **This template stands out from others due to the customised Makefiles**. These automate many processes with several checks in place so that **no time is wasted** on recompiling your document if it is not needed. They allow for (please find a more detailled description of the Makefile's targets and how to use it further below):
   - creating your thesis as a pdf,
-  - automatically detecting changes in references and automatically running LaTeX on your document again (only if required), until all references (in bibliography or to floating objects) are resolved.
-  - automatically detecting changes in your nomenclature (if present) and **building/updating the nomenclature if and only if changes were found**, in order to ensure **minimal compilation time**.
-  - creating separate image files (e.g. with Ti*k*Z/PGFPlots) stored in subdirectories,
-  - print out warnings from LaTeX output files,
-  - spellcheck your `.tex` files,
-  - search a pattern in all your `.tex` files (in all subdirectories) to quickly find a certain pattern,
-  - perform a word count on your document,
+  - **automatically detecting changes in references** and **automatically re-running** LaTeX on your document again (only if required), until all references (in bibliography or to floating objects) are resolved.
+  - automatically detecting changes in the nomenclature (if present) and **building/updating the nomenclature if and only if changes were found**, in order to **ensure minimal compile time**.
+  - creating separate image files (e.g. with Ti*k*Z/PGFPlots) stored in subdirectories (in order to **separate compilation of document from result plots** done in PGFPlots; depending on the complexity of your result plots, this has the potential to **drastically reduce the compile time** of your document/thesis),
+  - the structure of directories/Makefiles allows you to simply create more Ti*k*Z/PGFPlots graphics by placing their corresponding standalone LaTeX source files in the `images` subdirectories of the *chapter* directories, the `Makefile` hierachy in place automatically finds and compiles those for you,
+  - print out **warnings from LaTeX** output files,
+  - **spellcheck** your `.tex` files,
+  - **search a pattern** in all your `.tex` files (in all subdirectories) to quickly find a certain pattern,
+  - perform a **word count** on your document,
   - clean your directory (and subdirectories) from output files
 
 -------------------------------------------------------------------------
@@ -63,13 +64,21 @@ optional.
 -------------------------------------------------------------------------
 
 ### The Makefile
-As mentioned above, one of the main features of this template is the comprehensive use of recursive Makefiles. Please see a list of targets of the main Makefile (`./Makefile`) and their description below. Each target is executed on the command-line with `make <target-name>`.
+As mentioned above, one of the main features of this template is the comprehensive use of recursive Makefiles.
+
+Each target is executed on the command-line with `make <target-name>`.
+
+The most frequently used - and the once you should definitely know about - targets are:
+- `thesis`: this target compiles your main document `thesis.tex`, it also runs through BibTeX to sort out your bibliography. Moreover, it automatically detects changes in references/labels/citations and recompiles your target if required in order to resolve those changes. It does expect all images included in the document to be present (see target `imagedirs` below). Finally, it automatically detects a nomenclature, and if so, it also detects if changes were made to it. If both criteria are satisfied, the document is automatically updated to reflect the changes in the nomenclature.
+- `fullthesis`: in case of you separating the compilation of some plots/graphics from your main document (in order to save compile time), those Ti*k*Z graphics/PGFPlots need to be compiled (*before* you run `make thesis` and obviously every time you make changes to those graphics/plots. `fullthesis` invokes another target called `imagedirs` that takes care of thos graphics/plots. It compiles all standalone `texfiles` resulting in `.pdf` files in subdirectories `images`. Those `pdf` files can then be included in the main document. After that step, `fullthesis` invokes `thesis` to compile the main document.
+
+For those who want to know more, and might want to make some changes to the `Makefile`, here is a more detailled and technical description of all targets:
 - `ref`: executes the target `references` in `./references/Makefile`, which in turn executes the bash script `./references/create_bib_list.sh` which collects the names of all `.bib` files in `./references/` and includes them in a newly created file `./references/references.tex`. This can be included in your main LaTeX file (here: `thesis.tex`); example: imagine you have *A.bib*, *B.bib*, *C.bib* in the directory `./references/`, `make ref` creates `./references/references.tex` which has the following LaTeX command in it: `\bibliography{references/A,references/B,references/C}`. **Note:** Do not manually edit `references/references.tex` as it is automatically overwritten by the script every time you compile your thesis.
 - `run`: runs LaTeX (by default: `pdflatex`) on `thesis.tex`; all required files, such as image files are required/expected to be in place, otherwise this operation will fail.
 - `bib`: first executes `ref`, then: if `thesis.aux` does not exist, it executes `run`, followed by BibTeX (`bibtex thesis`)
 - `index`: executes `makeindex ${THESIS}.nlo -s nomencl.ist -o ${THESIS}.nls`, required for building a nomenclature.
-- `thesis`: first it executes `run`, `bib`, and `nomtest` in that order; then the logfile `thesis.log` is scanned for references of missing/changed citations, multiple/changed labels, and rerun suggestions, and executes `run` at each check of the logfile; finally, after having finished the checks and reruns, it prints out the warnings LaTeX provides in its logfile by executing `make warnings` (see below)
-- `imagedirs`: executes the target `all` in each subdirectory defined in `IMAGEDIRS` (this variable is defined in this Makefile); this is useful if some images are done with Ti*k*Z/PGFPlots, thus you can create standalone pdf files (which are vector graphics) of your Ti*k*Z/PGFPlots graphics that you then include in your main LaTeX document. This target `imagedirs` allows you to compile all of these graphics to be compiled on the fly. **Note:** This step is beneficial if you are using PGFPlots to read in lots of data points from data files to create a beautiful plot of your results. This process can take some time, hence you do not want this to be processed every time you change the text in your thesis. As the standalone `.pdf` graphic is a vector graphic, you do not loose quality.
+- `thesis`: first it executes `run`, `bib` and `nomtest` in that order; then the logfile `thesis.log` is scanned for references of missing/changed citations, multiple/changed labels, and rerun suggestions, and executes `run` at each check of the logfile; finally, after having finished the checks and reruns, it prints out the warnings LaTeX provides in its logfile by executing `make warnings` (see below)
+- `imagedirs`: executes the target `all` in each subdirectory defined in `IMAGEDIRS` (this variable is defined in this Makefile); this is useful if some images are done with Ti*k*Z/PGFPlots, thus you can create standalone `pdf` files (which are vector graphics) of your Ti*k*Z/PGFPlots graphics that you then include in your main LaTeX document. This target `imagedirs` allows you to compile all of these graphics to be compiled on the fly. **Note:** This step is beneficial if you are using PGFPlots to read in lots of data points from data files to create a beautiful plot of your results. This process can take some time, hence you do not want this to be processed every time you change the text in your thesis. As the standalone `.pdf` graphic is a vector graphic, you do not loose quality.
 - `fullthesis`: executes `allclean`, `imagedirs`, `ref`, `thesis` in that order; basically it removes all previous output files (in this and subdirectories) and builds your thesis from scratch (including graphics, e.g. Ti*k*Z/PGFPlots graphics as explained above)
 - `nomtest`: checking if there were changes made on the nomenclature the last time the main document was compiled. If so, it executes `make nomupdate`. **Note**: this target ensures a minimal number of LaTeX compilation neccessary to build/update the nomenclature.
 - `nomupdate`: executes `index` and `run` in that order. Gets triggered when `nomtest` found changes in the nomenclature and makes sure the changes are updated in the document.
@@ -89,7 +98,8 @@ See a list and short description of directories and files in this repository to
 + `common.mk` (some variable definitions that are used in Makefiles)
 + `thesis.tex` (main `.tex` file of your document that you run through `pdflatex`/`lualatex`, this file consists mainly of `\input{<filename>}` commands to include the content of your thesis).
 + `preamble/` (files that set up the layout of your thesis and include LaTeX packages are in here)
-  + `preamble.tex` (contains documentclass, usepackage commands and defines page layout)
+  + `preamble.tex` (contains documentclass, usepackage commands)
+  + `layout.tex` (defines overall page/text layout, chapter title layout)
   + `fancyheaders.tex` (defines custom header/footer styles using `fancyhdr`)
   + `loadlistings.tex` (some definitions for printing code)
   + `myinformation.tex` (commands for your name, title, university, etc)
@@ -111,10 +121,10 @@ See a list and short description of directories and files in this repository to
   + `quote.tex` (optional: include a quote of your choice)
 + `references/` (.bib files go in here with all the articles/books you like to reference)
   + `Makefile`
+  + `create_bib_list.sh` (bash script: automatically generates a `.tex` file that includes all present `.bib` files, just put all your `.bib` files in this directory, rest is done automatically)
   + `books.bib`
-  + `Theses.bib`
   + `futuristic_and_mystical.bib`
-  + `create_bib_list.sh` (bash script: automatically generates a `.tex` file that includes all present `.bib` files, just put all your `.bib` files in this directory, rest is done automatically)
+  + `Theses.bib`
 + `content/` (this is the main part of your thesis, chapters and supporting data files/plots should go in subdirectories of this one)
   + `introduction/`
     + `Makefile`
@@ -124,32 +134,49 @@ See a list and short description of directories and files in this repository to
     + `main.tex` (text for this chapter)
     + `images/` (subdirectory that contains files for images/figures)
       + `Makefile`
-      + `fem_basis_function_linear_cg.tex`
-      + `fem_basis_function_constant_dg.tex`
-      + `1way_coupling_prescribed_rotation.tex`
+      + `fem_basis_function_linear_cg.tex` (example of a (standalone) simple Ti*k*Z graphic)
+      + `fem_basis_function_constant_dg.tex` (example of a (standalone) simple Ti*k*Z graphic)
+      + `rotation_example.tex` (example of a (standalone) fancy Ti*k*Z graphic)
     + `table-data/` (subdirectory for `.csv` files that are used for tables)
+      + `scientists.csv` (example data file)
     + `python/`
       + `example_code.py` (python code that is printed as it is)
   + `reschap2/` (2nd main/result chapter)
     + `Makefile`
     + `main.tex` (text for this chapter)
     + `images/` (subdirectory for plots/images/pictures etc.)
+      + `Makefile`
+      + `2d_flow_past_cylinder_test_combinations.tex` (example of a (standalone) fancy Ti*k*Z graphic)
+      + `domain_3d_flow_past_sphere.tex` (example of a (standalone) fancy Ti*k*Z graphic)
+      + `velocity-x_interp_0-01.tex` (example of a (standalone) PGFPlots plot)
+      + `velocity-x_interp_0-001.tex` (example of a (standalone) PGFPlots plot)
+      + `data/` (subdirectory for data files for PGFPlots)
+        + `bounded_interp_0-01.csv` (example data file)
+        + `bounded_x_0-1_interp_0-0001.csv` (example data file)
+        + `boundeddg_interp_0-01.csv` (example data file)
+        + `boundeddg_x_0-1_interp_0-0001.csv` (example data file)
+        + `void_interp_0-01.csv` (example data file)
+        + `voiddg_interp_0-01.csv` (example data file)
     + `table-data/` (subdirectory for `.csv` files that are used for tables)
       + `scientists.csv` (example data file)
   + `reschap3/` (3rd main/result chapter)
     + `Makefile`
     + `main.tex` (text for this chapter)
+    + `parallel_efficiency_table.tex` (`.tex` file that includes a PGFPlotsTable, file is called by `main.tex`)
     + `images/` (subdirectory for plots/images/pictures etc.)
+      + `Makefile`
+      + `pgfplot_texfile_parallel_efficiency.tex` (example of a (standalone) PGFPlots plot)
     + `table-data/` (subdirectory for `.csv` files that are used for tables)
-      + `pgfplotstable.example1.dat` (example data file)
+      + `parallel_efficiency_data.pgfdat` (example data file)
+      + `pgftablesettings_parallel_efficiency_table.tex` (example file for PGFPlotsTable settings)
   + `conclusion/` (files for the summary, conclusion, future work should go in here)
     + `Makefile`
-    + `summary.tex`
-    + `conclusion.tex`
-    + `future_work.tex`
+    + `summary.tex` (text for your summary)
+    + `conclusion.tex` (text for your conclusion)
+    + `future_work.tex` (text for future work)
   + `appendix/` (if you need one, the appendix is set up in here)
     + `Makefile`
-    + `appendix.tex`
+    + `appendix.tex` (text for your appendix)
 
 -------------------------------------------------------------------------
 

abstract/abstract.tex

@@ -1,3 +1,3 @@
 \chapter*{Abstract}
 
-\blindtext
+\lipsum[1-2]

abstract/acknowledgements.tex

@@ -2,4 +2,4 @@ \chapter*{Acknowledgements}
 
 Your acknowledgements.
 
-\blindtext[3]
+\lipsum[1]

content/appendix/appendix.tex

@@ -1,2 +1,2 @@
 \section{Some additional stuff}
-\blindtext
+\lipsum

content/introduction/introduction.tex

@@ -1 +1,3 @@
 A nice introduction.
+
+\lipsum[1-3]

content/reschap1/main.tex

@@ -7,7 +7,7 @@ \section{Some Notes on Figures}
 Example of including programming code is shown in Program \ref{prog:some_program_label} on page \pageref{prog:some_program_label}.
 
 \section{More text}
-\blindtext
+\lipsum[1-3]
 
 \begin{figure}[p]
  \centering
@@ -18,8 +18,8 @@ \section{More text}
 
 \begin{figure}[p]
  \centering
- \includegraphics[scale=0.75]{content/reschap1/images/1way_coupling_prescribed_rotation}
- \caption[Schematic]{Schematic of a rotation}
+ \includegraphics[scale=0.75]{content/reschap1/images/rotation_example}
+ \caption{Schematic of a rotation}
  \label{fig:rotation_schematic}
 \end{figure}
 
@@ -31,7 +31,7 @@ \section{More text}
  \hfill
  \subcaptionbox{Basis function (constant DG).\label{subfig:basis_fun_dg}}{\fbox{\includegraphics[width=0.45\textwidth]{content/reschap1/images/fem_basis_function_constant_dg}}}
 %
- \caption[Figure caption to appear in \textsl{List of Figures}]{Figure caption to appear below the figure.}
+ \caption{Basis functions}
  \label{fig:basis_functions}
 \end{figure}