Praca nad dokumentacją w formatach takich jak doc/docx (Word, LibreOffice etc.) “obsysa”. To samo można powiedzieć o Latexie. Oba podejścia odciągają uwagę od samego procesu pisania - pierwsze przez potrzebę ciągłego nadzoru nad stylem, drugie przez konieczność zapanowania nad okrutną ilością znaczników… które dodatkowo wymagają wpisania. Ponieważ nie jest trudno mnie rozproszyć ;) nie jestem ich fanem.

Jednocześnie proste formaty tekstowe takie jak markdown nie dają bezpośrednio kontroli nad tym jak dokument zostanie wyświetlony / wydrukowany. Szczęśliwie dodanie tej fukncjonalności nie jest trudne - chociażby dzięki Pandoc-owi. Przy minimalnym wysiłku daje to całkiem przyjazne podejście do tworzenia artykułów akademickich.

To właśnie sposób, który rozwinąłem gdy rozpocząłem pisanie pracy inżynierskiej. Daje mi to dużą kontrolę nad formatem poprzez latex… nie zmuszając mnie jednocześnie do pisania w latexie. W skrócie - piszę markdown, po czym generuję pdf-a poprzez Pandoc-a z lekko zmodyfikowanym przeze mnie szablonem domyślnym. Załatwia mi to wszystkie marginesy, przypisy bibliograficzne, spisy treści itd.

Bardzo ułatwiło mi to pracę… ale do pełni szczęścia musiałem pokonać kilka barier.

Korzystaj z frontmatter

Bardzo szybo okazało się, że w miarę dodawania kolejnych opcji (wielkości marginesów, czcionki itd.) polecenie Pandoc-a szybko rozrosło się do pokaźnych rozmiarów i stało się nieczytelne.

Rozwiązanie jest proste - trzeba jak najwięcej tego typu opcji umieścić we frontmatter, na początku dokumentu .md np.

---
papersize: a4
geometry:
- top=25mm
- bottom=25mm
- left=30mm
- right=20mm
start-page: 5
author:
- Name Surname
title:  'Loremipsum - pandoc test'
lang: pl
numbersections: True
toc: True
bibliography: "samplebib.bib"
reference-section-title: "Bibliografia"
csl: "harvard-cite-them-right.csl"
---

Ten segment spowoduje ustawienie rozmiarów kartki na A4, marginesy na 25mm x 25mm x 30mm x 20mm, z numeracją stron zaczynającą się od 5 (co może się przydać jeśli chce się dodać gotowe strony tytułowe z jakimś oświadczeniem etc), przypisze autora i tytuł dokumentu, ustawi język na polski, doda numerację rozdziałów, z automatycznym spisem treści (można też dodać spis ilustracji i tabel - lof: True i lot: True), z osobną sekcją na bibliografię wykorzystującą plik .bib (stworzony np. w Zotero) i sformatowaną zgodnie z definicją w pliku harvard-cite-them-right.csl.

Dzięki temu polecenie zrobienia pdf-a skróciło się do:

pandoc --citeproc loremipsum.md -o test.pdf --template=./mystyle.latex

Przypisy w stopce

Jest kilka sposobów na dodanie przypisów, ale wg mnie najprostszy to tzw. inline notes. Wystarczy wpisać ^, następnie nawiasy kwadratowe [] z treścią przypisu między nimi.

Przykładowo:

Vel facilisis volutpat est velit egestas dui id ornare arcu.^[Inline notes are easier to write, since you don't have to pick an identifier and move down to type the note.]

może dać taki wynik:

Biblografia w stopce

Jeśli jest taka potrzeba to najlepiej jest użyć pliku z deklaracją stylu bibliograficznego (.csl), który przewiduje taką opcję. Jeśli jednak trzeba to wymusić to można np. dodać linka bibliograficznego jako inline note.

Lacus viverra vitae congue eu consequat ac felis donec et ^[@shah_ansible_2015].

Pandoc poradzi sobie z czymś takim, podmieni linka na odpowiedni przypis, doda też odpowiedni wpis w sekcji z bibliografią.

Okraś to Latexem

To co da się zrobić “gołym” markdownem ma swoje granice. Choć bardzo przyjemnie się w nim pisze, to czasami po prostu trzeba zrobić coś ekstra z układem strony (np. może być jakaś specyfikacja, która od nas tego wymaga).

Szczęśliwie można dodawać znaczniki Latex-owe bezpośrednio w markdownie.

Należy jednak zdawać sobie sprawę, że ma to swoją cenę - o ile zadziała to super do zrobienia pdf-a, to wykorzystanie tego samego pliku .md w np. generatorze stron statycznych (Hugo etc.) będzie już nieco kłopotliwe. W najlepszym przypadku te znaczniki wyświetlą się jako zwykły tekst.

Jednak jeśli celem jest artykuł “drukowany” to nie jest to problem. Sugerowałbym tylko sprowadzenie tych dodatkowych znaczników do minimum.

Podział strony

W sytuacji gdy jest potrzeba zaczęcia kolejnej sekcji tekstu na nowej stronie wystarczy dodać:

\pagebreak

• dodatkowa “sztuczka”: dodanie tego na końcu dokumentu spowoduje, że bibliografia będzie na nowej stronie, a nie bezpośrenio po ostatnim zdaniu.

Rozdziały bez numeracji

Gdy mamy do czynienia z rozdziałami, które mają być wyłączone z ogólnej numeracji (np. wstęp) to dodanie {-} po ich nazwie zapewni nam tę opcję.

# Some section {-}

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Sit amet luctus venenatis lectus magna fringilla urna.

Lista zdjęć / tabel w nietypowym miejscu

Jeśli specyfikacja artykułu wymaga umieszczenia spisu ilustracji / tabel w miejscu innym od tego, który używany jest domyślnie można to osiągnąć dodając:

\hypertarget{lof}{
\listoffigures\label{lof}}
\addcontentsline{toc}{section}{Nazwa sekcji}

• pamiętając, że lof to “list of figures” a lot to “list of tables”

Własny szablon tex

W sytuacji gdy własny szablon będzie niezbędny niestety nie da się uniknąć nauki podstaw Latexa. Zaskakująco dużo jednak da się uzyskać po prostu modyfikując lekko szablon domyślny. Aby go “wyciągnąć” można wpisać:

pandoc -D latex > *ścieżka/nazwapliku*

… podmieniając ścieżka/nazwapliku na interesującą nas lokalizację i nazwę.

Na zakończenie

Te proste kroki pokrywają 99% sytuacji na jakie natrafiłem do tej pory pisząc pracę inżynierską. Pisze się w ten sposób bardzo szybko i przyjemnie - jednocześnie zapewniając dostosowanie się do wymogów narzuconych przez uczelnię. Nie martwię się przypisami bibliograficznymi, spisami, podpisami itd.

Z tym podejściem jestem w stanie pracować w moich ulubionych edytorach (na tę chwilę Joplin i Obsidian - jaka szkoda, że ten drugi nie ma “normalnej” licencji, jedynie abonament) ciesząc się wszystkimi zaletami jakie niesie markdown (w tym łatwością dodania kontroli wersji Git i automatycznym generowaniem dokumentów poprzez Github Actions - ale o tym może kiedy indziej ;) ).