streamalism.org

1. Bemutatkozás

Ebben a cikkben gyorsan bemutatjuk az Asciidoctor Java használatát. Bemutatjuk, hogyan lehet HTML5 vagy PDF fájlokat létrehozni egy AsciiDoc dokumentumból.

2. Mi az AsciiDoc?

Az AsciiDoc egy szöveges dokumentum formátum. Használható dokumentáció, könyvek, weboldalak, kézikönyvek és még sok más írás.

Mivel nagyon konfigurálható, az AsciiDoc dokumentumok sok más formátumba konvertálhatók, például HTML, PDF, man oldalak, EPUB és mások.

Mivel az AsciiDoc szintaxisa meglehetősen egyszerű, nagyon népszerűvé vált a különféle böngészőbővítmények, a programozási nyelvek bővítményei és más eszközök nagy támogatásával.

Ha többet szeretne megtudni az eszközről, javasoljuk, hogy olvassa el a hivatalos dokumentációt, ahol számos hasznos forrást talál a megfelelő szintaxis elsajátításához és az AsciiDoc dokumentum más formátumokba történő exportálásának módszereihez.

3. Mi az Asciidoctor?

Asciidoctor a szövegfeldolgozó AsciiDoc dokumentumok konvertálásához HTML, PDF és más formátumokba. Ruby-ban írva és RubyGem-ként csomagolva.

Mint fent említettük, az AsciiDoc egy nagyon népszerű formátum a dokumentumok megírásához, így az Asciidoctor programot könnyen megtalálhatja standard csomagként számos GNU Linux disztribúcióban, például az Ubuntu, a Debian, a Fedora és az Arch között.

Mivel az Asciidoctor alkalmazást szeretnénk használni a JVM-en, beszélni fogunk az AsciidoctorJ-ról - ami a Java-val rendelkező Asciidoctor.

4. Függőségek

Az AsciidoctorJ csomag felvétele alkalmazásunkba az alábbiak szerint történik pom.xml bejegyzés szükséges:

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

A könyvtárak legújabb verziói megtalálhatók itt és itt.

5. AsciidoctorJ API

Az AsciidoctorJ belépési pontja a Asciidoctor Java felület.

Ezek a módszerek a következők:

• alakítani - elemzi az AsciiDoc dokumentumot a Húr vagy Folyam és átalakítja a megadott formátumra
• convertFile - elemzi az AsciiDoc dokumentumot egy biztosítottból File objektumot, és átalakítja a megadott formátumra
• convertFiles - ugyanaz, mint az előző, de a metódus többszöröset is elfogad File tárgyakat
• convertDirectory - elemzi az összes AsciiDoc dokumentumot a megadott mappában, és átalakítja a megadott formátumra

5.1. API használata a kódban

Annak létrehozásához Asciidoctor Például be kell szereznie a példányt a megadott gyári módszerből:

importál statikus org.asciidoctor.Asciidoctor.Factory.create; import org.asciidoctor.Asciidoctor; .. // valamilyen kód .. Asciidoctor asciidoctor = create (); 

A letöltött példánnyal nagyon egyszerűen konvertálhatjuk az AsciiDoc dokumentumot:

Karakterlánc kimenet = asciidoctor .convert ("Hello _Baeldung_!", Új HashMap ());

Ha szöveges dokumentumot akarunk konvertálni a fájlrendszerből, akkor a convertFile módszer:

Karakterlánc kimenet = asciidoctor .convertFile (új Fájl ("baeldung.adoc"), új HashMap ()); 

Több fájl konvertálásához a convertFiles módszer elfogadja Lista objektum első paraméterként, és a Húr tárgyakat.

Érdekesebb, hogy hogyan lehet konvertálni egy egész könyvtárat az AsciidoctorJ segítségével.

