Nota, bahasa dokumen browser untuk makalah akademik dan posting blog

 (nota-lang.org)
2 poin oleh GN⁺ 2023-10-21 | 1 komentar | Bagikan ke WhatsApp
  • Melampaui keterbatasan PDF dan halaman web statis, Nota bertujuan menjadi bahasa dokumen yang membuat browser memahami struktur dokumen dan memungkinkan pembaca memanfaatkannya secara langsung
  • Dokumen Nota dikompilasi menjadi program JavaScript yang berjalan di browser, sehingga variabel, fungsi, dan struktur data dapat digunakan dalam penulisan dokumen
  • Dirancang dengan mempertimbangkan integrasi pustaka JavaScript seperti KaTeX, Vega-Lite, dan Penrose, serta dukungan kebutuhan aksesibilitas
  • Dengan paket @nota-lang/nota, pengguna dapat memasang executable nota dan mengelola dokumen melalui alur build atau penyuntingan interaktif
  • Karena masih merupakan teknologi baru yang terus berubah, arsitektur dan API dapat berubah, dan pengguna perlu memperhitungkan bug, kekurangan, serta ketidakakuratan pada alat dan dokumentasinya

Struktur dokumen yang dipahami browser

  • Nota adalah bahasa untuk menulis dokumen seperti makalah akademik dan posting blog
  • Tujuannya adalah membawa dokumen menjadi media abad ke-21
  • Di dalam dokumen terdapat banyak struktur yang perlu diikuti pembaca, seperti definisi istilah dan referensi
    • Sebagai contoh, kata Nota merujuk pada istilah yang didefinisikan di paragraf sebelumnya
    • Nota memungkinkan penulis mengekspresikan struktur semacam ini, lalu browser memahaminya agar dapat dimanfaatkan pembaca
    • Pada halaman contoh, pengguna dapat mengeklik atau mengeklik ganda referensi Nota untuk melihat cara kerjanya
  • Dokumen Nota dikompilasi menjadi program JavaScript
    • Dokumen dapat dilihat di perangkat apa pun yang memiliki browser web
    • Variabel, fungsi, dan struktur data dapat digunakan untuk menyederhanakan penulisan dokumen
    • Dapat diintegrasikan dengan pustaka JavaScript seperti KaTeX, Vega-Lite, dan Penrose
    • Lebih mudah mendukung kebutuhan aksesibilitas seperti screen reader

Alur instalasi dan penyuntingan

  • Nota dapat digunakan dengan memasang executable nota melalui paket @nota-lang/nota
  • Satu dokumen Nota dapat dibangun dengan alur berikut
    • npm install --global @nota-lang/nota
    • echo "@Title: Hello world" > index.nota
    • nota build index.nota
    • open dist/index.html
  • File Nota dapat disunting secara interaktif dengan perintah nota edit index.nota
  • Cara menulis dokumen dapat dilihat di Reference
  • Untuk menambahkan Nota ke situs web atau melihat arsitekturnya, lihat Integration guide

Kesenjangan antara PDF dan web statis

  • Media utama dokumen digital terbagi menjadi PDF dan halaman web
    • PDF dirancang untuk merepresentasikan dokumen fisik, sehingga memiliki batasan kertas seperti pemisahan halaman, lebar tetap, dan gaya yang tidak berubah
    • Halaman web memungkinkan pemformatan dinamis, seperti penyesuaian ukuran untuk ponsel, penerjemahan ke bahasa lain, atau perubahan warna untuk pengguna dengan buta warna
    • Halaman web juga memungkinkan interaksi dinamis, seperti teks yang meminta konteks tambahan, diagram dengan perspektif yang berubah, dan anotasi untuk kemudian hari
  • Fitur dinamis seperti ini saat ini terutama hanya dapat diakses oleh pengembang web profesional
    • Alat dokumen yang ada seperti LaTeX, Pandoc, Markdown, dan Scribble sebagian besar hanya dapat menghasilkan halaman web statis
    • Nota berupaya menjembatani kesenjangan itu sebagai bahasa dokumen dengan hambatan masuk rendah, batas ekstensi tinggi, dan kurva belajar yang mulus

