Mengautomasi Penyusunan Dokumen ConTeXt: Bahagian 2

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.

Bahagian 1

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.

Turutan kod untuk paparan teks berwarna di terminal:-

1. \033[ - untuk non-printing escape sequences ;
   

2. SGR Parameters ;

3. m - untuk colour escape sequences

8 warna (Pautan ke fail konfigurasi zsh saya)

\033[1;33m

\033[0;47m\033[3;30m

256 warna: paparan skrin dengan resolusi 1920 lebar
(Pautan ke fail konfigurasi zsh saya)

\033[3;38;5;15m

\033[0;48;5;27m\033[1;38;5;15m

Bahagian 2

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 baris perintah, 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 poin ke-enam apabila jalankan perintah sudo -E zsh, terdapat sedikit ralat yang keluar disebabkan oleh penggunaan framework oh-my-zsh seperti gambar di bawah.

ZSH_DISABLE_COMPFIX="true"

source $ZSH/oh-my-zsh.sh

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.

Bahagian 3

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;

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

Bahagian 4

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.

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

unzip book.zip

cd book

mv build-template $HOME/bin

rm -r artefacts && rm 01.md

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}"
}

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
}

./ci -d

Saya langkau Bahagian 5 dan letakkan sedikit teaser untuk Bahagian 6 di bawah.

A bit of teaser from my modification for Part 6:

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.

Imej graf sebagai output berjaya diperolehi setelah memasang pakej Inkscape.