Cum să utilizați pandoc pentru a converti fișiere pe linia de comandă Linux

Puteți utiliza pandoc pe Linux pentru a converti între mai mult de 40 de formate de fișiere. De asemenea, îl puteți folosi pentru a crea un sistem docs-as-code simplu, scriind în Markdown, stocând în git și publicând în oricare dintre formatele acceptate.

Conversia documentelor și Documente ca cod

Dacă aveți un document în oricare dintre multele formate de fișier acceptate de pandoc's , convertirea lui în oricare dintre celelalte este o simplă simplă. Acesta este un instrument la îndemână!

Dar puterea reală a pandoc -ului devine evidentă atunci când îl folosiți ca bază a unui sistem simplu docs-as-code. Premisa docs-as-code este de a adopta unele dintre tehnicile și principiile dezvoltării software și de a le aplica la scrierea documentației, în special pentru proiectele de dezvoltare software. Îl poți aplica totuși la dezvoltarea oricărui tip de documentație.

Dezvoltatorii de software folosesc editorul preferat sau mediul de dezvoltare integrat (IDE) pentru a-și scrie programele. Codul pe care îl introduc este salvat în fișiere text. Acestea conțin codul sursă pentru program.

Ei folosesc un sistem de control al versiunilor sau VCS (Git este cel mai popular), pentru a capta modificările aduse codului sursă pe măsură ce este dezvoltat și îmbunătățit. Aceasta înseamnă că programatorul are un istoric complet al tuturor versiunilor fișierelor cu codul sursă. El sau ea poate accesa rapid orice versiune anterioară a unui fișier. Git stochează fișiere într-un depozit. Există un depozit local pe computerul fiecărui dezvoltator și un depozit central, partajat, la distanță, care este adesea găzduit în cloud.

Când sunt gata să producă o versiune de lucru a programului, folosesc un compilator pentru a citi codul sursă și a genera un executabil binar.

Scriind documentele într-un limbaj de marcare ușor, bazat pe text, puteți utiliza un VCS pentru a vă controla versiunea scrisului. Când sunteți gata să distribuiți sau să publicați un document, puteți utiliza pandoc pentru a genera câte versiuni diferite ale documentației dvs. aveți nevoie, inclusiv bazate pe web (HTML), procesate de text sau tipărite (LibreOffice, Microsoft Word, TeX) , format de document portabil (PDF), carte electronică (ePub) și așa mai departe.

Puteți face toate acestea dintr-un set de fișiere text ușoare controlate de versiune.

Instalarea pandoc

Pentru a instala pandoc pe Ubuntu, utilizați această comandă:

 sudo apt-get install pandoc 

Pe Fedora, comanda de care aveți nevoie este următoarea:

 sudo dnf install pandoc 

Pe Manjaro, trebuie să tastați:

 sudo pacman -Syu pandoc 

Puteți verifica ce versiune ați instalat utilizând opțiunea --version :

 pandoc --versiune 

Folosind pandoc fără fișiere

Dacă utilizați pandoc fără opțiuni de linie de comandă, acceptă, de asemenea, introducerea tastata. Doar apăsați Ctrl+D pentru a indica că ați terminat de tastat. pandoc se așteaptă să tastați în format Markdown și generează rezultate HTML.

Să ne uităm la un exemplu:

 pandoc 

Am tastat câteva rânduri de Markdown și suntem pe cale să apăsăm Ctrl+D.

De îndată ce o facem, pandoc generează rezultatul HTML echivalent.

Pentru a face ceva util cu pandoc , totuși, trebuie să folosim fișiere.

Noțiuni de bază pentru Markdown

Markdown este un limbaj de marcare ușor, iar anumitor caractere li se acordă o semnificație specială. Puteți utiliza un editor de text simplu pentru a crea un fișier Markdown.

Markdown poate fi citit cu ușurință, deoarece nu există etichete greoaie din punct de vedere vizual care să distragă atenția de la text. Formatarea în documentele Markdown seamănă cu formatarea pe care o reprezintă. Mai jos sunt câteva dintre elementele de bază:

