Buat Rantai Publikasi dengan Pandoc dan Docker

Diterbitkan: 2022-03-11

Hari ini, kita akan melihat lebih dekat bagaimana para profesional dapat meminta bantuan Pandoc untuk membuat rantai publikasi yang kuat dan mudah diterapkan. Pandoc adalah alat yang sangat sederhana namun kuat yang memungkinkan pengguna untuk mengubah dokumen ke dalam berbagai format, tergantung pada kebutuhan mereka.

Ini dapat sangat menyederhanakan dokumentasi dan publikasi, atau bahkan membuka beberapa kemungkinan otomatisasi baru. Yang terbaik dari semuanya, Pandoc bergantung pada Git-friendly Markdown, yang berarti Anda juga dapat menerapkan sistem kontrol versi untuk dokumentasi Anda tanpa kerumitan tambahan.

Berbicara tentang kerumitan, kami akan mengandalkan gambar Docker untuk menginstal Pandoc dan LaTeX dengan tarikan sederhana. Menginstal perangkat lunak dapat memakan waktu, dan menyiapkan lingkungan perangkat lunak yang berfungsi dari awal saat memulai proyek baru hampir tidak produktif. Docker membantu mengurangi masalah ini dengan memungkinkan pengguna mengatur semuanya dalam hitungan menit, apa pun platformnya.

Selain itu, tidak jarang majikan mengharuskan Anda menyediakan perangkat keras komputer Anda sendiri. Ini sering disebut sebagai Bring Your Own Device (BYOD), dan jangan lupa bahwa pandemi COVID-19 telah membuat bekerja dari rumah menjadi lebih lazim. Tanpa solusi seperti Docker, akan sulit untuk mendukung aplikasi yang berjalan di berbagai perangkat keras dan sistem operasi seperti Windows, macOS, dan Linux.

Mari kita mulai dengan melihat lebih dekat container dan gambar Docker sebelum melanjutkan ke Pandoc.

Docker untuk Menyelamatkan

Menggunakan wadah Docker dapat menghilangkan kebutuhan untuk menginstal beberapa aplikasi perangkat lunak pada mesin baru. Gambar Docker bawaan tersedia di Docker Hub untuk sejumlah besar aplikasi. Penyedia cloud terkemuka seperti AWS, Azure, dan Google semuanya menyediakan pendaftar container. Ada banyak pendaftar pihak ketiga lainnya termasuk GitLab dan Red Hat OpenShift.

Kemungkinan gambar akan tersedia untuk sebagian besar (jika tidak semua) aplikasi. Ini berarti tidak perlu menginstal sebagian besar aplikasi dan dependensinya. Aplikasi hanya dapat dijalankan dalam wadah Docker. Ini dengan mudah menghilangkan masalah yang terkait dengan anggota tim yang menjalankan aplikasi pada perangkat keras yang berbeda dan sistem operasi yang berbeda. Gambar yang sama dapat digunakan untuk menjalankan container pada sistem apa pun yang dapat menjalankannya, dan spesialis Docker dapat membuat proses ini menjadi sangat cepat dan efisien.

Kasus Penggunaan Pandoc: Dokumentasi

Dokumentasi mungkin diperlukan dalam beberapa format berbeda. Dokumen yang sama mungkin perlu tersedia dalam format yang berbeda seperti HTML untuk presentasi dan PDF untuk handout. Mengonversi antar format file bisa membosankan dan membutuhkan banyak waktu. Solusi yang baik adalah memiliki rantai publikasi dengan satu sumber kebenaran. Semua dokumen harus ditulis dalam bahasa yang sama. Ini harus menjadi bahasa berbasis teks karena lebih mudah untuk membuat versi dan menyimpannya di repositori Git.

Penurunan harga adalah pilihan yang baik untuk menciptakan satu sumber kebenaran. Perangkat lunak yang dapat mengonversi dokumen penurunan harga ke berbagai format lain sudah tersedia dan cenderung dapat diandalkan.

Penurunan harga dapat dengan mudah diubah menjadi berbagai format berbeda untuk berbagai kegunaan.

