A pandoc segítségével Linuxon konvertálhat több mint 40 fájlformátum között. Használhatja egyszerű dokumentumok kódként rendszer létrehozására is úgy, hogy Markdown-ba ír, git-ben tárolja, és bármely támogatott formátumában közzéteszi.
Tartalomjegyzék
Dokumentumkonverzió és Dokumentumok kódként
Ha van dokumentuma valamelyik pandocban számos támogatott fájlformátum, átkonvertálni a többiek közül egy simán. Ez egy praktikus eszköz!
De a pandoc valódi ereje akkor válik nyilvánvalóvá, ha egy egyszerű docs-as-code rendszer alapjaként használja. A docs-as-code előfeltétele, hogy átvegye a szoftverfejlesztés egyes technikáit és alapelveit, és alkalmazza azokat a dokumentáció írására, különösen szoftverfejlesztési projektek esetében. Bármilyen dokumentáció kidolgozásához alkalmazhatja.
A szoftverfejlesztők kedvenc szerkesztőjüket, ill integrált fejlesztői környezet (IDE), hogy megírják programjaikat. Az általuk beírt kód szöveges fájlokba kerül mentésre. Ezek tartalmazzák a forráskód a programhoz.
Használnak a verziókezelő rendszer, vagy VCS (Git a legnépszerűbb), hogy rögzítse a forráskód változásait annak fejlesztése és továbbfejlesztése során. Ez azt jelenti, hogy a programozó a forráskódfájlok összes verziójának teljes történetével rendelkezik. Gyorsan hozzáférhet a fájl bármely korábbi verziójához. A Git a fájlokat tárolóban tárolja. Minden fejlesztő számítógépén található egy helyi adattár, valamint egy központi, megosztott, távoli tároló, amely gyakran felhőalapú.
Amikor készen állnak a program működő verziójának elkészítésére, a fordítóprogram a forráskód olvasásához és egy bináris végrehajtható fájl létrehozásához.
Ha a dokumentumokat könnyű, szövegalapú jelölőnyelven írja meg, VCS-t használhat az írás verziószabályozására. Ha készen áll egy dokumentum terjesztésére vagy közzétételére, a pandoc segítségével annyi különböző verziót hozhat létre a dokumentációból, amennyire szüksége van, beleértve a webalapú (HTML), szövegszerkesztő vagy szedet (LibreOffice, Microsoft Word, TeX), Hordozható dokumentum formátum (PDF), e-könyv (ePub), stb.
Mindezt egyetlen verzió-vezérelt, könnyű szöveges fájlkészletből is megteheti.
Pandoc telepítése
A pandoc Ubuntu telepítéséhez használja ezt a parancsot:
sudo apt-get install pandoc
Fedorán a következő parancsra van szüksége:
sudo dnf install pandoc
A Manjaro-n be kell írnia:
sudo pacman -Syu pandoc
A –version opcióval ellenőrizheti, hogy melyik verziót telepítette:
pandoc --version
Pandoc használata fájlok nélkül
Ha a pandoc parancssori beállítások nélkül használja, akkor a gépelt bevitelt is elfogadja. Csak nyomja meg a Ctrl+D billentyűket, hogy jelezze, hogy befejezte a gépelést. A pandoc elvárja, hogy Markdown formátumban gépeljen, és HTML kimenetet generál.
Nézzünk egy példát:
pandoc
Beírtunk néhány sort a Markdownból, és hamarosan leütjük a Ctrl+D billentyűkombinációt.
Amint megtesszük, a pandoc létrehozza az egyenértékű HTML-kimenetet.
Ahhoz azonban, hogy bármi hasznosat tegyünk a pandoc segítségével, valóban fájlokat kell használnunk.
Markdown alapjai
A Markdown egy könnyű jelölőnyelv, és bizonyos karakterek különleges jelentést kapnak. Markdown fájl létrehozásához használhat egyszerű szövegszerkesztőt.
A Markdown könnyen olvasható, mivel nincsenek vizuálisan nehézkes címkék, amelyek elvonják a figyelmet a szövegről. A Markdown dokumentumok formázása hasonlít az általa képviselt formázásra. Az alábbiakban néhány alapelemet olvashat:
Ha a szöveget dőlt betűvel szeretné kiemelni, tegye csillagba. *Ezt hangsúlyozzuk*
A félkövér szöveghez használjon két csillagot. **Ez félkövérrel lesz szedve**
A címsorokat a számjel/hash jel (#) jelöli. A szöveget szóköz választja el a hash-től. Használjon egy hash-t a legfelső szintű címsorhoz, kettőt a második szinthez és így tovább.
Felsorolásos lista létrehozásához kezdje a lista minden sorát csillaggal, és szúrjon be egy szóközt a szöveg elé.
Számozott lista létrehozásához minden sort kezdjen egy számjeggyel, majd egy ponttal, majd szúrjon be egy szóközt a szöveg elé.
Hiperhivatkozás létrehozásához tegye a webhely nevét szögletes zárójelbe ([]), és az URL-t zárójelben [()] így: [Link to How to Geek](https://www.wdzwdz.com/).
Kép beszúrásához írjon be egy felkiáltójelet közvetlenül a zárójelek elé (![]). A zárójelbe írjon be bármilyen alternatív szöveget a képhez. Ezután tegye zárójelbe a kép elérési útját [()“]. Íme egy példa: .
A következő részben mindezekre további példákat mutatunk be.
Fájlok konvertálása
A fájlok konvertálása egyszerű. A pandoc általában ki tudja számítani, hogy milyen fájlformátumokkal dolgozik a fájlnevükből. Itt egy HTML-fájlt fogunk generálni egy Markdown-fájlból. Az -o (output) opció megmondja a pandocnak a létrehozni kívánt fájl nevét:
pandoc -o sample.html sample.md
A minta Markdown fájlunk, a sample.md tartalmazza a Markdown rövid részét, amely az alábbi képen látható.
Létrejön egy sample.html nevű fájl. Ha duplán kattintunk a fájlra, az alapértelmezett böngészőnk megnyitja azt.
Most generáljunk egy Nyissa meg a Dokumentumformátumot szöveges dokumentumot, amelyben meg tudjuk nyitni LibreOffice Writer:
pandoc -o sample.odt sample.md
Az ODT-fájl tartalma megegyezik a HTML-fájllal.
Egy ügyes érintés a kép alternatív szövege, amely szintén automatikusan generál egy feliratot az ábrához.
Fájlformátumok megadása
A -f (from) és -t (to) opciók arra szolgálnak, hogy megmondják a pandoc-nak, hogy mely fájlformátumokat szeretné konvertálni. Ez akkor lehet hasznos, ha olyan fájlformátummal dolgozik, amely megosztja a fájlkiterjesztést más kapcsolódó formátumokkal. Például, TeX, és Latex mindkettő a „.tex” kiterjesztést használja.
Az -s (önálló) opciót is használjuk, így a pandoc minden olyan LaTeX preambulumot generál, amely ahhoz szükséges, hogy egy dokumentum teljes, önálló és jól formázott LaTeX dokumentum legyen. Az -s (önálló) opció nélkül a kimenet továbbra is jól formázott LaTeX lenne, amelyet egy másik LaTeX dokumentumba lehetne beilleszteni, és nem elemezné megfelelően önálló LaTeX dokumentumként.
A következőket írjuk be:
pandoc -f markdown -t latex -s -o sample.tex sample.md
Ha megnyitja a „sample.tex” fájlt egy szövegszerkesztőben, látni fogja a generált LaTeX-et. Ha rendelkezik LaTeX szerkesztővel, megnyithatja a TEX fájlt, hogy megtekinthesse a LaTeX betűszedési parancsok értelmezésének előnézetét. Ha az ablakot összezsugorította, hogy illeszkedjen az alábbi képhez, a kijelző szűknek tűnt, de a valóságban rendben volt.
Az úgynevezett LaTeX szerkesztőt használtuk Texmaker. Ha Ubuntuba szeretné telepíteni, írja be a következőket:
sudo apt-get install texmaker
A Fedorában a parancs a következő:
sudo dnf install texmaker
Manjaroban használja:
sudo pacman -Syu texmaker
Fájlok konvertálása sablonokkal
Valószínűleg kezdi megérteni a pandoc által nyújtott rugalmasságot. Egyszer írhatsz és szinte bármilyen formátumban publikálhatsz. Ez nagy bravúr, de a dokumentumok kissé vaníliásnak tűnnek.
A sablonok segítségével megszabhatja, hogy a pandoc milyen stílusokat használjon dokumentumok generálásakor. Például megmondhatja a pandoc-nak, hogy használja az a-ban meghatározott stílusokat Lépcsőzetes stíluslapok (CSS) fájlt a –css kapcsolóval.
Létrehoztunk egy kis CSS-fájlt, amely az alábbi szöveget tartalmazza. Egy stílusban módosítja a szintfejléc feletti és alatti térközt. Ezenkívül a szöveg színét fehérre, a háttérszínt pedig kékre változtatja:
h1 {
color: #FFFFFF;
background-color: #3C33FF;
margin-top: 0px;
margin-bottom: 1px;
}
A teljes parancs alább található – vegye figyelembe, hogy az önálló opciót (-s) is használtuk:
pandoc -o sample.html -s --css sample.css sample.md
A pandoc a minimalista CSS-fájlunk egyetlen stílusát használja, és alkalmazza az első szintű fejlécre.
Egy másik finomhangolási lehetőség, amellyel HTML-fájlokkal dolgozik, a HTML-jelölés szerepeltetése a Markdown-fájlban. Ez szabványos HTML-jelölésként átkerül a generált HTML-fájlba.
Ezt a technikát azonban csak akkor kell fenntartani, amikor csak HTML-kimenetet generál. Ha több fájlformátummal dolgozik, a pandoc figyelmen kívül hagyja a nem HTML-fájlok HTML-jelölését, és azokat szövegként továbbítja.
Megadhatjuk, hogy mely stílusokat használjuk az ODT fájlok generálásakor. Nyisson meg egy üres LibreOffice Writer dokumentumot, és állítsa be a címsort és a betűstílust az igényeinek megfelelően. Példánkban fejlécet és láblécet is hozzáadtunk. Mentse el a dokumentumot „odt-template.odt” néven.
Ezt most sablonként használhatjuk a –reference-doc opcióval:
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
Hasonlítsa össze ezt a korábbi ODT példával. Ez a dokumentum más betűtípust használ, színes fejléceket, valamint fejlécet és láblécet tartalmaz. Azonban pontosan ugyanabból a „sample.md” Markdown fájlból állították elő.
Referencia dokumentumsablonok használhatók a dokumentum előállításának különböző szakaszainak jelzésére. Lehetnek például olyan sablonjai, amelyeken „Piszkozat” vagy „Ellenőrzésre” vízjel található. A véglegesített dokumentumhoz vízjel nélküli sablont használnak.
PDF-ek generálása
Alapértelmezés szerint a pandoc a LaTeX PDF motort használja a PDF fájlok létrehozásához. A legegyszerűbb módja annak, hogy megbizonyosodjunk arról, hogy a megfelelő LaTeX-függőségek elégedettek, egy LaTeX-szerkesztő telepítése, például a Texmaker.
Ez azonban elég nagy telepítés – a Tex és a LaTeX egyaránt elég izmos. Ha a merevlemezen korlátozott a hely, vagy tudja, hogy soha nem fog TeX-et vagy LaTeX-et használni, érdemes lehet ODT-fájlt létrehozni. Ezután egyszerűen nyissa meg a LibreOffice Writerben, és mentse el PDF-ként.
Dokumentumok kódként
A Markdown írási nyelvként való használatának számos előnye van, beleértve a következőket:
Az egyszerű szöveges fájlokkal való munkavégzés gyors: gyorsabban töltődnek be, mint a hasonló méretű szövegszerkesztő fájlok, és gyorsabban mozognak a dokumentumban. Sok szerkesztő, köztük a gedit, a Vim és az Emacs, szintaktikai kiemelést használ a Markdown szöveggel.
A dokumentumok összes verziójának idővonala lesz: Ha a dokumentációt VCS-ben, például Gitben tárolja, könnyen láthatja a különbségeket ugyanazon fájl két verziója között. Ez azonban csak akkor működik igazán, ha a fájlok egyszerű szövegesek, mivel a VCS elvárja, hogy ezzel működjön.
A VCS rögzítheti, hogy ki és mikor hajtott végre változtatásokat: Ez különösen akkor hasznos, ha gyakran dolgozik másokkal nagy projekteken. Ezenkívül központi tárhelyet biztosít maguknak a dokumentumoknak. Számos felhőalapú Git-szolgáltatás, például a GitHub, GitLab, és BitBucket, díjszabási modelljeikben ingyenes szintek találhatók.
Többféle formátumban is előállíthatja dokumentumait: Néhány egyszerű shell-szkripttel előhívhatja a stílusokat a CSS-ből és a referenciadokumentumokból. Ha a dokumentumokat olyan VCS-tárolóban tárolja, amely integrálható a Folyamatos integráció és folyamatos telepítés (CI/CD) platformokon, ezek automatikusan generálhatók a szoftver elkészítésekor.
Végső gondolatok
Ezen belül sokkal több lehetőség és funkció található pandoc mint amit itt leírtunk. A legtöbb fájltípus átalakítási folyamata módosítható és finomhangolható. Ha többet szeretne megtudni, nézze meg a kiváló példákat a hivatalos (és rendkívül részletes) oldalon. pandoc weboldal.