Vis dažniau techninės dokumentacijos pasaulyje, programinės įrangos kūrime ir akademinėje bendruomenėje susiduriame su failų plėtiniu „.adoc“. Nors daugelis yra pripratę prie standartinių „Word“ dokumentų ar paprasto teksto failų, AsciiDoc formatas sparčiai populiarėja dėl savo lankstumo ir galimybės valdyti sudėtingus dokumentus taip, kaip valdomas programinis kodas. Tačiau gavus tokį failą, dažniausiai kyla praktinis klausimas: kaip jį paversti į visiems suprantamą, lengvai skaitomą ir spausdinimui tinkamą PDF formatą? Laimei, šis procesas nėra toks sudėtingas, kaip gali pasirodyti iš pirmo žvilgsnio, o įrankių pasirinkimas svyruoja nuo paprastų naršyklės plėtinių iki galingų komandinės eilutės sprendimų, leidžiančių visiškai kontroliuoti galutinį rezultatą.
Kas yra AsciiDoc ir kodėl jis naudojamas?
Prieš pradedant konvertavimo procesą, naudinga suprasti, su kuo turime reikalą. AsciiDoc yra tekstinis dokumentų formatas, skirtas rašyti pastabas, dokumentaciją, straipsnius, knygas, e-knygas ir skaidres. Jis yra semantiškai lygiavertis DocBook formatui, tačiau naudoja paprastesnę sintaksę, panašią į Markdown. Pagrindinis skirtumas nuo Markdown yra tas, kad AsciiDoc yra žymiai galingesnis: jis natūraliai palaiko lenteles, išnašas, sudėtingas bibliografijas, kryžmines nuorodas ir sąlyginį teksto atvaizdavimą.
Dėl šių priežasčių „.adoc“ failai yra standartas didelės apimties techninėje dokumentacijoje. Tačiau, kadangi tai yra „žalias“ tekstas, norint jį pateikti galutiniam vartotojui ar vadovui, būtina jį „sukompiliuoti“ į PDF. Tai užtikrina, kad dokumento formatavimas išliks toks pat, nepriklausomai nuo to, kokiame įrenginyje jis bus atidarytas.
Profesionalus būdas: Asciidoctor PDF naudojimas
Jei siekiate aukščiausios kokybės ir norite, kad jūsų PDF failas atrodytų profesionaliai – turėtų turinį, viršelį, tinkamas paraštes ir šriftus – geriausias pasirinkimas yra oficialus įrankis Asciidoctor PDF. Tai yra Ruby programavimo kalba pagrįstas įrankis, kuris konvertuoja AsciiDoc tiesiogiai į PDF, nenaudodamas tarpinių formatų.
Diegimo procesas
Norint naudoti šį metodą, jūsų kompiuteryje turi būti įdiegta Ruby aplinka. Tai gali pasirodyti techniškai sudėtinga, tačiau tai vienkartinis procesas, atveriantis plačiausias galimybes. Įdiegus Ruby, terminale ar komandinėje eilutėje reikia įvykdyti komandą gem install asciidoctor-pdf. Ši komanda atsiųs ir įdiegs visus reikalingus bibliotekų paketus.
Konvertavimas
Turėdami įrankį, konvertavimą atliksite labai paprastai. Atsidarykite terminalą aplanke, kuriame yra jūsų „.adoc“ failas, ir įveskite komandą: asciidoctor-pdf jusu_failas.adoc. Po kelių sekundžių tame pačiame aplanke atsiras „jusu_failas.pdf“. Šis metodas automatiškai sugeneruoja turinį (jei jis nurodytas faile), pritaiko numatytąjį stilių ir sutvarko visas nuorodas.
Vienas didžiausių šio metodo privalumų yra stiliaus pritaikymas. Jūs galite sukurti savo temą (YAML formatu), kurioje nurodysite įmonės spalvas, logotipus antraštėse, šriftų dydžius ir kitus vizualinius elementus, ko paprasti konverteriai dažniausiai neleidžia.
Patogiausias būdas programuotojams: Visual Studio Code
Jei nenorite dirbti su komandine eilute ir pageidaujate grafinės sąsajos, populiariausias tekstų redaktorius „Visual Studio Code“ (VS Code) siūlo puikų sprendimą. Tai yra turbūt greičiausias būdas pamatyti rezultatą tiesiogiai redaguojant tekstą.
Procesas atrodo taip:
- Atsisiųskite ir įdiekite „Visual Studio Code“.
- Kairėje meniu juostoje pasirinkite „Extensions“ (plėtiniai) ir paieškos laukelyje įveskite „AsciiDoc“.
- Įdiekite populiariausią plėtinį, kurį sukūrė Asciidoctor komanda.
- Atidarykite savo „.adoc“ failą.
- Norėdami matyti peržiūrą realiuoju laiku, paspauskite klavišų kombinaciją Ctrl+Shift+V.
Norėdami išsaugoti failą kaip PDF, dažniausiai turėsite kelis pasirinkimus priklausomai nuo jūsų sistemos konfigūracijos. Paprasčiausias būdas atidarius peržiūros langą yra paspausti dešinį pelės klavišą ir pasirinkti „Print“ arba pasinaudoti komanda „AsciiDoc: Save as PDF“. Svarbu paminėti, kad norint gauti geriausią kokybę per VS Code, vis tiek rekomenduojama fone turėti įdiegtą asciidoctor-pdf, nes plėtinys geba jį panaudoti geresniam generavimui.
Pandoc – universalus formatų keitiklis
Kalbantiems apie dokumentų konvertavimą, neįmanoma nepaminėti Pandoc. Tai yra „šveicariškas peiliukas“ failų konvertavimo pasaulyje. Jei jūsų kompiuteryje jau yra Pandoc, galite jį panaudoti ir AsciiDoc failams, tačiau čia yra keletas niuansų.
Pandoc konvertuoja failus per tarpinius formatus. Dažniausiai, norint gauti PDF per Pandoc, jums reikės papildomo PDF variklio, pavyzdžiui, „pdflatex“ arba „wkhtmltopdf“. Komanda atrodytų maždaug taip: pandoc failas.adoc -o failas.pdf.
Nors Pandoc yra galingas, konvertuojant specifinius AsciiDoc elementus (pavyzdžiui, sudėtingas lenteles ar specifinius makrokomandas), gali atsirasti formatavimo klaidų, nes Pandoc interpretacija šiek tiek skiriasi nuo oficialaus Asciidoctor standarto. Šį metodą rekomenduojama rinktis tiems, kurie nori konvertuoti ne tik į PDF, bet ir į „Word“ (.docx) ar kitus retesnius formatus.
Greitasis būdas: Naršyklės plėtiniai
Tiems, kam nereikia sudėtingo formatavimo ir kas tiesiog nori greitai perskaityti gautą failą ar atspausdinti jį „į PDF“ formatą, naršyklės plėtiniai yra puikus pasirinkimas. Tiek „Chrome“, tiek „Firefox“, tiek „Edge“ naršyklėse galite rasti plėtinį pavadinimu Asciidoctor.js Live Preview.
Įdiegus šį plėtinį ir leidus jam pasiekti vietinius failus (tai reikia nustatyti plėtinių nustatymuose), tiesiog nutempkite „.adoc“ failą į naršyklės langą. Naršyklė iškart atvaizduos suformatuotą tekstą. Tuomet galite naudoti standartinę naršyklės spausdinimo funkciją (Ctrl+P) ir pasirinkti spausdintuvą „Save to PDF“. Tai nėra idealus būdas profesionalioms ataskaitoms, nes gali dingti kai kurie spausdinimui skirti nustatymai (paraštės, puslapių numeracija), tačiau tai pats greičiausias būdas pamatyti turinį be jokio programavimo žinių.
Dažniausiai pasitaikančios problemos ir jų sprendimai
Konvertuojant dokumentus, ypač didelės apimties, dažnai susiduriama su tam tikrais iššūkiais. Štai keletas patarimų, kaip juos spręsti:
- Paveikslėliai neatvaizduojami: Tai dažniausia problema. Jei PDF faile vietoje paveikslėlio matote tik jo pavadinimą ar nuorodą, patikrinkite, ar teisingai nurodytas paveikslėlių aplankas. AsciiDoc faile dažnai naudojamas atributas :imagesdir:. Įsitikinkite, kad kelias iki paveikslėlių yra reliatyvus jūsų konvertuojamam failui.
- Lietuviškos raidės: Jei vietoje specifinių simbolių matote kvadratėlius, problema yra šriftuose. Oficialus Asciidoctor PDF naudoja šriftus, kurie paprastai palaiko UTF-8, tačiau naudojant senesnes versijas ar specifines temas, gali tekti nurodyti šriftą, turintį pilną Baltijos šalių simbolių palaikymą.
- Kodo blokai netelpa į puslapį: Jei dokumentacijoje yra ilgų programinio kodo eilučių, jos gali būti nukirstos. Sprendimas yra naudoti atributą, kuris automatiškai perkelia eilutes, arba sumažinti kodo šrifto dydį globaliuose nustatymuose.
Dažniausiai užduodami klausimai (FAQ)
Ar galima konvertuoti .adoc failą į PDF naudojant „Microsoft Word“?
Tiesiogiai – ne. „Word“ neatidaro .adoc failų. Tačiau galite konvertuoti .adoc į .docx naudodami Pandoc (pandoc failas.adoc -o failas.docx), atidaryti gautą failą su „Word“ ir tada išsaugoti jį kaip PDF. Tai naudinga, jei prieš generuojant PDF reikia atlikti rankinius redagavimus.
Ar Asciidoctor įrankiai yra mokami?
Ne, dauguma pagrindinių įrankių, įskaitant Asciidoctor, Asciidoctor PDF ir VS Code plėtinius, yra atviro kodo ir visiškai nemokami.
Kuo skiriasi HTML versijos spausdinimas į PDF nuo Asciidoctor PDF generavimo?
Spausdinant HTML versiją per naršyklę, gaunate „web“ puslapio kopiją. Joje gali nebūti tinkamų puslapių lūžių, turinio nuorodų (kurios veiktų pačiame PDF), ir spaudos kokybės. Asciidoctor PDF generuoja failą tiesiogiai pagal PDF specifikacijas, todėl užtikrina tikslius puslapių lūžius, veikiantį turinį ir profesionalų maketavimą.
Ar galiu sujungti kelis .adoc failus į vieną PDF?
Taip. Paprastai tam sukuriamas vienas pagrindinis „master.adoc“ failas, kuriame naudojama komanda include::skyrius.adoc[]. Konvertuojant pagrindinį failą, visi įtraukti failai automatiškai sujungiami į vieną vientisą dokumentą.
AsciiDoc privalumai techninėje dokumentacijoje
Pasirinkimas naudoti AsciiDoc ir vėliau konvertuoti jį į PDF nėra atsitiktinis mados reikalas. Tai yra strateginis sprendimas, leidžiantis taikyti „Docs as Code“ (dokumentacija kaip kodas) praktiką. Laikydami dokumentus paprasto teksto formatu versijų kontrolės sistemose (kaip „Git“), komandos gali sekti pakeitimų istoriją, atlikti peržiūras (Code Reviews) ir automatizuoti PDF generavimą.
Tai reiškia, kad kiekvieną kartą atnaujinus programinę įrangą, serveris gali automatiškai sugeneruoti naujausią vartotojo vadovo PDF versiją be jokio žmogaus įsikišimo. Nors pradinis konfigūravimas ir įrankių perpratimas reikalauja šiek tiek laiko, ilgalaikėje perspektyvoje tai sutaupo šimtus valandų, kurios būtų praleistos rankiniu būdu formatuojant dokumentus tekstų redaktoriuose. Gebėjimas valdyti šiuos konvertavimo procesus yra vertingas įgūdis kiekvienam techniniam rašytojui ar programuotojui.
