Soluzione pronta markdown2pdf con codice sorgente per Linux

Prefazione

Markdown è un modo eccellente per scrivere articoli brevi e talvolta anche testi abbastanza lunghi, con una formattazione semplice come corsivo e grassetto. È anche utile per redigere articoli con inclusione di codice sorgente. Tuttavia, a volte si desidera convertirlo in un file PDF ben formattato senza perdite e senza complicazioni, come per esempio problemi che ho avuto: non è possibile scrivere in russo nei commenti del codice sorgente, righe troppo lunghe non vengono a capo ma vengono troncate, e altri piccoli problemi. Questa guida permette di configurare rapidamente il convertitore. md2pdf senza necessariamente comprendere come funzioni. Di seguito, il mio script per un'installazione abbastanza automatica.

Il mio esempio di modello TeX per la conversione utilizza il pacchetto di font PSCyr, che include il supporto per i font Microsoft, ossia Times New Roman. Tali sono stati i requisiti per il diploma secondo GOST. Se siete in grado, potete modificare il modello in base alle vostre esigenze. Nella mia guida, sarà necessario prima lavorare con la configurazione di PSCyr in TexLive. La configurazione avviene nella distribuzione Linux Mint Mate; per altre distribuzioni, potrebbe essere necessario cercare online le cartelle standard del pacchetto TexLive per il vostro sistema.

Installazione di TexLive

Naturalmente, è possibile installare solo le parti necessarie di questo pacchetto. Ma personalmente, ero sinceramente pigro nel cercare un'installazione minimale e funzionante. Per essere certi che funzioni, installiamo l'intero pacchetto TexLive. Si chiama texlive-full e pesa leggermente più di 2 gigabyte, tenete questo in mente. Eseguiamo il comando:

user@hostname:~$ sudo apt install texlive-full -y

Dopo un'installazione piuttosto lunga, possiamo passare al punto seguente.

Installazione del convertitore Pandoc

Pandoc è un pacchetto per Linux che permette di convertire diversi formati di testo in altri. Ha molte funzionalità interessanti, che puoi scoprire da solo su Internet. Ci interessa in particolare la possibilità di convertire un file markdown in PDF. Verifichiamo se Pandoc è installato e, se non lo è, lo installeremo. Ad esempio:

user@hostname:~$ dpkg -s pandoc

Se nell'output risulta che non è installato, procediamo all'installazione:

user@hostname:~$ sudo apt install pandoc -y

Installazione del pacchetto PSCyr per TexLive

Per iniziare, è necessario scaricare PSCyr. Attualmente è ancora disponibile a questo link, se al momento della lettura dell'articolo non è disponibile per qualche motivo, non disperare, è facile trovarlo insieme alle istruzioni per l'installazione cercando su Google qualcosa come «Installazione PsCyr texlive». Se è disponibile, sarà più semplice, scaricalo e consideriamo che hai estratto l'archivio nella tua home directory, quindi il percorso alla cartella contenuta nell'archivio appare come ~/PSCyr. Ora apriamo il Terminale ed eseguiamo le seguenti comandi:

