Skip to content

Contribution#

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.

 ---
 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} \vec E \cdot \diff \vec s\]

with electric field \(\vec E\), surface \(A\) and direction \(\vec 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

Images#

To include Images use the following commands

Diagramms#

We use mermaid for drawing diagramms. For this we created a liquid tag

{% mermaid %}
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
{% endmermaid %}

Check some demos and the online editor of mermaid: Live Editor

Output:

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

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.

```c
int main() {
    printf("Hello World");
}
```

This procudes

int main() {
    if (a < 3){
        printf("Hello World");
    }
}

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: {% emphbox %}Content in box{% endemphbox %}

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.