LaTeX Boilerplate

summary

LaTeX Boilerplate is for those starting a project or more experienced users who want an organized structure to their documents. All code (e.g. \newcommand, pgfkeys) and packages included are commented. The boilerplate contains examples for common tasks: figures, tables, BibTeX, index, new commands (including some using pgfkeys), and more.

A GitHub repository can be found at: LaTeX Boilerplate. I briefly explain the layout; installation and usage can be found in the repository readme.

For those who want to dive right in, the git repository (includes a readme):

LaTeX_Boilerplate
Intro

Creating a LaTeX project from scratch can be a headache, a lot of time is wasted figuring out the basic code and styles LaTeX needs to happily typeset your document. Also, unifying formatting for chapters, figures, etc. is not obvious to the beginner. In addition, large projects can become unwieldy and bogged down when the entire text is located in one file. And making sure that when you add or remove citations things don't go haywire can be a pain if not done properly.

Luckily, LaTeX includes solutions to all of these problems: functions to standardized common formatting, an include feature to manage sections sensibly, BibTeX for citation management, and other useful features. I have compiled a skeleton LaTeX project (a boilerplate) that allows the beginner (or even more advance user) to start a project quickly and with the proper groundwork. HTML5 Boilerplate is a great example of this sort of thing.

The ever useful pandoc should be downloaded. I included some batch files that can be used to convert common file formats into something a LaTeX compiler can read, e.g. you might want to take HTML files and turned them into LaTeX, as I do with my short stories. Bash scripts are forthcoming.

Main

The main project file is laid out to include packages, header/footer, and new commands first. This is followed by changing the font size to an appropriate amount (I use 12pt text with 15pt line spacing, see The Elements of Typographic Style). The title page is included along with thanks and a table of contents. The different sections, chapters, figures, and tables are included in separate .tex files to make project management easier.

References (bibtex) and index (makeidx) are included last under the appendix. Examples for their usage are sprinkled throughout the example figures and chapters.

Building the project has been made independent of specific editors by including batch (build.bat) and bash (build.sh) scripts to automatically build and clean-up the directory afterwards (e.g. removing .aux files), assuming you install some LaTeX distribution with pdflatex, xelatex, makeidx and bibtex that are included in the system PATH and callable via the command line.