user@hostname:~$ cd
user@hostname:~$ mkdir ./PSCyr/fonts/map ./PSCyr/fonts/enc
user@hostname:~$ cp ./PSCyr/dvips/pscyr/*.map ./PSCyr/fonts/map/
user@hostname:~$ cp ./PSCyr/dvips/pscyr/*.enc ./PSCyr/fonts/enc/
user@hostname:~$ echo "fadr6t AdvertisementPSCyr "T2AEncoding ReEncodeFont"" > ./PSCyr/fonts/map/pscyr.map

Ora vediamo dove si trova la directory locale texmf. Eseguiamo il comando:

user@hostname:~$ kpsewhich -expand-var='$TEXMFLOCAL'

Probabilmente questa directory è: /usr/local/share/texmf/, e allora eseguiamo:

user@hostname:~$ sudo cp -R ./PSCyr/* /usr/local/share/texmf/

Oppure si può semplicemente eseguire il comando che copierà nella cartella texmf doveunque sia:

user@hostname:~$ sudo cp -R ./PSCyr/* $(kpsewhich -expand-var='$TEXMFLOCAL')

I font PSCyr sono stati installati, colleghiamoli in TexLive:

user@hostname:~$ sudo texhash
user@hostname:~$ updmap --enable Map=pscyr.map
user@hostname:~$ sudo mktexlsr

Template LaTeX per la conversione da md a pdf

Non intendo descrivere come sia esattamente configurato questo template, ma lo riporterò qui sotto senza particolari spiegazioni. Basta dire che è impostato abbastanza bene, almeno per quanto riguarda la gestione di testi con molto codice sorgente. Se non sei soddisfatto delle dimensioni dei margini, degli spazi tra le righe, della mancanza di numerazione delle sezioni e sottosezioni, credo sia piuttosto facile cercare online 'come fare in Latex...' per trovare la soluzione. Se hai ancora dubbi, scrivi nei commenti, farò del mio meglio per rievocare le mie impostazioni di quattro anni fa e spiegarti a cosa serve ogni riga del template. Per ora, descriverò come l'ho impostato sul mio PC, e sei libero di ripetere o modificare secondo le tue esigenze.

Creiamo il file template.tex nella directory /usr/share/texlive/:

user@hostname:~$ sudo touch /usr/share/texlive/template.tex

Assegniamo i diritti di lettura:

user@hostname:~$ sudo chmod 444 /usr/share/texlive/template.tex

apriamo come root e incolliamo il contenuto nascosto nel spoiler qui sotto:

user@hostname:~$ sudo nano /usr/share/texlive/template.tex

Contenuto del template /usr/share/texlive/template.tex

documentclass[oneside,final,14pt]{extreport}
usepackage{extsizes}
usepackage{pscyr}
renewcommand{rmdefault}{ftm}
usepackage[T2A]{fontenc}
usepackage[utf8]{inputenc}
usepackage{amsmath}
usepackage{mathtext}
usepackage{multirow}
usepackage{listings}
usepackage{ucs}
usepackage{hhline}
usepackage{tabularx}
usepackage{booktabs}
usepackage{longtable}
usepackage{titlesec}
usepackage{hyperref}
usepackage{graphicx}
usepackage{setspace}
usepackage[center,it,labelsep=period]{caption}
usepackage[english,italian]{babel}
usepackage{vmargin}
newcommand{specialcell}[2][c]{%
    begin{tabular}[#1]{@{}c@{}}#2end{tabular}}
setpapersize{A4}
setmarginsrb {1cm}{1cm}{1cm}{1cm}{0pt}{0mm}{0pt}{13mm}
usepackage{indentfirst}
setlengthparindent{1cm}
renewcommand{baselinestretch}{1}
renewcommandthechapter{}
renewcommandthesection{}
renewcommandthesubsection{}
renewcommandthesubsubsection{}
titleformat
{chapter} % command
{bfseriesnormalsizecentering} % format
{thechapter} % label
{0.5ex} % sep
{
    centering
}
[
vspace{-1.5ex}
] % after-code
titleformat
{section}
[block]
{normalfontbfseries}
{thesection}{0.5em}{}
sloppy
letoldenumerateenumerate
renewcommand{enumerate}{
  oldenumerate
  setlength{itemsep}{1pt}
  setlength{parskip}{0pt}
  setlength{parsep}{0pt}
}
letolditemizeitemize
renewcommand{itemize}{
  olditemize
  setlength{itemsep}{1pt}
  setlength{parskip}{0pt}
  setlength{parsep}{0pt}
}
providecommand{tightlist}{%
  setlength{itemsep}{0pt}setlength{parskip}{0pt}}

titlespacing{subsubsection}{parindent}{3mm}{3mm}
titlespacing{subsection}{parindent}{3mm}{3mm}
usepackage{color}

lstset{
    basicstyle=footnotesizettfamily,
    inputencoding=utf8,
    extendedchars=true,
    showspaces=false,
    keepspaces=true
    showstringspaces=false,
    showtabs=false,
    tabsize=4,
    captionpos=b,
    breaklines=true,
    breakatwhitespace=true,
    breakautoindent=true,
    linewidth=textwidth
}

begin{document}
$if(title)$
maketitle
$endif$
$if(abstract)$
begin{abstract}
$abstract$
end{abstract}
$endif$

$for(include-before)$
$include-before$

$endfor$
$if(toc)$
{
$if(colorlinks)$
hypersetup{linkcolor=$if(toccolor)$$toccolor$$else$black$endif$}
$endif$
setcounter{tocdepth}{$toc-depth$}
tableofcontents
}
$endif$
$if(lot)$
listoftables
$endif$
$if(lof)$
listoffigures
$endif$
$body$

$if(natbib)$
$if(bibliography)$
$if(biblio-title)$
$if(book-class)$
renewcommandbibname{$biblio-title$}
$else$
renewcommandrefname{$biblio-title$}
$endif$
$endif$
bibliography{$for(bibliography)$$bibliography$$sep$,$endfor$}

$endif$
$endif$
$if(biblatex)$
printbibliography$if(biblio-title)$[title=$biblio-title$]$endif$

$endif$
$for(include-after)$
$include-after$

$endfor$
end{document}

Salva il file /usr/share/texlive/template.tex e scrivi uno script che convertirà il file Markdown in PDF, creando nella stessa cartella un file con il nome del file Markdown preceduto da .pdf, cioè dopo la conversione filename.md nella cartella apparirà filename.md.pdf. Lo script si chiamerà md2pdf e lo metteremo nel percorso /usr/bin. Eseguiremo i comandi in sequenza:

user@hostname:~$ cd
user@hostname:~$ touch md2pdf
user@hostname:~$ echo "#!/bin/bash" > md2pdf
user@hostname:~$ echo "pandoc --output=$1.pdf --from=markdown_github --latex-engine=pdflatex --listings --template=/usr/share/texlive/template.tex $1" >> md2pdf
user@hostname:~$ sudo cp md2pdf /usr/bin/
user@hostname:~$ sudo chmod 111 /usr/bin/md2pdf

Nella quarta riga è indicato il comando di conversione. Fai attenzione a —from=markdown_github. La versione GitHub di Markdown è retrocompatibile con il Markdown originale, quindi se il tuo testo è scritto in esso, non devi preoccuparti. Se invece il tuo file MD è scritto in un dialetto specifico di Markdown, consulta il manuale di Pandoc (man pandoc), assicurati che la tua implementazione lo supporti e modifica /usr/bin/md2pdf se necessario.

Script per un'installazione più o meno automatica

Se non avete voglia di configurare nulla e avete una distribuzione basata su Ubuntu, potete provare a creare uno script con il contenuto nascosto sotto il spoiler, e probabilmente si installerà da solo. Solo, il modello TeX, caricato nel spoiler sopra, dovrete copiarlo dove serve. Aprite il Terminale ed eseguite:

user@hostname:~$ cd
user@hostname:~$ touch installmd2pdf.sh

Successivamente, riempitelo con il seguente contenuto:

Contenuto dello script $HOME/installmd2pdf.sh

#!/bin/bash
cd /tmp
sudo apt install texlive-full pandoc -y
wget http://blog.harrix.org/wp-content/uploads/2013/02/PSCyr.zip
unzip -qq PSCyr.zip
cd
mkdir ./PSCyr/fonts/map ./PSCyr/fonts/enc
cp ./PSCyr/dvips/pscyr/*.map ./PSCyr/fonts/map/
cp ./PSCyr/dvips/pscyr/*.enc ./PSCyr/fonts/enc/
echo "fadr6t AdvertisementPSCyr "T2AEncoding ReEncodeFont"" > ./PSCyr/fonts/map/pscyr.map
sudo cp -R ./PSCyr/* $(kpsewhich -expand-var='$TEXMFLOCAL')
sudo texhash
updmap --enable Map=pscyr.map
sudo mktexlsr
sudo touch /usr/share/texlive/template.tex
touch md2pdf
echo "#!/bin/bash" > md2pdf
echo "pandoc --output=$1.pdf --from=markdown_github --latex-engine=pdflatex --listings --template=/usr/share/texlive/template.tex $1" >> md2pdf
sudo cp md2pdf /usr/bin/
sudo chmod 111 /usr/bin/md2pdf

Eseguitelo usando il comando:

user@hostname:~$ sudo bash $HOME/installmd2pdf.sh

Non dimenticate che /usr/share/texlive/template.tex è necessario riempire con il contenuto specificato nella sezione «Template LaTeX per la conversione da md a pdf».

Utilizzo di md2pdf

Basta aprire la cartella con il file Markdown (some_file.md) nel Terminale ed eseguire il comando:

user@hostname:~$ md2pdf some_file.md

Di conseguenza, apparirà un file nella cartella. some_file.md.pdf.

Conclusione

Sulla base del metodo descritto, è possibile costruire qualsiasi stile di file PDF. Inoltre, è possibile convertire, invece di md, altri formati, tutti supportati da Pandoc. Spero che un giorno questa guida possa tornare utile a 3,5 persone.

Fonte: habr.com