Markdown yerine rST’yi tercih etme nedenim

 (buttondown.email)
1 puan yazan GN⁺ 2024-08-02 | 1 yorum | WhatsApp'ta paylaş
  • Sphinx’in reStructured Text(rST) biçimi Markdown’dan öğrenmesi daha zor olsa da, kitap gibi büyük ölçekli belgelerde yapıyı ve çıktı biçimlerini ayrıntılı biçimde kontrol etmeyi kolaylaştırır
  • Markdown, HTML’i hafifçe yazmaya yarayan bir gösterime daha yakındır; rST ise soyut belge ağacını merkeze alarak yönergeleri, düğümleri ve renderer’ları birleştirip yeni belge nesneleri eklemeye olanak tanır
  • Sphinx, render etmeden önce doctree’yi dönüştürdüğü için çapraz referanslar, çıktı biçimine özel işleme ve belirli derleme aşamalarındaki dönüşümler gibi işler belge sistemi içinde ele alınabilir
  • Logic for Programmers’ta alıştırmalar ve çözümler metindeki ilgili yerlere yakın yazılır; ardından EPUB ve LaTeX çıktılarında konumlarını ve gösterim biçimlerini değiştiren özel bir eklenti kullanılır
  • Basit Markdown, birleşik bir genişletme söz dizimi ve render öncesi dönüşüm desteğinden yoksundur; belge üreticileri ayrı ön işleme ile etrafından dolaştıkça araç desteği ve genişletilebilirlik zayıflar

rST’yi seçme nedenim

  • Logic for Programmers’ın yeni sürümü, Sphinx ile yazdığım ikinci kitap; önceki çalışmam olan yeni Learn TLA+ da Sphinx kullanıyor
  • Sphinx, reStructured Text kullanır ve rST’nin öğrenme eğrisi Markdown’a göre daha diktir
  • Markdown ile birkaç kitap yazdıktan sonra daha iyi araçlara ihtiyaç duyduğum için rST’ye geçtim
  • rST’nin kendisi Sphinx’ten bağımsızdır; ancak pratikte çoğu kişi rST’yi Sphinx yüzünden kullandığı için ikisini birlikte ele alıyorum

Markdown ile rST arasındaki yapısal fark

  • En büyük fark, Markdown’ın HTML için hafif bir gösterime yakın olması, rST’nin ise soyut belge ağacı oluşturan orta ölçekli bir gösterim olmasıdır
  • Markdown’ın resim söz dizimi, basit bir dönüşümle <img alt="alttext" src="example.jpg"/> gibi HTML’e çevrilebilir
    • Modern Markdown motorları da çoğu zaman ara bir temsile ayrıştırır; ancak temel karakteri hafif HTML gösterimine yakındır
  • rST’de resimler .. image:: yönergesiyle ifade edilir
    • Sphinx kayıtlı yönerge işleyicisini bulup ImageDirective.run’ı çalıştırır
    • Çalıştırma sonucu, alt alanına sahip image_node gibi bir düğüm nesnesi olur
    • Tüm doctree işleme tamamlandığında HTML Writer, image_node render fonksiyonunu bulup HTML etiketini üretir
  • rST yaklaşımında uygulama ve söz dizimi daha karmaşıktır ve Markdown’a göre daha fazla boilerplate içerir; ancak resimler de diğer yönergelerle aynı genişletme mekanizması üzerinden ele alınır

Yeni belge nesneleri ekleme yöntemi

  • rST/Sphinx’te yeni metin nesneleri eklenti olarak eklenebilir
  • Örneğin <image> yerine <figure> ve <figcaption> oluşturmak istiyorsanız, standart Markdown’da HTML’i doğrudan eklemeniz gerekir
  • Sphinx’te bu, yeni bir figure yönergesi kaydedilerek ele alınır
    • FigureDirective, resim işlemenin büyük bölümünü yeniden kullanmak için ImageDirective’ten miras alabilir
  • Yönerge kaydetme, düğüm oluşturma ve builder’a özel renderer kaydetme kalıbı tüm eklentilerde aynı şekilde uygulanır

