Menyediakan tulisan blog saya sebagai halaman manual Linux

(jamesg.blog)

4 poin oleh GN⁺ 2024-03-01 | 1 komentar | Bagikan ke WhatsApp

Untuk pengguna yang ingin membaca tulisan web langsung di terminal, James' Coffee Blog juga menyediakan tulisan blog dalam format halaman manual Linux
Meski URL-nya sama, jika klien mengirim Accept: text/roff, situs menggunakan negosiasi konten HTTP agar klien menerima dokumen roff alih-alih HTML
File .man untuk setiap tulisan dibuat dari template yang memiliki bagian TITLE, AUTHOR, PUBLISHED, POST, dan URL
Di bagian isi, sumber Markdown dimasukkan agar lebih mudah dibaca daripada HTML, tetapi spasi/jaraknya tidak selalu rapi di halaman manual
NGINX mendeteksi permintaan text/roff dan menulis ulang URL ke file .man, sehingga setelah disimpan dengan curl, file itu bisa dibuka seperti man ./post.page

Membaca tulisan blog dengan `man`

Halaman manual di Linux adalah cara dasar untuk mengecek penggunaan perintah di terminal, dan biasanya dapat dibuka dengan man <command>
Misalnya, manual untuk perintah tac dapat dilihat seperti berikut

man tac

James' Coffee Blog menyusun alur agar tulisan blog web juga dapat dibaca dengan cara yang sama, yaitu mengunduh versi roff dari URL tulisan lalu membukanya dengan man
Contoh permintaan sebenarnya adalah sebagai berikut

curl -sL -H "Accept: text/roff" https://jamesg.blog/2024/02/28/programming-projects/ > post.page && man ./post.page

Memilih format dengan negosiasi konten HTTP

Inti implementasinya adalah negosiasi konten HTTP, yaitu klien memberi tahu server format respons yang diinginkan
Header Accept digunakan untuk menyampaikan tipe konten yang diinginkan
- Misalnya, Accept: image/png berarti meminta agar file PNG dikirim jika memungkinkan
- Beberapa tipe konten dan prioritasnya juga dapat ditentukan, tetapi di sini hanya digunakan permintaan format tertentu
Saat ingin menerima tulisan blog dalam format halaman manual, kirim header Accept: text/roff
Server melihat header ini dan mengembalikan respons text/roff yang dapat dibuka dengan man, bukan HTML

Cara membuat file `.man`

Halaman manual Linux ditulis dengan sintaks roff
Situs dimodifikasi agar menghasilkan versi halaman man untuk setiap tulisan blog
Struktur template yang digunakan adalah sebagai berikut

.TH jamesg.blog 1 "" "jamesg.blog"
.SH TITLE
...
.SH AUTHOR
James' Coffee Blog (https://jamesg.blog)
.SH PUBLISHED
...
.SH POST
...
.SH URL
...

Template memakai nama domain sebagai header dan membuat lima bagian
- TITLE
- AUTHOR
- PUBLISHED
- POST
- URL
Bagian isi menggunakan sumber Markdown
- Spasinya tidak selalu tersusun rapi di halaman manual
- Namun tetap lebih mudah dibaca daripada HTML, dan kehilangan informasi pemisahan judul serta paragraf lebih sedikit dibanding teks biasa

Mengambil dengan `curl` dan membuka dengan `man`

Versi roff dari tulisan blog dapat diminta dengan perintah berikut

curl -sL -H "Accept: text/roff" https://jamesg.blog/2024/02/28/programming-projects/ > post.page

Hasil yang disimpan dapat dibuka seperti halaman manual lokal

man ./post.page

Jika browser biasa meminta URL tulisan yang sama, ia akan menerima versi HTML
Sebaliknya, perintah curl di atas secara eksplisit meminta versi text/roff untuk URL yang sama

Menulis ulang ke file `.man` di NGINX

Server menangani permintaan text/roff secara terpisah dengan beberapa baris konfigurasi NGINX
Di /etc/nginx/nginx.conf, dideklarasikan variabel yang mengatur flag ketika tipe konten tertentu terdeteksi

map $uri $redirect_suffix {
~^/(.*)/$ $1;
default "";
}
map $http_accept $redirect_location {
default "";
"~^text/roff" 1;
}

Di bawah /etc/nginx/sites-enabled, yaitu file konfigurasi situs, ditambahkan aturan untuk menangani permintaan halaman roff

server {
...
location / {
if ($redirect_location = 1) {
rewrite ^/(.*)/$ /$1.man last;
}
...
}
}