pandoc

Pandoc adalah paket perangkat lunak yang dapat mengubah dokumen ke dalam format yang berbeda. Secara khusus, ini dapat mengubah penurunan harga menjadi HTML, PDF, dan format lain yang banyak digunakan. Proses konversi dapat dikustomisasi menggunakan templat dan metadata di sumber penurunan harga.

Pandoc memerlukan instalasi LaTeX untuk membuat file PDF. Menginstal Pandoc dan LaTeX cukup memakan waktu. Untungnya, ada image Docker bernama pandoc/latex , yang menghilangkan kebutuhan untuk menginstal apa pun selain Docker.

Perintah buruh pelabuhan

Gambar Docker yang sesuai perlu ditemukan atau dibuat yang berisi perangkat lunak yang diperlukan. Dianjurkan untuk menarik gambar ke registri lokal karena pengunduhan dapat memakan waktu.

 docker pull pandoc/latex

Untuk menjalankan perintah dalam wadah Docker memerlukan pembungkus untuk menjalankan wadah Docker dan menjalankan perintah dalam wadah. Solusi yang baik untuk ini adalah dengan menulis fungsi shell pada sistem macOS atau UNIX/Linux. Fungsi tersebut dapat dimasukkan ke dalam skrip login apa pun atau dalam file terpisah seperti $HOME/.functions . Dimungkinkan juga untuk menulis skrip atau alias dengan fungsi yang sama.

 function pandoc { echo pandoc $@ docker run -it --rm -v $PWD:/work -w /work pandoc/latex pandoc "$@" }

Fungsi ini melakukan hal berikut:

Ini mencetak perintah ke layar.
Ini menjalankan wadah Docker dari gambar pandoc/latex .
Opsi -it membuat sesi terminal interaktif dan membuat output dari perintah terlihat.
Opsi --rm menghapus wadah setelah perintah dihentikan.
-v $PWD:/work memasang direktori saat ini di Host ke direktori /work di wadah.
-w /work menjadikan direktori /work dalam wadah sebagai direktori kerja.
pandoc "$@" menjalankan perintah pandoc di wadah yang meneruskan semua opsi baris perintah yang diteruskan ke fungsi.

Shell atau skrip perlu memuat fungsi ke dalam memori.

 . $HOME/.functions

Fungsi tersebut sekarang menjadi perintah dalam dirinya sendiri dan berperilaku dengan cara yang sama seperti jika biner pandoc diinstal secara lokal. Pendekatan ini dapat digunakan untuk perintah apa pun yang tersedia di gambar Docker.

Penurunan harga ke HTML

Untuk mengonversi Markdown ke HTML, lebih baik menggunakan template dan metadata di Markdown.

Metadata Penurunan Harga

Sumber penurunan harga dapat memiliki bagian header yang dapat memiliki metadata arbitrer. Metadata mengambil bentuk pasangan nilai kunci. Nilai dapat diganti dalam template HTML.

 --- title: Document title links: prev: index next: page002 ...

Header dimulai dengan baris yang hanya berisi tiga tanda hubung --- . Itu diakhiri dengan garis yang hanya berisi tiga titik ... . Kunci adalah kata tunggal diikuti oleh titik dua dan nilainya. Kunci dapat bersarang. Contoh menunjukkan definisi kunci yang disebut title, links.prev dan links.next .

Pendekatan ini menggunakan file terpisah untuk setiap halaman. Dalam contoh, halaman sebelumnya adalah index.md , halaman saat ini adalah page001.md , dan halaman berikutnya adalah page002.md . Dalam praktiknya, nama file yang lebih bermakna akan digunakan sehingga lebih mudah untuk menyusun ulang dan menyisipkan halaman.

Template HTML

