From a21de1bcd3a26f517a9a324dcd0c217211458973 Mon Sep 17 00:00:00 2001
From: Oleg Hahm <oleg@riot-os.org>
Date: Wed, 20 Mar 2024 11:51:26 +0100
Subject: [PATCH] doc: add terminal program configuration

---
 doc/doxygen/riot.doxyfile            |  1 +
 doc/doxygen/src/terminal-programs.md | 49 ++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)
 create mode 100644 doc/doxygen/src/terminal-programs.md

diff --git a/doc/doxygen/riot.doxyfile b/doc/doxygen/riot.doxyfile
index 9c7fdfdce06f..01cfa3d83913 100644
--- a/doc/doxygen/riot.doxyfile
+++ b/doc/doxygen/riot.doxyfile
@@ -767,6 +767,7 @@ INPUT                  = ../../doc.txt \
                          src/driver-guide.md \
                          src/getting-started.md \
                          src/flashing.md \
+                         src/terminal-programs.md \
                          src/build-in-docker.md \
                          ../../tests/README.md \
                          src/build-system-basics.md \
diff --git a/doc/doxygen/src/terminal-programs.md b/doc/doxygen/src/terminal-programs.md
new file mode 100644
index 000000000000..fd03b318a289
--- /dev/null
+++ b/doc/doxygen/src/terminal-programs.md
@@ -0,0 +1,49 @@
+Terminal programs configuration                             {#terminal-programs}
+===========================================================
+
+[TOC]
+
+Background                                                         {#background}
+==========
+This page explains how to configure some popular terminal programs for correct
+display of newlines when using the serial interface of a RIOT powered device.
+When printing something using *stdio* (e.g., `printf("Hello World!\n");`, RIOT
+sends a line feed character (`0xA`) as `\n` (newline).
+
+Some terminals need more, for example, a carriage return and a line feed
+character (0xD, 0xA). See https://en.wikipedia.org/wiki/Newline for background.
+
+This page tries to collect needed settings for common terminal programs that
+will make them correctly display newlines.
+
+picocom                                                               {#picocom}
+=======
+- Generic method:
+    - Start with `--imap lfcrlf` parameter.
+- Via RIOT build system:
+    - `RIOT_TERMINAL=picocom make term`
+
+gtkterm                                                               {#gtkterm}
+======
+- Graphical method:
+    - Open the configuration menu.
+    - Click on ***CR LF auto***.
+- Manual method:
+    - Edit the file `~/.gtktermrc`.
+    - Change value of ***crlfauto*** option to `True`.
+
+minicom                                                               {#minicom}
+=======
+- Interactive method:
+    - Press ***Ctrl+A u***.
+- Manual method:
+    - Edit the configuration file (`~/.minirc.dfl` per default).
+    - Add the following line:
+    pu addcarreturn     Yes
+
+miniterm                                                             {#miniterm}
+========
+- Generic method:
+    - Start with `--eol CR`parameter.
+- Via RIOT build system:
+    - `RIOT_TERMINAL=miniterm make term`