Skip to content
This repository has been archived by the owner on Nov 19, 2020. It is now read-only.

Files

Latest commit

e9ff6a4 · Aug 17, 2020

History

History
841 lines (619 loc) · 45.6 KB

writing.md

File metadata and controls

841 lines (619 loc) · 45.6 KB

Writing

Documentation and general tips and tricks on how to write an academic text assignment for the DBHW-VS.

The udhbwvst class

The name of the class stands for Unofficial DHBW Villingen-Schwenningen LaTeX template. Despite what the name suggests this class isn't a template anymore but a solid LaTeX class which can be build upon.

Class options

Option Default Description
auto-generate true Generates all required pages around the text.
debug false Loads packages lipsum and blindtext and displays hyperref-links.
print-ndn true Prints the non-disclosure notice.
print-loa true Prints the list of acronyms.
print-lof true Prints the list of figures.
print-lot true Prints the list of tables.
print-lol true Prints the list of code listings.
bib-file literature.bib Path to the bibliography file.
plantuml false Loads the plantuml package.
title-style default Loads the specified title page style. Available options: default, modern.
font-size 12pt Sets the base font size.
abstract-file - Path to an abstract tex file to be included.

Required \dhbwSetup command

In order to use the template you have to run the \dhbwSetup{...} command in your preamble. All parameters inside parentheses are optional. You can access any key inside your document with the \dhbwGet* commands.

Parameter Stored in Default Description Example
author \dhbwGetAuthor - Full name of the author. Max Mustermann
faculty \dhbwGetFaculty - Faculty of the author. Wirtschaft
field of study \dhbwGetFieldOfStudy - Field of study of the author. Wirtschaftsinformatik
(academic year) \dhbwGetAcademicYear - Academic year of the author. 2017
(course) \dhbwGetCourse - Course of the author. B
title \dhbwGetTitle - Title of the text. Eine Arbeit
(subtitle) \dhbwGetSubtitle - Subtitle of the text Mit einem Untertitel
text type \dhbwGetTextType - Type of the text. Projektarbeit 2
company name \dhbwGetCompanyName - Name of the authors employer. Eine GmbH
(company logo) \dhbwGetCompanyLogo - Path to the logo of the authors employer. ./assets/logo.png
lecturer \dhbwGetLecturer - Name of the lecturer of the author. Prof. Dr. Martin Kimmig
(location) \dhbwGetLocation Villingen-Schwenningen Name of the location where the author signs the independence notice. Villingen-Schwenningen
(date) \dhbwGetDate \today When the author signs the independence notice. 21. August 2019

Document structure \dhbw* commands

If you set the class option auto-generate to false you can use following commands to build a custom document:

Command Description
\dhbwSetFrontMatter Sets up formatting for front pages.
\dhbwPrintTitle Prints the title page.
\dhbwPrintNonDisclosureNotice Prints the non-disclosure notice if the class option print-ndn is set to true.
\dhbwPrintAbstract Prints the abstract if a file path was given to udhbwvst as a class option.
\dhbwPrintTableOfContents Prints the table of content.
\dhbwSetListMatter Sets up formatting for the list pages.
\dhbwPrintListOfAcronyms Prints the list of acronyms if the class option print-loa is set to true.
\dhbwPrintListOfFigures Prints the list of figures if the class option print-lof is set to true.
\dhbwPrintListOfTables Prints the list of tables if the class option print-lot is set to true.
\dhbwPrintListOfListings Prints the list of code listings if the class option print-lol is set to true.
\dhbwSetMainMatter Sets up formatting for the main text pages.
\dhbwPrintBibliography Prints the bibliography.
\dhbwPrintIndependenceNotice Prints the independence notice.
\dhbwPrintEverythingBefore Prints all pages and sets up all formatting before the main text.
\dhbwPrintEverythingAfter Prints the bibliography and the independence notice.
\dhbwAppendix Creates a new appendix.

More \dhbw* commands

Command Description
\dhbwSetFontArial Sets the font to Arial. Make sure that Arial is installed as a system font. Should be called in your preamble.
\dhbwSetFontTimesNewRoman Sets the font to Times New Roman. Make sure that Times New Roman is installed as a system font. Should be called in your preamble.
\dhbwSetOneHalfLineSpacing Sets the line spacing to Microsoft Words interpretation of 1.5 line spacing.

