asciidoc: Asciidoctor og UML diagrammer

[lath]

asciidoc er fantastisk brugbart til at skrive dokumentation med.
Simpelt, og let at læse.

Lige som med LaTeX kan man også inkludere dokumenter, så man kan lave små sektioner og/eller afsnit, som til sidst inkluderes i hoveddokumentet. Skal man så flytte rundt på noget så flytter man kun linien der inkludere en asciidoc fil, som indeholder den sektion / det afsnit man vil flytte.

Mere om asciidoc (asciidoctor for at være mere specifik - den er Ruby implementationen af asciidoc):
Links:

• Asciidcoctor forside:
  http://asciidoctor.org/
• Asciidoctor dokumentation
  http://asciidoctor.org/docs/
• Asciidoctor - syntax quick reference
  http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
• AsciiDoc Writer’s Guide
  http://asciidoctor.org/docs/asciidoc-writers-guide/
• Asciidoctor User Manual
  http://asciidoctor.org/docs/user-manual/
• Asciidoctor Diagram
  Er nogle tilføjelser / plugins der giver mulighed for også at bruge:
  
  • UML diagrammer med PlantUML, http://plantuml.com:
    For eksempel, så giver denne test:
    

    Kode: Vælg alt

    @startuml
    :Main Admin: as Admin
    (Use the application) as (Use)
    
    User -> (Start)
    User --> (Use)
    
    Admin ---> (Use)
    
    note right of Admin : This is an example.
    
    note right of (Use)
      A note can also
      be on several lines
    end note
    
    note "This note is connected\nto several objects." as N2
    (Start) .. N2
    N2 .. (Use)
    @enduml
    

    
    Følgende diagram:
    
  • Du kan også bruge Graphviz diagrammer i AsciiDoc
  • Du kan bruge ditaa i AsciiDoc: http://ditaa.sourceforge.net/
  • Du kan bruge Shaape i AsciiDoc: https://github.com/christiangoltz/shaape - men jeg synes de andre ser mere spændende ud: Jeg har erfaring med at bruge Graphviz, og den gør det ret godt.
    

Asciidoctor findes i arkiverne:

Kode: Vælg alt

sudo apt-get --assume-yes install asciidoctor

men:
Den er håbløst bagud i versionsnummer:

• Asciidoctor fra Ubuntu Universe arkivet har versionsnummeret 0.1.4 i Ubuntu 14.04 LTS
• Upstream (dem der laver asciidoctor) har versionsnummeret 1.5.3 som nyeste stabile udgave.
• Note:
  Man finder versionsmummeret med:
  

  Kode: Vælg alt

  aciidoctor --vesion

  
  ... når asciidoctor er installeret.

Af den grund installerede jeg først Ruby fortolkeren fra arkiverne:

Kode: Vælg alt

sudo apt-get --assume-yes install ruby2.0

Vigtigt: Da vi her bruger Ruby 2.0 fortolkeren, så skal alle ruby CLI kommandoer i Ubuntu have suffixet(=tilføjelsen): 2.0. Eksempler på det er: gem2.0 og ruby2.0.
Derefter fyrede jeg en gem2.0 kommando af, så jeg får den nyeste nye asciidoctor, men før det skete, så kørte jeg lige:

Kode: Vælg alt

sudo apt-get --assume-yes purge asciidoctor

Hvordan du skal skrive gem kommandoen finder du på http://asciidoctor.org/docs/ web siden. Husk Ruby 2.0 CLI kommando suffixet!

/Lars