LaTeX
  1. %_______PREAMBLE_______
  2. %Include packages
  3. \include{common/packages}      
  4. %Include packages
  5. \include{common/header}
  6. %Get macro commands
  7. \include{common/codes} 
  8. %Meta information to put in PDF
  9. \hypersetup{pdfauthor={Author},pdftitle={Title},pdfsubject={Space},pdfkeywords={Space}}
  10. %_______DOCUMENT_______
  11. \begin{document}       
  12.         %Change font size and line spacing
  13.         %12pt font with 15pt spacing default   
  14.         \fontsize{12}{15}\leading{15pt}
  15.         %_______TITLE_______
  16.         \begin{titlepage}      
  17.                 \lbptitle{Title}{Subtitle}{Author}{}
  18.         \end{titlepage}
  19.         \pagenumbering{roman}  
  20.         %_______MISC_______
  21.         %Copyright and Thanks
  22.         \include{common/thanks}        
  23.         %_______TABLE_OF_CONTENTS_______
  24.         \tableofcontents
  25.         %Change to 1,2,3...
  26.         \pagenumbering{arabic} 
  27.         %_______MAIN_TEXT_______
  28.         %Part of book
  29.         \lbppart{Part I}{Subtitle}
  30.                 %Include section page
  31.                 \include{sections/section1}
  32.                         %Include introduction
  33.                         \include{chapters/chapter1}
  34.                         \include{chapters/chapter2}
  35.         %The end section page
  36.         \lbpendsection{End of Preview}{We've only just begun\dots}
  37.         %_______APPENDIX_______
  38.         \include{sections/appendix}
  39.                 %Input will insert to code directly, no new page
  40.                 \input{chapters/table}
  41.                 \input{chapters/figures}
  42.                 %_______BIBLIOGRAPHY_______
  43.                 \include{citations/references}
  44.                 %_______INDEX_______
  45.                 \input{citations/index}
  46. %_______
  47. \end{document}
BibTeX

One main advantage of LaTeX over Word or other processors is the bibliography feature. Using a plain-text file, one can add and comment all their references for a particular project. Because the default setting for bibtex is to include only references you actually cite, this allows you to build a library of references that you can call upon for different projects and not have to worry about improper citations.

The default style in the project is to number, subscript, and order (e.g. when you have multiple citations, will appears as 1-3,10 instead of 10,1,3,2) the citations. This style can easily be changed by altering \usepackage[numbers,super,sort&compress]{natbib} in \common\packages.tex.

An example entry is seen below, most bibtex citations can be automatically obtained from the web on a publication's website or on search engines like Google Scholar or Pubmed (using TeXMed).

More information cab be found at BibTeX.

LaTeX
  1. \usepackage[numbers,super,sort&compress]{natbib}
  2. Lorem impsum \citep{Febre:2005}
BibTeX
  1. @book{Febre:2005,
  2.         author = {Alain Fabre},
  3.         title = {Diccionario etnolingüístico y guía bibliográfica de los pueblos indígenas sudamericanos},
  4.         publisher = {Geoprojects},
  5.         volume = {},
  6.         number = {},
  7.         series = {},
  8.         address = {Beirut, Lebanon},
  9.         edition = {},
  10.         year = {2005},
  11.         month = {},
  12.         isbn = {},
  13.         note = {\url{butler.cc.tut.fi/~fabre/BookInternetVersio/Dic=Tupi.pdf}},
  14. }
Index

The index feature allows the easiest way to track particular words or concepts the reader might want to find throughout the text. It is automatically alphabetized and the index itself can be customized by renewing the environment (example included in \common\codes.tex).

I created the command \lbpindex{}{} to allow a standard input for all indexed words and concepts so if the package or layout changes, I don't have to change every command throughout a project. Subentries can be created using \index{entry!subentry}. More information can be found at LaTeX indexing with an example index found at the end of project.pdf in the git repository.

LaTeX
  1. \usepackage{makeidx}
  2. \clearpage
  3. \addcontentsline{toc}{chapter}{Index}
  4. \printindex
LaTeX
  1. Lorem ipsum \index{Lorem ipsum}{} dolor sit...
  2. We start with the Algonquin and then discuss the \lbpindex{Cahokia}{}...
Functions

Next, pgfkeys is used together with \newcommand to help get around the nine argument limit of \newcommand. This allows us to make standard formatting for a multi-figure panel, as seen below.

This is accomplished by loading a set of keys (see \pgfkeys) that map input variables in the \multifig[var=something] command to variables \newcommand can use (e.g. \figvar).

LaTeX
  1. %Example of multi-panel figure
  2. \multifig[
  3.         label=11,
  4.         capTitle=Early native American staples,
  5.         capDes={(a) Pueblo bonito was an.... (b) Located in Peru. (c) The different type of game hunted in the Americas. (d) The cenote, which were seen as sacred by the Maya.}
  6. ]{fig}{images/pueblobonito.jpg}{fig}{images/chavin.jpg}{fig}{images/nagame.jpg}{fig}{images/cenote.jpg}
LaTeX
  1. %_______Multi_Panel_Figure_______
  2. %Keys loaded when pgfkeys is called
  3. \pgfkeys{
  4.         %Call with \pgfkeys{/family, #1}
  5.         %Define a family directory to avoid name-clashes
  6.         /multifig/.is family, /multifig,
  7.         %key/.estore in = \newVariable
  8.         label/.estore in = \mfigLabel,
  9.         capTitle/.estore in = \mfigCapTitle,
  10.         capDes/.estore in = \mfigCapDesc,
  11. }
  12. %Create a new figure command
  13. \newcommand\multifig[9][]{
  14.         %command looks like \multifig[key=val,...]{panelTitle}{imageLocation}..
  15.         %example:
  16.         %First arg ([key=val,...]) passed to pgfkeys, get new variables back, circumvent the 9 argument rule for \newcommand
  17.         \pgfkeys{/multifig, #1}
  18.         \begin{figure*}[ht!]
  19.         \begin{center}
  20.                 \subfloat[#2]{\includegraphics[width=3.0in]{#3}}  
  21.                 \subfloat[#4]{\includegraphics[width=3.0in]{#5}} \\
  22.                 \subfloat[#6]{\includegraphics[width=3.0in]{#7}}
  23.                 \subfloat[#8]{\includegraphics[width=3.0in]{#9}}
  24.                 \captionsetup{labelformat=empty}
  25.                 \caption{\textbf{Figure \ref{fig:\mfigLabel} |  \mfigCapTitle}\\ \mfigCapDesc}
  26.                 \label{fig:\mfigLabel}
  27.         \end{center}
  28.         \end{figure*}  
  29. }
Conclusion

The main thrust for the project was to provide myself an evolving standard for LaTeX documents, as starting from scratch or trying to remember which project had the most up-to-date working skeleton was inefficient. However, sharing the project will hopefully allow others to gain use from it and induce me to keep it updated and well organized. In the future, I plan to flesh out the project to include more working examples and clean-up the code to make it more consistent and better commented. As the project evolves, I'll post more.

-biafra

comments

comments powered by Disqus

©2006-2017 | biafra ahanonu | updated 19 june 2017
biafra ahanonu