Template HTML hanyalah sebuah file HTML. Substitusi metadata dan struktur kontrol sederhana dapat ditambahkan di antara simbol dolar. Berikut adalah contoh sederhana dari template HTML untuk Pandoc:

 <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>$title$</title> <link href="../css/style.css" type="text/css" rel="stylesheet" /> </head> <header> <h1>$title$</h1> </header> <body> $body$ </body> <footer> $if(links.prev)$ <a href="$links.prev$.html" class="previous">&laquo; Previous</a> $endif$ $if(links.next)$ <a href="$links.next$.html" class="next">Next &raquo;</a> $endif$ </footer> </html>

Contoh menunjukkan template. $body$ diganti dengan teks penurunan harga yang dikonversi ke HTML. Pernyataan bersyarat hanya menghasilkan tautan HTML jika metadata didefinisikan di header Penurunan harga.

Menghasilkan HTML dari Penurunan Harga

Pandoc hanya perlu diberi tahu apa nama file input dan output ditambah file template apa pun. Format file input default adalah Markdown . Itu dapat menyimpulkan format file output dari ekstensi file output yang ditentukan.

Perintah untuk menghasilkan output dapat berupa skrip atau makefile.

 dir=Project for input_file in ${dir}/*.md do output_file=HTML/${input_file%.md}.html if [[ ${input_file} -nt ${output_file} ]] then pandoc --data-dir . --template presentations.html -t html \ -o ${output_file} ${input_file} fi done

Untuk setiap file .md di direktori Project , file .html yang sesuai akan dibuat di direktori HTML/Project jika file output lebih lama dari file input atau tidak ada.

Menghasilkan PDF Beamer dari Penurunan Harga

Beamer adalah paket LaTeX untuk menghasilkan presentasi. Outputnya adalah tayangan slide PDF.

File sumber penurunan harga yang sama dapat digunakan untuk menghasilkan PDF beamer.

 pandoc -t beamer -o PDF/Project.pdf -V theme:Boadilla -V colortheme:whale Project/index.md Project/page000.md

Detail perintahnya adalah:

Opsi -t beamer mengatakan gunakan LaTeX dan beamer untuk menghasilkan PDF.
Opsi -o menentukan file output.
Opsi -V memilih tema beamer dan tema warna.
Perintah diakhiri dengan daftar file penurunan harga yang akan digabungkan dalam urutan yang diberikan.

Semua pemrosesan dilakukan di dalam wadah Docker.

Penurunan harga ke PDF

Mengonversi dokumen penurunan harga ke dokumen PDF juga cukup sederhana. PDF selalu dihasilkan dengan terlebih dahulu mengonversi Markdown ke LaTeX. Metadata dapat ditambahkan ke header Markdown untuk menyesuaikan output seperti mengatur ukuran kertas dan ukuran margin.

 --- title: Title of document papersize: a4 geometry: - margin=20mm ...

Menghasilkan PDF dari Penurunan Harga

Perintah untuk mengonversi Markdown ke PDF sederhana:

 pandoc -s Project/outline.md -o PDF/ProjectOutline.pdf

Opsi -s membuat dokumen mandiri.

Kesimpulan

Tidak perlu lagi menghabiskan waktu berhari-hari untuk menginstal perangkat lunak. Cukup menjalankan perintah dalam wadah Docker menghilangkan kebutuhan untuk instalasi. Banyak aplikasi memiliki image Docker yang sesuai di Docker Hub. Jika perangkat lunak perlu diperbarui, cukup tarik gambar Docker terbaru.

Menyiapkan komputer baru hanyalah masalah menginstal Docker, menarik gambar yang diperlukan, dan membuat beberapa skrip.

Tidak perlu lagi membuat dokumen dalam format yang berbeda. Format tunggal seperti penurunan harga dapat digunakan untuk semua dokumen. Alat seperti Pandoc kemudian dapat menghasilkan dokumen dari penurunan harga menjadi sejumlah besar format berbeda.

Karena penurunan harga adalah file teks, saat diperiksa ke dalam repositori Git, riwayat versi lengkap tersedia. Repositori Git juga secara otomatis membuat penurunan harga dan memungkinkan orang untuk mengomentari perubahan tanpa harus menggunakan riwayat perubahan yang berantakan di file dokumen itu sendiri.