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

   Separator bagi kombinasi kod-kod parameter SGR adalah simbol semicolon, ;.

   Saya hanya rekodkan yang mana relevan kepada saya dari laman web di atas:

   Kod	Atribut paparan	Penerangan
   0	Tetapkan semula / Normal	Semua atribut ditutup.
   1	Bold	Tulisan tebal.
   2	Ringan	Tulisan nipis.
   3	Miring	Hanya untuk tulisan tertentu e.g: Hack. Terminus tidak menyokong atribut ini.
   4	Bergaris bawah	Tulisan dengan satu garisan bawah.
   5	Berkelip perlahan	Tulisan berkelip. Mengganggu konsentrasi. Tidak disokong sekiranya ditetapkan latar belakang.
   6	Berkelip laju	Tulisan berkelip. Mengganggu konsentrasi. Tidak disokong sekiranya ditetapkan latar belakang.
   7	Kontra (inverted)	Atribut terbalik antara warna latar belakang dan hadapan.
   30	Warna hitam	Tetapan latar hadapan (8 colors).
   31	Warna merah	Tetapan latar hadapan (8 colors).
   32	Warna hijau	Tetapan latar hadapan (8 colors).
   33	Warna kuning	Tetapan latar hadapan (8 colors).
   34	Warna biru	Tetapan latar hadapan (8 colors).
   35	Warna magenta	Tetapan latar hadapan (8 colors).
   36	Warna cyan	Tetapan latar hadapan (8 colors).
   37	Warna putih	Tetapan latar hadapan (8 colors).
   38	Tetapan latar hadapan	Diikuti kod ;5;N, dengan 'N' merujuk kepada nombor kod 256 warna (256 colours)
   40	Warna hitam	Tetapan latar belakang (8 colors).
   41	Warna merah	Tetapan latar belakang (8 colors).
   42	Warna hijau	Tetapan latar belakang (8 colors).
   43	Warna kuning	Tetapan latar belakang (8 colors).
   44	Warna biru	Tetapan latar belakang (8 colors).
   45	Warna magenta	Tetapan latar belakang (8 colors).
   46	Warna cyan	Tetapan latar belakang (8 colors).
   47	Warna putih	Tetapan latar belakang (8 colors).
   48	Tetapan latar belakang	Diikuti kod ;5;N, dengan 'N' merujuk kepada nombor kod 256 warna (256 colours)
   90	Warna hitam terang	Tetapan latar hadapan (8 colors).
   91	Warna merah terang	Tetapan latar hadapan (8 colors).
   92	Warna hijau terang	Tetapan latar hadapan (8 colors).
   93	Warna kuning terang	Tetapan latar hadapan (8 colors).
   94	Warna biru terang	Tetapan latar hadapan (8 colors).
   95	Warna magenta terang	Tetapan latar hadapan (8 colors).
   96	Warna cyan terang	Tetapan latar hadapan (8 colors).
   97	Warna putih terang	Tetapan latar hadapan (8 colors).
   100	Warna hitam terang	Tetapan latar belakang (8 colors).
   101	Warna merah terang	Tetapan latar belakang (8 colors).
   102	Warna hijau terang	Tetapan latar belakang (8 colors).
   103	Warna kuning terang	Tetapan latar belakang (8 colors).
   104	Warna biru terang	Tetapan latar belakang (8 colors).
   105	Warna magenta terang	Tetapan latar belakang (8 colors).
   106	Warna cyan terang	Tetapan latar belakang (8 colors).
   107	Warna putih terang	Tetapan latar belakang (8 colors).

3. m - untuk colour escape sequences

   8 warna (Pautan ke fail konfigurasi zsh saya)

   
   Contoh kod tanpa latar belakang:

   zsh

   \033[1;33m

   Contoh kod dengan latar belakang:

   zsh

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

   ---

   256 warna: paparan skrin dengan resolusi 1920 lebar

   (Pautan ke fail konfigurasi zsh saya)

   Kod warna 16 dan 232 sehingga 234 tidak kelihatan kerana warnanya gelap seakan-akan warna latar belakang. Memang sengaja saya tidak tetapkan warna latar belakang yang terang khusus untuk pameran warna tersebut kerana tidak mahu terkeliru dengan warna sebenar.
   Nombor kod adalah dari 0 sehingga 255.

   Contoh kod tanpa latar belakang:

   zsh

   \033[3;38;5;15m

   Contoh kod dengan latar belakang:

   zsh

   \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 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_DISABLE_COMPFIX="true"

sebelum baris

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.

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:-

1. 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

2. Esktrak fail .zip berkenaan ke dalam direktori projek;

   bash

   unzip book.zip

3. Masuk ke dalam direktori projek berkenaan;

   bash

   cd book

4. 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

5. 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

6. 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
   }

7. 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.
   

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 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.