streamalism.org

1. Úvod

V tomto článku stručne predstavíme, ako používať Asciidoctor s Javou. Ukážeme si, ako vygenerovať HTML5 alebo PDF z dokumentu AsciiDoc.

2. Čo je AsciiDoc?

AsciiDoc je formát textového dokumentu. Môže byť použitý na písanie dokumentácie, kníh, webových stránok, manuálových stránok a mnohých ďalších.

Pretože je veľmi konfigurovateľný, dokumenty AsciiDoc je možné prevádzať do mnohých ďalších formátov, ako sú HTML, PDF, manuálové stránky, EPUB a ďalšie.

Pretože syntax AsciiDoc je celkom jednoduchá, stala sa veľmi populárnou s veľkou podporou rôznych doplnkov prehľadávača, doplnkov pre programovacie jazyky a ďalších nástrojov.

Ak sa chcete dozvedieť viac informácií o tomto nástroji, odporúčame vám prečítať si oficiálnu dokumentáciu, kde nájdete veľa užitočných zdrojov na získanie správnej syntaxe a metód na exportovanie dokumentu AsciiDoc do iných formátov.

3. Čo je Asciidoctor?

Asciidoctor je a textový procesor na prevod dokumentov AsciiDoc do HTML, PDF a ďalších formátov. Je napísaný v Ruby a zabalený ako RubyGem.

Ako už bolo spomenuté vyššie, AsciiDoc je veľmi populárny formát na písanie dokumentácie, takže Asciidoctor môžete ľahko nájsť ako štandardný balík v mnohých distribúciách GNU Linux, ako sú Ubuntu, Debian, Fedora a Arch.

Pretože chceme použiť Asciidoctor na JVM, povieme si niečo o AsciidoctorJ - čo je Asciidoctor s Javou.

4. Závislosti

Ak chcete do našej aplikácie zahrnúť balík AsciidoctorJ, postupujte nasledovne pom.xml je potrebné zadať:

 org.asciidoctor asciidoctorj 1.5.5 org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.15 

Najnovšie verzie knižníc nájdete tu a tu.

5. AsciidoctorJ API

Vstupným bodom pre AsciidoctorJ je Asciidoctor Rozhranie Java.

Ide o tieto metódy:

• konvertovať - analyzuje dokument AsciiDoc z a String alebo Prúd a prevedie ho na poskytnutý typ formátu
• convertFile - analyzuje AsciiDoc dokument z poskytnutej Súbor objekt a prevedie ho na poskytnutý typ formátu
• convertFiles - rovnaké ako predchádzajúce, ale metóda akceptuje viac Súbor predmety
• convertDirectory - analyzuje všetky dokumenty AsciiDoc v poskytnutom priečinku a prevádza ich na zadaný typ formátu

5.1. Využitie API v kóde

Ak chcete vytvoriť Asciidoctor inštanciu, musíte inštanciu načítať z poskytnutej továrenskej metódy:

importovať statický org.asciidoctor.Asciidoctor.Factory.create; import org.asciidoctor.Asciidoctor; .. // nejaký kód .. Asciidoctor asciidoctor = create (); 

Vďaka načítanej inštancii môžeme dokument AsciiDoc previesť veľmi ľahko:

Reťazcový výstup = asciidoctor .convert ("Hello _Baeldung_!", Nový HashMap ());

Ak chceme previesť textový dokument zo súborového systému, použijeme convertFile metóda:

Reťazcový výstup = asciidoctor .convertFile (nový súbor ("baeldung.adoc"), nový HashMap ()); 

Na konverziu viacerých súborov slúži convertFiles metóda akceptuje Zoznam objekt ako prvý parameter a vráti polia String predmety.

Zaujímavejšie je, ako previesť celý adresár pomocou AsciidoctorJ.

