Jak używać pandoc do konwertowania plików w wierszu poleceń systemu Linux

Możesz wykorzystać pandoc na systemie Linux do konwersji pomiędzy ponad 40 różnymi formatami plików. Ponadto, dzięki niemu, możliwe jest stworzenie prostego systemu „docs-as-code”, gdzie piszesz w Markdown, przechowujesz w git i publikujesz w jednym z obsługiwanych formatów.

Konwersja dokumentów oraz dokumentacja jako kod

Jeśli posiadasz dokument w którymkolwiek z wielu obsługiwanych formatów plików pandoc, jego konwersja na inny format jest dziecinnie prosta. To niezwykle przydatne narzędzie!

Prawdziwa siła pandoc ujawnia się, gdy stosujesz go jako fundament dla prostego systemu „docs-as-code”. Koncepcja ta opiera się na zastosowaniu technik i zasad znanych z tworzenia oprogramowania do pisania dokumentacji, szczególnie w projektach programistycznych, ale może być też używana w każdym innym kontekście dokumentacyjnym.

Programiści korzystają ze swojego ulubionego edytora lub Zintegrowanego środowiska programistycznego (IDE) do pisania kodu. Ten kod jest przechowywany w plikach tekstowych, które zawierają kod źródłowy aplikacji.

W trakcie pracy używają systemów kontroli wersji (najpopularniejszym z nich jest Git), aby śledzić zmiany w kodzie źródłowym podczas jego rozwoju i udoskonalania. Dzięki temu programista ma pełną historię wszystkich wersji plików kodu źródłowego, co pozwala na szybki dostęp do dowolnej wcześniejszej wersji. Git przechowuje pliki w repozytorium, które można podzielić na lokalne i centralne, współdzielone repozytorium, często hostowane w chmurze.

Kiedy programiści są gotowi do stworzenia działającej wersji aplikacji, używają pliku kompilatora, który przetwarza kod źródłowy i generuje plik wykonywalny.

Pisząc dokumenty w lekkim języku znaczników, możesz również zastosować system VCS do kontroli wersji swojego pisania. Gdy jesteś gotowy do dystrybucji lub publikacji dokumentu, pandoc umożliwia generowanie różnych wersji dokumentacji, w tym wersji webowych (HTML), sformatowanych tekstowo lub zaawansowanych (LibreOffice, Microsoft Word, TeX), a także plików PDF (PDF), e-booków (ePub) i wielu innych.

Wszystko to możesz osiągnąć przy pomocy jednego zestawu lekkich plików tekstowych kontrolowanych wersjami.

Instalacja pandoc

Aby zainstalować pandoc na systemie Ubuntu, użyj następującego polecenia:

sudo apt-get install pandoc

Dla systemu Fedora polecenie, którego potrzebujesz, to:

sudo dnf install pandoc

W Manjaro należy wpisać:

sudo pacman -Syu pandoc

Aby sprawdzić, którą wersję zainstalowałeś, użyj opcji –version:

pandoc --version

Używanie pandoc bez plików

Jeżeli korzystasz z pandoc bez żadnych opcji wiersza poleceń, akceptuje również dane wejściowe. Po prostu naciśnij Ctrl + D, aby zakończyć pisanie. Pandoc oczekuje, że wprowadzisz tekst w formacie Markdown i generuje dane wyjściowe w formacie HTML.

Przykład:

pandoc

Wprowadziliśmy kilka wierszy w formacie Markdown i teraz naciśniemy Ctrl + D.

Po zakończeniu działania, pandoc generuje odpowiadające wyjście w formacie HTML.

Aby jednak wykorzystać pełen potencjał pandoc, naprawdę musimy pracować z plikami.

Podstawy Markdown

Markdown to lekki język znaczników, w którym określonym znakom przypisać specjalne znaczenie. Możesz stworzyć plik Markdown w dowolnym edytorze tekstowym.

Markdown jest łatwy do odczytania, gdyż nie zawiera uciążliwych znaczników, które mogłyby odciągać uwagę od treści. Formatowanie w dokumentach Markdown jest zbliżone do tego, co reprezentuje. Oto kilka podstawowych zasad:

Aby wyróżnić tekst kursywą, otocz go gwiazdkami. * To zostanie podkreślone *
Aby pogrubić tekst, użyj dwóch gwiazdek. ** To będzie pogrubione **
Nagłówki oznaczone są znakiem #. Tekst oddzielony jest od znaku spacją. Użyj jednej gwiazdki dla nagłówka najwyższego poziomu, dwóch dla drugiego poziomu itd.
Aby utworzyć listę punktowaną, zaczynaj każdy wiersz listy od gwiazdki, a następnie wstaw spację przed tekstem.
Aby stworzyć listę numerowaną, rozpocznij każdy wiersz od cyfry, po której następuje kropka, a następnie spacja.
Aby stworzyć hiperlink, umieść tekst w nawiasach kwadratowych, a adres URL w nawiasach okrągłych, np. [Link do How to Geek](https://www.newsblog.pl.com/).
Aby dodać obraz, wpisz wykrzyknik przed nawiasami kwadratowymi (![]), następnie wpisz alternatywny tekst obrazu w nawiasach, a ścieżkę do obrazu w nawiasach okrągłych. Przykład: .

Więcej przykładów omówimy w następnej sekcji.

Konwersja plików

Konwersja plików jest prosta. Pandoc zazwyczaj rozpoznaje formaty plików na podstawie ich rozszerzeń. Poniżej przedstawiamy sposób na wygenerowanie pliku HTML z pliku Markdown. Opcja -o (wyjście) wskazuje pandocowi nazwę pliku, jaki chcemy utworzyć:

pandoc -o sample.html sample.md

Przykładowy plik Markdown, sample.md, zawiera krótką sekcję Markdown przedstawioną na poniższym obrazku.

W wyniku tego powstaje plik o nazwie sample.html. Po dwukrotnym kliknięciu otworzy on naszą domyślną przeglądarkę.

Teraz stwórzmy dokument w formacie Open Document Format, który możemy otworzyć w LibreOffice Writer:

pandoc -o sample.odt sample.md

Plik ODT zawiera tę samą treść, co plik HTML.

Przydatnym dodatkiem jest alternatywny tekst obrazu, który można wykorzystać do automatycznego generowania podpisów.

Określanie formatów plików

Opcje -f (od) i -t (do) informują pandoc o formatach plików, z których chcesz konwertować. Może to być przydatne, gdy pracujesz z typem pliku, który ma rozszerzenie używane przez inne pokrewne formaty. Na przykład, zarówno TeX, jak i LaTeX mają rozszerzenie „.tex”.

Używając opcji -s (autonomiczna), pandoc generuje całą preambułę LaTeX, która jest potrzebna, aby dokument stał się kompletnym, samodzielnym dokumentem LaTeX. Bez tej opcji wynikowy dokument byłby poprawnie sformatowanym LaTeX, ale nie mógłby zostać poprawnie zinterpretowany jako samodzielny dokument.

Wpisujemy:

pandoc -f markdown -t latex -s -o sample.tex sample.md

Po otwarciu pliku „sample.tex” w edytorze tekstowym zobaczysz wygenerowany kod LaTeX. Jeśli używasz edytora LaTeX, możesz otworzyć plik TEX, aby zobaczyć podgląd interpretacji poleceń LaTeX. Zmniejszenie okna w celu dopasowania do obrazu poniżej sprawiło, że ekran wyglądał na ciasny, ale w rzeczywistości wszystko było w porządku.

Użyliśmy edytora LaTeX o nazwie Texmaker. Aby zainstalować go w Ubuntu, wpisz:

sudo apt-get install texmaker

W systemie Fedora polecenie to:

sudo dnf install texmaker

W Manjaro użyj:

sudo pacman -Syu texmaker

Konwersja plików przy użyciu szablonów

Prawdopodobnie zaczynasz dostrzegać elastyczność, jaką oferuje pandoc. Możesz pisać raz i publikować w niemal każdym formacie. To wielka zaleta, ale dokumenty mogą wyglądać odrobinę prosto.

Dzięki szablonom, możesz dyktować style, które pandoc ma zastosować podczas generowania dokumentów. Na przykład, możesz polecić pandocowi użycie stylów zdefiniowanych w pliku Kaskadowe arkusze stylów (CSS) za pomocą opcji –css.

Stworzyliśmy mały plik CSS, który zawiera poniższy kod. Zmienia on odstępy nad i pod stylem nagłówka pierwszego poziomu oraz kolor tekstu na biały, a tło na odcień niebieskiego:

h1 {
  color: #FFFFFF;
  background-color: #3C33FF;
  margin-top: 0px;
  margin-bottom: 1px;
}

Pełne polecenie wygląda tak – zwróć uwagę, że użyliśmy również opcji samodzielnej (-s):

pandoc -o sample.html -s --css sample.css sample.md

Pandoc zastosuje styl z naszego minimalistycznego pliku CSS do nagłówka pierwszego poziomu.

Inną opcją dostosowywania, dostępna podczas pracy z plikami HTML, jest dodawanie znaczników HTML do pliku Markdown. Zostaną one przekazane do wygenerowanego pliku HTML jako standardowe znaczniki HTML.

Jednak ta technika powinna być stosowana tylko w przypadku generowania danych wyjściowych w formacie HTML. Jeśli pracujesz z różnymi formatami plików, pandoc zignoruje znaczniki HTML dla plików innych niż HTML i przekaże je jako tekst.

Możemy również określić style, które mają być używane podczas generowania plików ODT. Otwórz pusty dokument w LibreOffice Writer i dostosuj style nagłówków oraz czcionek według własnych potrzeb. W naszym przykładzie dodaliśmy także nagłówek i stopkę, a następnie zapisaliśmy dokument jako „odt-template.odt”.

Możemy teraz użyć tego jako szablonu z opcją –reference-doc:

pandoc -o sample.odt --reference-doc=odt-template.odt sample.md

Porównując to z wcześniejszym przykładem ODT, w tym dokumencie zastosowano inną czcionkę, kolorowe nagłówki oraz nagłówki i stopki. Został on jednak wygenerowany z dokładnie tego samego pliku Markdown „sample.md”.

Szablony dokumentów referencyjnych mogą być używane do oznaczania różnych wersji dokumentu. Na przykład, możesz stworzyć szablony z oznaczeniami „Wersja robocza” lub „Do recenzji”. Szablon bez znaku wodnego byłby użyty do finalnej wersji dokumentu.

Generowanie plików PDF

Pandoc domyślnie używa silnika LaTeX do generowania plików PDF. Najłatwiejszym sposobem na zapewnienie, że masz zainstalowane wszystkie wymagane zależności LaTeX, jest zainstalowanie edytora LaTeX, takiego jak Texmaker.

Jednakże, jest to dość duża instalacja – TeX i LaTeX są dość rozbudowane. Jeśli miejsce na dysku jest ograniczone lub wiesz, że nigdy nie będziesz używać TeX ani LaTeX, możesz woleć wygenerować plik ODT, a następnie otworzyć go w LibreOffice Writer i zapisać jako plik PDF.

Dokumenty jako kod

Używanie Markdown jako języka pisania ma wiele zalet, w tym:

Praca na zwykłych plikach tekstowych jest szybka: ładują się szybciej niż pliki edytora tekstu o podobnych rozmiarach, a także umożliwiają szybsze przeszukiwanie dokumentu. Wiele edytorów, takich jak gedit, Vim czy Emacs, wspiera podświetlanie składni w Markdown.
Będziesz mieć dostęp do historii wszystkich wersji swoich dokumentów: jeśli przechowujesz dokumentację w systemie VCS, takim jak Git, możesz łatwo zobaczyć różnice między dowolnymi dwiema wersjami tego samego pliku. Jednak to działa tylko wtedy, gdy pliki są w formacie zwykłego tekstu, ponieważ VCS oczekuje takiego formatu.
System VCS rejestruje, kto i kiedy wprowadził zmiany: To szczególnie przydatne, gdy często współpracujesz z innymi nad dużymi projektami. Dostarcza to także centralnego repozytorium dla samych dokumentów. Wiele usług Git w chmurze, takich jak GitHub, GitLab, i BitBucket oferuje darmowe plany w swoich modelach subskrypcyjnych.
Możesz generować dokumenty w wielu formatach: używając kilku prostych skryptów powłoki, możesz pobrać style z CSS i dokumentów referencyjnych. Jeśli przechowujesz dokumenty w repozytorium VCS, które integruje się z Ciągłą integracją i ciągłym wdrażaniem (CI/CD), mogą być automatycznie generowane podczas budowy oprogramowania.

Końcowe przemyślenia

Istnieje wiele innych opcji i funkcji pandoc, niż te, które zostały tutaj omówione. Procesy konwersji dla większości typów plików można dostosować i optymalizować. Aby dowiedzieć się więcej, warto zapoznać się z doskonałymi przykładami na oficjalnej (i niezwykle szczegółowej) stronie pandoc.