Ahogy fent említettük, egy teljes könyvtár konvertálásához hívnunk kell a convertDirectory módszer. Ez beolvassa a megadott elérési utat, és megkeres minden AsciiDoc kiterjesztésű fájlt (.adoc, .ad, .asciidoc, .asc), és átalakítja azokat. Az összes fájl beolvasásához a DirectoryWalker meg kell adni a módszert.

Jelenleg az Asciidoctor az említett felület két beépített megvalósítását biztosítja:

• AsciiDocDirectoryWalker - konvertálja az adott mappa és annak almappáinak összes fájlját. Az összes „_” betűvel kezdődő fájlt figyelmen kívül hagyja
• GlobDirectoryWalker - konvertálja az adott mappa összes fájlját egy glob kifejezést követve

Karakterlánc [] eredmény = asciidoctor.convertDirectory (új AsciiDocDirectoryWalker ("src / asciidoc"), új HashMap ()); 

Is, meghívhatjuk a convert metódust a feltétellel java.io.Reader és java.io.író interfészek.Olvasó interfészt használják forrásként, és Író interfészt használnak konvertált adatok írásához:

FileReader olvasó = new FileReader (új File ("minta.adoc")); StringWriter író = new StringWriter (); asciidoctor.convert (olvasó, író, opciók (). asMap ()); StringBuffer htmlBuffer = író.getBuffer ();

5.2. PDF-generálás

Ha PDF fájlt akarunk létrehozni Asciidoc dokumentumból, meg kell adnunk a létrehozott fájl típusát az opciókban. Ha kicsit alaposabban megnézi az előző példákat, akkor észreveszi, hogy bármely konvertálási módszer második paramétere a Térkép - amely opciós objektumot képvisel.

Az in_place opciót igazra állítjuk, hogy a fájlunkat automatikusan létrehozzák és elmentse a fájlrendszerbe:

Térképopciók = opciók () .inPlace (true) .backend ("pdf") .asMap (); String outfile = asciidoctor.convertFile (új Fájl ("baeldung.adoc"), opciók);

6. Maven plugin

Az előző részben bemutattuk, hogyan tudunk PDF-fájlokat létrehozni közvetlenül a saját Java-implementációval. Ebben a részben bemutatjuk, hogyan lehet PDF fájlt előállítani a Maven összeállításakor. Simiar pluginok léteznek a Gradle és Ant számára.

A PDF-generálás engedélyezéséhez a build során hozzá kell adnia ezt a függőséget a pom.xml:

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

A Maven plugin-függőség legújabb verziója itt található.

6.1. Használat

A beépülő modul használatához meg kell adnia a pom.xml:

   output-html generál-erőforrások folyamat-asciidoc 

Mivel a plugin nem fut egyetlen konkrét fázisban sem, akkor azt a fázist kell beállítania, ahová el szeretné indítani.

Az Asciidoctorj pluginhoz hasonlóan itt is használhatunk különféle lehetőségeket a PDF létrehozásához.

Vessünk egy gyors pillantást az alapvető lehetőségekre, miközben további lehetőségeket talál a dokumentációban:

• sourceDirectory - annak a könyvtárnak a helye, ahol Asciidoc dokumentumokkal rendelkezik
• kimeneti könyvtár - annak a könyvtárnak a helye, ahol a létrehozott PDF fájlokat tárolni kívánja
• háttér - az Asciidoctor kimenetének típusa. A PDF előállításához állítsa be a pdf-et

Ez egy példa az alapvető opciók meghatározására a beépülő modulban:

  src / main / doc target / docs pdf 

A build futtatása után a PDF fájlok megtalálhatók a megadott kimeneti könyvtárban.

7. Következtetés

Annak ellenére, hogy az AsciiDoc nagyon könnyen használható és érthető, nagyon hatékony eszköz a dokumentációk és egyéb dokumentumok kezelésére.

Ebben a cikkben bemutattunk egy egyszerű módszert HTML és PDF fájlok előállítására AsciiDoc dokumentumból.

A kód a GitHub oldalon található.