[edit]

Definition

This article describes how you can contribute or edit articles.

If you want to contribute or edit an article do the following:

  1. fork the repository on github and clone it locally.
  2. edit the corresponding .md file in the folder '_article' or create a new one.
  3. once finished, push the changes to GitHub and create a pull request.

What content is suitable for Tex4TUM?

Before you start writing, think twice.

  1. A TeX4TUM article should mostly consist of diagrams, tables, and equations. Text paragraphs should only be used as a last method to explain details and these details should be hidden by default.
  2. The content should be timeless. Anything that out-dates or updates more frequent than 5 years is not suitable.
  3. The article should be an overview of knowledge that many engineers frequently need but often forget. The article should not focus on teaching or explaining something to the reader. These contribution guidelines are a good counter example of what should not be a normal TeX4TUM article.
  4. The content should stick to or inherit a pattern. For example, protocols always illustrate the header format and then explain the fields.

Our Format Syntax

The good news first: If you write text, it will be displayed as text. If you want to apply some text formatting you can use Markdown. Equations can be typset in TeX surrounded by $ without spaces.

File structure

Our file structure requires a YAML header (surrounded by ---) that states a title and some keywords (tags) that can be used to find the article.

File example

 ---
 title: Inter-Integrated Circuit I²C
 tags: i2c, bus, SDA, SCK
 ---

 The first paragraph is the definition (hidden by default).

 After the first blank line comes the introduction.

 ## First Heading
 text

The first paragraph will become the definition, which you should always provide. If you really want to omit a definition, indent the first paragraph by two spaces.

Markdown for Basic Text

We use Pandoc as Markdown interpreter with the extension footnotes and backtick_code_blocks. Thus, the following formatting is possible

## Heading Heading
**bold** bold
**italic** italic
[Link-Text](url) Link-Text

Own Parsers

We also use our own backend scripts to parse certain content categories, for example, to detect the definition paragraph of an article. Furthermore, we format examples, explanations, and legends. To format a paragraph as example you just need to write Example: before a paragraph. The paragraph is recognized by blank lines, so make sure that you have a blank line before the the Example: marker.

Example

This is an example Text and here is the code that produces it.
Example: This is an example Text and here is the code that produces it.

Besides that you can also mark content using the Liquid Tags described below.

Equations with TeX

We use KaTeX as TeX interpreter, such that you can typeset math equations simply using $. For example to display $\sqrt{x^2 + \alpha}$ as inline you write $\sqrt{x^2 + \alpha}$. Please note that there must not be a space between the $ and your tex code! For display style equations, leave a blank line and surround your tex code by double $$s. You may optionally explain used symbols by a line starting with with or where that directly follows the equation.

The equation (you can click on it)

$$\oint_{\partial A} {\boldsymbol E} \cdot {\,\text{d}}{\boldsymbol s}$$

with electric field ${\boldsymbol E}$, surface $A$ and direction ${\boldsymbol s}$

is written as

$$\oint_{\partial A} \vec E \cdot \diff \vec s$$
with electric field $\vec E$, surface $A$ and direction $\vec s$

Note: To define new LaTeX commands add them to res/parser_util/tex_definition.md

Jekyll and Liquid Tags

Our site is generated using Jekyll that manages every step of the conversion to the final HTML files. Thus, Jekyll collects and converts the Markdown files by piping them through Pandoc. However, before the conversion, Jekyll allows to substitute dynamic content using Liquid Tags {% include mycontent.md %} and Liquid variables {{ date }}. These tags allow sophisticated generation of content using backend Ruby scripts.

We created some custom templates, liquid tags and plugins to simplify the development process. The following sections describe how to use these during contribution. Also check our Demo Pages for some features.

Images

To include Images use the following commands

Figures

{% include figure.html filename="complex.svg" description="Description goes here" width="50%" %}

Output: Image in figure environment with image description

Description goes here
Description goes here

Inline Image

{% inlineimage capacitor_symbol.svg %}

Output: Inline Image ########################################################################################################################################################################################

SVG Objects

{% include svg-object.html width="18em" id="RC_obj" filename="rc.svg" description="Circuit of low-pass filter" %}
Output: SVG Object
Circuit of low-pass filter

Code Listings

Verbatime code can be placed inside backticks, e.g. `code` is displayed as code. If you want to highlight code put it in a block of three backticks. Directly after the backticks you can specify the language.

1
2
3
4
5
```c
int main() {
    printf("Hello World");
}
```

As an alternative we also support advanced syntax highlighting using the following liquid tag

{% highlight c linenos %}
int main() {
    if (a < 3){
        printf("Hello World");
    }
}
{% endhighlight %}

Acronyms

Acronyms, such as AES, are parsed and linked automatically. If you want to add a new abbreviation just add it to res/parser_util/abbreviations.md. The structure should look like this

*[AES]: Advanced Encryption Standard

Content Categories

We currently support four special categories of content, which visibility is influenced via interactions or the options (see Demo Page)

{% definition %}text{% enddefinition %}
{% example %}text{% endexample %}
{% explanation %}text{% endexplanation %}
{% legend %}text{% endlegend %}

Emphbox

{% emphbox %}Content in box{% endemphbox %}
Output:

Content in box

Interactivity: HTML/SVG + JavaScript

To create interactive content you can directly embedd HTML tags and JavaScript code. An easy to use framework is under development.

Resistance R = <span id="R_val" onclick="askValue(this.id)">10k</span>Ω

<script type="text/javascript">
 var R1 = getValue( document.getElementById("R_val").textContent );
</script>

Please ensure that you only have one <script> section at the end of the article! Otherwise our generator scripts might destroy your code.

Preview your article

When you are done editing, you can preview your article. Follow the instruction of the README to install all dependencies

Run the local server and browse to http://localhost:4000/ with

make run

List of TODOs

All lines starting with TODO will be added to the following TODO list.

ToDo Source File Page Reference
table for selecting resistors. i2c.md Inter-Integrated Circuit (I2C)
explain how values are read / written ram.md Random Access Memory (RAM)
typical values of RAM modules ram.md Random Access Memory (RAM)
jvascript that displays different encodings utf8.md UTF-8
color escape codes bash.md Bash
list all keywords c.md C
diagram explaining the GNU tool chain: linker c.md C
fill list http.md HTTP
page 58 image ieee-802-15-04.md IEEE 802.15.4
figure from p 51 ieee-802-15-04.md IEEE 802.15.4
write article mac.md Media Access Control
adjust JS library for blake2b blake2.md Blake 2
time zone diagram datetime.md Date and Time
show clocks datetime.md Date and Time
Float umwandlung mit precision fehler numbers.md Number Converter
explanation matrix.md Matrix
adjust svg like this: https://www.thinkcalculator.com/algebra/convolution-calculator.php convolution.md Convolution
explain alpha, beta, and P testing.md Hypothesis Testing
precision, recall, sensitivity testing.md Hypothesis Testing
draw image of the process github .md --> jekyll --> scripts --> pandoc --> .html + head.html = webpage about.md About TeX4TUM
should we use mermaid? contribution.md Contribution
This will be written into the todo-list demo.md Demo of Interactive Features
place as cards with logo (bootstrap) links.md Links
-->