Konfigurasi ini menghapus slash di akhir URL dan menambahkan .man saat ada header Accept: text/roff
Hasilnya, NGINX membaca file .man yang sesuai, bukan index.html untuk tiap tulisan
Dengan konfigurasi ini, tulisan blog yang sama bisa dibaca sebagai HTML di browser web dan sebagai halaman manual Linux di terminal

1 komentar

GN⁺ 2024-03-01

Pendapat Hacker News

Akan keren kalau menyediakan repositori deb sebagai cara berlangganan blog
Misalnya mengambil semua tulisan dengan apt update, lalu melihat tulisan terbaru dan tautan indeks semua tulisan dengan man your-blog
- Idenya sendiri bagus, tetapi kalau menyebar luas, peluang penyebaran malware yang melekat pada cara ini juga tampak cukup jelas
  Rasanya akan takut untuk berlangganan
- Ada presedennya. Debian dulu menyediakan akses ke Linux Gazette yang kini sudah tiada, dan sampai sekarang masih menyediakan berbagai paket informasional seperti dokumentasi paket, halaman manual, halaman info, RFC, Linux HOWTO, dan sebagainya
  Semua itu bisa dilihat secara lokal dengan paket dwww: “Read all on-line documentation with a WWW browser”
  https://packages.debian.org/bookworm/dwww
  Joerg Jaspert dulu adalah pengelola paket Linux Gazette: https://people.debian.org/~joerg/ (2002)
  Itu salah satu contoh terbaik yang pernah kulihat tentang pengintegrasian penyampaian informasi dan dokumentasi ke dalam sistem operasi, dan khususnya membuat dokumen man/info lebih berguna daripada antarmuka tradisional berbasis terminal
  Ada juga Debian Planet, blog terkait Debian, tetapi sepertinya tidak pernah disediakan sebagai paket Debian itu sendiri
  Sejujurnya, RSS kemungkinan besar adalah pilihan yang lebih baik untuk berlangganan blog
