Mengautomasi Penyusunan Dokumen ConTeXt: Bahagian 2

Via Skrip 'Continuous Integration' oleh Dave Jarvis

Selasa, 24 November 2020

#context | #automasi | #ci | #markdown | #R

Telah lebih dari satu tahun berlalu semenjak saya dihubungi oleh Dave Jarvis melalui emel. Beliau memperkenalkan kepada saya blog beliau yang memuatkan penerangan teknikal untuk menaip Markdown dengan ConTeXt, bersama-sama dengan bahasa pengaturcaraan R.

Jadi di sinilah saya, merekodkan perjalanan ini sebagai menghargai usaha beliau dalam menyediakan sesuatu yang amat bermanfaat dan hebat ini.

Dan saya amat berterima kasih kerana dengan skrip ci beliau inilah penyusunan dokumen ConTeXt dapat dijalankan secara automatik tanpa perlu lagi mengetik butang F9 pada papan kekunci yang saya tautkan melalui vim sebelum ini setiap kali ada perubahan dibuat kepada fail ConTeXt.

Skrip Pembinaan

Typesetting Markdown -- Part 1: Build Script

Di bahagian pertama dokumentasi beliau, beliau menerangkan bahawa skrip bash adalah salah satu alat untuk menjalankan perisian ini.

Perlu diterapkan bahawa sesuatu yang teknikal akan mengambil masa untuk dihadam. Proses yang dilalui itu yang penting, sehingga akhirnya penuntut perolehi kefahaman hasil daripada perjalanan yang ditempuhi sepanjang proses tersebut.

Setelah mengambil inisiatif menelaah perihal skrip bash ini, saya masih belum dapat memahami banyak perkara. Cuma ambil sedikit masa untuk menggali berkenaan penggunaan warna log mesej yang terpapar di terminal.

Puas juga mencari merata-rata di ruangan Internet.

Sebab kadang-kadang nak tangkap imej skrin. Warna tulisan boleh mempengaruhi kesan kualiti kepada gambar. Nak belajar kemahiran menyunting imej; aih, lama juga masa perlu diambil rasanya. Jadi saya kurangkan penggunaan masa dengan fokus kepada kod warna ANSI.

Boleh rujuk pada nota sampingan saya, “Turutan kod untuk paparan teks berwarna di terminal” untuk ringkasan teks berwarna di terminal.

Ulasan Alat

Typesetting Markdown -- Part 2: Tool Review

Di bahagian kedua ini, beliau bincangkan lima alat / perisian yang perlu ada. Tiga daripada lima perisian yang wajib itu adalah ConTeXt untuk enjin typesetting, pandoc untuk alat pemprosesan dokumen pelbagai format dan inotify-tools sebagai alat monitor sistem fail.

Dua lagi perisian yang perlu adalah mengikut cita rasa pengguna; saya menggunakan Vim untuk alat penyunting teks dan zathura untuk pembaca fail PDF.

Penjelasan digarap begitu baik oleh beliau tentang cara untuk menghasilkan fragmen dokumen ConTeXt dengan kombinasi perisian pandoc.

Beliau menggunakan bash untuk shell yang berfungsi menjalankan perintah baris, manakala saya menggunakan zsh.

Maka berdasarkan penerangan teknikal beliau untuk penetapan, konfigurasi adalah sedikit berlainan bagi saya.

Baris-baris yang disediakan oleh beliau di bahagian Setup saya tambahkan di fail $HOME/.zshrc.

Dan pada isi ke-enam apabila menjalankan perintah sudo -E zsh, terdapat sedikit ralat yang keluar disebabkan oleh penggunaan framework oh-my-zsh seperti gambar di bawah.

Berdasarkan paparan ralat berkenaan, saya hanya tambahkan baris

zsh

ZSH_DISABLE_COMPFIX="true"

sebelum baris

source $ZSH/oh-my-zsh.sh

pada fail $HOME/.zshrc dan tiada lagi ralat berkenaan dipaparkan selepas itu.

Langkah-langkah seterusnya berjaya dilaksanakan tanpa sebarang ralat. Seperti yang beliau nasihatkan, pastikan ConTeXt dipasang dengan konfigurasi yang betul, maka fail PDF pasti boleh dijana.

