#AsciiDoc #Docs-as-Code #Highlights

AsciiDoc - Meine persönlichen Highlights

AsciiDoc ist eine Evolutionsstufe von Markdown. Diese Markup-Sprache steigt in der beliebtheit in der Open-Source-Community von Jahr zu Jahr. Auf fast allen Entwicklerkonferenzen findet man zu diesem Thema einen Beitrag.

Wer genau wissen möchte, was AsciiDoc alles leistet oder auch nicht leistet, dem lege ich die Dokumentation ans Herz. Außerdem kann ich die folgenden Artikel empfehlen:

Meine persönlichen Highlights zu Asciidoc findet ihr hier:

Code-Snippets

Hier wird Klassisch ein Code-Snippet angezeigt:

 [source, java]
 ----
 char ch = 'a';
 int ascii = ch;
 // You can also cast char to int
 int castAscii = (int) ch;

 System.out.println("The ASCII value of " + ch + " is: " + ascii);
 System.out.println("The ASCII value of " + ch + " is: " + castAscii);
 ----
Rendered Code-Snippet
char ch = 'a';
int ascii = ch;
// You can also cast char to int
int castAscii = (int) ch;

System.out.println("The ASCII value of " + ch + " is: " + ascii);
System.out.println("The ASCII value of " + ch + " is: " + castAscii);

Ganze Klasse

Es gibt die Möglichkeit ganze Klassen zu rendern (bitte das \include durch include ersetzen):

 [source,java]
 .QuotientRemainder.java
 ----
 include::../src/main/java/de/parcit/example/QuotientRemainder.java[]
 ----
QuotientRemainder.java
package de.parcit.example;

public class QuotientRemainder {

	public static void main(String[] args) {

		int dividend = 25, divisor = 4;

		int quotient = dividend / divisor;
		int remainder = dividend % divisor;

		System.out.println("Quotient = " + quotient); //$NON-NLS-1$
		System.out.println("Remainder = " + remainder); //$NON-NLS-1$
	}

}

Teile aus Klasse

Mit s.g. Tags kann man auch nur Teile aus einer Klasse in der Dokumentation anzeigen

 [source,java]
 .de.parcit.example.Largest.main
 ----
 include::../src/main/java/de/parcit/example/Largest.java[tags=mainMethod]
 ----
de.parcit.example.Largest.main
double n1 = -4.5, n2 = 3.9, n3 = 2.5;
if (n1 >= n2 && n1 >= n3) {
    System.out.println(n1 + " is the largest number.");
} else if (n2 >= n1 && n2 >= n3) {
    System.out.println(n2 + " is the largest number.");
} else {
    System.out.println(n3 + " is the largest number.");
}
Tags im Code
// tag::mainMethod[]
some Code
// end::mainMethod[]

Diagramme

 [plantuml,uml-beispiel-1,png]
 ----
 class Alpha
 class Beta
 class Gamma

 Alpha <|-- Beta
 Alpha <|-- Gamma
 ----
uml beispiel 1
Figure 1. Beispiel 1

Es werden viele weitere Diagramme unterstützt. Dazu schaut euch gerne die folgende Dokumentation zu Diagrammen an:

Formeln

 [plantuml,"beispiel_formel_1",png]
 ----
 @startmath
 Sigma_{n=1}^\infty\frac{1}{2^n}=1
 @endmath
 ----
beispiel formel 1 
 [plantuml,"beispiel_formel_2",png]
 ----
 @startuml
 :<math>int_0^1f(x)dx</math>;
 :<math>x^2+y_1+z_12^34</math>;

 note right
 Try also
 <math>d/dxf(x)=lim_(h->0)(f(x+h)-f(x))/h</math>
 <math>P(y|bb"x") or f(bb"x")+epsilon</math>
 end note

 @enduml
 ----
beispiel formel 2

Variablen

:software-version: 6.6.0

Das ist die Dokumentation zur software-Version {software-version}

Das ist die Dokumentation zur software-Version 6.6.0

Tabellen

Normale Tabelle

.Normale Tabelle
|===
|Cell in column 1, header row |Cell in column 2, header row

|Cell in column 1, row 2
|Cell in column 2, row 2

|Cell in column 1, row 3
|Cell in column 2, row 3

|Cell in column 1, row 4
|Cell in column 2, row 4
|===
Cell in column 1, header row Cell in column 2, header row

Cell in column 1, row 2

Cell in column 2, row 2

Cell in column 1, row 3

Cell in column 2, row 3

Cell in column 1, row 4

Cell in column 2, row 4

Tabelle aus CSV

 [%header,format=csv,separator=;]
 |===
 include::../src/test/resources/test_data.csv[]
 |===
Artist Track Genre

Baauer

Harlem Shake

Hip Hop

The Lumineers

Ho Hey

Folk Rock