- Sedang kukerjakan
  Di https://github.com/capjamesg/jamesg.blog.deb ada isi yang bisa membuat berkas deb yang hanya berisi halaman man dengan perintah di bawah ini
  git clone [https://github.com/capjamesg/jamesg.blog.deb](<https://github.com/capjamesg/jamesg.blog.deb>;)
  cd jamesg.blog.deb
  dpkg-deb --build --root-owner-group jamesg.blog
  sudo dpkg -i jamesg.blog.deb
  Setelah itu akan terlihat keluaran seperti Processing triggers for man-db (2.9.1-1) ..., yang berarti halaman manual untuk man jamesg.blog sudah tersedia
  Saat ini baru ada placeholder, dan mungkin akan kuselesaikan besok
  Mungkin juga akan segera menjadi tulisan blog
Bisa langsung di-pipe ke man tanpa perlu fork atau memakai berkas perantara
curl -sL -H "Accept: text/roff" [https://jamesg.blog/2024/02/28/programming-projects/](<https://jamesg.blog/2024/02/28/programming-projects/>;) | man -l -
- Sebaiknya jangan begitu. Dua jam lalu yrro juga mengunggah sesuatu yang mirip, dan sekarang perdebatan soal mem-pipe {curl,wget} ke perintah dimulai lagi
  Teman tidak membiarkan temannya mem-pipe stream langsung ke perintah
  https://news.ycombinator.com/item?id=39554044
Sebagai referensi, curl -sL -H "Accept: text/roff" [https://jamesg.blog/2024/02/28/programming-projects/](<https://jamesg.blog/2024/02/28/programming-projects/>;) | man -l /dev/stdin berfungsi di lingkunganku
Tidak perlu menyimpan berkas roff secara lokal
- Sepertinya penulis asli sengaja tidak melakukannya seperti ini. Mem-pipe perintah atau konten dari internet langsung ke sesuatu seperti bash biasanya dianggap sebagai praktik buruk
  Secara pribadi menurutku tidak apa-apa. Orang yang paham implikasi keamanannya hampir pasti juga tahu metode konversi seperti ini, jadi tidak perlu diberi tahu
  Namun kurang baik untuk diajarkan kepada pemula. Suatu saat mereka bisa terkena masalah. Ketika kemampuan mereka meningkat, mereka akan mengetahui fitur seperti ini dengan sendirinya, dan semoga saat itu mereka juga sudah memahami implikasinya
  Ini bukan tulisanku: https://www.seancassidy.me/dont-pipe-to-your-shell.html
- Sayangnya perintah itu tidak berfungsi di macOS: /usr/bin/man: illegal option -- l
  Aku mencoba membuat perintah satu baris yang memakai pipe di Mac, tetapi terus mendapat galat
  Implementasi man di macOS tidak memiliki flag -l. Aku sudah memeriksa halaman manualnya
- Kalau memakai bash, kamu bisa mengurangi beberapa karakter dengan substitusi proses alih-alih pipe
  man -l <(curl -sL -H "Accept: text/roff" https://jamesg.blog/2024/02/28/programming-projects/)
Kalau bicara tentang URL yang melakukan hal menarik di terminal, dulu aku pernah melihat sesuatu di textfiles.com
Bentuknya menampilkan film animasi pendek dengan kode terminal VT100, dan semuanya disajikan dari satu URI
Di sistem modern, kamu bisa melihatnya dengan membatasi kecepatannya
curl --limit-rate 1000 [http://textfiles.com/sf/STARTREK/trek.vt](<http://textfiles.com/sf/STARTREK/trek.vt>;) && reset
reset disertakan karena terminal bisa jadi kacau
URI berbasis terminal lainnya: curl cheat.sh/tar mengambil contoh penggunaan program setelah /, dan curl wttr.in/berlin mengambil informasi cuaca dengan format terminal
- Kalau ingin membuat video ASCII sendiri langsung lewat telnet, ada yang kubuat dengan Go beberapa tahun lalu: https://github.com/bfontaine/RickASCIIRoll
  Sebenarnya cukup sederhana; bagian tersulitnya adalah membuat frame
  Ini bisa dilakukan dengan ffmpeg+img2txt.py: https://github.com/bfontaine/RickASCIIRoll/tree/master/movie...
- Beberapa tahun lalu aku membuat viewer seni ANSI dengan emulasi kecepatan modem
  Ada mirror lama dari https://16colo.rs/, jadi kamu bisa melihat sebagian besar seni ANSI yang pernah dirilis hingga sekarang
  Contoh: curl ansi.hrtk.in/ungenannt_1453.ans
- Benar-benar keren, tapi terminalku juga benar-benar dibuat kacau. Menyenangkan
- Ada juga Star Wars yang bisa ditonton lewat telnet
  https://itsfoss.com/star-wars-linux/
- Dengan tritty, kamu bisa meniru kecepatan transfer 1200/9600 BPS
Sekarang yang dibutuhkan hanyalah konverter dari Markdown ke roff, dan setelah dicari ternyata sudah ada
https://github.com/postmodern/kramdown-man
https://rtomayko.github.io/ronn/ronn.1.html
https://kristaps.bsd.lv/lowdown/
- Untuk pekerjaan seperti ini, pandoc bagus. Mendukung sebagian besar format markup yang kubutuhkan
  [0]: https://pandoc.org/
- md2groff sudah lama ada di komunitas garis suckless/2f30/cat-v
  https://codeberg.org/nereusx/md2roff
Ada paket Emacs yang memasang SICP karya Abelson dan Sussman ke direktori Info
Cukup ketik M-x package-install sicp RET
Melihat ini, aku terpikir bahwa dengan feed reader yang dimodifikasi, mungkin seluruh rak arsip blog juga bisa dipasang
Kalau membaca Info di Emacs, bookmark juga bisa dipakai
- chicken-scheme juga tinggal dipasang. Setelah itu jalankan sebagai root
  chicken-install srfi-203
  chicken-install srtfi216
  ~/.csirc untuk SICP adalah sebagai berikut
  (import scheme)
  (import (srfi 203))
  (import (srfi 216))
  (define (inc x) (+ x 1))
  (define (dec x) (- x 1))
  Setelah itu gunakan geiser user dan geiser untuk chicken seperti biasa
- Sebagai catatan, SICP adalah buku karya Abelson dan Sussman
Mungkin aku bisa menemukan jawabannya di internet, tapi aku ingin bertanya di HN
Saat SMA, di HP-UX, aku ingat seseorang menunjukkan cara melompat ke kata yang digarisbawahi, yaitu referensi bagian, dengan menekan kombinasi tombol tertentu, tapi sama sekali tidak ingat tombol apa itu
Aku sudah memeriksa man(1) dan man(7), tapi tidak menemukannya. Bisa saja ini ingatan palsu
- Kalau itu memang man, perlu diingat bahwa man ohman pada dasarnya adalah nroff -man /usr/share/man/man1/ohman.1 | $PAGER
  Jadi yang kamu ajak berinteraksi bukan man atau nroff, melainkan pager
  Sekarang less yang paling umum, dan more pun besar kemungkinan sebenarnya less, tetapi dulu ada yang lain juga, dan HPUX mungkin memakai sesuatu seperti pg
  pg berasal dari lini AT&T, more dari lini BSD, dan less dari lini GNU
  Ketiganya memulai pencarian regex dengan /, jadi bisa dicari terlepas dari ada garis bawah atau tidak
  less juga mendukung file tag sehingga bisa melompat ke tag berikutnya dengan t
- Aku tidak begitu tahu soal fitur viewer man terpisah, tetapi mungkin yang kamu ingat adalah dthelpview, viewer bantuan CDE. Bisa jadi itu menampilkan halaman man
- Ini terdengar seperti texinfo yang dibuka dengan perintah info
  Ironisnya, cukup banyak dokumentasi groff asli ditulis dalam texinfo: https://lists.gnu.org/archive/html/groff/2005-10/msg00107.ht...
Entah kenapa detail sepele ini memicu naluri saya untuk mencari-cari kesalahan. Mungkin karena ada seseorang di internet yang sedikit keliru
Bisa jadi karena sejak awal terlalu berpusat pada Linux tanpa perlu, atau karena saya mengharapkan sesuatu yang lain tetapi akhirnya hanya demo singkat content negotiation NGINX
Bagaimanapun, ada beberapa hal tidak penting yang tetap ingin saya katakan
Secara ketat, ini bukan mengembalikan roff. Hal seperti .TH bukan roff itu sendiri, melainkan bagian dari paket makro untuk menulis halaman man
Saya kecewa karena tidak ada konversi Markdown-ke-roff. Saya kira itu akan menjadi bagian menarik dari tulisan ini, dan setidaknya satu alat yang sudah ada bisa dipakai
Demikian pula, karena ini, pemformatan teksnya sebenarnya juga tidak benar. Masukan roff dimaksudkan satu kalimat per baris untuk membedakan . di akhir kalimat dari . untuk kegunaan lain
Selain itu, setiap baris yang diawali . akan ditafsirkan sebagai perintah dan bisa menimbulkan masalah
Atau mungkin saya hanya orang tua yang pemarah
- Terima kasih sudah membagikan ini. Saya tidak tahu persis bagaimana struktur hubungan roff dan man, dan saya mencoba menyesuaikannya sambil beberapa kali memperbaiki tulisan ini
  Adanya alat lain seperti groff dan nroff membuatnya makin membingungkan
  Tulisan yang hanya menjelaskan “apa itu roff/halaman man/nroff/varian lain dan bagaimana menggunakannya” saja sudah cukup layak menjadi satu artikel blog
  Kalau ada penjelasan yang singkat dan jelas, saya juga akan senang, dan sepertinya itu juga akan membantu orang lain
  Markdown-to-roff saya anggap sebagai v2. Saat saya mulai mempertimbangkan untuk mengimplementasikan parser, seseorang memberi tahu saya tentang https://github.com/sunaku/md2man, dan ini tampaknya menyelesaikan masalah tersebut
  Saya perlu mencari tahu bagaimana mengintegrasikan ini ke situs Python saya yang berjalan di atas GitHub Pages, jadi perlu sedikit penyesuaian
- Saya juga cukup terkejut karena tidak ada konversi Markdown-ke-roff
  Pandoc bisa mengonversi Markdown ke roff halaman man dengan sangat mudah
  Kalau dimasukkan ke template yang diberikan, hasilnya akan terlihat lebih seperti halaman man sungguhan
Tipe media yang benar menurut RFC 4263 adalah text/troff: https://www.rfc-editor.org/rfc/rfc4263.html
Ide yang keren. Sekarang tinggal pasang timer sampai muncul “menyajikan tulisan blog saya sebagai DOOM WAD yang bisa dimainkan”
- Tambahkan saja ke daftar segelintir hal keren yang benar-benar bisa dibantu oleh AI

Menyediakan tulisan blog saya sebagai halaman manual Linux

Membaca tulisan blog dengan man

Memilih format dengan negosiasi konten HTTP

Cara membuat file .man

Mengambil dengan curl dan membuka dengan man

Menulis ulang ke file .man di NGINX

Bacaan terkait

1 komentar

Pendapat Hacker News

Membaca tulisan blog dengan `man`

Cara membuat file `.man`

Mengambil dengan `curl` dan membuka dengan `man`

Menulis ulang ke file `.man` di NGINX