Praktiske tips om bruk av Asciidoc og Antora

1. Om Asciidoc-formatet

Asciidoc er et mye utbredt format for å skrive artikler og bøker som ren tekst, med enkel "markup" for formatering og metadata som egner seg for prosessering og konvertering til ulike visningsformater, slk som html, pdf osv.

Et tekstbasert kildeformat som Asciidoc egner seg godt for versjonsstyring i git og gratis løsninger som github. Sammen med gratisverktøy for redigering og publisering, fås en brukbar gratisløsning for Nasjonalt arkitekturbibliotek som alle offentlige virksomheter uten videre kan bidra inn i, med minimal binding til spesifikke leverandører.

Blant altermativer som f.eks. Markdown, er Asciidoc valgt fordi det gir mer avanserte muligheter, samtidig som det er enkelt å komme i gang med.

Her er noen kilder til generell informasjon om Asciidoc:

2. Om Antora som plattform for samarbeid og publisering av Asciidoc-dokumenter

Antora er en open-source publiseringsløsning som støtter integrasjon og publisering av Asciidoc-innhold fra ulike git-repos, og er designet for maksimal fleksibilitet i produksjonsprosesser og brukergrensesnitt.

Større e-bøker eller biblioteker kan settes sammen av moduler i en eller flere komponenter. Filer adresseres gjennom å angi komponent og modul, ikke fysisk filplassering. Gjennom noen gitte konvensjoner og konfigurering, kan Antora selv synkronisere innholdet mot git og finne fram til fysisk filplassering for referert innhold.

Dette tillater en distribuert modell for innholdsproduksjon, med ansvar for ulike moduler fordelt på ulike redaksjoner. Tilgangsstyring kan gjøres på basis av git-repo, med en eller flere moduler i hvert repo.

Digdir har per oktober 2020 etablert et git-repo under https://gitlab.com/digdir, som kan bygges ut og lenke inn innhold fra andre git repos (kan være fra f.eks. github eller gitbucket).

Publisering gjøres inntil videre under github wiki under https://nasjonal-arkitektur.github.io.

Se også:

3. Tips om redigeringsverktøy for Asciidoc - kom i gang!

Det finnes flere brukbare verktøy for editering av Asciidoc. De fleste vil ha nytte av en editor som gir støtte til formatering og gir forhåndsvisnig av resultatet, men det er også mulig å benytte en ordinær teksteditor som f.eks. Notepad++ eller redigere tekst direkte i netleseren på Github.com.

Om du ikke har mulighet til å installere programvare på din maskin og ikke vil vente til du får hjelp av noen med administratorrettigheter, kan du forsøke å arbeide direkte i nettleseren under https://github.com/difi/nasjonal_arkitektur , uten å klone til lokalt filområde. Du kan alternativt bruke asciidoclive; ref. https://asciidoclive.com/edit/scratch/1

Anbefalt her:

  • AsciidocFX fungerer godt for editering av innhold på AsciiDoc-format, og støtter dessuten en rekke andre formater, inkl. Markdown. Last ned AsciidocFX_Windows.exe fra https://github.com/asciidocfx/AsciidocFX/releases/ og kjør denne filen for å insatllere. Arbeid så lokalt etter å ha klonet Github-biblioteket.

    Merk: Oppstart av AsciidocFX kan ta litt tid, men fungerer ellers meget raskt. Html forhåndsvisning er umiddelbar og nær opp til det endelige resultatet (som Difi genererer med programmet Asciidoctor). Noen mindre bugs finnes, men programmet er i kontinuerlig utvikling.

Se også mer om AsciidocFX.

Du står helt fritt til å bruke andre verktøy om du vil.

4. Tips om konvertering mellom asciidoc og andre formater

4.1. Generelt

I det følgende gis noen tips om de mest aktuelle konverteringsbehovene og noen utvalgte verktøy.

4.2. Verktøy

4.2.1. Pandoc

Verktøyet Pandoc dekker konvertering mellom en rekke formater, og omtales gjerne som en "Swiss Army Knife".

Du finner download og enkel installeringsoppskrift for ditt OS, f.eks. Windows (64-bit), under Pandoc download and installation guide.

Pandoc kjøres fra kommandolinjen; se Pandoc User’s Guide.

4.2.2. Asciidoctor

Asciidoctor er en publiseringsløsning for asciidoc som, i tillegg til html, også støtter visse andre formater, herunder docbook.

Asciidoctor benyttes som "motor" av Antora for generering av html, men må installeres særskilt for å være tilgjengelig som CLI.

Asciidoctor installeres enklest som en gem med Rubygems.

4.2.2.1. Installer Ruby og Rubygems (om ikke allerede gjort)

Last ned og kjør siste versjon installasjonsprogram, f.eks. rubyinstaller-devkit-3.0.0-1-x64, fra https://rubyinstaller.org/downloads/.

