3. Tipps für Berichte¶
Hier sind ein paar Tipps zum Schreiben von kleineren Berichten und Ausarbeitungen.
Für umfangreichere Texte wie Bachelor- und Masterarbeiten gelten strengere Regeln [1]!
3.1. Der Kopf¶
Der Text beginnt mit einem Kopf, so wie bei diesem Demo-Bericht. Darin steht
Hochschule Augsburg, Fakultät
Name der Veranstaltung, z.B. „DVA Praktikum (Prof. Dr. Högl)“
Titel des Berichtes. Bei diesem Text „Berichte mit Sphinx schreiben“.
Semester mit Jahreszahl, z.B. „Sommersemester 2023“.
Der Autor oder die Autoren (jeweils Name, E-mail, Fach, Matrikelnr.)
Autor: Anna Muster, <Anna.Muster@hs-augsburg.de>, TI3, #123456
Sollte es mehrere Autoren geben, dann diese wie folgt mit E-mail Adresse,
Studiengang+Semester, Matrikel-Nummer untereinander unter Autoren:
schreiben. Damit die Zeilen untereinander stehen, muss man einen senkrechten
Strich an den Anfang stellen:
Autoren:
| Paul Muster, <Paul.Muster@hs-augsburg.de>, TI3, #12345
| Anna Muster, <Anna.Muster@hs-augsburg.de>, TI3, #12346
Schauen Sie sich auch die Startseite dieses Beispielberichtes im Quelltext an.
Lizenz
Ich habe in den Kopf auch die Creative Commons Lizenz aufgenommen. Zum einen gibt es eine grafische Veranschaulichung
und zum anderen den Lizenztext:
Dieser Text steht unter der Creative Commons Lizenz Namensnennung/Keine kommerzielle Nutzung
Somit ist der Bericht eine Open-Source Ware, die andere wiederverwenden dürfen. Da das Euro-Symbol durchgestrichen ist, dürfen andere damit nicht Geld verdienen. Sollte Sie eine andere Kombination aus dem Creative Commons Lizenzbaukasten aufnehmen wollen, dann lohnt es sich, mal auf der Website https://creativecommons.org vorbeizuschauen.
3.2. Einleitung¶
Es soll immer eine kurze Einleitung vorhanden sein, die erklärt, worum es in dem Text geht.
3.3. Gliederung¶
Eine klare Gliederung mit aussagekräftige Überschriften überlegen.
3.4. Rechtschreibung¶
Auf richtige Rechtschreibung und Kommasetzung achten.
3.5. Ausformulieren¶
Wenn möglich den Text in Absätzen ausformulieren.
3.6. Zitieren¶
Textauszüge und Abbildungen, die von Texten anderer Leute übernommen wurden, müssen mit einer Quellenangabe versehen werden, das nennt man „zitieren“. Das gilt auch, wenn etwas von fremden Websites übernommen wurde.
Hier ist eine Abbildung, die ich aus dem Buch von [YIU] entnommen habe. Wichtig ist, dass man unter das Bild schreibt, woher es kommt und auf welcher Seite man es gefunden hat:
Wenn man es ganz genau nehmen würde, dann müsste man auch noch nach der Erlaubnis des Verlages fragen. Bei einzelnen Bildern muss das meiner Meinung nach aber noch nicht sein.
Hier ist die Literaturangabe, auf die in der Bildunterschrift verwiesen wird:
3.7. Literaturangaben¶
Sphinx hat einen eigenen Befehl, um Literaturangaben zu schreiben. Hier ist ein Beispiel:
.. [SPHINX] Die Sphinx Homepage (besucht am 13.3.2023):
https://www.sphinx-doc.org
.. [YIU] Joseph Yiu, The Definitive Guide to the ARM Cortex-M3.
2nd edition, Newnes 2010.
.. [SPHTUT] Thomas Cokelaer, Sphinx and RST syntax guide, 2014 (besucht am
13.3.2023)
https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
Jede Literaturstelle leitet man also ein mit .. [xxx] , an der Stelle
xxx soll eine leicht verständliche Abkürzung verwendet werden. Im Text
bezieht man sich auf eine Literaturstelle mit der Syntax [xxx]_ (den
Unterstrich am Ende nicht vergessen), also z.B. mit [SPHINX]_. Das erzeugt
folgenden Link: [SPHINX]. Wie diese Literaturangaben im HTML Ausgabeformat
aussieht, sieht man in Abschnitt 2.6.
Bei einem Buch sollte Autor, Buchtitel, Auflage, Verlag und Jahr enthalten sein.
Bei der Angabe einer Stelle im Internet (URL) sollte eine kurze Beschreibung dabei sein und und eine Angabe wann der Link zuletzt besucht wurde.
3.8. Quelltext¶
Quelltext sollte man „schön“ darstellen, das erleichtert die Lesbarkeit. Dazu gehört:
Verwenden einer nicht-proportionalen Schriftart wie z.B. „Courier“ oder „Monospace“.
Farbige Syntaxhervorhebung („syntax highlighting“)
Zeilennummern
All das kann mit Sphinx sehr einfach realisiert werden, wie man in Abschnitt 2.4 sieht.
3.9. Bilder¶
Jedes Bild das im Text erscheint sollte auch im Text erwähnt werden. Das kann man so sehen:
Auf der folgenden Abb. 3.9.1 sieht man einen kleinen Rechner auf dem Embedded Linux läuft. Es ist quadratisch, praktisch, gut, …
Die Referenz wurde mit der Anweisung :numref:`gnublin_fig` gemacht. Die
ähnliche Anweisung :ref:`gnublin_fig` hingegen produziert die
Bildunterschrift Das Gnublin Board.
Abb. 3.9.1 Das Gnublin Board¶
Merke also: Bilder niemals in den Text aufnehmen, ohne dass man sich darauf im Text bezieht.
Achten Sie darauf, dass Bilder nicht zu viel Platz verschwenden. Oft haben
Bilder, die mit dem Smartphone aufgenommen wurden, Dateigrössen von 4 bis
5 MByte. Man kann diese in der Regel ohne nennenswerte Einbussen in der
Qualität um den Faktor 10 verkleinern. Ich verwende dazu meist das
convert Programm aus ImageMagick (https://imagemagick.org).
Die Abbildung hat eine Bildunterschrift und eine Nummer, weil
in conf.py der Eintrag:
numfig = True
ist.
Das Label gnublin_fig kommt von der Zeile:
.. _gnublin_fig:
die direkt vor der Abbildung steht.
Nebenbei gesagt funktioniert die „numref“ Umgebung auch noch mit anderen Elementen, z.B. Code-Blöcken (siehe Codeabschnitt 3.9.1), oder auch mit Tabellen (siehe Tab. 3.9.1).
if __name__ == "__main__":
print("Hello World")
Stadt |
Einwohner |
Bundesland |
|---|---|---|
Augsburg |
360.000 |
Bayern |
Frankfurt |
750.000 |
Hessen |
3.10. Videos¶
Ein Video kann man mit dem HTML5 <video> Tag einbauen. Man kann dazu wie
folgt einen „rohen“ HTML-Abschnitt in das Sphinx Dokument aufnehmen:
.. raw:: html
<video controls>
<source src="_static/small.ogv" type="video/ogg" />
</video>
Als Formate eigenen sich Ogg (.ogv/.ogm/.ogg), WebM
(.webm) oder MP4 (.mp4).
Ein Demo-Video (Quelle: http://techslides.com/demos/sample-videos/small.ogv).
Achten Sie darauf, dass Videos nicht zu viel Platz verschwenden. Sie sollten
Videos soweit in der Dateigrösse komprimieren, dass man den Inhalt noch
gut erkennen kann. Als Werkzeug wird dazu oft ffmpeg verwendet. Das
vorherige Beispielvideo ist z.B. nur ca. 440 kbyte gross.
Dokumentation zum Video Tag findet man unter https://developer.mozilla.org/de/docs/Web/HTML/Element/video.
3.11. Zusammenfassung¶
Es sollte am Ende des Textes zumindest eine kleine Zusammenfassung geben, die den Text abschliesst.
Fussnoten