Możesz użyć pandoc w systemie Linux do konwersji między ponad 40 formatami plików. Możesz również użyć go do stworzenia prostego systemu docs-as-code, pisząc w Markdown, przechowując w git i publikując w dowolnym z obsługiwanych formatów.
Spis treści:
Konwersja dokumentów i dokumentacja jako kod
Jeśli masz dokument w którymkolwiek z pandoców wiele obsługiwanych formatów plikówKonwersja na którykolwiek z pozostałych to pestka. To przydatne narzędzie!
Ale prawdziwa moc pandoc staje się oczywista, gdy używasz go jako podstawy prostego systemu docs-as-code. Założeniem docs-as-code jest przyjęcie niektórych technik i zasad tworzenia oprogramowania i zastosowanie ich do pisania dokumentacji, zwłaszcza w projektach programistycznych. Możesz go jednak zastosować przy tworzeniu dowolnej dokumentacji.
Twórcy oprogramowania używają swojego ulubionego edytora lub Zintegrowane środowisko programistyczne (IDE) do pisania swoich programów. Kod, który wpisują, jest zapisywany w plikach tekstowych. Te zawierają kod źródłowy do programu.
Używają system kontroli wersjilub VCS (Git jest najpopularniejsza), aby uchwycić zmiany w kodzie źródłowym w trakcie jego opracowywania i ulepszania. Oznacza to, że programista ma pełną historię wszystkich wersji plików kodu źródłowego. Może szybko uzyskać dostęp do dowolnej poprzedniej wersji pliku. Git przechowuje pliki w repozytorium. Na komputerze każdego programisty znajduje się lokalne repozytorium oraz centralne, współdzielone, zdalne repozytorium, które często jest hostowane w chmurze.
Kiedy są gotowi do stworzenia działającej wersji programu, używają pliku kompilator do odczytu kodu źródłowego i wygenerowania pliku wykonywalnego binarnego.
Pisząc dokumenty w lekkim, tekstowym języku znaczników, możesz użyć VCS do kontroli wersji swojego pisania. Kiedy jesteś gotowy do rozpowszechniania lub publikowania dokumentu, możesz użyć pandoc do wygenerowania dowolnej liczby różnych wersji dokumentacji, w tym opartych na Internecie (HTML), przetworzone w tekście lub złożone (LibreOffice, Microsoft Word, TeX), format dokumentu przenośnego (PDF), e-book (ePub), i tak dalej.
Możesz to wszystko zrobić za pomocą jednego zestawu lekkich plików tekstowych z kontrolą wersji.
Instalowanie pandoc
Aby zainstalować pandoc na Ubuntu, użyj tego polecenia:
sudo apt-get install pandoc
W Fedorze polecenie, którego potrzebujesz, jest następujące:
sudo dnf install pandoc
Na Manjaro musisz wpisać:
sudo pacman -Syu pandoc
Możesz sprawdzić, którą wersję zainstalowałeś, używając opcji –version:
pandoc --version
Korzystanie z pandoc bez plików
Jeśli używasz pandoc bez żadnych opcji wiersza poleceń, akceptuje również wpisywane dane. Po prostu naciśnij Ctrl + D, aby wskazać, że skończyłeś pisać. pandoc oczekuje, że wpiszesz w formacie Markdown i generuje dane wyjściowe HTML.
Spójrzmy na przykład:
pandoc
Wpisaliśmy kilka wierszy Markdown i zaraz uderzymy Ctrl + D.
Jak tylko to zrobimy, pandoc generuje równoważne wyjście HTML.
Aby jednak zrobić cokolwiek pożytecznego z pandoc, naprawdę musimy używać plików.
Podstawy Markdown
Markdown to lekki język znaczników, a określonym znakom nadaje się specjalne znaczenie. Możesz użyć zwykłego edytora tekstu, aby utworzyć plik Markdown.
Markdown można łatwo odczytać, ponieważ nie ma kłopotliwych wizualnie tagów, które mogłyby odciągać uwagę od tekstu. Formatowanie w dokumentach Markdown przypomina formatowanie, które reprezentuje. Poniżej znajduje się kilka podstawowych informacji:
Aby wyróżnić tekst kursywą, zawiń go gwiazdkami. * To zostanie podkreślone *
Aby pogrubić tekst, użyj dwóch gwiazdek. ** To będzie pogrubione **
Nagłówki są reprezentowane przez znak liczby / znak krzyżyka (#). Tekst jest oddzielony od krzyżyka spacją. Użyj jednego skrótu dla nagłówka najwyższego poziomu, dwóch dla drugiego poziomu i tak dalej.
Aby utworzyć listę punktowaną, rozpocznij każdy wiersz listy gwiazdką i wstaw spację przed tekstem.
Aby utworzyć listę numerowaną, rozpocznij każdy wiersz od cyfry, po której następuje kropka, a następnie wstaw spację przed tekstem.
Aby utworzyć hiperłącze, umieść nazwę witryny w nawiasach kwadratowych ([]), a adres URL w nawiasach [()] tak: [Link to How to Geek](https://www.newsblog.pl.com/).
Aby wstawić obraz, wpisz wykrzyknik bezpośrednio przed nawiasami kwadratowymi (![]). Wpisz alternatywny tekst obrazu w nawiasach. Następnie umieść ścieżkę do obrazu w nawiasach [()“]. Oto przykład:.
Więcej przykładów tego wszystkiego omówimy w następnej sekcji.
Konwertowanie plików
Konwersje plików są proste. pandoc może zwykle dowiedzieć się, z jakimi formatami plików pracujesz, na podstawie ich nazw plików. Tutaj mamy zamiar wygenerować plik HTML z pliku Markdown. Opcja -o (wyjście) mówi pandocowi nazwę pliku, który chcemy utworzyć:
pandoc -o sample.html sample.md
Nasz przykładowy plik Markdown, sample.md, zawiera krótką sekcję Markdown pokazaną na poniższym obrazku.
Tworzony jest plik o nazwie sample.html. Kiedy klikniemy dwukrotnie plik, otworzy go nasza domyślna przeglądarka.
Teraz wygenerujmy plik Open Document Format dokument tekstowy, w którym możemy otworzyć LibreOffice Writer:
pandoc -o sample.odt sample.md
Plik ODT ma taką samą zawartość jak plik HTML.
Zgrabny dotyk jest alternatywnym tekstem obrazu, który jest również używany do automatycznego generowania podpisu dla figury.
Określanie formatów plików
Opcje -f (od) i -t (do) służą do informowania pandoc, z których formatów plików chcesz konwertować. Może to być przydatne, jeśli pracujesz z formatem pliku, który ma rozszerzenie pliku z innymi pokrewnymi formatami. Na przykład, TeX, i Lateks oba mają rozszerzenie „.tex”.
Używamy również opcji -s (autonomiczna), więc pandoc wygeneruje całą preambułę LaTeX wymaganą do tego, aby dokument był kompletnym, samodzielnym i dobrze sformułowanym dokumentem LaTeX. Bez opcji -s (autonomiczna) wynik nadal byłby dobrze sformatowany LaTeX, który można by umieścić w innym dokumencie LaTeX, nie byłby on poprawnie przeanalizowany jako samodzielny dokument LaTeX.
Wpisujemy:
pandoc -f markdown -t latex -s -o sample.tex sample.md
Jeśli otworzysz plik „sample.tex” w edytorze tekstu, zobaczysz wygenerowany LaTeX. Jeśli masz edytor LaTeX, możesz otworzyć plik TEX, aby zobaczyć podgląd interpretacji poleceń LaTeX-a. Zmniejszenie okna w celu dopasowania do obrazu poniżej sprawiło, że wyświetlacz wyglądał na ciasny, ale w rzeczywistości wszystko było w porządku.
Użyliśmy edytora LaTeX o nazwie Texmaker. Jeśli chcesz zainstalować go w Ubuntu, wpisz:
sudo apt-get install texmaker
W Fedorze polecenie to:
sudo dnf install texmaker
W Manjaro użyj:
sudo pacman -Syu texmaker
Konwersja plików za pomocą szablonów
Prawdopodobnie zaczynasz rozumieć elastyczność, jaką zapewnia pandoc. Możesz pisać raz i publikować w prawie każdym formacie. To wielki wyczyn, ale dokumenty wyglądają na trochę waniliowe.
Korzystając z szablonów, możesz dyktować style używane przez pandoc podczas generowania dokumentów. Na przykład możesz powiedzieć pandoc, aby używał stylów zdefiniowanych w pliku Kaskadowe arkusze stylów (CSS) z opcją –css.
Stworzyliśmy mały plik CSS zawierający poniższy tekst. Zmienia odstępy powyżej i poniżej jednego stylu nagłówka poziomu. Zmienia również kolor tekstu na biały, a kolor tła na odcień niebieskiego:
h1 {
color: #FFFFFF;
background-color: #3C33FF;
margin-top: 0px;
margin-bottom: 1px;
}
Pełne polecenie znajduje się poniżej – zwróć uwagę, że użyliśmy również opcji samodzielnej (-ów):
pandoc -o sample.html -s --css sample.css sample.md
pandoc używa jednego stylu z naszego minimalistycznego pliku CSS i stosuje go do nagłówka pierwszego poziomu.
Inną opcją dostrajania dostępną podczas pracy z plikami HTML jest dołączenie znaczników HTML do pliku Markdown. Zostanie to przekazane do wygenerowanego pliku HTML jako standardowe znaczniki HTML.
Jednak ta technika powinna być zarezerwowana tylko wtedy, gdy generujesz dane wyjściowe HTML. Jeśli pracujesz z wieloma formatami plików, pandoc zignoruje znaczniki HTML dla plików innych niż HTML i zostanie do nich przekazany jako tekst.
Możemy również określić, które style są używane podczas generowania plików ODT. Otwórz pusty dokument LibreOffice Writer i dostosuj style nagłówków oraz czcionek do swoich potrzeb. W naszym przykładzie dodaliśmy również nagłówek i stopkę. Zapisz swój 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ównaj to z wcześniejszym przykładem ODT. W tym dokumencie zastosowano inną czcionkę, kolorowe nagłówki oraz nagłówki i stopki. Jednak został on wygenerowany z dokładnie tego samego pliku Markdown „sample.md”.
Wzorce dokumentów referencyjnych mogą służyć do wskazania różnych etapów tworzenia dokumentu. Na przykład, możesz mieć szablony ze znakami wodnymi „Wersja robocza” lub „Do recenzji”. Szablon bez znaku wodnego zostałby użyty do sfinalizowanego dokumentu.
Generowanie plików PDF
Domyślnie pandoc używa silnika LaTeX PDF do generowania plików PDF. Najłatwiejszym sposobem upewnienia się, że masz spełnione odpowiednie zależności LaTeX, jest zainstalowanie edytora LaTeX, takiego jak Texmaker.
To jednak dość duża instalacja – Tex i LaTeX są dość solidne. Jeśli miejsce na dysku twardym jest ograniczone lub wiesz, że nigdy nie użyjesz TeX lub LaTeX, możesz preferować wygenerowanie pliku ODT. Następnie możesz po prostu otworzyć go w LibreOffice Writer i zapisać jako plik PDF.
Dokumenty jako kod
Używanie języka Markdown jako języka pisania ma kilka zalet, w tym:
Praca na zwykłych plikach tekstowych jest szybka: ładują się szybciej niż pliki edytora tekstu o podobnej wielkości, a także mają tendencję do szybszego poruszania się po dokumencie. Wiele edytorów, w tym gedit, Vim i Emacs, używa podświetlania składni w tekście Markdown.
Będziesz mieć oś czasu 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 naprawdę działa tylko wtedy, gdy pliki są zwykłym tekstem, ponieważ VCS spodziewa się, że będzie z nimi współpracować.
System VCS może rejestrować, kto i kiedy wprowadził zmiany: Jest to szczególnie przydatne, jeśli często współpracujesz z innymi przy dużych projektach. Zapewnia również centralne repozytorium samych dokumentów. Wiele usług Git hostowanych w chmurze, takich jak GitHub, GitLab, i BitBucketmają darmowe poziomy w swoich modelach cenowych.
Możesz generować dokumenty w wielu formatach: za pomocą zaledwie 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ła integracja i ciągłe wdrażanie (CI / CD), mogą być generowane automatycznie podczas tworzenia oprogramowania.
Końcowe przemyślenia
Istnieje wiele innych opcji i funkcji pandoc niż to, co tutaj omówiliśmy. Procesy konwersji dla większości typów plików można dostosować i dopracować. Aby dowiedzieć się więcej, zapoznaj się z doskonałymi przykładami na oficjalnym (i niezwykle szczegółowym) Strona internetowa pandoc.