Slide 1

Slide 1 text

AsciiDoctor Dokumentation schreiben kann Spass machen!

Slide 2

Slide 2 text

Sebastian Hempel IT-Consulting Hempel @ithempel

Slide 3

Slide 3 text

Welche Dokumente schreiben Entwickler?

Slide 4

Slide 4 text

Warum macht das Schreiben keinen Spass?

Slide 5

Slide 5 text

Was muss anders werden?

Slide 6

Slide 6 text

AsciiDoctor

Slide 7

Slide 7 text

AsciiDoc leightweight markup language erste Veröffentlichung im November 2002

Slide 8

Slide 8 text

AsciiDoctor Implementierung von AsciiDoc in Ruby erste Veröffentlichung im Januar 2013

Slide 9

Slide 9 text

= Hello, AsciiDoc! Doc Writer An introduction to http://asciidoc.org[AsciiDoc]. == First Section * item 1 * item 2 [source,ruby] puts "Hello, World!"

Slide 10

Slide 10 text

direkte Erstellung von HTML5

Slide 11

Slide 11 text

Ausgabe im DocBook Format

Slide 12

Slide 12 text

Dan Allen @mojavelinux

Slide 13

Slide 13 text

Wer nutzt AsciiDoc(tor)

Slide 14

Slide 14 text

Formatierung *fett* _kursiv_ `nicht proportional`

Slide 15

Slide 15 text

Listen * Element ** nächstes Ebene * weiteres Element

Slide 16

Slide 16 text

Checklisten - [ ] noch nicht erledigt - [*] erledigt

Slide 17

Slide 17 text

Aufzählung . erstes Element . zweites Element .. erstes Unterelement

Slide 18

Slide 18 text

Labeled Lists Label:: Beschreibung noch ein Label:: eine weitere Beschreibung

Slide 19

Slide 19 text

Zitate [quote, Bill Gates, Microsoft] ____ 640 KB are enough for everyone. ____

Slide 20

Slide 20 text

Literal Block .... Jetzt wird alles wie angegeben - ausgegeben. ....

Slide 21

Slide 21 text

Code Blöcke ---- public class EnterpriseAbstractFactory { public doSomething(int howLong) { Thread.sleep(howLong); } } ----

Slide 22

Slide 22 text

Callouts ---- public class EnterpriseAbstractFactory { <1> public doSomething(int howLong) { Thread.sleep(howLong); <2> } } ---- <1> to shoort <2> busy waiting please

Slide 23

Slide 23 text

Codeformatierung [source,java] ---- public class EnterpriseAbstractFactory { public doSomething(int howLong) { Thread.sleep(howLong); } } ----

Slide 24

Slide 24 text

Codeformatierung ohne Zeilenumbruch [source,java,options="nowrap"] ---- public class EnterpriseAbstractFactory { public doSomething(int howLong) { if (checkSomeThingThatLeadsToAVeryLongLine() == WE_EXPECT_EXACTLY_THIS) { Thread.sleep(howLong); } } } ----

Slide 25

Slide 25 text

Tabellen |=== | Kopfzeile | mit zweiter Spalte | JDK | 8 | Java EE | 7 |===

Slide 26

Slide 26 text

Tabellen aus CSV [format="csv",options="header"] |=== Operation System,Software,Version Linux,JDK,8 NoArch,WildFly,8.1 |===

Slide 27

Slide 27 text

Einbinden von Bildern image::filename.png[A Picture,200,100]

Slide 28

Slide 28 text

Festlegung des Bilderverzeichnisses :imagesdir: ./img

Slide 29

Slide 29 text

Inhaltsverzeichnis :toc: :toclevels: 3 :toc-title: Inhaltsverzeichnis :toc-placement!: :sectanchors: :numbered: toc::[]

Slide 30

Slide 30 text

Integration in Build-Tool

Slide 31

Slide 31 text

Integration des Plugins ... org.asciidoctor asciidoctor-maven-plugin 0.1.4 ... ...

Slide 32

Slide 32 text

Konfiguration des Plugins ... ${basedir}/src/main/doc ${basedir}/target/docs html book ... ...

Slide 33

Slide 33 text

Aufruf des Plugins ... ... output-html generate-resources process-asciidoc ... ...

Slide 34

Slide 34 text

Integration in JavaDoc AsciiDoc statt HTML

Slide 35

Slide 35 text

Integration in JavaDoc-Erstellung org.apache.maven.plugins maven-javadoc-plugin 2.9 1.7 org.asciidoctor.Asciidoclet org.asciidoctor asciidoclet 0.1.4

Slide 36

Slide 36 text

Kommentar mit AsciiDoc /** = Example Class * * This ist an example class. * * * This is a List * * This is *bold* or _italic_. */ public class Example { private String attribute; /** * Get some attribute. * * null:: The value might be null. * other:: The name of the attribute. */ public String getAttribute() { } }

Slide 37

Slide 37 text

AsciiDoctor Plugins

Slide 38

Slide 38 text

Beispiel AsciiDoctor-Diagram Graphviz PlantUML Ditaa

Slide 39

Slide 39 text

Installation gem install asciidoctor-diagram

Slide 40

Slide 40 text

Integration #!/usr/bin/ruby require 'asciidoctor' require 'asciidoctor-diagram/plantuml' Asciidoctor.render_file('sample.adoc', :in_place => true, :safe => 'unsafe')

Slide 41

Slide 41 text

Integration ab 1.5.x Vorraussetzung: Java (JAVA_HOME) asciidoctor -r asciidoctor-diagram sample.adoc

Slide 42

Slide 42 text

Beispiel ["plantuml", "asciidoctor-diagram-classes", "png"] ---- interface BlockProcessor class DiagramBlock class DitaaBlock class PlantUmlBlock class GraphvizBlock BlockProcessor <|-- DiagramBlock DiagramBlock <|-- DitaaBlock DiagramBlock <|-- PlantUmlBlock DiagramBlock <|-- GraphvizBlock ----

Slide 43

Slide 43 text

Bildnachweis (1) Sebastian Hempel / Sebastian Hempel / CC-BY SA (2) document folders / John Keogh / CC-BY NC (3)frustration / Sybren Stüvel / CC-BY NC (4) There are years that ask questions and years that answer. / theunquietlibrarian / CC-BY NC (5) Day 9 / Jay Reed / CC-BY SA (8) Dan Allen / Dan Allen (18) puzzle / Olga Berrios / CC-BY

Slide 44

Slide 44 text

Creative Commons CC-BY SA