Sectioning

Sections and subsections are automatically numbered and added to the table of contents in order of appearance. Use \section*{title}, \subsection*{title} and \subsubsection*{title} to add unnumbered sections which don't appear in the table of contents.

You can add a marker to a section using \label{sec:marker} to be able to refer to it later.

You can manually add unnumbered sections to the table of contents using the \addcontentsline command.

Sections

Command: \section{title}

Parameter Description
title The title of the section.

Adds a new numbered section to the text and the table of contents. Example below:

...this is the last sentence of the previous section.

\section{The title of the next section}

The first sentence in the next section...

Subsections

Use \subsection{title}, \subsubsection{title} and \paragraph{title} to create subsections below a section, subsubsections below a subsection and subsubsubsections below subsubsections. Use the label subsec: to mark a subsection.

Example below:

...this is the last sentence of the previous section.

\section{The title of the next section}

The first sentence in the next section...

\subsection{The title of my subsection}

The first sentence in this subsections...

\subsubsection{The title of my subsubsection}\label{subsec:somelabel}

Nobody reads this anyway...

\paragraph{The title of my subsubsubsection}

We're here in \autoref{subsec:somelabel}.
And yes, nobody reads the docs...

Use \setcounter{tocdepth}{4} in your preamble if paragraphs should be listed in the table of contents.

Sections / Subsections should always have a least two childs!

Citing

Every cite command will add the referenced bibliography entry to the bibliography at the end of the text.

Cite with footnote

Command: \footcite[prenote][page]{bibEntryId}

Parameter Description
bibEntryId The identifier of the entry in the bibliography.
prenote A prenote that will appear in front of the short reference (Usually Vgl.). Optional.
page The number of the page you are citing from. Optional.

Adds a footnote with given bibEntryId, prenote and page. Example below:

A Hitchhiker’s Guide To The Galaxy PDF by Adam Douglas
is a timeless science fiction masterpiece.\footcite[Vgl.][42]{hitchhiker78}
This is the next sentence...

A footnote is always followed by a blank space. Use \unskip to suppress this blank space. Use case:

This is a sentence (with some thing to footcite
in parentheses\footcite[Vgl.][42]{hitchhiker78}\unskip) in the middle of the sentence.

Cite direct with footnote

Command: \dfootcite[page]{bibEntryId}{text}

Parameter Description
bibEntryId The identifier of the entry in the bibliography.
text The text you want to cite directly.
page The number of the page you are citing from. Optional.

Wraps given text in and " and adds a footnote with given bibEntryId and page. Example below:

...so thats why a \dfootcite[42]{hitchhiker78}{towel is the most
important item a Hitchhiker can carry}.

This is just a wrapper using \footcite and \enquote from the CTAN package csquotes.

Cite indirect with footnote

Command: \ifootcite[page]{bibEntryId}

Parameter Description
bibEntryId The identifier of the entry in the bibliography.
page The number of the page you are citing from. Optional.

Adds a footnote with given bibEntryId, page and the prenote Vgl.. Example below:

A Hitchhiker’s Guide To The Galaxy PDF by Adam Douglas
is a timeless science fiction masterpiece.\ifootcite[42]{hitchhiker78}
This is the next sentence...

This is just a wrapper using \footcite.

Cite without footnote

Command: \cite[prenote][page]{bibEntryId}

Parameter Description
bibEntryId The identifier of the entry in the bibliography.
prenote A prenote that will appear in front of the short reference (Usually Vgl.). Optional.
page The number of the page you are citing from. Can be empty. Optional.

Creates a short reference with given bibEntryId, prenote and page where the command is called. Example below:

Here is a short reference: \cite[Vgl.][42]{hitchhiker78}

Cite indirect without footnote

Command: \icite[page]{bibEntryId}

Parameter Description
bibEntryId The identifier of the entry in the bibliography.
page The number of the page you are citing from. Can be empty. Optional.

Creates a short reference with given bibEntryId, page and prenote Vgl. where the command is called. Example below:

Here is a short reference: \icite[42]{hitchhiker78}

This is just a wrapper using \cite.

Acronyms

