Puoi usare pandoc su Linux per convertire tra più di 40 formati di file. Puoi anche usarlo per creare un semplice sistema docs-as-code scrivendo in Markdown, archiviando in git e pubblicando in uno qualsiasi dei formati supportati.
Sommario:
Conversione di documenti e Documenti come codice
Se hai un documento in uno qualsiasi dei file pandoc molti formati di file supportati, convertirlo in uno qualsiasi degli altri è un gioco da ragazzi. È uno strumento utile da avere!
Ma il vero potere di pandoc diventa evidente quando lo si utilizza come base di un semplice sistema docs-as-code. La premessa di docs-as-code è quella di adottare alcune delle tecniche e dei principi dello sviluppo del software e applicarli alla scrittura della documentazione, specialmente per i progetti di sviluppo del software. Puoi applicarlo allo sviluppo di qualsiasi tipo di documentazione, però.
Gli sviluppatori di software usano il loro editor preferito o ambiente di sviluppo integrato (IDE) per scrivere i propri programmi. Il codice digitato viene salvato in file di testo. Questi contengono il file codice sorgente per il programma.
Usano un file sistema di controllo della versioneo VCS (Idiota è il più popolare), per acquisire le modifiche al codice sorgente man mano che viene sviluppato e migliorato. Ciò significa che il programmatore ha una cronologia completa di tutte le versioni dei file del codice sorgente. Lui o lei può accedere rapidamente a qualsiasi versione precedente di un file. Git archivia i file in un repository. C’è un repository locale sul computer di ogni sviluppatore e un repository centrale, condiviso e remoto che è spesso ospitato nel cloud.
Quando sono pronti per produrre una versione funzionante del programma, usano un file compilatore per leggere il codice sorgente e generare un eseguibile binario.
Scrivendo i tuoi documenti in un linguaggio di markup leggero e basato su testo, puoi utilizzare un VCS per controllare la versione della tua scrittura. Quando sei pronto per distribuire o pubblicare un documento, puoi utilizzare pandoc per generare tutte le versioni differenti della tua documentazione di cui hai bisogno, comprese quelle basate sul web (HTML), elaborato a parole o composto (LibreOffice, Microsoft Word, TeX), formato di documento portatile (PDF), e-book (ePub), e così via.
Puoi fare tutto questo da un set di file di testo leggeri e controllati dalla versione.
Installazione di pandoc
Per installare pandoc su Ubuntu, usa questo comando:
sudo apt-get install pandoc
Su Fedora, il comando che ti serve è il seguente:
sudo dnf install pandoc
Su Manjaro, devi digitare:
sudo pacman -Syu pandoc
Puoi controllare quale versione hai installato utilizzando l’opzione –version:
pandoc --version
Utilizzo di pandoc senza file
Se usi pandoc senza alcuna opzione della riga di comando, accetta anche l’input digitato. Basta premere Ctrl + D per indicare che hai finito di digitare. pandoc si aspetta che tu digiti in formato Markdown e genera output HTML.
Diamo un’occhiata a un esempio:
pandoc
Abbiamo digitato alcune righe di Markdown e stiamo per premere Ctrl + D.
Non appena lo facciamo, pandoc genera l’output HTML equivalente.
Per fare qualcosa di utile con pandoc, però, abbiamo davvero bisogno di usare i file.
Nozioni di base su Markdown
Markdown è un linguaggio di markup leggero e a determinati caratteri viene assegnato un significato speciale. Puoi utilizzare un semplice editor di testo per creare un file Markdown.
Il markdown può essere letto facilmente, poiché non ci sono tag visivamente ingombranti per distrarre dal testo. La formattazione nei documenti Markdown è simile alla formattazione che rappresenta. Di seguito sono riportate alcune delle basi:
Per enfatizzare il testo con corsivo, racchiudilo tra asterischi. * Questo sarà sottolineato *
Per il testo in grassetto, usa due asterischi. ** Questo sarà in grassetto **
Le intestazioni sono rappresentate dal segno del numero / cancelletto (#). Il testo è separato dall’hash da uno spazio. Usa un hash per un’intestazione di primo livello, due per un secondo livello e così via.
Per creare un elenco puntato, inizia ogni riga dell’elenco con un asterisco e inserisci uno spazio prima del testo.
Per creare un elenco numerato, inizia ogni riga con una cifra seguita da un punto, quindi inserisci uno spazio prima del testo.
Per creare un collegamento ipertestuale, racchiudere il nome del sito tra parentesi quadre ([]) e l’URL tra parentesi [()] così: [Link to How to Geek](https://www.howtogeek.com/).
Per inserire un’immagine, digita un punto esclamativo immediatamente prima delle parentesi (![]). Digita un testo alternativo per l’immagine tra parentesi. Quindi, racchiudi il percorso dell’immagine tra parentesi [()“]. Ecco un esempio:.
Tratteremo più esempi di tutti questi nella sezione successiva.
Conversione di file
Le conversioni di file sono semplici. pandoc di solito può capire con quali formati di file stai lavorando dai loro nomi di file. Qui, genereremo un file HTML da un file Markdown. L’opzione -o (output) dice a pandoc il nome del file che vogliamo creare:
pandoc -o sample.html sample.md
Il nostro file Markdown di esempio, sample.md, contiene la breve sezione di Markdown mostrato nell’immagine sottostante.
Viene creato un file denominato sample.html. Quando facciamo doppio clic sul file, il nostro browser predefinito lo aprirà.
Ora, generiamo un file Apri formato documento documento di testo in cui possiamo aprire LibreOffice Writer:
pandoc -o sample.odt sample.md
Il file ODT ha lo stesso contenuto del file HTML.
Un tocco pulito è che il testo alternativo per l’immagine viene utilizzato anche per generare automaticamente una didascalia per la figura.
Specifica dei formati di file
Le opzioni -f (da) e -t (a) sono usate per dire a pandoc in quali formati di file vuoi convertire. Questo può essere utile se stai lavorando con un formato di file che condivide un’estensione di file con altri formati correlati. Per esempio, TeX, e LaTeX entrambi utilizzano l’estensione “.tex”.
Stiamo anche usando l’opzione -s (standalone) in modo che pandoc genererà tutto il preambolo LaTeX richiesto affinché un documento sia un documento LaTeX completo, autonomo e ben formato. Senza l’opzione -s (standalone), l’output sarebbe ancora LaTeX ben formato che potrebbe essere inserito in un altro documento LaTeX, non sarebbe analizzato correttamente come un documento LaTeX autonomo.
Digitiamo quanto segue:
pandoc -f markdown -t latex -s -o sample.tex sample.md
Se apri il file “sample.tex” in un editor di testo, vedrai il LaTeX generato. Se hai un editor LaTeX, puoi aprire il file TEX per vedere un’anteprima di come vengono interpretati i comandi di composizione LaTeX. Restringere la finestra per adattarla all’immagine sottostante faceva sembrare il display angusto, ma, in realtà, andava bene.
Abbiamo usato un editor LaTeX chiamato Texmaker. Se vuoi installarlo in Ubuntu, digita quanto segue:
sudo apt-get install texmaker
In Fedora, il comando è:
sudo dnf install texmaker
In Manjaro, usa:
sudo pacman -Syu texmaker
Conversione di file con modelli
Probabilmente stai iniziando a capire la flessibilità offerta da pandoc. Puoi scrivere una volta e pubblicare in quasi tutti i formati. È una grande impresa, ma i documenti sembrano un po ‘vanigliati.
Con i modelli, puoi stabilire quali stili utilizza pandoc quando genera documenti. Ad esempio, puoi dire a pandoc di utilizzare gli stili definiti in un file Fogli di stile (CSS) con l’opzione –css.
Abbiamo creato un piccolo file CSS contenente il testo seguente. Cambia la spaziatura sopra e sotto lo stile dell’intestazione di livello uno. Cambia anche il colore del testo in bianco e il colore di sfondo in una tonalità di blu:
h1 {
color: #FFFFFF;
background-color: #3C33FF;
margin-top: 0px;
margin-bottom: 1px;
}
Il comando completo è di seguito: nota che abbiamo utilizzato anche l’opzione standalone (-s):
pandoc -o sample.html -s --css sample.css sample.md
pandoc utilizza lo stile unico del nostro file CSS minimalista e lo applica all’intestazione di livello uno.
Un’altra opzione di regolazione fine che hai a disposizione quando lavori con i file HTML consiste nell’includere il markup HTML nel tuo file Markdown. Questo verrà passato al file HTML generato come markup HTML standard.
Tuttavia, questa tecnica dovrebbe essere riservata a quando stai generando solo output HTML. Se stai lavorando con più formati di file, pandoc ignorerà il markup HTML per i file non HTML e verrà passato a quelli come testo.
Possiamo anche specificare quali stili vengono utilizzati quando vengono generati file ODT. Apri un documento LibreOffice Writer vuoto e regola l’intestazione e gli stili dei caratteri in base alle tue esigenze. Nel nostro esempio, abbiamo anche aggiunto un’intestazione e un piè di pagina. Salva il documento come “odt-template.odt”.
Ora possiamo usarlo come modello con l’opzione –reference-doc:
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
Confronta questo con l’esempio ODT di prima. Questo documento utilizza un carattere diverso, ha intestazioni colorate e include intestazioni e piè di pagina. Tuttavia, è stato generato dallo stesso identico file Markdown “sample.md”.
I modelli di documento di riferimento possono essere utilizzati per indicare le diverse fasi della produzione di un documento. Ad esempio, potresti avere modelli con filigrane “Bozza” o “Per revisione”. Per un documento finalizzato verrà utilizzato un modello senza filigrana.
Generazione di PDF
Per impostazione predefinita, pandoc utilizza il motore PDF LaTeX per generare file PDF. Il modo più semplice per assicurarsi di avere soddisfatte le dipendenze LaTeX appropriate è installare un editor LaTeX, come Texmaker.
Questa è un’installazione abbastanza grande, però, Tex e LaTeX sono entrambi piuttosto pesanti. Se lo spazio sul disco rigido è limitato o sai che non utilizzerai mai TeX o LaTeX, potresti preferire generare un file ODT. Quindi, puoi semplicemente aprirlo in LibreOffice Writer e salvarlo come PDF.
Documenti come codice
Ci sono diversi vantaggi nell’usare Markdown come linguaggio di scrittura, inclusi i seguenti:
Lavorare con file di testo semplice è veloce: si caricano più velocemente di file di elaboratori di testi di dimensioni simili e tendono anche a spostarsi più velocemente nel documento. Molti editor, inclusi gedit, Vim ed Emacs, usano l’evidenziazione della sintassi con il testo Markdown.
Avrai una sequenza temporale di tutte le versioni dei tuoi documenti: se archivi la documentazione in un VCS, come Git, puoi facilmente vedere le differenze tra due versioni qualsiasi dello stesso file. Tuttavia, questo funziona davvero solo quando i file sono in testo normale, poiché è quello con cui un VCS si aspetta di lavorare.
Un VCS può registrare chi ha apportato modifiche e quando: Ciò è particolarmente utile se collabori spesso con altri su grandi progetti. Fornisce inoltre un archivio centrale per i documenti stessi. Molti servizi Git ospitati nel cloud, come GitHub, GitLab, e BitBucket, hanno livelli gratuiti nei loro modelli di prezzo.
Puoi generare i tuoi documenti in più formati: con solo un paio di semplici script di shell, puoi estrarre gli stili da CSS e documenti di riferimento. Se archivi i tuoi documenti in un repository VCS che si integra con Integrazione continua e distribuzione continua (CI / CD), possono essere generati automaticamente ogni volta che il software viene costruito.
Pensieri finali
Ci sono molte altre opzioni e funzionalità all’interno pandoc di quello che abbiamo trattato qui. I processi di conversione per la maggior parte dei tipi di file possono essere modificati e ottimizzati. Per saperne di più, guarda gli ottimi esempi sul sito ufficiale (ed estremamente dettagliati) pagina web pandoc.