Last ned rubygems zip-fil fra https://rubygems.org/pages/download og følg bruksanvisningen fra samme sted, dvs.

Last ned zip-fil som nevnt
Pakk ut til "en mappe"
Åpne kommandolinjevindu (f.eks. gitbash) i "en mappe"
Kjør: ruby setup.rb
4.2.2.2. Installer Asciidoctor

$ gem install asciidoctor

Successfully installed asciidoctor-2.0.12
Parsing documentation for asciidoctor-2.0.12
Installing ri documentation for asciidoctor-2.0.12
Done installing documentation for asciidoctor after 3 seconds
1 gem installed

4.3. Konvertering fra MS Word (docx) til Asciidoc

Konvertering fra MS Word (docx) til Asciidoc kan gjøres vha. Pandoc (se over).

Eksempel:

pandoc --from docx --to asciidoctor dokument.docx -o dokument.adoc --extract-media=./

Resultat: Bilder/figurer i Word lagres som PNG-filer i en undermappe ved navn media (dette mappenavnet er default).

4.4. Konvertering fra Asciidoc til pdf

Under utprøving.

Det finnes flere alternative verktøy for generering av pdf fra asciidoc, men ikke alle fungerer like bra. Se f.eks. https://stackoverflow.com/questions/50477523/how-to-convert-asciidoc-to-pdf om noen av alternativene. Husk at Antora har utvidelser til Asciidoc-syntaksen som ikke uten videre støttes av rene Asciidoc-verktøy.

Foreløpig om toolchain som går via docbook5.

Eksempel:

$ asciidoctor --backend docbook5 "Del og innhent data, verdistrøm.adoc"
$ pandoc --from docbook --to pdf "Del og innhent data, verdistrøm.xml" -o "Del og innhent data, verdistrøm.pdf"

4.5. Konvertering fra Asciidoc til docx

Forutsetninger:

  • Installert Asciidoctor

  • Installert Pandoc

Eksempel:

$ asciidoctor --backend docbook5 Felleskomponenter.adoc
$ pandoc --from docbook --to docx Felleskomponenter.xml -o Felleskomponenter.docx
Du kan også kjøre dette som en enkelt kommando, som en "kjede", slik dette er vist i https://rmoff.net/2020/04/16/converting-from-asciidoc-to-google-docs-and-ms-word/.

5. Konvensjoner for bruk av Asciidoc

5.1. Generelt

Se https://asciidoctor.org/docs/asciidoc-recommended-practices/ for generelle anbefalinger fra asciidoctor.org.

Digdir har i tillegg til dette etablert noen konvensjoner og maler i tilknytning til arkitekturverkstedet som er ment å skulle forenkle arbeidet for hver enkelt, samtidig som en får et ensartet utseende og et opplegg for å vedlikeholde metadata, tekster på flere språk, m.m.

Det er ønskelig at disse konvensjonene følges. Enkeltstående Asciidoc-artikler eller -bøker som ikke følger konvensjonene, kan likevel inkluderes i biblioteket.

5.2. Metadata og attributter

Absolutt minimum metadata for (norske) asciidoc-filer er at det oppgis følgende:

lang: <no for norsk eller en for engelsk>
doctitle: <dokumentittel>

under construction

5.3. Språkstøtte

Første linje i asciidoc-filen skal angi default språk. Angi :lang: no for norsk eller :lang: en for engelsk.

Om "lang"-attributten ikke angis, antas engelsk.

Det kan skrives tekstblokker i flere språk (engelsk og norsk) i samme fil. I så fall angis språk slik (eksempel):

ifeval::["{lang}"=="no"]
Blokk med norsk tekst...
endif::[]
ifeval::["{lang}"=="en"]
Block with english text...
endif::[]

Her vil uten videre kun ett av språkene vises, dvs. enten "Blokk med norsk tekst…​" eller "Block with english text…​".

Dette kan overstyres fra kommandolinjen ved generering av html (Asciidoctor attributter), slik at det f.eks. kan genereres en komplett samling av engelske dokumenter.

Ved oversettelse til annet språk, kan det angis hvilket språk det er oversatt fra. En kan da benytte attributten difi_orig_language.

Attributten difi_translation_status kan benyttes for å angi om oversettelsen er komplett (complete), delvis (incomplete) eller foreløpig manglende (missing eller bare -).

5.4. Kommentering

ifdef-direktivet kan brukes til å inkludere eller eksludere kommentarer fra visningen på en fleksibel måte.

Eksempel

Følgende Asciidoc…​

:Eriks-kommentarer:
ifdef::Eriks-kommentarer[]
#Erik 2018-08-19: Er denne beskrivelsen god nok?#
endif::[]
vil vise kommentaren slik:

Erik 2018-08-19: Er denne beskrivelsen god nok?

Det eneste som behøves for å fjerne alle Eriks kommentarer fra visningen er å kommentere ut definisjonen av attributten (to skråstreker "//" først på linjen, dvs. "//:Eriks-kommentarer:").