This template uses the acro CTAN package which sorts acronyms by their ID automatically! Have a look at it's documentation for details on advanced usage.

Define a new acronym

Before you can use an acronym in your text you have to define it in your preamble (below the \dhbwSetup command).

\dhbwSetup{%
    ...
}

\DeclareAcronym{PDF}{%
    short     = PDF,
    long      = Portable Document Format
}

If you don't specify the short field the ID will be used as short.

Define a custom plural

The acro package adds an s to the short and long version of an acronym if no custom plural is defined. There are many cases when adding an s doesn't work. See the german example below:

\DeclareAcronym{GF}{%
    short               = GF,
    short-plural-form   = GF,
    long                = Globale Firma
    long-plural-form    = Globale Firmen
}

Using acronyms in text

Commands: \ac{acronym} (singular) and \acp{acronym} (plural)

The acro package will make sure that first time an acronym is used it will be defined with the long version inline!

The \acp{acronym} command will add an s to the acronym if no custom plural was defined.

\ac{NiP} was the first professional esports team to launch our own gaming peripheral
company, Xtrfy. \ac{NiP} is also active in the space of education within the esports
industry through several initiatives. In addition to this, \ac{NiP} is also an active
shareholder in the clothing company DRKN.

The example above will translate to:

NiP (Ninjas in Pyjamas) was the first professional esports team to launch our
own gaming peripheral company, Xtrfy. NiP is also active in the space of
education within the esports industry through several initiatives. In addition
to this, NiP is also an active shareholder in the clothing company DRKN.

⚠ You always have wrap your acronyms in one of the commands above in order for the acro package to work correctly.

Using hyphens

There are different hyphens for different occasions:

  • "= Hyphen with automatic separation before and after.
  • "- Separation point, in case of separation, hyphen is inserted as usual.
  • "" Separation point, nothing is inserted in case of separation.

Read more about it here.

Figures

All figures will be automatically numbered and added to the list of figures.

The dhbwfigure environment

When adding a figure you should wrap it inside the dhbwfigure environment so that the DHBW formatting requirements are met automatically.

\begin{dhbwfigure}{caption=Pikachu,label=fig:pikachu,source={Internet People}}
    \includegraphics[width=\textwidth]{surprised_pikachu.png}
\end{dhbwfigure}

The dhbwfigure environment parameters caption and label are mandatory. See all possible parameters below:

Parameter Default Description
caption - Title of the figure.
label - Marker for hyperref. Make sure to start your marker with fig: so that automatic referencing works. This marker has to be unique.
float ht Floating specifier.
source Eigene Darstellung Source of the picture.

The \dhbwFigure command

If you only want to quickly embed an image file you can use the \dhbwFigure command:

\dhbwFigure{caption=Pikachu,label=fig:pikachu,path=surprised_pikachu.png}

The parameters caption, path and label are required. See a full list of available parameters below:

Parameter Default Description
caption - Title of the figure.
path - Path to the image.
label - Marker for hyperref. Make sure to start your marker with fig: so that automatic referencing works. This marker has to be unique.
source Eigene Darstellung Source of the picture.
width \textwidth Width of the figure.
float ht Floating specifier.

\dhbwFigure is like the dhbwfigure environment with integrated \includegraphics command.

The \dhbwWrapfigure command

If you want to embed a small graphic wrapped by your text you can use the \dhbwWrapfigure command which uses the wrapfigure environment from the wrapfig CTAN package.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis condimentum
lacus quis nisi pulvinar, sed bibendum neque posuere. Nam ipsum nisl,
egestas at lectus vel, suscipit hendrerit mi. Sed dapibus fermentum mauris,
ut euismod leo vehicula ut. Mauris bibendum imperdiet nunc.

\dhbwWrapfigure{caption=Small Pikachu,label=fig:smallpikachu,path=small_pikachu.png}

Nullam accumsan, odio at ultrices vehicula, velit massa porta turpis, sed
auctor sem nisl in tortor. Nullam sollicitudin mollis arcu vitae sollicitudin.
Nunc rhoncus augue luctus erat maximus, sit amet commodo quam pellentesque.  
Parameter Default Description
caption - Title of the figure.
label - Marker for hyperref. Make sure to start your marker with fig: so that automatic referencing works. This marker has to be unique.
path - Path to the image.
source Eigene Darstellung Source of the picture.
placement R Placement specifier.
width 0.45\textwidth Width of the wrapfigure environment.
image width 0.4\textwidth Width of the picture.