Bukti hasil pelaksanaan.

Integrasi Berterusan

Typesetting Markdown -- Part 3: Automagicify

Saya putuskan untuk kekal dengan skrip Bash berbanding Zsh. Belum cukup rajin untuk mengkaji apa yang perlu saya sunting jika mahu menukar skrip asal kepada Zsh. Namun perbincangan di atas saya kekalkan sebagai nota tambahan.

Di bahagian ini, beliau menerangkan dengan lebih mendalam skrip binaan untuk menjalankan integrasi yang berterusan setiap kali menulis dokumen melalui ConTeXt.

Dengan bantuan skrip yang telah dibangunkan oleh beliau ini, terdapat enam fungsi yang menjalankan proses-proses berikut;

mencipta direktori sementara untuk menyimpan fail-fail Markdown;
di dalam direktori yang sama, sumber fail Markdown yang baru juga akan ditambah;
pandoc dijalankan untuk menjana dokumen ConTeXt (body.tex);
menjalankan ConTeXt untuk menukar pengeluaran pandoc ke fail PDF (body.pdf);
menukar nama fail PDF tersebut kepada output.pdf;
proses pembersihan dengan memadam direktori sementara tadi;

Seperti biasa, kita tunjuk bukti hasil pelaksanaan-lah!

Penggayaan Tema

Typesetting Markdown -- Part 4: Theme Style

Jujurnya, saya hanya mampu menelaah sehingga bab enam sahaja buat masa ini. Diskusi untuk bahagian empat, lima dan enam oleh Dave ini boleh tahan panjang-nya.

Dokumentasi yang saya rekodkan ini hanyalah ringkasan kepada apa yang saya pelajari sendiri sepanjang pengajian melalui blog beliau ini.

Di bahagian ini, beliau fokuskan perbincangan kepada reka bentuk dokumen melalui warna, jenis tulisan dan susur atur persembahan isi di dalamnya. Banyak sungguh perkara yang berlaku di sini.

Dan skrip ci di bahagian inilah yang saya sunting mengikut keperluan untuk digunakan sebagai alat dalam mengautomasi pembinaan dokumen ConTeXt secara berterusan.

Apa yang saya maksudkan di atas adalah tidak semua keadaan dapat digantikan dengan Markdown. Sebagai contoh, apabila melibatkan penghasilan pelbagai grafik melalui ConTeXt MetaPost, tidak dapat tidak saya hanya dapat bergantung kepada ConTeXt.

Dalam kes seperti ini di mana saya memutuskan untuk tidak menggunakan Markdown, saya lakukan perkara-perkara yang berikut:-

Saya muat turun fail ‘.zip’ yang disediakan oleh Dave;

bash

wget https://dave.autonoma.ca/blog/2019/06/23/typesetting-markdown-part-4/book.zip

Esktrak fail .zip berkenaan ke dalam direktori projek;
bash
```
unzip book.zip
```
Masuk ke dalam direktori projek berkenaan;
bash
```
cd book
```
Pindahkan fail build-template yang terkandung di dalam direktori projek yang telah diekstrak tadi ke dalam direktori ‘bin’ lokal (sebabnya adalah skrip ini akan diulangpakai tanpa sebarang suntingan diperlukan);
bash
```
mv build-template $HOME/bin
```
Padam fail ‘01.md’ dan juga direktori ‘artefacts’ kerana direktori ini akan dicipta oleh skrip ‘ci’ apabila perubahan terhadap mana-mana fail dikesan di dalam direktori;
bash
```
rm -r artefacts && rm 01.md
```

Sunting skrip bash ‘ci’ di bahagian ‘build_document()’;

Daripada:

build_document() {
  local -r DIR_BUILD="artefacts"
  mkdir -p "${DIR_BUILD}"

  local -r FILE_MAIN_PREFIX="main"
  local -r FILE_BODY_PREFIX="${DIR_BUILD}/body"

  local -r FILE_CAT="${FILE_BODY_PREFIX}.md"
  local -r FILE_TEX="${FILE_BODY_PREFIX}.tex"
  local -r FILE_PDF="${FILE_BODY_PREFIX}.pdf"
  local -r FILE_DST="$(basename "${ARG_FILE_OUTPUT}" .pdf).pdf"

  $log "Concatenate into ${FILE_CAT}"
  cat ./??.md > "${FILE_CAT}"

  $log "Generate ${FILE_TEX}"
  pandoc --to context "${FILE_CAT}" > "${FILE_TEX}"

  $log "Generate ${FILE_PDF}"
  context --nonstopmode --batchmode --purgeall \
    --path=artefacts,styles \
    "${FILE_MAIN_PREFIX}.tex" > /dev/null 2>&1

  $log "Rename ${FILE_MAIN_PREFIX}.pdf to ${FILE_DST}"
  mv "${FILE_MAIN_PREFIX}.pdf" "${FILE_DST}"
}

Kepada:

bash

build_document() {
  local -r DIR_BUILD="artefacts"
  mkdir -p "${DIR_BUILD}"

  local -r FILE_MAIN_PREFIX="main"
  local -r FILE_DST="$(basename "${ARG_FILE_OUTPUT}" .pdf).pdf"

  $log "Generate ${FILE_MAIN_PREFIX}"
  context --nonstopmode --batchmode --purgeall \
    --path=artefacts,styles \
    "${FILE_MAIN_PREFIX}.tex" > /dev/null 2>&1

  $log "Rename ${FILE_MAIN_PREFIX}.pdf to ${FILE_DST}"
  mv "${FILE_MAIN_PREFIX}.pdf" "${FILE_DST}"

  $log "Move other generated PDFs to ${DIR_BUILD} except output.pdf"
  for PDF in *.pdf; do
    mv "${PDF}" "${DIR_BUILD}";
  done
  mv "${DIR_BUILD}/${FILE_DST}" .

  $log "Remove outputs of other ConTeXt files"
  rm *.log *.tuc
}

Jalankan skrip ci;
bash
```
./ci -d
```
Atau jalankan arahan ./ci -V dengan menggunakan build-template paling terbaharu oleh Dave yang beliau muatkan dalam penulisan blog Bahagian 8.
Edit fail ‘main.tex’ dengan menukar baris ‘\input body’ kepada nama fail .tex yang mahu disusun. Saya beri contoh jika fail ConTeXt yang mahu disusun dinamakan sebagai ‘projek.tex’, maka tukarkan baris itu kepada ‘\input projek’. Editlah juga mana-mana ‘styles’ yang berkenaan.
Apa yang berlaku di sini adalah andai penggunaan MetaPost ada melibatkan \typesetfile kepada fail-fail .tex yang lain, maka penyusunan dokumen untuk fail-fail ini akan dibuat di dalam direktori ‘artefacts’ (dibuat secara automatik melalui skrip ci yang asal).
Penambahan $log ketiga dan keempat dalam skrip di atas adalah untuk memindahkan kesemua fail PDF yang dijana (jika terdapat penghasilan grafik MetaPost daripada fail-fail .tex yang lain) ke dalam direktori ‘artefacts’ (kecuali fail output.pdf) dan seterusnya membuang fail-fail tambahan yang dijana secara automatik tadi.
P.S. Boleh lihat sampel di repositori GitHub saya ini.

Saya langkau bahagian 5, Typesetting Markdown -- Part 5: Interpolation dan letakkan sedikit teaser untuk bahagian 6 di bawah.

A bit of teaser from my modification for Typesetting Markdown -- Part 6: Computation:

Saya cedok kod 'Random Variables and Probability Distributions' dari laman web Econometrics with R dan ubah suai fail .R berdasarkan telaah saya ke atas fail-fail yang disediakan oleh Dave.

Setelah itu, saya buat fail R Markdown dengan isi yang berikutnya. Fail inilah yang akan menjalani proses knitting.

Saya sunting fail bootstrap.R dengan memasukkan sumber kepada fail probability.R yang saya buat di atas tadi.

Imej yang berikutnya menunjukkan output yang diperolehi setelah menjalankan arahan ./ci -d -k.
Oops! Where is the graph? This was resulted from a lack of another package named Inkscape that will be responsible for converting outputs to SVG images.