🥇Gotowe rozwiązanie markdown2pdf z kodem źródłowym dla Linux

Wstęp

Markdown to doskonały sposób na napisanie krótkiego artykułu, a czasami również dość obszernego tekstu, z prostym formatowaniem w postaci kursywy i pogrubienia. Markdown sprawdza się również w pisaniu artykułów z włączeniem kodu źródłowego. Ale czasami chcemy bez strat i zbędnych komplikacji przekonwertować go do zwykłego, dobrze sformatowanego pliku PDF, aby uniknąć problemów podczas konwersji, takich jak na przykład miałem ja — nie można pisać po rosyjsku w komentarzach kodu źródłowego, zbyt długie linie nie są przenoszone, a są obcinane oraz inne drobne problemy. Instrukcja pozwoli szybko skonfigurować konwerter md2pdf nie wnikając specjalnie w to, jak to działa. Skrypt do mniej więcej automatycznej instalacji poniżej w odpowiedniej sekcji.

Mój przykład szablonu TeX do konwersji wykorzystuje pakiet czcionek PSCyr, który zapewnia wsparcie dla czcionek Microsoft, a konkretnie Times New Roman. Takie wymagania dotyczące dyplomu były zgodne z normą. Jeśli potrafisz, możesz zmodyfikować szablon według własnych potrzeb. W mojej instrukcji trzeba będzie najpierw pomęczyć się z konfiguracją PSCyr w TexLive. Konfiguracja jest przeprowadzana w dystrybucji Linux Mint Mate, w przypadku innych dystrybucji może być konieczne poszukaniu standardowych folderów pakietu TexLive dla twojego systemu.

Instalacja TexLive

Oczywiście, można zainstalować tylko niezbędne części tego pakietu. Ale osobiście było mi ewidentnie leniwie szukać minimalnej koniecznej instalacji roboczej. Aby wszystko dokładnie działało, instalujemy cały pakiet TexLive. Nazywa się on texlive-full i zajmuje nieco ponad 2 gigabajty, miej to na uwadze. Wykonujemy polecenie:

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

Po dość długiej instalacji możemy przejść do następnego punktu.

Instalacja konwertera Pandoc

Pandoc — pakiet Linux, który pozwala na konwersję niektórych formatów tekstowych na inne. Posiada wiele ciekawych możliwości, z którymi możesz zapoznać się samodzielnie w internecie. Nas interesuje tylko możliwość konwersji pliku markdown na PDF. Sprawdźmy, czy Pandoc jest zainstalowany, a jeśli nie, zainstalujemy go. Na przykład tak:

user@hostname:~$ dpkg -s pandoc

Jeśli w wyjściu napisano, że nie jest zainstalowany — instalujemy:

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

Instalacja pakietu PSCyr dla TexLive

Na początek trzeba pobrać PSCyr. Na razie nadal jest dostępny pod tym adresem linkiem, jeśli w momencie czytania artykułu z jakiegoś powodu nie będzie dostępny, nie martw się, można go łatwo znaleźć w internecie, wpisując w Google coś w stylu „Instalacja PsCyr texlive”. Jeśli jest dostępny, wystarczy pobrać, a będziemy zakładać, że rozpakowałeś archiwum w swoim katalogu domowym, więc ścieżka do folderu, który znajduje się w archiwum, wygląda tak ~\/PSCyr. Wtedy otwieramy Terminal i wykonujemy kolejno następujące polecenia:

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

Dalej dowiemy się, gdzie znajduje się lokalny katalog texmf. Wykonujemy polecenie:

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

Prawdopodobnie ten katalog to — /usr/local/share/texmf/, a więc wykonujemy:

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

Lub po prostu możemy wykonać polecenie, które skopiuje do katalogu texmf gdziekolwiek się znajduje:

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

Czcionki PSCyr zainstalowane, podłączamy w TexLive:

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

Szablon LaTeX do konwersji md2pdf

Nie będę opisywał, jak dokładnie ten szablon jest skonfigurowany, po prostu podam go pod spoilerem bez szczególnych wyjaśnień. Wystarczy powiedzieć, że jest dobrze skonfigurowany, przynajmniej jeśli chodzi o przetwarzanie tekstów z dużą ilością kodu źródłowego. Jeśli nie podobają ci się rozmiary wcięć, odstępy między wierszami, brak numeracji rozdziałów i podrozdziałów, to moim zdaniem dość łatwo można to znaleźć w internecie, pytając „jak w LaTeX zrobić…”, a potem to, co ci potrzeba. Jeśli to wszystko jest wciąż niezrozumiałe, pisz w komentarzach, postaram się przypomnieć moje ustawienia sprzed czterech lat i opisać, za co odpowiada która linia szablonu. Na razie opiszę, jak zrobiłem to na swoim komputerze, a ty możesz powtórzyć lub zmodyfikować to według własnych potrzeb.

Tworzymy plik template.tex w katalogu /usr/share/texlive/:

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

Nadajemy mu prawa do odczytu:

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

otwieramy jako root i wklejamy w niego zawartość ukrytą pod spoilerem poniżej:

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

Zawartość szablonu \/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}

Zapisujemy plik /usr/share/texlive/template.tex i piszemy skrypt, który będzie konwertować plik Markdown na PDF, tworząc w tym samym katalogu plik o nazwie pliku Markdown z sufiksem .pdf, czyli po konwersji filename.md w katalogu pojawi się filename.md.pdf. Nazwiemy skrypt md2pdf i umieścimy go w lokalizacji /usr/bin. Wykonamy kolejno polecenia:

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

W 4. linii faktycznie podana jest komenda konwersji. Zwróć uwagę na —from=markdown_github. Wersja Markdown GitHub jest w pełni zgodna z oryginalnym Markdown, więc jeśli twój tekst jest w nim napisany, nie ma się czym martwić. Jeśli twój plik MD jest napisany w specyficznym dialekcie Markdown, przeczytaj dokumentację Pandoc (man pandoc), upewnij się, że twoja implementacja jest obsługiwana i wprowadź niezbędne poprawki /usr/bin/md2pdf w razie potrzeby.

Skrypt do bardziej lub mniej automatycznej instalacji

Jeśli nie chcesz w ogóle nic konfigurować, a masz dystrybucję podobną do Ubuntu, możesz spróbować stworzyć skrypt z zawartością ukrytą pod spoilerem, a prawdopodobnie wszystko zainstaluje się samo; jedynie szablon TeX, umieszczony pod powyższym spoilerem, musisz skopiować we właściwe miejsce. Otwórz Terminal i wykonaj:

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

Następnie wypełnij go następującą zawartością:

Zawartość skryptu $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

Uruchom go za pomocą polecenia:

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

Nie zapomnij, że /usr/share/texlive/template.tex musisz uzupełnić wskazanym w sekcji „Szablon LaTeX do konwersji md2pdf” zawartością.

Użycie md2pdf

Po prostu otwórz folder z plikiem Markdown (some_file.md) w Terminalu i wykonaj polecenie:

user@hostname:~$ md2pdf some_file.md

W rezultacie w folderze pojawi się plik some_file.md.pdf.

Podsumowanie

Na podstawie opisanego metodu można stworzyć dowolny styl plików PDF, a także można konwertować inne formaty zamiast md, wszystkie obsługiwane przez Pandoc. Mam nadzieję, że pewnego dnia ta instrukcja przyda się 3,5 osobom.

Źródło: habr.com