It is not possible to provide a dhbwwrapfigure environment because the wrapfigure environment doesn't work if wrapped in another environment.

PlantUML figures

If you have set up PlantUML as described and also set the class option plantuml to true you can embed PlantUML-diagrams in your LaTeX code. Just surround you PlantUML notation with the plantuml environment:

\begin{dhbwfigure}{caption=Informative Sequence Diagram,label=fig:seq}
    \begin{plantuml}
        @startuml

        box "Machine"
            participant "Sensors" as sensors
            participant "OPC UA Server" as opc
        end box
        participant "Cloud" as cloud

        sensors <-> opc
        opc <-> cloud

        @enduml
    \end{plantuml}
\end{dhbwfigure}

⚠ Until version 0.3.0 of the plantuml LuaLaTeX package UTF8 wasn't supported. You can still use any unicode character if you are using an earlier version (see special characters). For example <U+00D6> can be used to express Ö. Use a unicode character table.

Tables

When adding a table you should wrap it inside the dhbwtable environment so that the DHBW formatting requirements are met automatically.

\begin{dhbwtable}{caption={Evilplan},label=tab:mytable,source={\icite{peterson16}},float=h}
    \begin{tabular}{ | c | l |}
        \hline
        \textbf{Phase}  & \textbf{Action}       \\ \hline
        1               & Use a latex template  \\ \hline
        2               & ???                   \\ \hline
        3               & Profit!               \\ \hline
    \end{tabular}
\end{dhbwtable}
Parameter Default Description
caption - Title above the table.
label - Marker for hyperref. Make sure to start your marker with tab: so that automatic referencing works. This marker has to be unique.
float ht Floating specifier.
source Eigene Darstellung Source of the data in the table.

Inside the tabular environment the actual table is created. Click here for a detailed guide on how to use the tabular environment.

Long tables

The environment dhbwlongtable provides a wrapper for the longtable CTAN package which enables tables spanning across pagebreaks. The frist argument is the longtable definition and the second argument is a key-value list. Here is an example:

\begin{dhbwlongtable}{ | p{0.3\linewidth} | p{0.7\linewidth} | }{%
    caption = This is the caption,
    label   = tab:label
}

\hline
\textbf{Column 1} & \textbf{Column 2} \\ \hline
This & is an example \\ \hline

\end{dhbwlongtable}
Parameter Default Description
caption - Title above the table.
label - Marker for hyperref. Make sure to start your marker with tab: so that automatic referencing works. This marker has to be unique.
source Eigene Darstellung Source of the data in the table.

Read the longtable manual for guidance on how to define long tables!

Code listing

You can add a code listing using the code environment:

\begin{code}{caption={Express Example},language=javascript,label=lst:express}{\icite[2]{example}}
const express = require('express')
const app = express()
const port = 3000

app.get('/', (req, res) => res.send('Hello World!'))

app.listen(port, () => console.log(`Example app listening on port ${port}!`))
\end{code}

The code environment is a custom listings environment. The first argument is used to pass options through to the listings environment and the second argument is the used for the short reference.

⚠ You should always pass the options listed below to the listings environment:

Option Description
caption The caption to appear above the code listing and in the list of code listings.
language The language of the source code used for syntax highlighting. In addition to the languages supported by default this template adds support for csharp and javascript.
label The marker used for referencing. Has to begin with lst:.

⚠ The short reference below the code listing is not inside the same float as the code. It can happen that the code listing and the reference have a page break between them. To prevent this you have to wrap the code environment with a minipage environment:

\begin{minipage}[c]{\textwidth}
\begin{code}{...}{...}
...
\end{code}
\end{minipage}

Labels and referencing

When you want to refer to a section, figure, table or code listing you have to use a reference command like \autoref{marker} from the hyperref CTAN package to do so because the number of a section for example is only determined at build time.

Using \autoref{} presupposes that you are using following tags in your labels so that it can produce the correct output:

Tag Type Output (German; first appearance)
sec: Section Abschnitt 1
subsec: Subsection Unterabschnitt 1.1
tab: Table Tabelle 1
fig: Figure Abbildung 1
lst: Code listing Quellcode 1

Take a look at the german example below:

\section{Dieser Abschnitt ist wahr}\label{sec:widerspruch_beispiel}
Dieser Abschnitt ist nicht wahr

\section{Anderer Abschnitt}\label{sec:andere}
Beim Lesen des \autoref{sec:widerspruch_beispiel} konnten Sie einen Widerspruch feststellen.
In \autoref{sec:andere} findet sich kein Widerspruch.

The text in the second section translates to:

Beim Lesen des Abschnitt 1 konnten Sie einen Widerspruch feststellen.
In Abschnitt 2 findet sich kein Widerspruch.

Click here or read the documenation of the hyperref package for details on advanced usage.

Appendices

This template uses the appendix CTAN package for managing appendices. Below you can see how to add one or more appendices:

% your text

\begin{dhbwappendices}

    \dhbwAppendix{app:example}
    This is an appendix.

\end{dhbwappendices}

% bibliography & independence-notice

You can refer to an appendix from your text using \autoref{app:example} which will print Anhang I, Anhang II and so on. The app: label-prefix is optional. Any labeled section created inside the dhbwappendices environment will be refered to as Anhang.

Appendix with custom title

You can create appendices with custom titles as shown below:

% your text

\begin{dhbwappendices}

    \newpage
    \section{Roadmap}\label{app:roadmap}
    This is an appendix.

\end{dhbwappendices}

% bibliography & independence-notice

The example above will create an appendix with the title Anhang I Roadmap.

Abstract

If you want to add an abstract to your text simply use the abstract-file class option.

Example abstract:

\section*{Abstract}

It is a period of civil wars in the galaxy. A brave alliance of underground freedom fighters has challenged the tyranny and oppression of the awesome GALACTIC EMPIRE.

Striking from a fortress hidden among the billion stars of the galaxy, rebel spaceships have won their first victory in a battle with the powerful Imperial Starfleet. The EMPIRE fears that another defeat could bring a thousand more solar systems into the rebellion, and Imperial control over the galaxy would be lost forever.

To crush the rebellion once and for all, the EMPIRE is constructing a sinister new battle station. Powerful enough to destroy an entire planet, its completion spells certain doom for the champions of freedom.

Bibliography

When you're researching it is advised to store every source of information as an entry in your bibliography file. Biblatex will make sure to only print references you actually refered to in your bibliography at the end of the text. Biblatex will also sort entries by author, then by year, then by month, then by day and finally by title.

⚠ The DHBW-VS bibliography style was only tested with the entires of type article, book and online. law and verdict are experimental. However other types of entries should also work as long as they provide a shorttitle field!

⚠ Make sure to escape special characters with \.

Add entry of type book

In order to satisfy the DHBW-VS requirements an bibliography entry of type book has to provide following fields:

Field Description
author Author or authors of the book. See author field format.
title Title of the book.
shorttitle Shorttitle for the reference. Has to be unique.
year Year of the publication of the book. ⚠ Do not add a year field when the year is unknown.
edition The edition of the book. ⚠ Do not add an edition field when you're refering to the first edition of a book.
publisher The publisher of the book.
location The city or place where to book was published.

Take a look at the documentation of the biblatex package for optional entry fields. Example below:

@book{adams79,
    author      = {Douglas Adams},
    title       = {The Hitchhiker's Guide to the Galaxy},
    shorttitle  = {Hitchhiker},
    year        = {1979},
    publisher   = {Pan Books},
    location    = {Somecity}
}

Add entry of type online

In order to satisfy the DHBW-VS requirements an bibliography entry of type online has to provide following fields:

Field Description
author Author or authors of the online entry. See author field format.
title The title of the online entry
shorttitle The shorttitle of the online entry. Has to be unique.
date The date of the publication of the online entry. ⚠ Do not add a date field when the date is unknown.
url The URL pointing to the online entry.
urldate The date when the URL was visited the last time in yyyy-mm-dd format.

Valid example:

@online{hackthewood_first_article,
    author      = {Christian Neumann},
    title       = {HACK THE WOOD 2019},
    shorttitle  = {Hackathon},
    date        = {2019-03-14},
    urldate     = {2019-08-08},
    url         = {https://www.tapio.one/de/blog/hack-the-wood-2019}
}

Add entry of type article

In order to satisfy the DHBW-VS requirements an bibliography entry of type article has to provide following fields:

Field Description
author Author or authors of the article entry. See author field format.
title The title of the article entry
shorttitle The shorttitle of the article entry. Has to be unique.
year Year of the publication of the article.
journal The name of the journal. May be abbreviated.
pages The first and last page of the article in the journal separated by --.

Valid example:

@article{linklabs_zwave_vs_zigbee,
    author      = {Brian Ray},
    title       = {Z-Wave Vs. Zigbee},
    shorttitle  = {LOL},
    year        = {3000},
    journal     = {Harvard Business Review},
    pages       = {69--420}
}

Add entry of type law

In order to satisfy the DHBW-VS requirements an bibliography entry of type law has to provide following fields:

Field Description
author Should always be o.V..
title The title of the law entry
shorttitle The shorttitle of the law entry. Has to be unique.
src Where the law was found. E.g. Bundesgesetzblatt.
srcyear The year the source of the law was published.
srcvol The volume of the law. E.g. I.
srcpage The first page where the law was found in the source.
date The date of the law.

Valid example:

@law{bgb,
    title       = {Bürgerliches Gesetzbuch},
    author      = {o.V.},
    shorttitle  = {BGB},
    src         = {Bundesgesetzblatt},
    srcyear     = {2002},
    srcvol      = {I},
    srcpage     = {42},
    date        = {2020-03-19}
}

Add entry of type verdict

In order to satisfy the DHBW-VS requirements an bibliography entry of type verdict has to provide following fields:

Field Description
author Should always be o.V..
title The title of the verdict entry
shorttitle The shorttitle of the verdict entry. Has to be unique.
court The name of the court.
date The date the verdict was announced.
url Url to the source of the verdict.
urldate Date the url to the verdict was visited.

Valid example:

@verdict{shell,
    author			= {o.V.},
    title			= {I ZR 138/99},
    shorttitle		= {Shell-Urteil},
    court	        = {BGH},
    date		    = {2001-11-22},
    url				= {http://juris.bundesgerichtshof.de/cgi-bin/rechtsprechung/document.py?Gericht=bgh&nr=23718},
    urldate			= {2020-06-03}
}

Author field format

There are many ways to use the author field. The most common ways are shown below. For advanced usage of the author field take a look at the documentation of the biblatex package.

Firstname lastname combinations

Both examples listed below are valid:

@online{tesla,
    author = {Elon Musk},
    ...
}
@online{tesla,
    author = {Musk, Elon},
    ...
}

Author is just one word

When the Author ist just one word for example the name of a company you have to define the author field this way:

@online{hackthewood,
    author = "{tapio}",
    ...
}

More than one author

You can add more than one author to an author field. Use the and keyword to seperate the names of the authors.

@online{programming,
    author = {Martin Fowler and Hanselman, Scott},
    ...
}

You can use different firstname-lastname-combinations in the same author field.

You can use the keyword and others if there are to many authors:

@online{paypalmafia,
    author = {Jawed Karin and Stoppelman, Jeremy and Peter Thiel and others},
    ...
}

VSCode snippets

There are a few VSCode snippets predefined in .vscode/udhbwvst.code-snippets you can take advantage of:

Prefix Description
udhbwvst Setup the udhbwvst class.
\dhbwSetup Snippet for the \dhbwSetup command.
\footcite Snippet for the \footcite command.
\dfootcite Snippet for the \dfootcite command.
\ifootcite Snippet for the \ifootcite command.
\icite Snippet for the \icite command.
dhbwfigure Snippet for the dhbwfigure environment.
\dhbwFigure Snippet for the \dhbwFigure command.
\dhbwWrapfigure Snippet for the \dhbwWrapfigure command.
dhbwtable Snippet for the dhbwtable environment.
dhbwlongtable Snippet for the dhbwlongtable environment.
code Snippet for the code environment.
codeprotected Snippet for the code environment but wrapped in a minipage.
@online Snippet for an @online bibliography entry.
@book Snippet for an @book bibliography entry.
\decacro Snippet for setting up an acronym.