• Pentru a evidenția textul cu caractere cursive , împachetați-l cu asteriscuri. *This will be emphasized*
• Pentru textul aldine , utilizați două asteriscuri. **This will be in bold**
• Titlurile sunt reprezentate de semnul numeric/marca de simbol ( # ). Textul este separat de hash printr-un spațiu. Utilizați un hash pentru un titlu de nivel superior, doi pentru un al doilea nivel și așa mai departe.
• Pentru a crea o listă cu marcatori, începeți fiecare rând a listei cu un asterisc și introduceți un spațiu înaintea textului.
• Pentru a crea o listă numerotată, începeți fiecare rând cu o cifră urmată de un punct, apoi introduceți un spațiu înaintea textului.
• Pentru a crea un hyperlink, includeți numele site-ului între paranteze drepte ( [] ) și adresa URL în paranteze [ () ] astfel: [Link to How to Geek](https://www.howtogeek.com/) .
• Pentru a insera o imagine, introduceți un semn de exclamare imediat înaintea parantezelor ( ![] ). Introduceți orice text alternativ pentru imagine între paranteze. Apoi, includeți calea către imagine între paranteze [ () “]. Iată un exemplu: ![The Geek](HTG.png) .

Vom acoperi mai multe exemple din toate acestea în secțiunea următoare.

LEGATE: Ce este Markdown și cum îl folosiți?

Conversia fișierelor

Conversiile fișierelor sunt simple. pandoc poate determina de obicei formatele de fișiere cu care lucrați din numele lor de fișiere. Aici, vom genera un fișier HTML dintr-un fișier Markdown. Opțiunea -o (ieșire) îi spune pandoc numele fișierului pe care dorim să-l creăm:

 pandoc -o sample.html sample.md 

Exemplul nostru de fișier Markdown, sample.md, conține secțiunea scurtă a Markdown prezentată în imaginea de mai jos.

Este creat un fișier numit sample.html. Când facem dublu clic pe fișier, browserul nostru implicit îl va deschide.

Acum, să generăm un document text în format Open Document pe care îl putem deschide în LibreOffice Writer:

 pandoc -o sample.odt sample.md 

Fișierul ODT are același conținut ca și fișierul HTML.

O atingere îngrijită este textul alternativ pentru imagine este, de asemenea, folosit pentru a genera automat o legendă pentru figură.

Specificarea formatelor de fișiere

Opțiunile -f (de la) și -t (către) sunt folosite pentru a spune pandoc ce formate de fișiere doriți să convertiți din și către. Acest lucru poate fi util dacă lucrați cu un format de fișier care partajează o extensie de fișier cu alte formate înrudite. De exemplu, TeX și LaTeX folosesc ambele extensia „.tex”.

De asemenea, folosim opțiunea -s (autonomă), astfel încât pandoc va genera tot preambulul LaTeX necesar pentru ca un document să fie un document LaTeX complet, autonom și bine format. Fără opțiunea -s (autonomă), rezultatul ar fi în continuare LaTeX bine format, care ar putea fi introdus într-un alt document LaTeX, nu ar fi analizat corect ca document LaTeX autonom.

Introducem următoarele:

 pandoc -f markdown -t latex -s -o sample.tex sample.md 

Dacă deschideți fișierul „sample.tex” într-un editor de text, veți vedea LaTeX generat. Dacă aveți un editor LaTeX, puteți deschide fișierul TEX pentru a vedea o previzualizare a modului în care sunt interpretate comenzile de compunere LaTeX. Strângerea ferestrei pentru a se potrivi cu imaginea de mai jos a făcut ca afișajul să pară înghesuit, dar, în realitate, a fost bine.

Am folosit un editor LaTeX numit Texmaker. Dacă doriți să-l instalați în Ubuntu, introduceți următoarele:

 sudo apt-get install texmaker

În Fedora, comanda este:

 sudo dnf install texmaker

În Manjaro, utilizați:

 sudo pacman -Syu texmaker

Conversia fișierelor cu șabloane

Probabil că începi să înțelegi flexibilitatea pe care o oferă pandoc . Puteți scrie o dată și publica în aproape orice format. Este o performanță grozavă, dar documentele arată puțin vanilie.

Cu șabloane, puteți dicta ce stiluri folosește pandoc atunci când generează documente. De exemplu, puteți spune pandoc să folosească stilurile definite într-un fișier CSS (Cascading Style Sheets) cu opțiunea --css .

Am creat un mic fișier CSS care conține textul de mai jos. Schimbă spațierea de deasupra și dedesubtul antetului de nivel cu un stil. De asemenea, schimbă culoarea textului în alb și culoarea de fundal într-o nuanță de albastru:

 h1 {
  culoare: #FFFFFF;
  culoare de fundal: #3C33FF;
  margin-sus: 0px;
  margine-jos: 1px;
}

Comanda completă este mai jos - rețineți că am folosit și opțiunea independentă ( -s ):

 pandoc -o sample.html -s --css sample.css sample.md

pandoc folosește stilul unic din fișierul nostru minimalist CSS și îl aplică antetului de nivel unu.

O altă opțiune de reglare fină pe care o aveți la dispoziție atunci când lucrați cu fișiere HTML este să includeți marcajul HTML în fișierul Markdown. Acesta va fi transmis în fișierul HTML generat ca markup HTML standard.

Totuși, această tehnică ar trebui să fie rezervată atunci când generați numai rezultate HTML. Dacă lucrați cu mai multe formate de fișiere, pandoc va ignora marcajul HTML pentru fișierele non-HTML și va fi transmis acestora ca text.

Putem specifica ce stiluri sunt folosite atunci când sunt generate fișiere ODT. Deschideți un document LibreOffice Writer necompletat și ajustați titlul și stilurile fonturilor pentru a se potrivi nevoilor dvs. În exemplul nostru, am adăugat și un antet și un subsol. Salvați documentul ca „odt-template.odt”.

Acum îl putem folosi ca șablon cu opțiunea --reference-doc :

 pandoc -o sample.odt --reference-doc=odt-template.odt sample.md 

Comparați acest lucru cu exemplul ODT de mai devreme. Acest document folosește un font diferit, are anteturi colorate și include anteturi și subsoluri. Cu toate acestea, a fost generat din același fișier Markdown „sample.md”.

Șabloanele de documente de referință pot fi utilizate pentru a indica diferitele etape ale producției unui document. De exemplu, este posibil să aveți șabloane care au filigrane „Schiță” sau „Pentru revizuire”. Un șablon fără filigran ar fi utilizat pentru un document finalizat.

Generarea PDF-urilor

În mod implicit, pandoc utilizează motorul LaTeX PDF pentru a genera fișiere PDF. Cel mai simplu mod de a vă asigura că aveți dependențele LaTeX corespunzătoare satisfăcute este să instalați un editor LaTeX, cum ar fi Texmaker.

Este o instalare destul de mare, totuși — Tex și LaTeX sunt ambele destul de voluminoase. Dacă spațiul pe hard disk este limitat sau știi că nu vei folosi niciodată TeX sau LaTeX, ai putea prefera să generezi un fișier ODT. Apoi, îl puteți deschide în LibreOffice Writer și îl puteți salva ca PDF.

Docs-as-Code

Există mai multe avantaje în utilizarea Markdown ca limbaj de scriere, inclusiv următoarele:

• Lucrul în fișiere text simplu este rapid: se încarcă mai repede decât fișierele de procesor de text de dimensiuni similare și tind să se deplaseze mai repede prin document. Mulți editori, inclusiv gedit , Vim și Emacs , folosesc evidențierea de sintaxă cu textul Markdown.
• Veți avea o cronologie a tuturor versiunilor documentelor dvs.: dacă vă stocați documentația într-un VCS, cum ar fi Git, puteți vedea cu ușurință diferențele dintre oricare două versiuni ale aceluiași fișier. Cu toate acestea, acest lucru funcționează cu adevărat numai atunci când fișierele sunt text simplu, deoarece asta se așteaptă să lucreze un VCS.
• Un VCS poate înregistra cine a făcut modificări și când: Acest lucru este util mai ales dacă colaborați adesea cu alții la proiecte mari. De asemenea, oferă un depozit central pentru documentele în sine. Multe servicii Git găzduite în cloud, cum ar fi GitHub, GitLab și BitBucket, au niveluri gratuite în modelele lor de prețuri.
• Vă puteți genera documentele în mai multe formate: Cu doar câteva scripturi shell simple, puteți extrage stilurile din documentele CSS și de referință. Dacă vă stocați documentele într-un depozit VCS care se integrează cu platformele de integrare continuă și implementare continuă (CI/CD), acestea pot fi generate automat ori de câte ori este construit software-ul.

RELATE: Ce este GitHub și pentru ce este folosit?

Gânduri finale

Există mult mai multe opțiuni și caracteristici în cadrul pandoc decât ceea ce am acoperit aici. Procesele de conversie pentru majoritatea tipurilor de fișiere pot fi ajustate și reglate fin. Pentru a afla mai multe, consultați exemplele excelente de pe pagina web oficială (și extrem de detaliată) pandoc.