Render öncesi doctree dönüşümü

  • Sphinx, render etmeden önce doctree dönüşümü gerçekleştirebilir
  • Belgeler arası çapraz referanslar da bu özellikle işlenir
    • Bir belgede foo anchor’ı ve başka bir belgede :ref:\image <foo>`` varsa, Sphinx son işleme aşamasında doğru URL’yi ekler
  • Dönüşüm kodu, derleme sürecinin birinci sınıf bir özelliği gibi ele alınır
    • Yalnızca HTML çıktısında belirli bir dönüşüm uygulanabilir
    • Dönüşüm belirli bir derleme aşamasında çalıştırılabilir
    • Çalıştırmak istemediğiniz yerleşik dönüşümler de kaldırılabilir
  • Her belgenin böyle bir güce ihtiyacı yoktur; Markdown hafif ve taşınabilir olduğu için yaygın kullanılır

Alıştırma ve çözüm eklentisi örneği

  • Logic for Programmers matematiğe yakın bir kitap olduğu için okuyuculara yönelik alıştırmalar gerekir
  • Yazarken alıştırmaları ve çözümleri belge içinde birbirine yakın tutmak daha kolaydır; ancak okuyucuya çözümlerin kitabın arka tarafında görünmesi gerekir
  • Gereksinimler çıktı biçimine göre değişiyordu
    • Alıştırmalar ve çözümler birbirine linklenmeliydi
    • Yazdırılabilirlik düşünülerek PDF’te sayfa referansları da gerekliydi
    • LaTeX/PDF çıktısı ile EPUB çıktısında render yöntemi farklı olmalıydı
  • Bunun için exercise, solution, solutionlist işleyen özel bir Sphinx eklentisi yazdım
  • HTML hata ayıklama çıktısında alıştırmalar ve çözümler inline olarak render edilir
  • EPUB ve LaTeX üretiminde, tüm doctree oluşturulduktan sonra dönüşüm çalıştırılır
    • Orijinal konumlarındaki tüm solution_node öğeleri solutionlist altına taşınır
    • Her alıştırmaya yeni çözüm konumuna giden bir referans düğümü eklenir
    • Her çözüme, orijinal alıştırmaya geri dönen bir referans düğümü eklenir
  • LaTeX builder, alıştırmaları ve çözümleri answers environment içine sarar
  • EPUB builder, çözümleri popup footnote olarak render eder
  • Bu yapı, kitabın ücretsiz örneğini hazırlarken de yardımcı olur
    • Ücretsiz örneğin arka kısmında tüm kitabın çözümleri değil, yalnızca örneğe dahil edilen bölümlerin çözümleri yer alır

Söz dizimi zevki ve alternatifler

  • rST’ye yönelik en yaygın itiraz, söz diziminin çirkin olmasıdır
  • Bir aracı görünüşünü sevmediğiniz için kullanmamak da gayet geçerli bir seçimdir; Lisp’i kabullenmenin zor olmasının nedeni de aynı zevk meselesi olarak görülebilir
  • Alternatifler arasında asciidoc, MyST, Typst, Pollen ve pandoc-extended markdown bulunur
  • Ana fikir, Sphinx/rST’nin büyük ölçekli belgelendirme için istisnai derecede iyi olması değil; basit Markdown’ın büyük ölçekli belgelendirme için istisnai derecede uygunsuz olmasıdır

Markdown tabanlı üreticilerin sınırları

  • Basit Markdown’da birleşik bir genişletme söz dizimi ya da render öncesi dönüşüm için yerel destek yoktur
  • Birçok Markdown tabanlı belge üreticisi, yeni kullanım senaryolarını desteklemek için kendi ön işleme aşamasını ekler
  • Bu yöntem genelde çalışır; ancak iş Markdown içinde yapılmak yerine Markdown’ın çevresinden dolaşan bir yapıya dönüşür
  • Bunun sonucunda işlevlerin gücünde sınırlar oluşur ve programcılara yönelik araçların bu varyantları iyi anlaması zorlaşır
    • Markdown ve rST için LSP ve treesitter vardır; ancak gitbook-markdown, md-markdown, leanpub-markdown için aynı düzeyde araç beklemek zordur
  • rST’nin çirkin söz dizimi, aksine zengin bir söz dizimi ağacına sahip olma avantajı sağlayabilir
    • Belirli bir todo yönergesinin yalnızca gövdesini değiştiren treesitter sorguları mümkündür
    • Bu, rST söz dizimi ağacının Markdown söz dizimi ağacından daha zengin olması sayesinde mümkündür

