Markdown'a kıyasla rST tercih etme eğilimi

Neden rST'yi tercih ediyorum

Bu iddiadan vazgeçmeyeceğim

• "Logic for Programmers"ın yeni sürümü v0.2'yi yayımladım. Bu sürüm epub desteği, kısıt çözümü ve biçim belirtimleriyle ilgili içerikler barındırıyor.
• İkinci kitabım "Learn TLA+"yı da Sphinx ile yazdım. Sphinx, reStructured Text (rST) adlı kendine özgü bir işaretleme dili kullanıyor.
• rST'nin öğrenme eğrisi Markdown'dan daha dik. Markdown ile birkaç kitap yazdıktan sonra daha iyi bir şeye ihtiyaç duyduğumu hissedip rST'ye geçtim.

rST neden daha iyi

• Markdown, HTML'nin hafif bir gösterimiyken rST, soyut belge ağacının orta ağırlıkta bir gösterimidir.
• Markdown'da görsel oluşturma yöntemi:

  ![alttext](example.jpg)
  

• rST'de görsel oluşturma yöntemi:

  .. image:: example.jpg
     :alt: alttext
  

• rST genişletilebilir. Yeni metin nesneleri ekleyebilirsiniz.
• Sphinx, çapraz başvuruları işleyebilir. Örneğin bir belgede foo bağlantı noktasını koyup başka bir belgede :ref:image <foo>`` eklerseniz, Sphinx doğru URL'yi yerleştirir.
• rST, dönüştürme kodunu derleme sürecinin geri kalanıyla birlikte yapılandırmanıza olanak tanır.

Bir kullanım örneği

• "Logic for Programmers" matematikle ilgili bir kitap ve okurlar için alıştırmalara ihtiyaç duyuyor.
• Alıştırmaları ve çözümleri belgede yan yana yerleştirmek istiyorum, ancak okurlar için çözümlerin kitabın arka kısmında görünmesi gerekiyor.
• Bunun için kendi alıştırma eklentimi yazdım.

  .. in chapter.rst
  .. exercise:: Fizzbuzz
     :name: ex-fizzbuzz
     An exercise
     .. solution:: ex-fizzbuzz
        A solution
  .. in answers.rst
  .. solutionlist::
  

• HTML'de alıştırmalar ve çözümler satır içinde render ediliyor.
• epub ve latex'te, dönüştürme yoluyla çözüm düğümleri solutionlist altına taşınıyor ve her alıştırmaya bir başvuru düğümü ekleniyor.

"Ama ben sözdizimini sevmiyorum"

• Birçok kişi rST'nin sözdiziminin çirkin olduğunu düşünüyor.
• Sözdizimini sevmediğiniz için iyi bir aracı kullanmamanızı anlayabilirim.
• asciidoc, MyST, Typst, Pollen, pandoc-extended markdown gibi başka belge oluşturucular da var.
• Markdown tabanlı belge üreticileri, yeni kullanım senaryolarını desteklemek için sık sık kendi ön işleme adımlarını ekliyor.
• Markdown ve rST için LSP ve treesitter var, ancak gitbook-markdown, md-markdown veya leanpub-markdown için yok.

Gelecek hafta bülten yok

• Hong Kong'da olacağım.

2024-07-31 güncellemesi

• "Logic for Programmers" hakkında kısa bir açıklama ekledim.
• Bu kitap, biçimsel mantığın günlük yazılım mühendisliğinde nasıl yararlı olabileceğini ele alıyor.
• Temel bir matematik özeti ve sekiz farklı uygulama içeriyor.
• Hâlâ alfa aşamasında, ancak şimdiden 20.000'den fazla kelime yazıldı ve çok sayıda faydalı içerik barındırıyor.

GN⁺ özeti

• rST, Markdown'dan daha güçlü bir belge yazım aracıdır.
• Sphinx ile birlikte kullanıldığında, belge ağacını dönüştürme ve genişletme yetenekleri sunar.
• "Logic for Programmers" gibi kitaplar yazmak için kullanışlıdır.
• Birçok kişi rST'nin sözdiziminin çirkin olduğunu düşünse de başka alternatifler de vardır.
• Biçimsel mantıkla ilgili yazılım mühendisliğine ilgi duyanlar için faydalı olabilir.

[GN⁺]

Hacker News görüşleri

• Markdown'un en büyük avantajı, okunmasının ve yazılmasının kolay olmasıdır
• Markdown kitap yazmak için en iyi araç olmayabilir, ancak hızlıca biçimlendirilmiş metin yazmak için idealdir
• Kitap yazmak için LaTeX kullanılır; Markdown not alma, hızlı dokümantasyon ve yorum yazımı için uygundur
• reStructuredText (reST) kendi başına biraz pürüzlüdür, ancak Sphinx ile birleştirildiğinde çok iyidir
  • Sphinx, büyük ölçekli ve profesyonel dokümantasyon siteleri için uygun bir seçimdir
  • Sphinx, sitenin ortak öğelerini kolayca özelleştirmeyi sağlar
  • Dahili bağlantıların her zaman çözümlenmesini garanti eder
  • Eklenti ve tema API'si iyi tanımlanmıştır
  • PyPI'de çeşitli eklentiler ve temalar vardır
• Markdown, HTML'nin hafif bir gösterimidir; reST ise soyut belge ağacının orta ağırlıkta bir gösterimidir
• Markdown, e-posta mesajları ve Usenet gönderilerindeki biçimlendirilmiş metni dönüştürmek için tasarlanmıştır
• reST araçları, RST dosyalarını otomatik oluşturma konusunda yetersizdir
• Markdown, basit işleri hızlıca yapmayı sağlar ve gerektiğinde ham HTML eklenebilir
• MyST, reStructuredText'in özelliklerini sunarken Markdown sözdizimini kullanmayı mümkün kılar
• GitHub proje sayfalarındaki dokümantasyon karmaşık olabilir; Sphinx ve Markdown'u birlikte kullanmak faydalı olabilir
• Yazar, kendi kitabının dizgisini yaptığı bağlamda rST'den söz etmektedir
• reST, Markdown'un rakibi değil, Markdown'dan daha önce ortaya çıkmış bir formattır
• Markdown ve reST temelde aynı hedeflere sahiptir
• Markdown ve reST'in ikisi de okunması kolaydır ve hızlıca yazılabilir
• Markdown, tarihsel nedenlerle daha yaygın hale gelmiştir
• Markdown, özel blok türleri tanımlamaya ve belge ağacını dönüştürmeye olanak tanır
• Jupyter Book, Markdown kullanarak PDF gibi başka hedeflere render edebilen iyi bir örnektir