Soluția completă markdown2pdf cu cod sursă pentru Linux

Prefață

Markdown este o modalitate excelentă de a scrie un articol scurt, dar uneori chiar și un text destul de voluminos, cu un format simplu, cum ar fi italic și bold. De asemenea, Markdown este util pentru scrierea de articole care includ cod sursă. Totuși, uneori vrei să-l convertești în mod direct într-un fișier PDF bine structurat, fără probleme de conversie, cum ar fi cele pe care le-am întâmpinat eu - nu poți scrie în rusă în comentariile codului sursă, liniile prea lungi nu se împart, ci sunt tăiate și alte probleme minore. Instrucțiunea va permite configurarea rapidă a converterului. md2pdf fără a pătrunde în mod special cum funcționează. Scriptul pentru o instalare mai puțin sau mai mult automată este mai jos în secțiunea corespunzătoare.

Exemplul meu de șablon TeX pentru conversie folosește pachetul de fonturi PSCyr, care include suport pentru fonturile Microsoft, și anume Times New Roman. Aceasta a fost cerința pentru diplomă conform GOST. Dacă te descurci, poți modifica șablonul în funcție de nevoile tale. În instrucțiunea mea, va trebui mai întâi să îți faci puțin de lucru cu configurarea PSCyr în TexLive. Configurarea se realizează în distribuția Linux Mint Mate; pentru alte distribuții, s-ar putea să trebuiască să cauți folderele standard ale pachetului TexLive pentru sistemul tău.

Instalarea TexLive

Desigur, poți instala doar părțile necesare ale acestui pachet. Dar personal, mi-era lene să caut o instalare minimală de lucru. Pentru ca totul să funcționeze corect, instalăm întregul pachet TexLive. Se numește texlive-full și are o dimensiune de puțin peste 2 gigabytes, ține cont de acest fapt. Executăm comanda:

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

După o instalare destul de lungă, putem trece la următorul punct.

Instalarea converterului Pandoc

Pandoc este un pachet Linux care permite conversia unor formate de text în altele. Are multe funcționalități interesante pe care le poți explora singur pe internet. Noi suntem interesați doar de posibilitatea de a transforma un fișier markdown în PDF. Vom verifica dacă Pandoc este instalat și, dacă nu, îl vom instala. De exemplu:

user@hostname:~$ dpkg -s pandoc

Dacă în ieșire scrie că nu este instalat — îl instalăm:

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

Instalarea pachetului PSCyr pentru TexLive

În primul rând, trebuie să descarci PSCyr. Deocamdată este încă disponibil prin acesta linkul, dacă în momentul citirii articolului acesta nu este disponibil din diverse motive, nu vă descurajați, deoarece este ușor de găsit împreună cu instrucțiunile de instalare, căutând pe Google ceva de genul „Instalare PsCyr texlive”. Dacă este disponibil, atunci este mai simplu pentru dumneavoastră, descărcați-l și să presupunem că ați dezarhivat arhiva în folderul personal, astfel încât calea către folderul conținut în arhivă arată ca ~\/PSCyr. Atunci deschidem Terminalul și executăm secvențial comenzile:

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

Apoi aflăm unde se află catalogul local texmf. Executăm comanda:

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

Cu siguranță acest catalog este la dumneavoastră — /usr/local/share/texmf/, atunci executăm:

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

Sau, dacă doriți, puteți executa comanda care va copia în folder texmf indiferent de unde ar fi:

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

Fonturile PSCyr sunt instalate, le conectăm în TexLive:

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

Șablon LaTeX pentru conversia md2pdf

Nu voi descrie cum este configurat acest șablon, ci îl voi prezenta pur și simplu sub spoiler fără explicații suplimentare. E suficient să spun că este configurat destul de bine, cel puțin modul în care procesează texte cu mult cod sursă. Dacă dimensiunile indentărilor, intervalele între linii, lipsa numerotării secțiunilor și subsecțiunilor nu vă mulțumesc, atunci după părerea mea este destul de ușor să căutați pe internet întrebând „cum în Latex să fac…”, iar apoi faceți ceea ce aveți nevoie. Dacă este complet neclar, scrieți în comentarii, voi încerca să-mi amintesc setările mele de acum patru ani și să explic ce face fiecare linie a șablonului. Deocamdată, voi descrie cum am făcut eu pe PC-ul meu, iar dvs. sunteți liberi să repetați sau să modificați după cum doriți.

Creăm fișierul template.tex în catalogul /usr/share/texlive/:

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

Îi setăm permisiunile de citire:

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

deschidem cu root și inserăm în el conținutul ascuns sub spoilerul de mai jos:

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

Continutul șablonului \/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,russian,ukrainian]{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}

Salvăm fișierul /usr/share/texlive/template.tex și scriem un script care va converti fișierul Markdown în PDF, creând în aceeași folder un fișier cu numele fișierului Markdown cu sufixul .pdf, adică după conversie filename.md în folder va apărea filename.md.pdf. Să numim scriptul md2pdf și să-l plasăm în calea /usr/bin. Vom executa secvențial comenzile:

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

În linia a 4-a este de fapt indicată comanda de conversie. Acordați atenție la —from=markdown_github. Versiunea GitHub a Markdown este compatibilă înapoi cu Markdown-ul original, așa că, dacă textul tău este scris în acesta, nu trebuie să-ți făcăt griji. Dacă fișierul tău MD este scris într-un dialect specific de Markdown, citește manualul Pandoc (man pandoc), asigură-te că implementarea ta este suportată și ajustează /usr/bin/md2pdf dacă este necesar.

Script pentru o instalare mai mult sau mai puțin automată

Dacă nu vrei să configurezi nimic, și ai o distribuție similară cu Ubuntu, poți încerca să creezi un script cu conținutul ascuns sub spoiler, iar foarte probabil totul se va instala singur, singurul lucru este că șablonul TeX, postat sub spoilerul de mai sus, va trebui să-l copiezi unde trebuie tu. Deschide Terminalul și execută:

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

Apoi umple-l cu următorul conținut:

Conținutul scriptului $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

Execută-l cu comanda:

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

Nu uita că /usr/share/texlive/template.tex trebuie să-l umpli cu conținutul specificat în secțiunea „Șablon LaTeX pentru conversia md2pdf”.

Utilizarea md2pdf

Deschide pur și simplu folderul cu fișierul Markdown (some_file.md) în Terminal, și execută comanda:

user@hostname:~$ md2pdf some_file.md

Ca rezultat, în folder va apărea un fișier some_file.md.pdf.

Concluzie

Pe baza metodei descrise, poți construi orice stil de fișiere PDF, poți de asemenea să convertești în loc de md alte formate, orice suportate de Pandoc. Sper că această instrucțiune va fi utilă odată pentru 3,5 oameni.

Sursa: habr.com