Logic for Programmers güncellemesi

  • Logic for Programmers, biçimsel mantığın gündelik yazılım mühendisliğinde nasıl yararlı olabileceğini ele alan bir kitaptır
  • Kitap temel bir matematik özetiyle başlar ve özellik tabanlı test, veritabanı kısıtları, karar tabloları gibi 8 uygulama ile devam eder
  • Henüz alfa aşamasında olsa da 20.000 kelime hacmindedir ve okuyucu geri bildirimi almaktadır

İlgili okumalar

1 yorum

 
GN⁺ 2024-08-02
Hacker News yorumları

  • “Sırf bakınca bile kusacak gibi oluyorsun diye iyi bir aracı kullanmayacak mısın?” diye sorarsanız, evet derim. Markdown’ın en büyük avantajı okunmasının kolay olması, ikinci avantajı da yazmasının kolay olmasıdır.
    Ayrıştırmasının ne kadar kolay olduğu ya da genişletmesinin ne kadar kolay olduğu pek önemli değil. Kitap yazmak için Markdown’ın en iyi seçenek olup olmamasından bağımsız olarak, sözdizimini iyi bilmeyen insanların bile kolayca okuyabileceği biçimde hızlıca biçimli metin yazmak için Markdown en iyisi. Kitap yazmaya çalışmıyorum; yalnızca not almam, hızlı dokümantasyon hazırlamam, yorum yazmam gerekiyor. Kitap yazacak olsam RST’den önce LaTeX kullanırdım.

    • Markdown geliştiriciler arasında popülerleşmeye başladığında epey gülünç bir tercih gibi görünüyordu. O dönemde de düz metni biçimli belgelere dönüştürmek için daha iyi birçok seçenek vardı; buna rağmen geliştiriciler Markdown merkezli CMS’ler, üretkenlik uygulamaları, belge yönetim araçları ve eklentiler geliştiriyordu.
      Ama gerçek uygulamalarda kullanınca Markdown’ın özünün bu olmadığını gördüm. Amaç, yalnızca asgari biçimlendirme sunarak düz metin hâlindeyken bile HTML’e işlenmiş hâli kadar doğal okunmasını sağlamak. Desteklediği biçimlendirme bilinçli olarak küçük tutulduğu için akılda kalıyor ve araç çubuğu olmadan kullanılabiliyor. Yorum kutuları, sohbet, commit mesajları, belki blog yazıları için uygun; ama kurumsal düzeyde ürün dokümantasyonu yazmak için uygun değil. Günümüzde HTML’e render edilmeyecek yerlerde bile Markdown kullanılıyor; çünkü kendi başına okunaklı. HN’nin de desteklemesini isterdim.
    • Markdown ile kitap yazdım ve pek sorun yaşamadım. Teknik doküman değil, roman olsa da Markdown’a ara sıra HTML karıştırarak çözemeyeceğim bir şey olmadı.
      Teknik dokümanların da oldukça fazlasını Markdown ile hazırladım; Pandoc uzantılarıhttps://pandoc.org/MANUAL.html kullanıldığında karmaşık formüller ve sözdizimi vurgulamalı kod blokları dâhil ihtiyaç duyulan biçimlendirmelerin neredeyse tamamı eklenebiliyor. Bu Markdown; HTML’e, Word belgesine, ePub’a, PDF’e vb. dönüştürülebiliyor. Markdown dışında başka bir şeye başvurmak için çok ikna edici bir gerekçe gerekir.
    • TeX kullanıcıları arasında muhtemelen ilk %10 civarında yer alırım, ama Markdown ile TeX arasına başka bir dizgi dilinin girebileceği alanın çok büyük olduğunu sanmıyorum. Markdown kolay ama sınırlı, TeX ise biraz zor ama fiilen sınırsız esnekliğe sahip.
      TeX’te gördüğüm en büyük sorun dil değil, insan sorunu. İnsanlar sık sık berbat tarzda spagetti TeX yazıyor. Ama “belgeler de koddur” zihniyetiyle yazınca oldukça temiz sonuçlar çıkıyor. İkinci en büyük sorun ise iyi bir TeX → HTML derleyicisinin olmaması.
    • “Kitap yazacak olsam LaTeX kullanırdım” demek, yazma ve yapılandırma aşaması için korkunç bir tercih gibi görünüyor. Ben bunun yerine Markdown ile yazıp dizgiyi umursamaz, yalnızca yayın aşamasında LaTeX’e dönüştürürdüm.
      LaTeX’te usta değilim ama bir ara öğrenmeye çalıştığımda böceksi bir uzaylı medeniyetinin dilini öğreniyormuşum gibi hissettirmişti. Hiç sezgisel değildi; başkalarının zaten yaptığı şeyleri kopyalayıp yalnızca kendi yazımı araya yerleştirmek dışında yeni bir şey yapmak neredeyse imkânsızdı. Hatırladığım kadarıyla birinci sınıf Unicode desteği de yoktu.
    • Markdown’ın “sözdizimini iyi bilmeyen insanların bile kolayca okuyabileceği biçimde hızlıca biçimli metin yazmak için en iyi araç” olduğu sözünde hemfikir olmam zor. Sadece temellere bakınca bile en iyisi değil.
      İtalik için yıldız ya da alt çizgi kullanmak da alışkanlık gerektiriyor; /italic slashes/ gibi çok daha sezgisel yöntemler var. Temellerin dışına çıkınca tablolar, metadata ve etiketler metni gölgelediği için uygun araçlar olmadan yazması ve okuması da kolay olmuyor. Genişletmesi kolay olursa bu temel sorunlar da düzeltilebilir; dolayısıyla genişletilebilirlik de konuyla ilgili.

  • Yaklaşık 12 yıl teknik dokümantasyon yazarı olarak çalıştım; kariyerimin başlarında bir startup’ın dokümanlarını Word’den Sphinx’e taşıdım. Sonrasında Google’ın kendi CMS/geliştirici dokümantasyon platformunda, Eleventy tabanlı sitelerde ve son 2 yıldır yeniden Sphinx tabanlı bir site olan pigweed.dev’de çalıştım. readme.com tabanlı startup işleri de yaptım; Docusaurus, Astro ve Hugo ile de biraz uğraştım.
    Tek başına reStructuredText kaba gelebilir, ama Sphinx ile birleşen reST çok iyi. Sphinx’in güçlü yanları reST’in zayıflıklarını fazlasıyla aşıyor. 100 sayfadan fazla, 10’dan çok katkıcısı olan büyük ve profesyonel bir dokümantasyon sitesi için uzun vadede Sphinx’in en sorumlu tercih olduğuna oldukça güçlü biçimde inanıyorum. Örneğin Pigweed’de yalnızca :bug:\59385981`` yazınca bunun https://pwbug.dev/59385981 bağlantısına dönüşmesini sağladık; ileride hata bağlantılarını topluca taşımamız gerekse bile bu kolay. Dahili bağlantıların da her zaman çözümlendiği garanti ediliyor; var olmayan bir yere bağlantı verirseniz uyarı ya da hata oluşuyor. Bunun dokümantasyon sitelerinde standart olmaması tuhaf diye daha önce https://technicalwriting.dev/src/link-text-automation.html adresinde yazmıştım. Sphinx’in eklenti ve tema API’leri de iyi tanımlanmış durumda; PyPI üzerinde de oldukça büyük bir ekosistemi var. Son zamanlarda Sphinx’e dokümantasyon sistemlerinin uyuyan devi diyorum; biraz güç birliğiyle çok daha etkileyici hale gelebilir.

    • Bu kısım gerçekten önemli. CMS’ler ve statik site üreteçleri arasında, yazı yazarken nihai URL’yi doğrudan girmenizi isteyen çok fazla sistem var.
      Slug değişirse ya da site yapısını yeniden düzenlerseniz tüm sitede bul-değiştir yapmanız gerekiyor. Statik site üreteçleri [Hello](../hello.md) gibi bağlantı verdirip bunu derleme sırasında çözebilecekken, çok kullanılan ya da incelediğim araçların çoğu [Hello](/why/hello/) adresini doğrudan yazdırıyor. Bu özellik sanki zevk meselesi gibi görülüyor. Bir statik site üreteci ekibinden birine söylediğimde de “Bunu neden isteyesin ki?” yanıtını aldım; açıklasam da anlatamadım. Sorunu yaşamadan çözümün değerini anlayamıyorlar mı, yoksa bir kez yazıp 10 yıldan fazla bakım yapmamaya alışkınlar mı bilmiyorum; ama daha yaygın desteklenmesini isterim.
    • Sphinx harika ama ciddi biçimde değeri bilinmiyor. Bildiğim kadarıyla Sphinx, yapısal olarak sağlam, genişletilebilir ve yaygın kullanılan tek dokümantasyon framework’ü.
      Eklenti ekosistemi mükemmel; ekiplerin ve projelerin dokümantasyonunu iyileştirmede muazzam bir kaldıraç sağlıyor. reStructuredText’in kendisini sevmiyorum, ama bugünlerde MyST-Parser sayesinde eskiden Sphinx’in RST’ye sıkı sıkıya bağlı olduğu işlerin çoğu Markdown ile de yapılabiliyor: https://github.com/executablebooks/MyST-Parser
    • Site genelindeki ortak öğeleri özelleştirmek Markdown+Pandoc ile de çok kolaydı. YouTube bağlantısı içeren image tag’lerini video tag’i ve alternatif metinli küçük görsellerle değiştirmek; yerel video dosyası image tag’lerini ffmpeg’e bağlayıp optimize etmek ve yeniden boyutlandırmak da birkaç satır kodla halledildi.
    • Bu yorumu görmeden önce Sphinx’i bilmiyordum. 20 yılı aşkın süredir geliştiricilik işimin yanında teknik dokümantasyon yazıyorum; şimdiye kadar daha çok TeX ve özel XSL tarafına yakındım.
      Dahili bir dili/VM’i/soyutlama katmanını anlatan 200 sayfadan uzun bir kitabı yeni Sphinx’e taşıdım ve gerçekten hayat değiştiren bir sistem. Sphinx’in kendi dokümantasyonunun giriş eşiği daha düşük ya da örnekleri daha fazla olsa isterdim, ama şu anda oldukça güçlü bir balayı dönemi hissi var. Başlıca ilgi alanım, iyi görünen PDF kitaplar üretmenin yolu ve kitabı bölüm ve alt bölüm bazında POSIX uyumlu man sayfalarına bölen bir sistem.
    • Sphinx’in kitlesel ölçekte büyük başarı kazanmasını istiyorsanız 1 numaralı öncelik yüksek kaliteli, güzel temalar edinmek olmalı.
      Bir site üreteci seçerken görsellik oldukça önemli bir etken. Hugo ve Gatsby’nin varsayılan temaları mükemmel; hatta sırf bu yüzden projelerde onları seçtiğim oldu. Sphinx tema koleksiyonları https://sphinx-themes.org/ ve https://sphinxthemes.com/#featured-themes genel olarak sönük. Standart Sphinx RTD temasını https://sphinx-rtd-theme.readthedocs.io/en/stable/ Apple dokümantasyonu https://developer.apple.com/documentation/swift/array veya Fluent UI https://react.fluentui.dev/?path=/docs/concepts-developer-positioning-components--default ile karşılaştırınca eski görünüyor.

  • “Markdown, HTML’nin hafif bir gösterimidir” cümlesinin bu yazıdaki en büyük sorun olduğunu düşünüyorum. Bu kesinlikle hatalı
    Markdown, 1990’ların başındaki e-posta ve Usenet yazılarında fiilî standart gibi kullanılan metin biçimlendirme alışkanlıklarını dönüştürmek için bir araç olarak tasarlandı. 7 bit ASCII kısıtı yüzünden vurgu veya başlık gibi biçimlendirmeler özel işaretlerle gösteriliyordu; HTML’in de bu adı konmamış alışkanlıklarla pek çok benzerliği vardı. Bu yüzden John Gruber 2004’te bunu HTML’e çeviren temel betiği https://daringfireball.net/projects/markdown/ yazdı, ama bunun bu kadar yaygın bir fiilî standart hâline geleceğini muhtemelen beklemiyordu

    • O bağlantıdaki ilk cümle zaten “Markdown is a text-to-HTML conversion tool for web writers.”
      Gruber, Usenet’in fiilî standardını alıp yalnızca bir HTML dönüştürücüsü yapmadı; Usenet’ten ve başka alışkanlıklardan ödünç alarak kendi markup’ını tasarladı. Bağlantının altındaki “Acknowledgements” bölümü de bunu gösteriyor. Markdown baştan itibaren web CMS’leri için bir markup söz dizimi olarak amaçlandı ve ona HTML’nin hafif bir gösterimi demek doğru. Söz diziminin her parçasının doğrudan karşılık gelen HTML üretmesini sağlamak temel fikirdi
    • Katılmıyorum. Markdown her zaman HTML ile ilişkiliydi; Markdown parser’larının gerçek HTML etiketlerini karıştırmayı destekleyecek kadar bile
      E-posta alışkanlıklarından esinlenmiş olması, “Markdown, HTML’nin hafif bir gösterimidir” ifadesini daha az doğru yapmaz
    • Bu tür anlamsal çekişmelerin artık bırakılmasını isterim. Sıkıcı bir sohbet yaratıyor ve HN yönergelerine de aykırı
      Karşınızdakinin söylediğinin en makul ve güçlü yorumuna yanıt verin; eleştirmesi kolay zayıf yorumu seçmeyin diye bir kural var. Yazıdaki en kışkırtıcı cümleyi seçip şikâyet etmek yerine ilginç kısımlarına yanıt verin diye bir kural da var: https://news.ycombinator.com/newsguidelines.html
      Yazının ana fikrine katılmıyorsanız rST yerine Markdown’ı tercih ettiğinizi söyleyip nedenini açıklayabilirsiniz. Markdown’ın tam olarak ne olduğu konusunda tek bir cümle üzerinden kavga etmek aptalca
    • Markdown’ın kendisi e-posta ve Usenet biçimlendirmesinden ayrı bir şey. Markdown belirli bir söz dizimiydi ve iyi tanımlanmamıştı; sonrasında birbirine genel olarak benzeyen birkaç söz dizimi ailesine genişledi
      E-posta veya Usenet gibi alışkanlıklardan esinlendi; bunların bazıları bilgisayardan bile önce vardı. Örneğin eski daktilo belgelerinde yıldız işaretinin italik gibi kullanıldığı örnekler gördüğümü sanıyorum. Ama Markdown HTML ile güçlü biçimde bağlantılıdır; söz dizimi de HTML tarafından çok kısıtlanır ve onu HTML’den ayırma girişimleri büyük ölçüde başarısız olmaya mahkûmdur
    • İkisi de doğru. İlk uygulama HTML’nin üst kümesiydi. Yaygın olan şeyleri hafif söz dizimiyle, geri kalanını HTML ile yazma yaklaşımıydı

  • Markdown’ın özünün, ham HTML’e göre basit işleri daha hızlı yaparken gerektiğinde ham HTML karıştırmaya izin vermek olduğunu düşünüyorum
    Markdown’dan daha fazla RST gücüne ihtiyaç duyan projelerde, doğrudan HTML yazmak bana daha rahat gelmişti

    • Yazarın yaptığı gibi “Sphinx’i genişletip yeni metin nesneleri oluşturabilirsiniz. Varsayılan Markdown’da doğrudan HTML eklemeniz gerekir” diye yazılınca, böyle bir özelliğe ihtiyaç olduğunda sadece HTML kullanmanın nesi sorun diye merak ediyorum. Neden bir katman daha koyulduğunu anlamıyorum

  • Benzer karmaşıklıkta bir dokümantasyon sistemi kurarken, RST dosyalarının yapısını veritabanında saklayıp veritabanı sonuçlarını içerikle karıştırmak gibi işler için açık anlamlara sahip markup’a çok ihtiyaç duyduğumdan RST’yi değerlendirdim
    Karşılaştığım iki sorun vardı. Birincisi, RST araçlarında RST’yi tekrar dışa veren bir unparser yok. Birden çok RST dosyasını ve başka kaynakları birleştirip otomatik RST dosyaları üretmek ve bunları dokümantasyon API’siyle işlemek istiyordum, ama desteklenmiyordu. İkincisi, RST araçları belirli bir belge için tanımlanmış blok kümesini bekliyor. Bloklar genel biçimde temsil edilseydi, iç blok tanımlarını bilmeden belgeyi dönüştüren araçlar mümkün olabilirdi; ama durum böyle değil. Bu RST’nin kendisinden çok araç sorunu, fakat kodu her seferinde en temeline kadar sökmek gerektiğinde HTML tabanlı gibi başka markup sistemlerini düşünmeye başlıyorum

    • HTML yerine yapılandırılmış belgeler için XML kullanılabilir. XML, gereken özel etiketleri tanımlamanıza izin verir ve isterseniz şema doğrulaması da mümkündür
      Bu yöntemin avantajı, girdi şemasını ve çıktıyı tamamen denetleyebilmeniz; dezavantajı ise Markdown veya RST’ye göre söz dizimsel gürültünün çok daha fazla olması ve istediğiniz çıktı biçimine parse edip dönüştürecek bir betiğe ihtiyaç duymasıdır
    • Python’da rST, docutils’in desteklediği birden fazla girdi biçiminden yalnızca biridir: https://docutils.sourceforge.io/README.html#purpose
      docutils’in genel amacı biçimleri parse edip API’ye dönüştürmektir: https://www.docutils.org/docs/index.html#api-reference-material-for-client-developers
    • rST ve AsciiDoc özellik bakımından kabaca benzer görünüyor. Zayıf yanları ve eksik özellikleri de kabaca benzer mi merak ediyorum
    • rST’nin başlıca aracı olan docutils’te committer’dım. Araçları Markdown’a taşımamın nedenlerinden biri docutils ile uğraşmanın fazlasıyla acı verici olmasıydı. GitHub gibi yerlere taşınmayı reddetmesine bakmak bile birlikte çalışmanın ne kadar kullanıcı dostu olmadığını gösteriyor
    • Şu an bilgisayarım olmadığı için test edemiyorum ama include yönergesiyle istediğinizi yapabileceğinizi düşünüyorum

  • Birkaç yıl önce ezberlemeye değer bir reStructuredText alt kümesini derlemiştim: https://simonwillison.net/2018/Aug/25/restructuredtext/
    Son projelerde MyST kullanmaya başladım; reStructuredText’te önemli gördüğüm referans ve içindekiler tablosu özelliklerini sunarken, katkı verenlerin yazması kolay Markdown sözdizimini kullanmasına da olanak tanıyor

    • Bağlantılar, özellikle de dış bağlantılar konusunda büyük avantajı var. Dokümantasyon sitelerinde aynı dış bağlantıya birçok yerde referans verilebiliyor ve değiştiğinde yalnızca bir kez güncellemek istiyorsunuz
      Asıl oyunun kurallarını değiştiren şey ise iç bağlantılarda rST+Sphinx ile :ref:, :doc: direktifleri. Aynı içerik içinde bir ankora ya da belge bağlantısına referans verirken başlığı elle yazmak zorunda kalmıyor, elle yazılan başlığın sonunda bayatlamasını önleyebiliyorsunuz: https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role
      rST ile yazarken en çok özlediğim özelliklerden biri

  • ReStructuredText sohbetini bölmek istemem ama Markdown’dan daha fazlasını sunan bir işaretleme dili arıyorsanız ReStructuredText yerine AsciiDoc’a bakmanızı öneririm. Üçüyle de yıllarca teknik dokümantasyon yazdım ve AsciiDoc’un ReStructuredText ile Markdown’dan daha iyi olduğunu düşünüyorum
    Örneğin Markdown ve ReStructuredText’in tablo desteği çok zahmetli. AsciiDoc tablo biçimi okumayı, yazmayı ve bakımını kolaylaştırıyor; ayrıca başlıklar, altyazılar, tablo ve satırlar için özel boyutlar, tablo içinde karmaşık biçimlendirme gibi daha güçlü özellikler sunuyor. Markdown gibi birçok lehçesi olmayan tek bir standart biçim; sözdizimi kısa ve okunaklı, öğrenme eğrisi ReStructuredText’ten daha yumuşak. Çıktı stillendirme seçenekleri daha iyi, araç zinciri daha üstün ve yerleşik dokümantasyon özellikleri zengin olduğu için üçüncü taraf eklentilere daha az ihtiyaç duyuluyor. AsciiDoc baştan itibaren teknik dokümantasyon için tasarlanmış; diğer ikisi ise bu role sonradan uydurulmuş gibi

  • 5–10 sayfalık bir Markdown belgesini güzelce düzenleyip, kendisini daha dinamik bir Jinja şablonundan render edilecek hâle getirince başlangıç oldukça tatmin edici oluyor. Otomatik dokümantasyon için bir derleme süreci de var ve tek bir GitHub README’sine sığmayacak kadar büyük. Ama acı bundan sonra başlıyor
    GitHub proje sayfası dokümantasyonu pek uymuyor; .nojekyl dosyasına gerek var mı, gh-pages dalı hâlâ gerekiyor mu derken kafa karışıyor. Depo ayarlarında mı hata var, yoksa değişiklikler mi yansımadı anlayamıyorsunuz; GitHub Actions’ı denemeye kalkıp birkaç saat geçince iş mantıksızlaşıyor. Read the Docs’a tekrar bakınca Sphinx istiyor gibi görünüyor; Markdown ile Sphinx’i birleştiriyorsunuz, derleme oluyor ama dağıtımdan sonra sayfa genişliği bozuluyor, yerelde yeniden üretilemiyor; muhtemelen topluluk katmanı reklam eklemesinden kaynaklanıyor. Birçok projede iyi çalışıyor ve ben de daha önce yaptım, ama çalışana kadar inanılmaz derecede küçük ayrıntılarla uğraştırıyor. Sonuçta Markdown’a karşı RST meselesi umurumda değil; asıl mesele orta ölçekli dokümantasyon projeleri ve statik barındırma için iyi uyan bileşimi bulmak

    • mdBook’a bakıp bakmadığınızı merak ediyorum. Kendim kullanmadım ama mdBook kullanan çeşitli projelerin dokümantasyonlarını beğendim ve tek README dosyasını aştığınız noktada oldukça iyi görünüyor
      Otomatik dağıtım yönergeleri de iyi hazırlanmış: https://github.com/rust-lang/mdBook

  • Yazarın bunu kendi kitabının dizgisi bağlamında söylediği gözden kaçırılıyor gibi. Genel olarak rST’nin Markdown’dan daha iyi olduğunu savunmuyor
    Genel durumda Markdown’un basitliği yaygın kullanılmasının nedeni, ama yazarın bahsettiği şey bu değil

  • reST, Markdown’a rakip olarak yapılmış gibi tepki verilmesi ilginç. Aslında durum neredeyse tam tersi. reST, 2002’de StructuredText’in geliştirilmiş hâliydi; Markdown ise ilk kez 2004’te yayımlandı
    İkisinin hedefleri çok benzer ve en temel metinlerde ikisi de düz metin gibi okunup yazılabiliyor. O dönemde herkes böyle bir şey istemeye başlayınca birden fazla biçim ortaya çıktı. Markdown’un kazanmasının “daha basit” ya da “daha okunaklı” olmasıyla pek ilgisi olduğunu düşünmüyorum. Saf ASCII ve boşluklarla kolayca ifade edilebilen içeriklerde çoğunlukla birbirinin yerine kullanılabilirler. Örnekteki reST belgesinin bir ayrıştırıcı olmadan okunamayacak kadar anlaşılmaz olduğunu kim söyler? Markdown türevlerinin bundan hangi açıdan daha iyi olduğunu pek bilmiyorum; tarihsel tesadüfe yakın biçimde biri baskın hâle geldi, yoksa ikisi de temel hedefler için yeterince iyi

    • Çok basit bir örnek verildiği için hem Markdown hem reST bunu kolayca halledebiliyor
      reST gerektiğinde birçok yararlı ek biçimlendirme özelliği sunuyor, ama gerekmediğinde bunlar fazlalık. GitHub’a katıldığım 2010 civarında GitHub-flavored Markdown kullanmaya başladım; Python dokümantasyonu nedeniyle reStructuredText’i de birkaç kez kullandım. İkincisinin öğrenme eğrisi çok daha yüksekti ve sonrasında kullanmak için bir nedenim olmadı
    • Okunamaz mı derseniz hayır; ama yazması sinir bozucu mu derseniz evet. Altı çizgili başlıklar düzenlerken can sıkıcı ve uzunluğu birebir tutmak gerekmese bile tutmak zorundaymışsınız gibi baskı yaratıyor
      Çift backtick de gerçekte harcadığı süreye kıyasla gereğinden fazla sinir bozucu bir sözdizimi