%% da_manual_EN.tex %% Copyright 2015 Simon M. Laube % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 % of this license or (at your option) any later version. % The latest version of this license is in % http://www.latex-project.org/lppl.txt % and version 1.3 or later is part of all distributions of LaTeX % version 2005/12/01 or later. % % This work has the LPPL maintenance status `author maintained'. % % The Current Maintainer of this work is S. M. Laube % % This work consists of the files listed in ./Help/files.txt %%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~%% %% Documentation of the etdipa-template %% %%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~%% \PassOptionsToPackage{xcolor}{dvipsnames} \documentclass[12pt,paper=a4]{scrartcl} \usepackage[utf8]{inputenc} \usepackage[naustrian,english]{babel} \usepackage[scale=0.7]{geometry} \usepackage{graphicx} \usepackage{float} \usepackage{circuitikz} \usepackage{listings} \usepackage{array} \lstset{language=[LaTeX]TeX, texcsstyle=*\ttfamily\color{red!80!black}, literate={{ß}{{\ss}}2}, basicstyle={\ttfamily\color{black}}, commentstyle=\color{green!60!black}, keywordstyle=\ttfamily\color{red!80!black}, numberstyle=\tiny\color{red}, numbers=left, captionpos=b, %otherkeywords={}, basicstyle=\footnotesize, morekeywords={\diplomand ,\breite ,\@width@dpl ,\@sep@dpl,\ifundefined, \@breite,\@default@breite,\setlength,\providecommand,{\ },{\\},\includegraphics, \responsible,\hypersetup,\tikz,\",\href,\node,\dipalistoffigures,$, \{, \}, \[, \],\includepdf,\frontmatter,\appendix,\mainmatter,\schuljahr,\professor,\maketitle,\addchap,\acro,\unterschrift,\usetikzlibrary,\includepdf, \schule,\firma, \Masse,\TikZ,\S,\D,\DS,\SD,\dipacolor,\@@eid@text,\definecolor \dipalistoffigures,\dipalistoftables,\dplversion,\ETdipaversion,\manversion,\dokumenttyp,\dipvorname,\eidname,\dankname, \definecolor,\place,\setmyheadings} } \usepackage{etdipa} \clearscrheadfoot\relax \pagestyle{empty} \pagestyle{scrheadings} \setfootsepline{.5pt} \setheadsepline{.5pt} \ohead{\today} \ihead{Simon~Michael~Laube} \ifoot{{\ttfamily etdipa} -- Manual} \ofoot{\pagemark} \title{How to use the {\ttfamily etdipa}-template \ETdipaversion} \author{Simon~Michael~Laube\\5BHET~2014/15} \date{\today} \def\TikZ{Ti\textit{k}Z} \def\addtoc#1#2{\addcontentsline{toc}{#1}{#2}} \def\nsec#1{\section*{#1}\addtoc{section}{#1}} \def\nsubsec#1{\subsection*{#1}\addtoc{subsection}{#1}} \def\nsubsubsec#1{\subsubsection*{#1}\addtoc{subsubsection}{#1}} \setlength{\parindent}{0pt} %% DIRTY TRICK :) \makeatletter \def\maketitle{% \thispagestyle{empty} \begin{figure}[H] \includegraphics[scale=1]{Images/ET_logo.jpg} \centering \end{figure} \begin{center} \Huge \bfseries\sffamily\@title\\ \vskip 1em \Large\mdseries\rmfamily\@author\\ \vskip .5em \large\mdseries\@date\\ \normalsize \rmfamily \end{center} }% \makeatother \usepackage[colorlinks=true, linkcolor=black, citecolor=green, urlcolor=blue, bookmarks=true, bookmarksopen=true]{hyperref} \begin{document} \maketitle \tableofcontents\newpage \addtocontents{toc}{\protect \large {\bfseries Part~I: Conventions \& Structure}\protect\vspace{1mm}\hrule\normalsize} \nsec{Introduction} The {\ttfamily etdipa}-package provides a simple, lightweight \LaTeX{} template for the documentation of scientific projects. It is distributed as a whole working directory for an arbitrary project\footnote{Please note that the template is optimized for the {\ttfamily scrreprt} class.}.\par The motivation for this template was to reach as many users as possible at different levels of \LaTeX{} knowledge. Nevertheless some macros are assumed as a minimum requirement and will be used without any explaination.\par\medskip The current version is \ETdipaversion{}. It is now possible to modify several colors and the title page. Further, the manual has been translated to English. For additional information please have a look at the \href{http://www.ctan.org/pkg/etdipa}{README} file or the complete \href{https://medium.com/@simon_m_laube/etdipa-offical-release-details-by-the-author-59b6d9ad104b}{project history}.\par \medskip If there are any suggested improvements, feel free to write an email using the following adress: \href{mailto:simon.laube@gmx.at}{simon.laube@gmx.at}. Please note that this email adress is not intended to be used as a source of information for the use of this template.\par\medskip \nsubsec{Acknowledgement} I would like to thank Prof. Mag. Dipl.-Ing. Dr.~Daniel~Asch and Prof. Dipl.-Ing. Dr.~Wilhelm~Haager for their help with \TeX nical questions and the supervisory of the whole project. Further, I would like to thank everyone who helped improving the template macros and documentation.\par\medskip \null\hfill -- Simon Michael Laube, \today{} -- \section{Conventions} This section is to briefly summarize the conventions made for this document.\par\bigskip \begin{tabular}{>{\bfseries}c l} Commands & are written in {\ttfamily typewriter}-font,\\ & and within a \textit{listings-} or \textit{verbatim}-environment. \\ &\\ \LaTeX{}-terms& and emphases are typeset in \textit{italics}. \end{tabular}\par\bigskip An overview of all template-specific marcos can be found in appendix~\ref{sec:befehle}.\par \section{Structure} %% ==== Ordner ==== %% \subsection{Directory structure} \begin{figure}[H] \centering \includegraphics[width=0.7\textwidth]{Images/Ordnerstruktur.pdf} \caption{Predefined directory structure of the template\newline \protect\tikz{\protect\node[rectangle,fill=blue!50!white]{};} \dots\dots master directory\newline \protect\tikz{\protect\node[rectangle,fill=yellow!70!red]{};} \dots\dots predefined subfolders\newline \protect\tikz{\protect\node[rectangle,fill=red!80!blue]{};} \dots\dots explaination} \label{pic:ordnerstruktur} \end{figure} Figure~\ref{pic:ordnerstruktur} shows the predefined directory structure. The user should use the master directory \verb|| as his working directory. All the additional files should be copied to \textit{Data, Images} and \textit{Textparts}. The \textit{Help} directory contains the template documentation and additional help files.\par\bigskip When a school or company is using this template, the given structure should not be modified for reasons of consistency. Nevertheless the users can create subfolders within the given structure. An example is given in figure~\ref{pic:unterordner}. To learn how to work with multiple \LaTeX{} files you should read section~\ref{sec:master}.\par \vspace{1mm} \begin{figure}[H] \centering \includegraphics[width=0.4\textwidth]{Images/subordner.pdf} \caption{An example for creating subfolders within the predefined directories} \label{pic:unterordner} \end{figure} \def\labelitemi{$>$} \begin{itemize} \item The \textit{Data} folder contains all the additional data that is not really needed for the documentation. This could be simulation files (e.g.: Proteus, {\scshape Spice}) as well as technical drawings (e.g.: AutoCAD, \TikZ) or circuit diagrams (e.g.: EPlan). One could also use this folder to create a separate presentation of the project -- e.g. with PowerPoint, Beamer-\LaTeX{}, Prezi or any other program. \item The \textit{Textparts} folder is the main working directory for your documentation files. It contains all the sub files of your master document. If you are unsure what a master document is, please read section~\ref{sec:master}. \item The \textit{Images} folder contains all the images of your documentation and work. Of course you do not have to include all the files in this folder into your document. \end{itemize}\bigskip The master document of your documentation is located in the master directory of the template. Thus, it is possible to include all the files from your subfolders into the master document.\par \newpage %% ==== Mastefile ==== %% \subsection{Working with master files}\label{sec:master} Normally a \LaTeX{} document consists of one {\ttfamily *.tex} file. Setting up a document that way makes sense, but if the document gets longer and longer you might loose track of all the sections and textparts. There is a special technique for large documents, which is commonly used by real \TeX{}nicians.\par \bigskip There are two cases:\par \begin{itemize} \item[$-$] The \LaTeX{} file is large, but not too large to loose track of your sections. If this is true for you, you can keep your current workflow and create only one \TeX{} file. \item[$-$] The \LaTeX{} file is very large. In this case you should split your document into separate files. \end{itemize} Since this template is for scientific documents, the second case is true. The following \textit{minimal working examples} show how to work with master and sub files.\par\bigskip \subsubsection{Standalone documents} Before someone starts to work with master documents, he/she normally works with standalone documents, which are basically all the text in one file. Listing~\ref{lst:normalesarbeiten} shows such a standalone file.\par \lstset{caption=A normal \LaTeX{} document,label=lst:normalesarbeiten} \begin{lstlisting}[ xleftmargin=.14\textwidth, xrightmargin=.14\textwidth] % documentclass / style \documentclass{article} %UTF8 encoding \usepackage[utf8]{inputenc} \begin{document} \section{Title} Here is some text. \par % end of the paragraph \end{document} \end{lstlisting} \subsubsection{Master and sub files} The first step for handling large documents is to create a so called \textit{master file}. This file contains the \LaTeX{} preamble and the start and end of the document. Listing~\ref{lst:masterfile} shows an example of a simple master file.\par \lstset{caption=A simple \LaTeX{} master file,label=lst:masterfile} \begin{lstlisting}[ xleftmargin=.1\textwidth, xrightmargin=.1\textwidth] % preamble \documentclass{article} \usepackage[utf8]{inputenc} % document starts here \begin{document} % empty for now \end{document} % document ends here \end{lstlisting} The second step is to create a \textit{sub file} that only contains text and sections, but no preamble and no start- or end-of-document command -- see Listing~\ref{lst:subfile}. Thus, this sub file could not be compiled by \TeX{}! \lstset{caption=A \LaTeX{} sub file,label=lst:subfile} \begin{lstlisting}[ xleftmargin=.1\textwidth, xrightmargin=.1\textwidth] %% file: mytext.tex \section{My text part} This is a text part of my large document.\par \end{lstlisting}\par\vspace{20mm} To finally create the complete document one has to use the \TeX{} command \verb|\input|. The argument has to be the relative path of your sub file based on the absolute path of the master file.\par Furthermore a PDF could be included via \verb|\includepdf[]{}|, but the package {\ttfamily pdfpages} needs to be included for that. The problem with PDFs is that they have to be scaled when included, otherwise the header and footer will not fit the page. \par \lstset{caption=\LaTeX{} master file with included subfiles,label=lst:fullmaster} \begin{lstlisting}[ xleftmargin=.1\textwidth, xrightmargin=.1\textwidth] % preamble \documentclass{article} \usepackage[utf8]{inputenc} \usepackage{pdfpages} % document starts here \begin{document} % my first text part % \input{mytext.tex} % my second text part % as PDF \includepdf[pages=3-5]{mypdf.pdf} \end{document} % document ends here \end{lstlisting} \addtocontents{toc}{\protect\large\protect\newpage{\bfseries Part~II: How to use the template} \protect \vspace{1mm}\hrule\normalsize} \section{How to use the macros}\label{sec:macros} In this section all functions and macros of the {\ttfamily etdipa}-template will be explained. The new commands are not part of the \LaTeX{} standard macros. Therefore, the user has to use the \verb|etdipa.sty| package to enable the template macros.\par \subsection{Title page -- {\ttfamily maketitle}} In \LaTeX{} the \verb|\maketitle| command is used to automatically create the title page from the given information. The command was redefined for this template to get a different title page look. Thus, one can simply say \verb|\maketitle| at the beginning of the document and he/she will get the template title page.\par \smallskip Listing~\ref{lst:maketitle_info} shows the necessary information that the template-user has to provide.\par \lstset{caption=Setup for the title page,label=lst:maketitle_info} \begin{lstlisting}[xleftmargin=.14\textwidth, xrightmargin=.14\textwidth] %%==== Setup for the title page ===============%% \dokumenttyp{DIPLOMARBEIT} \title{} \author{Student 1 \and Student 2} \place{<Place>} \date{<Date>} \schuljahr{<Year>} \professor{Professor 1 \and Professor 2} \dipacolor{<Color>} %%============================================%% \end{lstlisting} At the beginning of your document you should use \verb|\maketitle| to create the title page. Next to that the writer should set his name into the footer via the \verb|\responsible| command.\par \lstset{caption=Possible beginning of your document,label=lst:maketitle} \begin{lstlisting}[xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] \begin{document} \frontmatter %%============ Title page =============%% \maketitle % Author of this section \responsible{Student 1, Student 2} %%====================================%% . . . . . . . . . \end{lstlisting} \subsection{Affidavit} The affidavit can be added to your document by using a predefined environment called \textit{Eid}\footnote{German word for affidavit}. This environment automatically adds the affidavit text to your document, the only thing a user has to add is the signature line -- see listing~\ref{lst:eid}. Further, it arranges the text at the vertical middle of the page.\par \lstset{caption=How to add the affidavit,label=lst:eid} \begin{lstlisting}[xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] %%===== Affidavit =======================%% \begin{Eid} % adding the signature lines \unterschrift{Student 1} \unterschrift{Student 2} \end{Eid}\newpage %%=======================================%% \end{lstlisting} \subsection{Acknowledgement} The text of your acknowledgement should be written in an external file. Again, there is a special environment for the acknowledgement called \textit{Danksagung}\footnote{German word for acknowledgement}.\par \lstset{caption=How to add the acknowledgement,label=lst:dank} \begin{lstlisting}[xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] %% Acknowledgement \begin{Danksagung} % We would like to thank \dots \end{Danksagung} \end{lstlisting} \subsection{References} References are one of the most important things in technical documentations. They should be written in a consistent style. \LaTeX{} offers the possibility to automatically create the reference list out of an external bibliography file, but this template does not use this option to keep things a little bit simpler.\par\medskip The template uses the \LaTeX{} bibliography environment with a little modification, so the user has to do less work. Listing~\ref{lst:literatur} shows how to use the modified bibliography environment.\par \newpage \lstset{caption=References,label=lst:literatur} \begin{lstlisting}[xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] %% References \begin{Literatur} \bibitem[1] % optional number {TeXbook}% cite-key % text: {\textbf{Donald~E.~Knuth:} \emph{The \TeX{}book}. 1986, {\scshape Addison--Wesley}, ISBN-13: 978-0-201-13447-6} \end{Literatur} \end{lstlisting} The bibliography entry in listing~\ref{lst:literatur} results in entry number~\cite{TeXbook}. To refer to a reference one has to use the \verb|\cite| command.\par \lstset{caption=How to cite a bibliography entry,label=lst:zitate} \begin{lstlisting}[xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] Text~\cite{<cite-key>} % for example Text~\cite{TeXbook} \end{lstlisting} \subsection{Acronyms} The \textit{acronym} package of Tobias~Oetiker~\cite{acronym} was used to implement the list of acronyms. Since acronyms are not always necessary, the acronym environment was not modified for the template.\par \lstset{caption=List of acronyms,label=lst:abkuerz} \begin{lstlisting}[xleftmargin=.1\textwidth, xrightmargin=.1\textwidth] % List of acronyms % Add chapter to contents \addchap{Acronyms} \begin{acronym}[ACRONYM] % an entry: %{spi}[SPI]{Serial Peripheral Interface} \acro{ugs}[ugs.]{umgangssprachlich} \end{acronym}\newpage \end{lstlisting} The acronym can be used in the text by calling \verb|\ac{spi}|. At the first use the whole expansion is shown in the text, for all other cases the macro expands to the acronym.\par \subsection{Short CV -- the {\ttfamily diplomand} macro}\label{subsec:diplomand} \begin{figure}[H] \centering \diplomand{Max~Mustermann} {12.12.2012 in St.P\"olten} {XY-Street 14} {3100 St.Pölten} {\schule{2010--2015}{HTBLuVA St.Pölten, department for electrical\\ engineering} \schule{2006--2010}{Lower secondary school XY}} {max.muster@xy.at} {Images/bild} \caption{Result of the short CV command} \label{pic:diplomandenvorstellung} \end{figure}\newpage The short CV can be used to include a short employment and education history of yourself and every member of the project into the documentation. The design of the CV is based on the \LaTeX{} documentclass {\ttfamily moderncv}\footnote{This documentclass can be used to create high quality CVs in different colors and designs.} and was realized via \TikZ{}.\par \lstset{caption=How to create a short CV,label=lst:diplomandeneintrag} \begin{lstlisting}[ xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] \begin{Diplomandenvorstellung} % new CV entry \diplomand {<Name>} {<Date of birth>} {<Street and number>} {<City and Postal Code>} {<Education and employment>} {<Email>} {<Path of the picture>} \end{Diplomandenvorstellung} \end{lstlisting} Listing~\ref{lst:diplomandeneintrag} shows how to use the {\verb|\diplomand|} command. This macro uses the given data and sets up the short CV of one person. If there are more people working on the project everyone has to create a short CV. The individual CVs should be separated with \verb|\newpage|, because every CV arranges itself at the vertical middle of the page. The command also automatically sets the person's name into the footer.\par \medskip All short CVs must be written within this environment. As mentioned above they should be separated by \verb|\newpage|. The width of the short CV picture can be changed by setting it to another value via \verb|\breite|. A default value of $3\,\mathrm{cm}$ is already preset by the template package.\par \lstset{caption=Changing the picture's width,label=lst:breite} \begin{lstlisting}[ xleftmargin=.2\textwidth, xrightmargin=.2\textwidth] \breite{<Wert>} \end{lstlisting} \subsubsection{Including your previous education or work} Since version v2.4 there are two new macros that offer a better possibility to add your employment or education history to the short CV. Listing~\ref{lst:firma_schule} shows how the commands can be used.\par \lstset{caption=Adding your employment/education history,label=lst:firma_schule} \begin{lstlisting}[ xleftmargin=.11\textwidth, xrightmargin=.11\textwidth] \firma{<Period>}{<Name of your job>} \schule{<Period>}{<Name of your education/school>} \end{lstlisting} Although these commands are easy to use, the chronological order of the entries must be set by the user. Listing~\ref{lst:diplomandenvorstellung} shows the source code that was used to create figure~\ref{pic:diplomandenvorstellung}.\par \lstset{caption=An example for a short CV,label=lst:diplomandenvorstellung} \begin{lstlisting}[ xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] \begin{Diplomandenvorstellung} \diplomand{Max~Mustermann} {12.12.2012 in St.P\"olten} {XY-Street 14} {3100 St.P\"olten} {\schule{2010--2015}{HTBLuVA St.P\"olten, department for electrical\\ engineering} \schule{2006--2010}{Lower secondary school XY}} {max.muster@xy.at} {Images/bild} \end{Diplomandenvorstellung} \end{lstlisting} \subsection{Header and footer} For the setup of the header and footer the \textit{KOMA-script} package \verb|scrpage2.sty| is used. The style is defined in the template package \verb|etdipa| and should not be modified. Do not use other header-packages than \verb|scrpage2| with \verb|etdipa|, otherwise you will get warnings or errors.\par If the header does not show up in your document you may not have used the \verb|\mainmatter| or \verb|\frontmatter| command. In this case you can get the predefined style by using \verb|\setmyheadings| at the beginning of your document.\par\medskip The author of a page in the project documentation should always be listed in the footer. Therefore the \verb|\responsible| macro was defined -- see listing~\ref{lst:responsible}.\par \lstset{caption=Authors names in the footer,label=lst:responsible} \begin{lstlisting}[ xleftmargin=.2\textwidth, xrightmargin=.2\textwidth] \responsible{<Name1>, <Name2>} \end{lstlisting}\vspace{5mm} \subsection{Page and chapter numeration} Mostly documentations consist of three parts. Every part has a specific page and chapter enumeration. To toggle these numeration styles some basic \LaTeX{} commands must be used. \par\newpage \begin{enumerate} \item \textit{Frontmatter}, contains everything that is not part of your main text (e.g.: Contents, CV,\dots) \item \textit{Mainmatter}, contains your main text \item \textit{Appendix}, contains additional documents like datasheets and so on \end{enumerate}\bigskip All the necessary lists -- except for the table of contents -- are located after the appendix and therefore must be included after the appendix in your master document.\par\medskip The commands for toggling the enumeration are: \lstset{caption=Toggling the enumeration within your document,label=lst:nummerierung} \begin{lstlisting}[xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] \frontmatter % \mainmatter % \appendix % \end{lstlisting}\par \newpage \section{Basic typographical rules} Every kind of document follows some simple typographical rules. Like Till~Tantau says: ``keep it as simple as possible''~\cite[translated, page\,48--52]{TikZ}). The readers' attention should be drawn to your text, not to a confusing layout. Thus, you should know some simple rules~\cite{LaTeX}:\par \begin{enumerate} \item Hyphenations are typeset with - \hfill (\verb|-| in \LaTeX{} )\\ Domains, e.g. page numbers with ``page\,40--50'' \hfill(\verb|--| in \LaTeX{} )\\ Dashes with -- and a space before and after\footnote{That is how it is done in Europe and the UK, the USA~\cite{TeXbook, LaTeX} is using---without a space before and after the dash.} \hfill (\verb|--| in \LaTeX{} )\\ \item There should be a small space between a number and its unit. Units are never typeset in \textit{italics}.\\ e.g.: $I= 12\,\mathrm{A}$\quad\quad (\verb|$I = 12\,\mathrm{A}$|) \item Only use acronyms when they are necessary and keep it simple for the reader. \item Align and numerate long equations (in \LaTeX{} this can be obtained by the math environments \textit{displaymath, align, gather,\dots}) \item Use protected spaces that a name is never torn apart into its pieces e.g. \verb|S.~Laube| \item Use small spaces to make large numbers more readable\\ e.g.: $1.782\,135\,567$ \quad\quad(\verb|$1.782\,135\,567$|) \end{enumerate}\bigskip \subsection{Labels and referencing} Cross referencing is one of the great strenghts of \LaTeX{}. Thus, one should never write a sentence like: ``{\verb|Figure 1 shows|\dots}''. This sentence contains two mistakes. At first, \LaTeX{} uses so called \textit{labels} to get the cross references right. Second, references are always typeset with a protected space between text and number.\par A typographically correct cross reference starts when the target element is included into the document. At that point the user has to set a unique label for this element. Further, that unique label contains the number of the included element -- for example the label returns $1$ if your element is the float ``Figure 1''. \lstset{caption=Setting labels,label=lst:label} \begin{lstlisting}[xleftmargin=.2\textwidth, xrightmargin=.2\textwidth] % Sections \section{Test}\label{sec:test} % Pictures \label{pic:test} % Figures / Diagrams \label{fig:test} % Tables \label{tab:test} \end{lstlisting} All the created labels can be used within the text to refer to the desired element -- see listing~\ref{lst:referenz}.\par \medskip \lstset{caption=Correct cross referencing,label=lst:referenz} \begin{lstlisting}[xleftmargin=.2\textwidth, xrightmargin=.2\textwidth] Figure~\ref{pic:test} shows ... \end{lstlisting} \newpage \appendix \section{Packages} The following listing~\ref{lst:packages} shows all the packages that are by default loaded by the template. Thus, these packages need not be loaded by the user.\par \lstset{caption=Packages loaded by the template,label=lst:packages} \begin{lstlisting}[xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] % style \usepackage[scale=0.75]{geometry} \usepackage[automark]{scrpage2} % encoding and fonts \usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} \usepackage{textcomp} % language \usepackage[english, naustrian]{babel} % color \usepackage[dvipsnames]{xcolor} % floats \usepackage{graphicx} \usepackage{tabularx} \usepackage{listings,scrhack} \usepackage[printonlyused,withpage]{acronym} \usepackage{array} \usepackage{float} %TikZ \usepackage[europeanresistors, europeaninductors]{circuitikz} \usetikzlibrary{arrows,automata,positioning} \usepackage{pgfgantt} % math packages \usepackage{amsmath,amssymb} % others \usepackage{pdfpages} \usepackage{etdipa} \usepackage{todonotes} % hyperlinks \usepackage[colorlinks=true, linkcolor=black, citecolor=green, bookmarks=true, urlcolor=blue, bookmarksopen=true]{hyperref} \end{lstlisting}\newpage \section{Template-specific macros}\label{sec:befehle} \lstset{caption=List of all template-specific macros,label=lst:commands} \begin{lstlisting}[xleftmargin=.08\textwidth, xrightmargin=.08\textwidth] % version number \ETdipaversion % puts the author in % the footer \responsible{#1} % header and footer \setmyheadings % title page \dokumenttyp{#1} \and \professor{#1} \schuljahr{#1} \place{#1} % affidavit \unterschrift{#1} % short CV \firma{#1}{#2} \schule{#1}{#2} \diplomand{#1}{#2}{#3}{#4}{#5}{#6}{#7} \breite{#1} % colors \dipacolor{#1} ETred IForange ELyellow MBblue WIgreen % name variables \dipvorname \dankname \eidname % affidavit text \@@eid@text % environments \begin{Diplomandenvorstellung} \end{Diplomandenvorstellung} \begin{Eid} \end{Eid} \begin{Danksagung} \end{Danksagung} \begin{Literatur} \end{Literatur} %'zero' environments by Prof. Haager \begin{zeroitemize} % auch mit description und enumerate \end{zeroitemize} % lists \dipalistoffigures \dipalistoftables % additional commands \TikZ \Masse % GND Symbol (TikZ) \S % Y-connection symbol \D % delta connection symbol \DS % delta-Y connection symb. \SD % Y-delta connection symb. % TabularX-extension by Prof. Haager L / C / R % as column-type \end{lstlisting} \section{Additional information for teachers} This section is for teachers or supervisors of projects who use this template. Please read this section before you introduce the template to your students/colleagues.\par\medskip The preparation of every part of the documentation is very essential and should be done carefully. \par \subsection{Design setup} At first you should think about the look of the design you want to use. It is also possible to change the look every year or two.\par \medskip You can either save your setup as a \TeX{} file which is then included on top of the documentation -- see section~\ref{sec:master}, or you help your students/colleagues setting up the document rules.\par \subsubsection{Document type} On top of your document -- or better: in the preamble -- you need to specify the type of your documentation, for example ``project documentation'' or ``final exam project'' or something other that fits your project.\par \medskip The standard document type is set to the German word \textit{DIPLOMARBEIT}, but it can easily be changed -- listing~\ref{lst:doctype} shows how.\par \lstset{caption=Changing the document type,label=lst:doctype} \begin{lstlisting}[xleftmargin=.1\textwidth, xrightmargin=.1\textwidth] %% Set document type \dokumenttyp{DIPLOMARBEIT}% or \dokumenttyp{PROJECT DOCUMENTATION}% or \dokumenttyp{BIOLOGY PROJECT}% anything is possible \end{lstlisting} \subsubsection{Title page} A very critical part in your document is the title page. Since it is only possible to replace the title picture with the current version~\ETdipaversion{} of this template, you will have to have a look at the \LaTeX{} \textit{titlepage} environment and the \textit{maketitle} command, if you want to completely change the title page look.\par\medskip The whole document is licensed with the \LaTeX{} Project Public License, so you are allowed to modify everything -- including the documentation -- to meet your own needs. \par \bigskip \subsubsection{Colors} The color of the short CV is another thing supervisors have to worry about. This template was originally written for the upper secondary school HTL St.Pölten in Lower Austria. Thus, the five department colors of the school are predefined by the template: \begin{itemize} \item ETred \item ELyellow \item MBblue \item IForange \item WIgreen \end{itemize} If you do not want to use one of the predefined colors, you could easily define your own one, like it is shown in listing~\ref{lst:colordef}.\par \lstset{caption=Defining your own color,label=lst:colordef} \begin{lstlisting}[xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] % Color definition \definecolor{ETred}{RGB}{255,0,0} % Set the color for your CV \dipacolor{ETred} \end{lstlisting} \subsubsection{Name variables} Name variables are an essential feature of the template, since the standard names are in German. The English translation for every name variable is automatically set, if the babel option 'english' is used. Furthermore the name variables can be changed manually -- see listing~\ref{lst:names}.\par \lstset{caption=Changing name variables,label=lst:names} \begin{lstlisting}[xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] % Short CV \dipvorname{Short student introduction} % Acknowledgement \dankname{Acknowledgement} % Affidavit \eidname{Affidavit} \end{lstlisting} \subsubsection{Printing} In Austria most of the final year project documentations are printed in a one-side format. Nevertheless the twoside option is supported by the template and can be used if necessary. In case you do not know how two change this option, please have a look at listing~\ref{lst:druck}.\par \lstset{caption=The twoside option,label=lst:druck} \begin{lstlisting}[xleftmargin=.1\textwidth, xrightmargin=.1\textwidth] % twoside option enabled \documentclass[twoside,paper=a4,12pt]{scrreprt} % twoside option disabled \documentclass[paper=a4,12pt]{scrreprt} \end{lstlisting} \subsubsection{Fonts} The font for sans-serif texts was changed to be \textit{Helvetica}. All the other ones are still the \LaTeX{} default fonts.\par \subsubsection{Affidavit} To keep things simple for the user the text for the affidavit is predefined in the \verb|etdipa| package. If one would like to change the text\footnote{since this is an English manual you will have to, because the original text is written in German} he or she has to copy the \LaTeX{} source code from listing~\ref{lst:eidaendern} into the target document's preamble and add the new text for the affidavit. \par \medskip \lstset{caption=Changing the text of the affidavit,label=lst:eidaendern} \begin{lstlisting}[xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] \makeatletter \long\def\@@eid@text{ %% put your text here } \makeatother \end{lstlisting} \subsubsection{Leave a note} There is one thing I want you to do: If your school or company is using my template officially, please let me know. Just write an email with the name and city of your institution. I am not going to publish the information I get from your institution -- the purpose of this question is to get a personal list of schools/companies that use the template. Thank you in advance.\par \subsection{\TeX nical additions} \subsubsection{Definition of various dimensions} The following paragraphs explain the internal dimensions that were used to create the short CV macro \verb|\diplomand|. An optical representation of the dimensions can be seen in figure~\ref{pic:bemassungdipl}.\par \paragraph{Width of the whole CV.} The value of this dimension is set to be about two thirds of \verb|\textwidth|, namely \verb|0.6\textwidth|. This value should be appropriate for page margins up to $30\%$ -- therefore the scaling factor of the page could be lowered to $scale=0.7$. \lstset{caption=Width of the whole short CV,label=lst:ges_breite} \begin{lstlisting}[ xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] \newlength{\@width@dpl} \setlength{\@width@dpl}{0.6\textwidth} \end{lstlisting} \paragraph{Distance between picture and frame.} Another new dimension is the distance between the picture and the surrounding frame. The default distance is $1\,\mathrm{mm}$ and the default line width is \TikZ{}'s internal default value. \lstset{caption=Dimension of the frame-picture distance,label=lst:rahmenabstand} \begin{lstlisting}[ xleftmargin=.15\textwidth, xrightmargin=.15\textwidth] %Distance picture<->frame \newlength{\@sep@dpl} \setlength{\@sep@dpl}{1mm} \end{lstlisting} \paragraph{Default width of the picture.} To enable any user of this template to change the picture's width the \verb|\breite|\footnote{German word for \textit{width}} macro was defined. Listing~\ref{lst:breite_abfrage} shows how the commands and dimensions related to the picture's width were defined and how the width could be set by a user.\par\newpage \lstset{caption=Definition of the picture's width,label=lst:breite_abfrage} \begin{lstlisting}[ xleftmargin=.14\textwidth, xrightmargin=.14\textwidth] % macro definition make the % width dimension accessible \let\@breite\relax \providecommand{\breite}[1]{\gdef\@breite{#1}} % defining a default value for the width \newlength{\@default@breite} \setlength{\@default@breite}{3cm} % set the value \breite{\@default@breite} \end{lstlisting} \subsubsection{Dimensions of the short CV}\label{sec:bemassungdipl} \vspace{-10mm} \begin{figure}[H] \centering \includegraphics[width=0.8\textwidth]{Images/diplomand_erklaerung.pdf} \caption{Dimensions within the short CV} \label{pic:bemassungdipl} \end{figure} \textit{Note:} Figure~\ref{pic:bemassungdipl} is to demonstrate the relations between the different dimensions. As you may notice, there is a $\approx$ sign in there. That is because even the figure does not describe the dimensions as they really are, but it is more likely to understand the things this way.\par \newpage \def\refname{References} \phantomsection \addcontentsline{toc}{section}{\refname} \begin{thebibliography}{abcd} \bibitem[1]{TeXbook}{\textbf{Donald~E.~Knuth:} \emph{The \TeX{}book}. 1986, {\scshape Addison--Wesley},\\ ISBN-13: 978-0-201-13447-6} \bibitem[2]{LaTeX}{\textbf{Klaus~Braune, Joachim~{\&}~Marion~Lammarsch:}\\ \emph{\LaTeX{}--Basissystem, Layout, Formelsatz.} 2006, Springer Verlag,\\ ISBN-13: 978-3-540-00718-0} \bibitem[3]{TikZ}{\textbf{Till~Tantau:} \TikZ{} \emph{and {\scshape pgf}--Manual for version~1.18.} 2007,\\ {\scshape gnu} Free Documentation License, Version 1.2} \bibitem[4]{clsguide}{\textbf{The \LaTeX 3 Project:} \emph{\LaTeXe{} for class and package writers.}\\ February 2006} \bibitem[5]{fonts}{\textbf{Carl~G.~Heise:} \emph{\LaTeX{} Kurs: Schriftarten (Kurzeinführung).}\\ TU~Munich, October~2011} \bibitem[6]{tugboat}{\textbf{Peter~Flynn:} \emph{Rolling your own Document Class: Using \LaTeX{} to keep away from the Dark Side.} TUGboat, Volume 28 (2007), No. 1} \bibitem[7]{maketitle}{\textbf{Markus~Kohm:} \emph{Titelseite mit KOMA-Script.} 8.June~2011,\\ found at \url{www.golatex.de/wiki/Titelseite_mit_KOMA-Script}} \bibitem[8]{headings}{\textbf{Tanja~Richter:} \emph{Fußnoten, Kopf- und Fußzeilen in \LaTeX{}.} May~2004} \bibitem[9]{acronym}{\textbf{Tobias~Oetiker:} \emph{An Acronym Environment for \LaTeXe .} October~2010} \bibitem[10]{websites}{\textbf{Public forums:} \url{www.latex-community.org}, \url{www.mrunix.de},\\ \url{www.golatex.de}, \url{www.tex.stackexchange.com}, \url{www.texample.net}} \end{thebibliography}\bigskip The references above contain all the sources I used to create and document the {\ttfamily etdipa}-template. Furthermore they could be useful for any user of this template.\par \end{document}