Status saat ini dan referensi

  • Nota masih merupakan teknologi baru yang terus berevolusi
    • Arsitektur dan API terus berubah
    • Alatnya mungkin memiliki bug dan fitur yang belum ada
    • Dokumentasinya mungkin belum lengkap atau tidak akurat
    • Saat ini, Nota mencari pengguna awal yang ingin ikut menjadikannya bahasa dokumen masa depan
  • Komponen @Definition dan @Ref memungkinkan penulis menambahkan sedikit anotasi dokumen, sehingga runtime Nota dapat menampilkan definisi dari referensi sebagai tooltip di dalam konteks
    • Versi Nota di masa mendatang dapat mencakup fitur seperti menemukan semua referensi untuk definisi tertentu
  • Filosofi desainnya dapat dilihat lebih lanjut di A New Medium for Communicating Research on Programming Languages

Bacaan terkait

1 komentar

 
GN⁺ 2023-10-21
Pendapat di Hacker News

  • Saya pembuat Nota, dan sejak prototipe awal halaman webnya, saya sedang menyempurnakan ulang desainnya
    Saya sedang membangun landasan yang lebih kuat untuk persoalan seperti bagaimana mencampur konten dan komputasi(https://arxiv.org/abs/2310.04368), serta bagaimana sintaks membuat pekerjaan dokumen menjadi mudah/sulit/tidak mungkin(https://github.com/cognitive-engineering-lab/doclang-benchma...)
    Saya masih percaya pada filosofi besarnya, tetapi Nota tampaknya akan cukup berubah dalam sekitar 6 bulan. Sementara itu, menurut saya perkembangan paling keren di bidang bahasa dokumen adalah Typst, jadi saya sarankan untuk mengeceknya: https://typst.app/
    Versi Nota berikutnya rencananya akan ditulis 99% dalam Rust :-)

    • Daripada pilihan bahasa, membuat API mudah digunakan oleh basis pengguna yang luas tampaknya lebih penting
      Jika performa benar-benar menjadi masalah, Rust lebih masuk akal daripada JavaScript, tetapi saya tidak yakin itu akan menjadi penentu untuk sebagian besar use case
      Saya tidak pernah menyukai LaTeX meski sudah banyak menulis dokumen besar dengannya; rasanya seperti monster untuk akademia, bukan untuk bisnis. Bahkan di Word, hal-hal yang ingin dilakukan secara konsisten tidak selalu mudah, style cepat berantakan, dan penomoran serta bullet juga mudah disusupi kesalahan
      Ketika beberapa putaran revisi bolak-balik, pelacakan perubahan menjadi masalah besar, dan pada akhirnya kita bergantung pada kepercayaan bahwa pihak lain tidak menimpa pelacakan itu. Produk yang sejak awal hingga persetujuan akhir menjamin semua perubahan terlihat dengan benar saja sudah bisa menjadi killer app yang disukai perusahaan dan pengacara
      Kalau ditaburi blockchain, mungkin akan lebih mudah menggalang investasi, tetapi sebenarnya ini tampak lebih dekat ke masalah kriptografi dasar daripada blockchain, dan kompleksitas sebesar itu tampaknya tidak diperlukan
    • Sebagai orang akademia, 99% waktu saya dipakai untuk dua hal: menulis komputasi statistik dalam bahasa seperti R atau Python, dan menulis teks bahasa Inggris
      Hal terpenting dalam bahasa dokumen adalah memprioritaskan keduanya. Misalnya, dokumen TeX dimulai dengan kode persiapan seperti \documentclass, berbagai \usepackage, definisi theorem, dan pengaturan font, sedangkan dokumen R Markdown/Quarto langsung dimulai dengan makna tulisan yang sebenarnya seperti judul, penulis, dan abstrak
      Perbedaan penekanannya terlihat jelas
    • Akan menarik jika Nota bisa menyelesaikan masalah yang secara teori mungkin dilakukan TeX/LaTeX, tetapi dalam praktiknya tidak ditangani dengan baik. Yaitu kemudahan styling untuk memenuhi persyaratan eksternal yang konyol
      Ini mencakup layout yang padat dan sarat informasi seperti poster konferensi A0, style dokumen standar nasional seperti GOST di wilayah pasca-Soviet, tuntutan style bibliografi yang meledak sesuai tiap tradisi internasional, membuatnya tampak seperti style default versi MS Word tertentu, menempatkan gambar atau teks secara presisi di atas gambar untuk koreksi cepat pada paper, dan menyesuaikan hal-hal semacam itu secara sadar
      Di dunia TeX, semuanya secara teknis mungkin, tetapi dalam praktiknya membutuhkan sihir hitam yang begitu dalam sampai pengguna biasa bergelar akademik pun tidak ingin menggalinya
    • Nota tampak bagus. Saya membuat sesuatu yang mirip bernama Literate Markdown, diambil dari “literate programming” Knuth, dan sejak awal berfokus pada pencampuran komputasi dan penjelasan
      Selama beberapa bulan terakhir, saya senang menggunakannya untuk mengeksplorasi ide animasi SVG(https://simpatico.io/svg) atau mematangkan struktur data/algoritme baru(https://simpatico.io/stree3)
      Seluruh server dan pemroses Markdown-nya sekitar 500 baris kode Node yang mudah dibaca, dependensinya sangat sedikit, tidak ada dependensi transitif, dan tidak perlu tahap kompilasi. Secara default, server tidak mengizinkan sumber daya pihak ketiga atau cookie jenis apa pun
      Ada di GitHub dengan lisensi MIT, dan sedang saya rapikan sambil memindahkannya dari repositori pribadi ke repositori organisasi. Referensi: https://simpatico.io/lit
    • Menariknya, masalah seperti ini dan lebih banyak lagi sudah diselesaikan dengan cukup masuk akal di Org Mode. Hanya saja terlalu sedikit orang yang memakai Emacs, jadi terlalu sedikit pula yang mengetahuinya

  • Di tempat yang tidak membutuhkan “kedimanisan yang esensial”, justru ketiadaannya adalah fitur, bukan bug

    • Sepenuhnya setuju. Kedimanisan memang bagus untuk aplikasi web, tetapi justru hal yang paling tidak diinginkan dalam dokumen
    • Untuk membaca PDF dengan nyaman di layar kecil, terutama mobile, tampaknya tetap perlu tata letak dinamis dasar
      Di mobile, saya jauh lebih suka membaca halaman web daripada PDF, karena halaman web yang masuk akal biasanya bisa menyesuaikan diri dengan layar mobile
    • PDF membatasi informasi dengan membatasi cara ia direproduksi secara digital. Di PDF tidak ada copy/paste yang “sekadar” berfungsi; penuh galat aneh, sehingga teks harus banyak diformat ulang atau melewati perangkat lunak khusus
      Kita perlu format yang mengodekan informasi visual dan informasi digital sekaligus. Lapisan digital pada dasarnya tidak harus terlihat, tetapi harus bisa diakses saat diperlukan
    • Spesifikasi PDF dari Adobe secara mengejutkan mendukung eksekusi JavaScript(https://helpx.adobe.com/acrobat/using/applying-actions-scrip...), grafik 3D interaktif(https://www.youtube.com/watch?v=PKfyFt3zT5A, https://www.youtube.com/watch?v=vW5-1LVtd9U), audio dan video(https://helpx.adobe.com/acrobat/using/rich-media.html), bahkan “Liquid Mode” untuk dokumen PDF responsif(https://www.adobe.com/acrobat/hub/what-is-adobe-liquid-mode....)
      Tentu saja “fitur-fitur” semacam ini dianggap bug dan dihapus dari spesifikasi ISO PDF/A untuk preservasi jangka panjang: https://en.wikipedia.org/wiki/PDF/A
      Intinya, terkadang dokumen harus tetap sekadar dokumen. Dalam makalah ilmiah, LaTeX adalah sesuatu yang ditulis manusia untuk manusia, dan berkat perintah serta paket kustom, kita bisa menulis dokumen teks polos yang semudah dibaca seperti makalah yang dihasilkan. Dari sisi aksesibilitas pun bagus
    • Kalau melihat contoh makalah PLDI, simbol-simbol dalam rumus besar dan padat diberi penjelasan popup. Hal seperti ini benar-benar bisa membantu
      Ada wilayah menarik yang belum banyak dieksplorasi dalam dokumen dinamis, tetapi dibutuhkan contoh-contoh bagus tentang cara menggunakannya secara elegan

  • Ringkasnya, ini lebih dekat ke LaTeX dan juga memiliki sebagian elemen Markdown; ditulis dengan JavaScript sehingga banyak orang bisa berkontribusi memakai bahasa yang sudah mereka kenal, dan bagus juga karena berlisensi MIT
    Saya belum tahu apakah akan langsung punya kebutuhan untuk memakainya, tetapi kelihatannya cukup keren. Jika saya menulis sesuatu yang membutuhkan fitur ala LaTeX tetapi tempat pengajuannya tidak mewajibkan LaTeX, sepertinya saya akan mencoba Nota
    Saya menganggap Knuth hampir seperti sosok setengah dewa, tetapi bukan berarti ia turun dari langit, memberikan TeX, lalu berkata “jangan pernah mencoba hal baru selamanya”

    • TeX jelas merupakan terobosan, tetapi saya melihatnya sebagai produk zamannya. Terlalu banyak kecerdikan dicurahkan ke ekspansi makro dan teknik weaving demi memenuhi batas memori yang menurut standar sekarang terasa konyol
      Terlalu banyak juga perlindungan dari kesalahan dan fitur kenyamanan yang diberikan bahasa modern tetapi tidak ada di sana. Saat memakai LaTeX, saya sangat bergantung pada potongan \input{} untuk mengisolasi blok, demi menghindari kerusakan hanya karena satu escape terlewat
      Saya terus berharap ada penafsiran ulang yang modern, tetapi rasanya kita terjebak di optimum lokal yang sulit ditinggalkan karena puluhan tahun inersia dan paket yang menumpuk di TeX
    • https://typst.app/ juga layak dilihat

  • Hal-hal serupa mencakup https://pandoc.org/, https://quarto.org/, https://markdoc.dev/, https://mdxjs.com/, https://typst.app/

    • Daftar format yang didukung Pandoc mengesankan

  • Masalahnya, setiap percobaan baru di bidang ini masuk ke ruang yang sudah terlalu sesak. Tidak terlalu penting apakah solusi yang ada sudah sempurna atau belum
    Ini mirip masuk ke kota bersejarah di Eropa dengan seribu tahun sejarah arsitektur lalu mengusulkan rancangan bangunan baru yang hebat. Lahan kosong jarang ada, dan orang tidak akan begitu saja merobohkan struktur lama hanya untuk menguji yang baru. Mereka harus merasakan keunggulan yang luar biasa
    Dalam arsitektur, baja dan beton bertulang membuka dimensi vertikal dan sangat meningkatkan pemanfaatan ruang, lalu sejarah berubah setelahnya
    Pertanyaan utamanya adalah apakah ada dimensi yang belum dieksplorasi yang cukup kuat untuk menarik orang ke format dokumen lain lagi demi “memperbaiki” ASCII, reStructuredText, wikitext, Markdown, TeX/LaTeX, AsciiDoc, HTML, dan sebagainya
    Jawaban yang umum adalah infrastruktur hiperteks semantik. Visi aslinya belum terwujud. Jika kita menganggap ekosistem tertutup masa kini sebagai mimpi buruk yang akan berlalu, web yang kembali terdesentralisasi membutuhkan infrastruktur penulisan dokumen yang modern, ramah pengguna, dan memberdayakan
    Namun mungkin juga ada dimensi lain yang dapat mengangkat penulisan dan berbagi dokumen ke tingkat baru. Keindahan inovasi adalah bahwa ia tidak terikat oleh aturan dan kebijaksanaan yang sudah ada

    • Jika menginginkan web terdesentralisasi, semacam “Userweb” yang sedikit berpadanan dengan Usenet, saya rasa kita membutuhkan protokol seperti BitTorrent
      Kita membutuhkan format dokumen yang efisien, dan untuk itu format tersebut tidak boleh berusaha melakukan semuanya. Artinya, tabel harus memisahkan jenis dokumen per file, seperti format spreadsheet standar; berbeda dari HTML yang mencoba menangani sendiri tabel, grafik (SVG), dan sebagainya
      Dengan memisahkan masing-masing ke file tersendiri, pengguna bisa memilih program yang mereka inginkan untuk melihat atau memanipulasi dokumen, alih-alih melihat semuanya lewat satu browser; ini juga membantu distribusi jaringan dan menguntungkan di lingkungan dengan ruang penyimpanan atau bandwidth rendah
      Jadi dari sudut pandang saya, tidak ada yang perlu diciptakan baru. Cukup spesialisasikan dan poles apa yang sudah ditemukan

  • Jika mengikuti tautannya, https://willcrichton.net/nota/ menunjukkan keunggulan yang meyakinkan di ceruk penggunaan yang memang dituju Nota, yaitu membuat makalah akademik ilmu komputer tentang bahasa pemrograman lebih mudah dipahami
    Apakah bisa dirender menjadi PDF berkualitas tinggi tentu saja merupakan kebutuhan sekaligus pertanyaan. Demi kompatibilitas dengan sistem yang sudah ada, mungkin justru lebih baik jika bisa dirender ke LaTeX

  • Pada dasarnya Nota adalah markup + kode (JavaScript), dan kombinasi ini adalah area yang dibidik MDX. Dulu ketika seseorang menyebutkan hal ini, pembuatnya mengatakan bahwa Nota ditujukan untuk dokumentasi, sedangkan MDX untuk situs web: https://news.ycombinator.com/item?id=31349579
    Kalau begitu, menurut saya agar Nota bisa populer, seseorang perlu membungkusnya sebagai produk. Hasilnya terlihat bagus, tetapi harus berurusan dengan Node.js hanya untuk membuat dokumen itu terlalu merepotkan, dan rasanya kembali seperti LaTeX. Kebanyakan orang akan lebih memilih Notion atau pengolah kata

    • LaTeX, atau lebih umum keluarga TeX, tidak pernah hilang. Sampai sekarang pun itu adalah alat standar untuk menulis artikel jurnal di sebagian besar bidang STEM
      Selain itu, Nota bukan pesaing langsung keluarga TeX. Nota membuat sesuatu untuk dibaca browser web, sementara xxxTeX membuat sesuatu untuk dibaca pembaca PDF. Saya tahu xxxTeX juga bisa menghasilkan format keluaran lain, tetapi kebanyakan orang memakainya untuk membuat PDF
    • Fakta bahwa Nota menyertakan gaya bawaan, semacam gaya penulisan, saja sudah menempatkannya di kelas yang sama sekali berbeda dari MDX
      MDX siap dipakai dengan framework apa pun seperti React/Vue, tetapi itu pada dasarnya berarti ia tidak memberikan opini bawaan apa pun
      Nota terasa seperti bisa ditancapkan ke static site generator. Tentu saja untuk itu keduanya harus dibuat bekerja sama, tetapi menurut saya itu ekspektasi yang bisa dicapai oleh seseorang yang sedikit lebih berdedikasi daripada saya

  • Saya tidak mengerti mengapa diperlukan bahasa yang dikompilasi ke JavaScript untuk membuat halaman teks. Tujuan yang sama sudah ditangani oleh AsciiDoc
    Penerbit sungguhan seperti O’Reilly pun memakai AsciiDoc sebagai format input untuk membuat buku dan situs web

    • Saya setuju soal AsciiDoc. Jika Markdown lebih cocok untuk konten yang relatif pendek, dan LaTeX lebih dekat ke makalah akademik serius dengan sitasi, rumus, dan sebagainya, maka AsciiDoc berhasil menempati titik tengah yang pas di antaranya
      Saya sudah memakai AsciiDoc selama beberapa tahun terakhir dan menyukainya. Saya hanya kembali ke Markdown di tempat yang belum mendukung AsciiDoc. Misalnya GitHub dan GitLab mendukung rendering AsciiDoc
      Sayangnya PyPI belum mendukungnya, tetapi menyenangkan melihat makin banyak orang meninjaunya: https://github.com/pypa/readme_renderer/issues/205
    • Berkat Asciidoctor, asciidoc adalah yang terbaik. Saya setuju bahwa sebagai format ia berada di titik yang tepat
      Namun ada hal yang membuat frustrasi pada tooling saat ini. Saya bisa melihat dan menghargai upaya besar yang masuk ke Asciidoctor, tetapi tidak ada keluaran HTML5 semantik, integrasi dengan generator gambar sulit atau setidaknya lebih sulit daripada semestinya, dan cukup berat sampai-sampai menjadi satu-satunya dependensi Ruby di seluruh mesin saya
      Selain masalah Ruby, isu-isu ini sudah terbuka di GitHub, jadi sepertinya akan terselesaikan jika ada lebih banyak waktu dan sumber daya

  • Entahlah. Emacs org-mode tampaknya lebih baik dan lebih rendah ketergantungannya pada JavaScript
    https://docusaurus.io/ juga sangat bagus dan fleksibel. Jika ingin mengembangkan Nota dengan cara serupa, saya menyarankan untuk melihat keduanya

  • Saya sedang memikirkan cara termudah membuat blog yang sebagian besar berisi konten statis, tetapi bila mau bisa memasukkan grafik interaktif atau kustomisasi sesuka hati. Saya penasaran apakah Nota pilihan yang bagus
    Sebagai opsi lain, saya juga melihat Quarto(https://quarto.org/), dan mungkin juga bisa memakai blog static site sederhana seperti Jekyll lalu mengedit langsung HTML keluarannya saat diperlukan

    • Saya memakai XHTML dengan sedikit XML kustom, lalu menghasilkan XHTML final dengan XSLT: https://git.uberspace.net/homepage/
      Dengan cara ini saya bisa memakai seluruh HTML, proses pembuatannya bisa dikustomisasi, dependensinya relatif mudah dikelola, dan format-format terkait sudah distandardisasi
    • Saya sangat merekomendasikan Astro: https://astro.build/
      Dengan Astro, jika Anda menulis komponen bergaya React, ia akan mengompilasinya menjadi HTML/CSS murni kecuali pada kasus yang benar-benar membutuhkan JavaScript. Situs pribadi dan blog saya juga dibuat dengan Astro: https://sjer.red/, sumbernya ada di https://github.com/shepherdjerred/shepherdjerred.com
      Ada juga tutorial membuat blog dengan Astro: https://docs.astro.build/en/tutorial/0-introduction/
    • Ada juga jalan memakai shortcode di Hugo. Sepertinya Jekyll juga punya yang serupa, dan file HTML keluaran dari pustaka visualisasi data seperti Vega-Altair (Python) atau plotly bisa dipakai sebagai input shortcode