Du kan bruge Pandoc på Linux til at konvertere mellem mere end 40 filformater. Du kan også bruge det til at skabe et simpelt docs-as-code-system ved at skrive i Markdown, gemme i git og udgive i et hvilket som helst af dets understøttede formater.
Indholdsfortegnelse
Dokumentkonvertering og Docs-as-Code
Hvis du har et dokument i nogen af Pandoc’s mange understøttede filformater, at konvertere det til en af de andre er en cinch. Det er et praktisk værktøj at have!
Men den virkelige kraft af Pandoc bliver tydelig, når du bruger den som grundlag for et simpelt docs-as-code-system. Udgangspunktet for docs-as-code er at adoptere nogle af teknikkerne og principperne for softwareudvikling og anvende dem til at skrive dokumentation, især til softwareudviklingsprojekter. Du kan dog anvende det til udvikling af enhver form for dokumentation.
Softwareudviklere bruger deres foretrukne editor eller integreret udviklingsmiljø (IDE) til at skrive deres programmer. Den kode, de indtaster, gemmes i tekstfiler. Disse indeholder kildekode for programmet.
De bruger en versionskontrolsystemeller VCS (Git er den mest populære), for at fange ændringer i kildekoden, efterhånden som den udvikles og forbedres. Dette betyder, at programmøren har en komplet historik over alle versioner af kildekodefilerne. Han eller hun kan hurtigt få adgang til enhver tidligere version af en fil. Git gemmer filer i et lager. Der er et lokalt lager på hver udviklers computer og et centralt, delt fjernlager, der ofte er cloud-hostet.
Når de er klar til at producere en fungerende version af programmet, bruger de en compiler at læse kildekoden og generere en binær eksekverbar.
Ved at skrive dine dokumenter i et let, tekstbaseret markup-sprog kan du bruge en VCS til at versionsstyre din skrivning. Når du er klar til at distribuere eller udgive et dokument, kan du bruge Pandoc til at generere så mange forskellige versioner af din dokumentation, som du har brug for, inklusive webbaserede (HTML), tekstbehandlet eller sat (LibreOffice, Microsoft Word, TeX), Bærbart dokumentformat (PDF), e-bog (ePub), og så videre.
Du kan gøre alt dette fra ét sæt versionskontrollerede, lette tekstfiler.
Installerer pandoc
For at installere Pandoc på Ubuntu, brug denne kommando:
sudo apt-get install pandoc
På Fedora er kommandoen du har brug for følgende:
sudo dnf install pandoc
På Manjaro skal du skrive:
sudo pacman -Syu pandoc
Du kan kontrollere, hvilken version du har installeret ved at bruge –version-indstillingen:
pandoc --version
Brug af pandoc uden filer
Hvis du bruger Pandoc uden nogen kommandolinjeindstillinger, accepterer den også indtastet input. Du trykker bare på Ctrl+D for at indikere, at du er færdig med at skrive. pandoc forventer, at du skriver i Markdown-format, og det genererer HTML-output.
Lad os se på et eksempel:
pandoc
Vi har skrevet et par linjer Markdown og er ved at trykke Ctrl+D.
Så snart vi gør det, genererer pandoc det tilsvarende HTML-output.
For at gøre noget nyttigt med Pandoc, skal vi dog virkelig bruge filer.
Grundlæggende om Markdown
Markdown er et letvægts opmærkningssprog, og visse karakterer får særlig betydning. Du kan bruge en almindelig teksteditor til at oprette en Markdown-fil.
Markdown kan nemt læses, da der ikke er nogen visuelt besværlige tags til at distrahere fra teksten. Formatering i Markdown-dokumenter ligner den formatering, den repræsenterer. Nedenfor er nogle af de grundlæggende ting:
For at understrege tekst med kursiv skal du pakke den ind i stjerner. *Dette vil blive understreget*
For at fed tekst skal du bruge to stjerner. **Dette vil være med fed skrift**
Overskrifter er repræsenteret ved taltegnet/hash-mærket (#). Tekst er adskilt fra hashen med et mellemrum. Brug én hash til en overskrift på øverste niveau, to til et andet niveau og så videre.
For at oprette en punktopstilling skal du starte hver linje på listen med en stjerne og indsætte et mellemrum før teksten.
For at oprette en nummereret liste skal du starte hver linje med et ciffer efterfulgt af et punktum og derefter indsætte et mellemrum før teksten.
For at oprette et hyperlink skal du indsætte navnet på webstedet i firkantede parenteser ([]), og URL’en i parentes [()] ligesom: [Link to How to Geek](https://www.wdzwdz.com/).
For at indsætte et billede skal du skrive et udråbstegn umiddelbart før parenteser (![]). Indtast en alternativ tekst til billedet i parentes. Indsæt derefter stien til billedet i parentes [()“]. Her er et eksempel: .
Vi vil dække flere eksempler på alle disse i næste afsnit.
Konvertering af filer
Filkonverteringer er ligetil. pandoc kan normalt regne ud, hvilke filformater du arbejder med, ud fra deres filnavne. Her skal vi generere en HTML-fil fra en Markdown-fil. Indstillingen -o (output) fortæller pandoc navnet på den fil, vi ønsker at oprette:
pandoc -o sample.html sample.md
Vores eksempel på Markdown-fil, sample.md, indeholder det korte afsnit af Markdown vist på billedet nedenfor.
En fil kaldet sample.html oprettes. Når vi dobbeltklikker på filen, åbner vores standardbrowser den.
Lad os nu generere en Åbn dokumentformat tekstdokument vi kan åbne i LibreOffice Writer:
pandoc -o sample.odt sample.md
ODT-filen har samme indhold som HTML-filen.
En pæn touch er den alternative tekst til billedet, der også bruges til automatisk at generere en billedtekst til figuren.
Angivelse af filformater
Indstillingerne -f (fra) og -t (til) bruges til at fortælle pandoc, hvilke filformater du vil konvertere fra og til. Dette kan være nyttigt, hvis du arbejder med et filformat, der deler en filtypenavn med andre relaterede formater. For eksempel, TeX, og LaTeX begge bruger udvidelsen “.tex”.
Vi bruger også muligheden -s (standalone), så pandoc vil generere al den LaTeX-præamble, der kræves for, at et dokument kan være et komplet, selvstændigt og velformet LaTeX-dokument. Uden muligheden -s (standalone), ville output stadig være velformet LaTeX, der kunne placeres i et andet LaTeX-dokument, det ville ikke parses korrekt som et selvstændigt LaTeX-dokument.
Vi skriver følgende:
pandoc -f markdown -t latex -s -o sample.tex sample.md
Hvis du åbner filen “sample.tex” i en teksteditor, vil du se den genererede LaTeX. Hvis du har en LaTeX-editor, kan du åbne TEX-filen for at se en forhåndsvisning af, hvordan LaTeX-typeindstillingskommandoerne fortolkes. At krympe vinduet, så det passer til billedet nedenfor, fik skærmen til at se trang ud, men i virkeligheden var det fint.
Vi brugte en LaTeX-editor kaldet Texmaker. Hvis du vil installere det i Ubuntu, skal du skrive følgende:
sudo apt-get install texmaker
I Fedora er kommandoen:
sudo dnf install texmaker
I Manjaro skal du bruge:
sudo pacman -Syu texmaker
Konvertering af filer med skabeloner
Du er sikkert begyndt at forstå den fleksibilitet, som Pandoc giver. Du kan skrive én gang og udgive i næsten alle formater. Det er en stor bedrift, men dokumenterne ser lidt vanilje ud.
Med skabeloner kan du diktere, hvilke typografier Pandoc bruger, når den genererer dokumenter. For eksempel kan du fortælle pandoc at bruge de stilarter, der er defineret i en Cascading Style Sheets (CSS) fil med –css-indstillingen.
Vi har lavet en lille CSS-fil, der indeholder teksten nedenfor. Det ændrer afstanden over og under niveauoverskriften én stil. Det ændrer også tekstfarven til hvid og baggrundsfarven til en blå nuance:
h1 {
color: #FFFFFF;
background-color: #3C33FF;
margin-top: 0px;
margin-bottom: 1px;
}
Den fulde kommando er nedenfor – bemærk, at vi også brugte den selvstændige mulighed (-s):
pandoc -o sample.html -s --css sample.css sample.md
pandoc bruger den enkelte stil fra vores minimalistiske CSS-fil og anvender den på niveau 1-headeren.
En anden finjusteringsmulighed, du har tilgængelig, når du arbejder med HTML-filer, er at inkludere HTML-markering i din Markdown-fil. Dette vil blive sendt videre til den genererede HTML-fil som standard HTML-markup.
Denne teknik bør dog reserveres til, når du kun genererer HTML-output. Hvis du arbejder med flere filformater, ignorerer pandoc HTML-markeringen for ikke-HTML-filer, og den vil blive videregivet til dem som tekst.
Vi kan også angive, hvilke stilarter der bruges, når ODT-filer genereres. Åbn et tomt LibreOffice Writer-dokument, og juster overskriften og skrifttypestilene, så de passer til dine behov. I vores eksempel tilføjede vi også et sidehoved og en sidefod. Gem dit dokument som “odt-template.odt.”
Vi kan nu bruge dette som en skabelon med –reference-doc muligheden:
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
Sammenlign dette med ODT-eksemplet fra tidligere. Dette dokument bruger en anden skrifttype, har farvede overskrifter og inkluderer sidehoveder og sidefødder. Den blev dog genereret fra den nøjagtig samme “sample.md” Markdown-fil.
Referencedokumentskabeloner kan bruges til at angive forskellige stadier af et dokuments produktion. For eksempel kan du have skabeloner, der har “Udkast” eller “Til gennemsyn” vandmærker. En skabelon uden vandmærke vil blive brugt til et færdiggjort dokument.
Generering af PDF’er
Pandoc bruger som standard LaTeX PDF-motoren til at generere PDF-filer. Den nemmeste måde at sikre, at du har de passende LaTeX-afhængigheder opfyldt, er at installere en LaTeX-editor, såsom Texmaker.
Det er dog en ret stor installation – Tex og LaTeX er begge ret heftige. Hvis din harddiskplads er begrænset, eller du ved, at du aldrig vil bruge TeX eller LaTeX, foretrækker du måske at generere en ODT-fil. Derefter kan du bare åbne den i LibreOffice Writer og gemme den som en PDF.
Docs-as-Code
Der er flere fordele ved at bruge Markdown som dit skrivesprog, herunder følgende:
Det er hurtigt at arbejde i almindelige tekstfiler: De indlæses hurtigere end tekstbehandlingsfiler af tilsvarende størrelse og har også en tendens til at bevæge sig hurtigere gennem dokumentet. Mange redaktører, inklusive gedit , Vim og Emacs, bruger syntaksfremhævning med Markdown-tekst.
Du vil have en tidslinje over alle versioner af dine dokumenter: Hvis du gemmer din dokumentation i en VCS, såsom Git, kan du nemt se forskellene mellem to versioner af den samme fil. Dette virker dog kun rigtigt, når filerne er almindelig tekst, da det er det, en VCS forventer at arbejde med.
En VCS kan registrere, hvem der har foretaget ændringer, og hvornår: Dette er især nyttigt, hvis du ofte samarbejder med andre om store projekter. Det giver også et centralt lager for selve dokumenterne. Mange cloud-hostede Git-tjenester, såsom GitHub, GitLab, og BitBucket, har gratis niveauer i deres prismodeller.
Du kan generere dine dokumenter i flere formater: Med blot et par simple shell-scripts kan du hente typografierne fra CSS og referencedokumenter. Hvis du gemmer dine dokumenter i et VCS-lager, der integreres med Kontinuerlig integration og kontinuerlig implementering (CI/CD) platforme, kan de genereres automatisk, når softwaren bygges.
Afsluttende tanker
Der er mange flere muligheder og funktioner indenfor pandoc end hvad vi har dækket her. Konverteringsprocesserne for de fleste filtyper kan justeres og finjusteres. For at lære mere, tjek de fremragende eksempler på den officielle (og ekstremt detaljerede) pandoc webside.