{"id":1123,"date":"2021-09-11T16:24:12","date_gmt":"2021-09-11T14:24:12","guid":{"rendered":"https:\/\/blogs.uni-bremen.de\/studytools\/?p=1123"},"modified":"2023-08-02T14:17:18","modified_gmt":"2023-08-02T12:17:18","slug":"projekte-dokumentierenmit-asciidoc","status":"publish","type":"post","link":"https:\/\/blogs.uni-bremen.de\/studytools\/2021\/09\/11\/projekte-dokumentierenmit-asciidoc\/","title":{"rendered":"Projekte dokumentieren\u2009\u2014\u2009mit AsciiDoc"},"content":{"rendered":"<div id=\"content\">\n<div id=\"preamble\">\n<div class=\"sectionbody\">\n<div class=\"ulist\">\n<figure id=\"attachment_1122\" aria-describedby=\"caption-attachment-1122\" style=\"width: 1024px\" class=\"wp-caption alignnone\"><a href=\"https:\/\/blogs.uni-bremen.de\/studytools\/files\/asciidoc2.png\" data-rel=\"lightbox-image-0\" data-rl_title=\"\" data-rl_caption=\"\" title=\"\"><img loading=\"lazy\" decoding=\"async\" class=\"size-large wp-image-1122\" src=\"https:\/\/blogs.uni-bremen.de\/studytools\/files\/asciidoc2-1024x591.png\" alt=\"Screenshot des Asciidoc-Artikels im Texteditor (links) und als HTML-Seite (rechts)\" width=\"1024\" height=\"591\" \/><\/a><figcaption id=\"caption-attachment-1122\" class=\"wp-caption-text\">Mit der flexiblen Markup-Sprache AsciiDoc kannst du komplexe technische Dokumentation in schlichte aber lesbare Textdateien schreiben. Viele n\u00fctzliche Funktionen helfen dir dabei.<\/figcaption><\/figure>\n<ul>\n<li>Du musst ein Projekt oder ein Programm dokumentieren?<\/li>\n<li>Bitte keine unterschiedlich alten Office-Dokumente auf den &#8222;Dokumentations-&#8222;Kompost mehr tun\u2026 du brauchst eine aktuelle Hilfe!?<\/li>\n<li>Ihr w\u00fcrdet auch gern eine Versionsverwaltung nutzen?<\/li>\n<\/ul>\n<p>Was du dazu brauchst, ist eine Markup-Sprache!<\/p>\n<p>Die gibt es wie Sand am Meer:<br \/>\nvon den Urgesteinen <a href=\"https:\/\/de.wikipedia.org\/wiki\/Troff\">troff<\/a> und <a href=\"https:\/\/de.wikipedia.org\/wiki\/Groff\">Groff<\/a> \u00fcber Dokumentations-Tools wie <a href=\"https:\/\/docbook.org\/\">DocBook<\/a> und <a href=\"https:\/\/de.wikipedia.org\/wiki\/ReStructuredText\">reStructuredText<\/a> oder Textsatz-Systemen wie <a href=\"https:\/\/blogs.uni-bremen.de\/studytools\/2020\/12\/12\/latex-textsatz-fuer-wissenschaft-buchdruck-und-typografinnen\/\">LaTeX<\/a>\u2026 oder aber der allgegenw\u00e4rtige und hippe Star <a href=\"https:\/\/blogs.uni-bremen.de\/studytools\/2021\/09\/07\/markdown-einfach-gut-schreiben\/\">Markdown<\/a>.<\/p>\n<p><strong>Hinweis:<br \/>\n<\/strong><em>All diese Markup-Sprachen sind konventionen oder Standards, um einfache Textdateien zu schreiben. Aus diesen werden sp\u00e4ter Webseiten, Dokumente oder PDF-Dateien generiert, die den &#8222;fertigen&#8220; Text enthalten. <a href=\"https:\/\/blogs.uni-bremen.de\/studytools\/2021\/09\/07\/markdown-einfach-gut-schreiben\/\">Markdown<\/a> beispielsweise liest und schreibt sich _sehr viel einfacher als <a href=\"https:\/\/blogs.uni-bremen.de\/studytools\/2020\/12\/12\/latex-textsatz-fuer-wissenschaft-buchdruck-und-typografinnen\/\">LaTeX<\/a>\u2009\u2014\u2009hat aber auch einige Haken im Detail und wesentlich weniger Funktionen. Daf\u00fcr brauchst du aber auch wesentlich weniger Vorwissen als f\u00fcr LaTeX.<\/em><br \/>\n<em>Kurz: jede Markup-Sprache hat ihre eigenen Vor- und Nachteile.<\/em><\/p>\n<p>AsciiDoc wurde speziell f\u00fcr Dokumentationen entwickelt und baut auf dem etablierten <em>DocBook<\/em> auf. Es bringt daher viele n\u00fctzliche Funktionen f\u00fcr das Schreiben und Verweisen in Dokumentationen mit.<br \/>\nNat\u00fcrlich sind die \u00fcblichen \u00dcberschriften, Tabellen, Bilder und Querverweise sind kein Problem. Auch Formeln lassen kannst du mit Asciimath oder LaTeX-Formeln setzen. Und: AsciiDoc bleibt immer gut lesbar\u2009\u2014\u2009auch im Quellcode!<\/p>\n<p><strong>Hinweis:<br \/>\n<\/strong><em><strong>Ascii<\/strong> ist die Abk\u00fcrzung f\u00fcr &#8222;American Standard Code for Information Interchange&#8220; und ist eine Zeichenkodierung.<br \/>\n<strong>AsciiDoc<\/strong> ist die standardisierte Markup-Sprache selbst.<br \/>\n<strong>AsciiDoctor<\/strong> das dazugeh\u00f6rige Programm, das Dokumente in andere Formate umwandelt.<\/em><\/p>\n<h2>Features, Features, Features\u2026<\/h2>\n<p>Wichtig f\u00fcr Anleitungen sind aussagekr\u00e4ftige K\u00e4sten mit <strong>&#8222;Wichtig!&#8220;<\/strong> oder <strong>&#8222;Info&#8220;<\/strong>. Daher geh\u00f6ren sie auch zum Standard-Repertoire (inklusive der passenden Beschriftung oder Symbole).<br \/>\nEine gro\u00dfe St\u00e4rke sind auch Tabellen, deren Zeilen sich f\u00fcr einfachere Lesbarkeit einf\u00e4rben lassen. Features f\u00fcr Fortgeschrittene, wie etwa Zellen zusammenfassen und Spaltenbreiten festlegen, kannst du ebenfalls leicht umsetzen.<br \/>\nUnd damit du die Features deines Projekts gut hervorheben kannst, musst du auch auf deine geliebten Checklisten nicht verzichten.<\/p>\n<p>Unter-Dokumenten kannst du in AsciiDoc per <code>include<\/code> einbinden. Willst du beispielsweise eine bestimmte Warnung mehrmals im Dokument anzeigen, schreibst du sie nicht immer wieder; du schreibst sie in eine eigene Datei, die du mehrmals aufrufst.<br \/>\nBesonderer Leckerbissen f\u00fcr Programmierer*innen: auch Code-Listings und Schnipsel aus Quellcode lassen sich so direkt aus AsciiDoc heraus aufrufen: einfach auf die andere Datei mit dem Quellcode verweisen\u2009\u2014\u2009so einfach kann das sein!<br \/>\nMit <em>Attributen<\/em> (z.B. einer Versionsnummer) kannst du kleinere Texte ebenfalls merhmals an anderen Stellen benutzen. Auch das ist nicht nur f\u00fcr Schreibfaule, sondern beugt Wiederholungsfehlern vor.<\/p>\n<p>Mit AsciiDoc geht aber noch mehr:<br \/>\nTastenkombinationen f\u00fcr die Bedienung von Programmen kannst du damit ebenfalls darstellen. Sogar Wenn-Dann Abfragen bei der Dokumentenerstellung sind m\u00f6glich (wenn etwa eine Information nur n\u00fctzlich f\u00fcr ein bestimmtes Ausgabeformat ist). Ein Video ergibt auf einer Webseite n\u00e4mlich mehr Sinn als in einer PDF\u2026<\/p>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"sect1\">\n<div class=\"sectionbody\">\n<div class=\"paragraph\">\n<p>Au\u00dferdem kannst du Diagramme mit <em>Mermaid<\/em> oder <a href=\"https:\/\/blogs.uni-bremen.de\/studytools\/2021\/09\/07\/plantuml-diagramme-von-projektplanung-bis-programmcode\/\">PlantUML<\/a> ebenfalls direkt in deine Dokumente einbetten.<\/p>\n<p>Ach und \u00fcbrigens:<br \/>\nNeben <em>HTML<\/em>-Dateien l\u00e4sst sich AsciiDoc auch als <em>DocBook<\/em>, <em>Man page<\/em>, <em>PDF<\/em>, <em>EPUB<\/em> oder Pr\u00e4sentation mit <em>reveal.js<\/em> ausgeben.<br \/>\nDie Vorlagen f\u00fcr alle Formate lassen sich dabei anpassen. Sogar wissenschaftliche Texte kannst du damit schreiben, denn mit Erweiterungen unterst\u00fctzt AsciiDoc auch BibTeX-Dateien, die deine Quellen enthalten.<\/p>\n<h2>Dokumentation als Code<\/h2>\n<p>Du siehst: 1000 N\u00fctzlichkeiten um deine Dokumentation konsistent und aktuell zu halten. Hilfreich ist dabei auch, dass sich AsciiDoc-Dateien (weil sie schlichte Textdateien sind) perfekt mit einer Versionsverwaltung wie z.B. Git verwalten lassen. Damit k\u00f6nnt ihr auch im Team arbeiten und seid direkt bei den Programmierer*innen, die die Software schreiben.<\/p>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"sect1\">\n<div class=\"sectionbody\">\n<div class=\"paragraph\">\n<p>AsciiDoc eignet sich bestens, um aus einfachen Textdateien sp\u00e4ter umfangreiche Dokumente zu erzeugen\u2009\u2014\u2009egal ob Webseite, Buch oder Pr\u00e4sentation. Viele tolle Funktionen helfen dir dabei, Fehler zu vermeiden und komplexe Anforderungen umzusetzen. Dabei bleibt AsciiDoc immer lesbar\u2009\u2014\u2009egal ob im Quellcode oder als Dokument.<br \/>\nWenn du also ein &#8222;Mittelding&#8220; aus <a href=\"https:\/\/blogs.uni-bremen.de\/studytools\/2020\/12\/12\/latex-textsatz-fuer-wissenschaft-buchdruck-und-typografinnen\/\">LaTeX<\/a> und <a href=\"https:\/\/blogs.uni-bremen.de\/studytools\/2021\/09\/07\/markdown-einfach-gut-schreiben\/\">Markdown<\/a> suchst, k\u00f6nnte AsciiDoc genau das richtige sein.<\/p>\n<div class=\"title\"><strong>Fun-Fact:<\/strong><\/div>\n<div class=\"paragraph\">\n<p>Dieser Beitrag wurde extra in AsciiDoc geschrieben\u2009\u2014\u2009nur so als Test.<\/p>\n<p style=\"text-align: center\"><a href=\"https:\/\/asciidoc.org\/\">https:\/\/asciidoc.org\/<\/a><\/p>\n<h2>Hilfe<\/h2>\n<ul>\n<li>Dokumentation von Asciidoctor (Sprache: EN)\n<ul>\n<li><a class=\"bare\" href=\"https:\/\/docs.asciidoctor.org\/home\/\">https:\/\/docs.asciidoctor.org\/home\/<\/a><\/li>\n<\/ul>\n<\/li>\n<li>AsciiDoc Quick-Reference (Sprache: EN)\n<ul>\n<li><a class=\"bare\" href=\"https:\/\/docs.asciidoctor.org\/asciidoc\/latest\/syntax-quick-reference\/\">https:\/\/docs.asciidoctor.org\/asciidoc\/latest\/syntax-quick-reference\/<\/a><\/li>\n<\/ul>\n<\/li>\n<li>Vergleich zwischen AsciiDoc- und Markdown-Syntax\n<ul>\n<li><a class=\"bare\" href=\"https:\/\/docs.asciidoctor.org\/asciidoc\/latest\/asciidoc-vs-markdown\/\">https:\/\/docs.asciidoctor.org\/asciidoc\/latest\/asciidoc-vs-markdown\/<\/a><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<div class=\"sect1\">\n<div class=\"sectionbody\">\n<div class=\"ulist\">\n<ul>\n<li>Webseite des AsciiDoc-Projekts:\n<ul>\n<li><a class=\"bare\" href=\"https:\/\/asciidoc.org\/\">https:\/\/asciidoc.org\/<\/a><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<h3>Videos<\/h3>\n<ul>\n<li>Video-Pr\u00e4sentation &#8222;Documentation with any editor&#8220; (<em>Christoph Stoettner<\/em>; <a class=\"bare\" href=\"https:\/\/media.ccc.de\">https:\/\/media.ccc.de<\/a>):\n<ul>\n<li><a class=\"bare\" href=\"https:\/\/media.ccc.de\/v\/froscon2018-2192-documentation_with_any_editor\">https:\/\/media.ccc.de\/v\/froscon2018-2192-documentation_with_any_editor<\/a><\/li>\n<\/ul>\n<\/li>\n<li>Video &#8222;Asciidoctor Deep Dive&#8220;(<em>Alexander Schwartz<\/em>;YouToube; Sprache:DE):\n<ul>\n<li><a class=\"bare\" href=\"https:\/\/www.youtube.com\/watch?v=JWuUyLTihac\">https:\/\/www.youtube.com\/watch?v=JWuUyLTihac<\/a><\/li>\n<\/ul>\n<\/li>\n<li>Video &#8222;10 Useful Asciidoctor Tips&#8220; (<em>Parleys<\/em>; YouTube; Sprache: EN):\n<ul>\n<li><a class=\"bare\" href=\"https:\/\/www.youtube.com\/watch?v=8PuIeBn8Qg4\">https:\/\/www.youtube.com\/watch?v=8PuIeBn8Qg4<\/a><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<hr \/>\n<p><a href=\"http:\/\/creativecommons.org\/licenses\/by-sa\/4.0\/\" rel=\"license\"><img decoding=\"async\" class=\"aligncenter\" style=\"border-width: 0\" src=\"https:\/\/i.creativecommons.org\/l\/by-sa\/4.0\/88x31.png\" alt=\"Creative Commons Lizenzvertrag\" \/><\/a><br \/>\nDieses Werk ist lizenziert unter einer <a href=\"http:\/\/creativecommons.org\/licenses\/by-sa\/4.0\/\" rel=\"license\">Creative Commons Namensnennung &#8211; Weitergabe unter gleichen Bedingungen 4.0 International Lizenz<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"<div class=\"entry-summary\">\nDu musst ein Projekt oder ein Programm dokumentieren? Bitte keine unterschiedlich alten Office-Dokumente auf den &#8222;Dokumentations-&#8222;Kompost mehr tun\u2026 du brauchst&hellip;\n<\/div>\n<div class=\"link-more\"><a href=\"https:\/\/blogs.uni-bremen.de\/studytools\/2021\/09\/11\/projekte-dokumentierenmit-asciidoc\/\" class=\"more-link\">Continue reading<span class=\"screen-reader-text\"> &ldquo;Projekte dokumentieren\u2009\u2014\u2009mit AsciiDoc&rdquo;<\/span>&hellip;<\/a><\/div>\n","protected":false},"author":2209,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_bbp_topic_count":0,"_bbp_reply_count":0,"_bbp_total_topic_count":0,"_bbp_total_reply_count":0,"_bbp_voice_count":0,"_bbp_anonymous_reply_count":0,"_bbp_topic_count_hidden":0,"_bbp_reply_count_hidden":0,"_bbp_forum_subforum_count":0,"footnotes":""},"categories":[720477,721020,640],"tags":[838863,838864,838828,86,21138,640],"coauthors":[838704],"class_list":["post-1123","post","type-post","status-publish","format-standard","hentry","category-dienste-und-programme","category-open-source-programme","category-schreiben","tag-asciidoc","tag-asciidoctor","tag-code","tag-dokumentation","tag-programmieren","tag-schreiben","entry"],"_links":{"self":[{"href":"https:\/\/blogs.uni-bremen.de\/studytools\/wp-json\/wp\/v2\/posts\/1123","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blogs.uni-bremen.de\/studytools\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.uni-bremen.de\/studytools\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.uni-bremen.de\/studytools\/wp-json\/wp\/v2\/users\/2209"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.uni-bremen.de\/studytools\/wp-json\/wp\/v2\/comments?post=1123"}],"version-history":[{"count":1,"href":"https:\/\/blogs.uni-bremen.de\/studytools\/wp-json\/wp\/v2\/posts\/1123\/revisions"}],"predecessor-version":[{"id":1157,"href":"https:\/\/blogs.uni-bremen.de\/studytools\/wp-json\/wp\/v2\/posts\/1123\/revisions\/1157"}],"wp:attachment":[{"href":"https:\/\/blogs.uni-bremen.de\/studytools\/wp-json\/wp\/v2\/media?parent=1123"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.uni-bremen.de\/studytools\/wp-json\/wp\/v2\/categories?post=1123"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.uni-bremen.de\/studytools\/wp-json\/wp\/v2\/tags?post=1123"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/blogs.uni-bremen.de\/studytools\/wp-json\/wp\/v2\/coauthors?post=1123"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}