Puoi usare pandoc su Linux per convertire tra più di 40 formati di file. Puoi anche usarlo per creare un semplice sistema di documenti come codice scrivendo in Markdown, memorizzare in gite pubblica in uno qualsiasi dei suoi formati supportati.
Converti documenti e documenti come codice
Se hai un documento in uno qualsiasi dei pandoc's molti formati di file supportati, trasformarlo in uno degli altri è un gioco da ragazzi. È uno strumento utile da avere!
Ma il vero potere di pandoc diventa evidente quando lo usi come base di un semplice sistema di documenti come codice. La premessa di docs-as-code è prendere alcune delle tecniche e dei principi dello sviluppo del software e applicarli alla scrittura della documentazione, soprattutto per progetti di sviluppo software. Nonostante questo, puoi applicarlo allo sviluppo di qualsiasi tipo di documentazione.
Gli sviluppatori di software usano il loro editor preferito o ambiente di sviluppo integrato (QUI) per scrivere i tuoi programmi. Il codice che scrivono viene salvato in file di testo. Questi contengono il codice sorgente per il programma.
Usano un sistema di controllo della versione, il 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.. Puoi accedere rapidamente a qualsiasi versione precedente di un file. Git memorizza 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 compilatore per leggere il codice sorgente e generare un eseguibile binario.
Scrivendo i tuoi documenti in un linguaggio di markup basato su testo leggero, puoi usare un VCS per controllare la versione del tuo script. Quando sei pronto per distribuire o pubblicare un documento, Puoi usare pandoc per generare tutte le versioni differenti della tua documentazione di cui hai bisogno, compresi quelli supportati sul web (HTML), elaborazione del testo o tipografica (LibreOffice, Microsoft Word, Texas), Formato documento portatile (PDF), ebook (ePub), e così via.
Puoi fare tutto questo da una serie di leggeri file di testo controllati dalla versione.
Installazione di Pandoc
Installare pandoc in Ubuntu, usa questo comando:
sudo apt-get install pandoc
In Fedora, il comando che ti serve è il seguente:
sudo dnf install pandoc
A Manjaro, deve scrivere:
sudo pacman -Syu pandoc
Puoi controllare quale versione hai installato usando il --version opzione:
pandoc --versione
Usa pandoc senza file
Se usi pandoc senza alcuna opzione della riga di comando, accetta anche input scritti. Basta premere Ctrl + D per indicare che hai finito di digitare. pandoc si aspetta che tu scriva in formato Markdown e genera output HTML.
Vediamo un esempio:
pandoc
Abbiamo scritto alcune righe da Markdown e stiamo per premere Ctrl + D.
Non appena lo facciamo pandoc genera un output HTML simile.
Per fare qualcosa di utile con pandoc, nonostante questo, abbiamo davvero bisogno di usare i file.
Nozioni di base sul markdown
Markdown è un linguaggio di markup leggero e viene dato un significato speciale a determinati caratteri. Puoi usare un semplice editor di testo per creare un file Markdown.
Markdown può essere facilmente letto, poiché non ci sono etichette visivamente ingombranti per distrarre dal testo. Il formato nei documenti Markdown assomiglia al formato che rappresenta. Di seguito sono riportate alcune delle nozioni di base:
- Per enfatizzare il testo con corsivo, avvolgerlo in asterischi.
*This will be emphasized* - Per carattere in grassetto testo, usa due asterischi.
**This will be in bold** - Le intestazioni sono rappresentate dal cancelletto / segno di pad (
#). 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 e poi inserisci uno spazio prima del testo.
- Per creare un collegamento ipertestuale, racchiudere il nome del sito tra parentesi quadre (
[]) e l'URL tra parentesi [()] nello stesso modo in cui:[Link to How to Geek](https://www.systempeaker.com/). - Per inserire un'immagine, digita un punto esclamativo subito prima delle parentesi (
![]). Scrivi qualsiasi testo alternativo per l'immagine tra parentesi. Successivamente, racchiudere il percorso dell'immagine tra parentesi [()“]. Ecco un esempio:.
Tratteremo più esempi di tutti questi nella prossima sezione..
IMPARENTATO: Cos'è Markdown e come si usa?
Conversione file
Le conversioni di file sono facili. pandoc Generalmente, puoi determinare con quali formati di file stai lavorando dai loro nomi di file. Qui, genereremo un file HTML da un file Markdown. il -o (Uscita) opzione dice pandoc il nome del file che vogliamo creare:
pandoc -o sample.html sample.md
Il nostro file di esempio Markdown, campione.md, contiene la breve sezione Markdown mostrata nell'immagine qui sotto.
Viene creato un file chiamato sample.html. Quando facciamo doppio clic sul file, il nostro browser predefinito lo aprirà.
Ora, generemos un Formato documento aperto documento di testo che possiamo aprire in LibreOffice Writer:
pandoc -o sample.odt sample.md
Il file ODT ha lo stesso contenuto del file HTML.
Un tocco pulito è il testo alternativo dell'immagine che viene utilizzato anche per generare automaticamente un titolo per la figura.
Specifica i formati dei file
il -f (a partire dal) e -t (un) le alternative sono usate per dire pandoc i formati di file che vuoi convertire da e verso. Questo può essere utile se stai lavorando con un formato di file che condivide un'estensione di file con altri formati correlati. Come esempio, Texas, e lattice entrambi usano l'estensione ".tex".
Utilizziamo anche il -s (Indipendente) opzione pandoc genererà tutto il preambolo LaTeX necessario affinché un documento sia un documento LaTeX completo, autonomo e ben addestrato. Senza di lui -s (Indipendente), l'output sarebbe ancora LaTeX ben formato che potrebbe essere inserito in un altro documento LaTeX, non verrebbe analizzato correttamente come documento LaTeX autonomo.
Scriviamo quanto segue:
pandoc -f markdown -t latex -s -o sample.tex sample.md
Se apri il file “campione.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 di LaTeX. Riducendo la finestra per adattarla all'immagine sottostante, lo schermo appare stretto, ma, in realtà, è stato bello.
Usiamo un editor LaTeX chiamato Texmaker. Se vuoi installarlo su Ubuntu, scrivi quanto segue:
sudo apt-get install texmaker
In Fedora, il comando è:
sudo dnf install texmaker
A Manjaro, utilizzo:
sudo pacman -Syu texmaker
Converti file con modelli
Probabilmente stai iniziando a capire la flessibilità che pandoc fornisce. Puoi scrivere una volta e postare in quasi tutti i formati. È una grande impresa, ma i documenti sembrano un po' vanigliati.
Con i modelli, può dettare quali stili pandoc utilizzato durante la generazione di documenti. Come esempio, si può dire pandoc usa gli stili definiti in a Fogli di stile (CSS) file con --css opzione.
Abbiamo creato un piccolo file CSS contenente il testo sottostante. Modifica lo spazio sopra e sotto lo stile dell'intestazione del livello. Cambia anche il colore del testo in bianco e il colore di sfondo in una sfumatura di blu.:
h1 {
colore: #FFFFFF;
colore di sfondo: #3C33FF;
margine superiore: 0px;
margine inferiore: 1px;
}Il comando completo è sotto; nota che usiamo 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 alternativa al wrapper che hai a disposizione quando lavori con i file HTML è includere il markup HTML nel tuo file Markdown.. Questo verrà passato al file HTML generato come markup HTML standard.
Nonostante questo, questa tecnica dovrebbe essere riservata quando si genera solo output HTML. Se lavori con un numero sufficiente di formati di file, pandoc ignorerà il markup HTML per i file non HTML e passerà ad essi come testo.
Possiamo anche specificare quali stili vengono utilizzati durante la generazione di 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, aggiungiamo anche un'intestazione e un piè di pagina. Salvare il documento come “odt-template.odt”.
Ora possiamo usarlo come modello con il --reference-doc opzione:
pandoc -o sample.odt --reference-doc = odt-template.odt sample.md
Confronta questo con l'esempio ODT sopra. Questo documento usa un font diverso, ha intestazioni colorate e include intestazioni e piè di pagina. Nonostante questo, è stato generato esattamente dallo stesso file Markdown “campione.md”.
I modelli di documenti di riferimento possono essere utilizzati per indicare diverse fasi nella produzione di un documento. Come esempio, È possibile disporre di modelli con filigrane “Brutta copia” oh “Per la revisione”. Un modello senza filigrana verrebbe utilizzato per un documento finito.
Generazione di file PDF
Predefinito, pandoc utilizza il motore PDF LaTeX per generare file PDF. Il modo più semplice per garantire che le dipendenze LaTeX corrette siano soddisfatte è installare un editor LaTeX, nel ruolo di Texmaker.
Nonostante questo, è una struttura abbastanza grande: Tex e LaTeX sono piuttosto pesanti. Se lo spazio sul disco rigido è limitato, sai che non userai mai TeX o LaTeX, potresti preferire generare un file ODT. Successivamente, puoi aprirlo in LibreOffice Writer e salvarlo come PDF.
Documenti come codice
Usare Markdown come linguaggio di scrittura ha diversi vantaggi, compreso quanto segue:
- Lavorare in file di testo semplice è veloce: Si caricano più velocemente dei file di word processor di dimensioni simili e tendono anche a spostarsi più velocemente nel documento. Molti editori, incluso
gedit,Vim, eEmacs, usa l'evidenziazione della sintassi con il testo Markdown. - Avrai una cronologia di tutte le versioni dei tuoi documenti: Se archivi la tua documentazione in un VCS, come git, puoi facilmente vedere le differenze tra due versioni dello stesso file. Nonostante questo, questo funziona veramente solo quando i file sono di testo normale, poiché questo è ciò 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 progetti di grandi dimensioni.. Fornisce anche un repository 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, può estrarre 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), può essere generato automaticamente ogni volta che viene creato il software.
IMPARENTATO: Che cos'è GitHub e a cosa serve?
Pensieri finali
Ci sono molte più opzioni e funzioni 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 adattati. Per maggiori informazioni, dai un'occhiata ai fantastici esempi nel post ufficiale (ed estremamente dettagliato) sito web pandoc.