Ako už bolo spomenuté vyššie, na prevedenie celého adresára by sme mali zavolať convertDirectory metóda. Toto naskenuje zadanú cestu a vyhľadá všetky súbory s príponami AsciiDoc (.adoc, .ad, .asciidoc, .asc) a prevedie ich. Na skenovanie všetkých súborov slúži inštancia súboru DirectoryWalker by mali byť poskytnuté metóde.

V súčasnosti Asciidoctor poskytuje dve zabudované implementácie uvedeného rozhrania:

• AsciiDocDirectoryWalker - prevádza všetky súbory daného priečinka a jeho podpriečinkov. Ignoruje všetky súbory začínajúce sa „_“
• GlobDirectoryWalker - previesť všetky súbory z daného priečinka podľa globálneho výrazu

Reťazec [] result = asciidoctor.convertDirectory (nový AsciiDocDirectoryWalker ("src / asciidoc"), nový HashMap ()); 

Tiež môžeme zavolať metódu prevodu s poskytnutou java.io. Čítačka a java.io.Spisovateľ rozhrania.Čitateľ - ako zdroj sa používa rozhranie a - Spisovateľ rozhranie sa používa na zápis prevedených údajov:

Čítačka FileReader = nový FileReader (nový súbor ("sample.adoc")); Zapisovateľ StringWriter = nový StringWriter (); asciidoctor.convert (čitateľ, spisovateľ, options (). asMap ()); StringBuffer htmlBuffer = writer.getBuffer ();

5.2. Generovanie PDF

Ak chcete vygenerovať súbor PDF z dokumentu Asciidoc, musíme v možnostiach určiť typ vygenerovaného súboru. Ak sa podrobnejšie pozriete na predchádzajúce príklady, všimnete si, že druhý parameter akejkoľvek metódy prevodu je a Mapa - ktorý predstavuje objekt možností.

Nastavíme možnosť in_place na true, aby sa náš súbor automaticky generoval a ukladal do súborového systému:

Možnosti mapy = options () .inPlace (true). Backend ("pdf") .asMap (); String outfile = asciidoctor.convertFile (nový súbor ("baeldung.adoc"), možnosti);

6. Doplnok Maven

V predchádzajúcej časti sme si ukázali, ako môžeme vygenerovať súbor PDF priamo s vašou vlastnou implementáciou v prostredí Java. V tejto časti si ukážeme, ako vygenerovať súbor PDF počas zostavovania Maven. Podobné doplnky existujú pre Gradle a Ant.

Ak chcete povoliť generovanie PDF počas zostavovania, musíte túto závislosť pridať do svojho pom.xml:

 org.asciidoctor asciidoctor-maven-plugin 1.5.5 org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.15 

Najnovšiu verziu závislosti doplnkov Maven nájdete tu.

6.1. Využitie

Ak chcete použiť doplnok v zostave, musíte ho definovať v pom.xml:

   output-html generate-resources process-asciidoc 

Pretože plugin nefunguje v žiadnej konkrétnej fáze, musíte nastaviť fázu, kde ho chcete spustiť.

Rovnako ako v prípade doplnku Asciidoctorj, aj tu môžeme použiť rôzne možnosti generovania PDF.

Poďme sa rýchlo pozrieť na základné možnosti, zatiaľ čo ďalšie možnosti nájdete v dokumentácii:

• sourceDirectory - umiestnenie adresára, kde máte dokumenty Asciidoc
• outputDirectory - umiestnenie adresára, kam chcete uložiť vygenerované súbory PDF
• backend - typ výstupu z Asciidoctor. Pre generovanie PDF sada pre PDF

Toto je príklad, ako definovať základné možnosti v doplnku:

  src / main / doc target / docs pdf 

Po spustení zostavenia je možné súbory PDF nájsť v určenom výstupnom adresári.

7. Záver

Aj keď je AsciiDoc veľmi ľahko použiteľný a zrozumiteľný, je to veľmi výkonný nástroj na správu dokumentácie a ďalších dokumentov.

V tomto článku sme demonštrovali jednoduchý spôsob generovania súborov HTML a PDF z dokumentu AsciiDoc.

Kód nájdete ďalej na GitHub.