man sayfaları harika, sorun man okuyucularında

• man sayfalarının “birbirine bağlı bağlantıları olmadığı” ya da “terminal penceresi küçültülünce metnin yeniden akmadığı” yönündeki eleştiriler yaygındır; ancak gerçekte man formatının kendisi bağlantı ve yeniden akış özelliklerini destekler
• Sorun, man sayfalarını okuyan araçların (man komutu ve less gibi) bu özellikleri düzgün biçimde uygulamamasıdır

man sayfası formatının yapısı

• man belgeleri çoğunlukla iki formatta yazılır:
  • mdoc(7): modern, anlam tabanlı işaretleme formatı
  • man(7): 1979~1989 arasında kullanılan eski format
• Örnek (mdoc sözdiziminin bir kısmı):

  .Sh NAME  
  .Nm openrc  
  .Nd stops and starts services for the specified runlevel  
  .Sh SYNOPSIS  
  

• .Sh, .Nm, .Nd sırasıyla bölüm başlığını, komut adını ve açıklamayı ifade eder
• Doğrudan düzenlemek için mdoc makro listesini incelemek gerekir

Başvuru (bağlantı) özelliği de yerleşik olarak var

• mdoc formatında aşağıdaki bağlantı makroları bulunur:
• .Xr: başka bir man sayfasına çapraz başvuru
• .Sx: aynı sayfa içindeki başka bir bölüme başvuru
• HTML’ye dönüştürüldüğünde gerçek bağlantılar olarak render edilir ve tarayıcıda tıklanabilir
• .Sh bölüm başlıkları anchor olarak işlenir ve .Sx bağlantılarının hedefi olabilir
• Ancak terminalde man komutuyla görüntülendiğinde bu bağlantı özelliği çalışmaz

Sonuç: sorun man formatında değil, görüntüleyicide

• Mevcut man komutu sayfayı lesse pipe ederek gösteriyor; bu yöntem bağlantıları işleyemiyor
• Çözüm şu:
• man formatını anlayan ve bağlantıları destekleyen yeni bir sayfa görüntüleyici gerekli
• Terminal genişliği değiştiğinde metnin otomatik yeniden akış (reflow) özelliğinin de birlikte uygulanması daha iyi olur

Arka plan bilgisi

• mdoc(7) 1990’larda 4.4BSD’de tanıtılan formattır
• man(7) 1979 ile 1989 arasında kullanılan klasik formattır ve bugün neredeyse hiç kullanılmaz

[scari]

Slack bot bildiriminde sadece ilk satırı görüp hemen empati kurarak tıkladım. Ben de sorunun okuyucuda olduğu tespitine %100 katılıyorum.

...ama görünüşe göre modern insanlık man bir yana, terminal bile kullanmıyor. rtfm de romantik çağın bir kalıntısı olmuş.

[winterjung]

Ben macOS'ta aşağıdaki gibi tanımlayıp pman ls gibi kullanarak PDF olarak görüntülüyorum.

pman() {  
  mandoc -Tpdf "$(man -w $@)" | open -f -a Preview  
}  

[pcj9024]

Süper ipucu... teşekkürler

[pkj3186]

Vay canına, çok teşekkürler

[bbulbum]

Vay, buna o kadar katılıyorum ki. man'i iyi okursan gerçekten çok iyi, ama iyi okumak aşırı zor..

[GN⁺]

Hacker News görüşleri

• Uzun süredir mdoc ve mandb biçiminde belge yazdığı, ancak bu dili ustalaşmanın zor olduğu yönünde bir görüş var
  • mdoc ve mandb, roff üzerinde yer alan makro setleri gibi
  • Tüm man sayfalarının Markdown'a dönüştürülüp sistem tarafından öyle gösterilmesinin önerilebileceği düşünülüyor
  • Markdown'ın daha fazla aracı var ve teknik olmayan kullanıcılar da kolayca belge yazabiliyor
  • Ancak Markdown daha az biçimseldir ve farklı programlarda birbirinden farklı lehçeler bulunur
• Emacs'ta info sayfalarında gezinmek kullanışlıdır ve man sayfalarında da benzer şeyler yapılabilir
  • Mevcut man sayfalarının zenginliği, birçok kişinin fark etmediği bir avantajdır
  • Markdown'a geçmek isteyenler için bir hayıflanma var
  • Markdown'a geçilirse mevcut çözümdeki bağlantıları ve genel anlamsallığı uygulamak zor olacaktır
  • Veriyi JSON'a taşıyan örneklerde, karmaşık özellikler ekleme girişimleri görülüyor
• Vim'in yerleşik ft-man-plugin'ini varsayılan man sayfası görüntüleyicisi olarak kullanmak sorunun çözümüne yardımcı oluyor
  • Bağlantılar çalışıyor ve satır kaydırıldığında girintiyi koruyor
  • less'in varsayılan ayarları iyileştirilebilir, ancak yatay kaydırma gerekiyor
• Birçok web tabanlı man sayfası sürümünün tekdüze yazı tipiyle ayarlanmış olması üzücü
  • OpenBSD'nin çevrimiçi man sayfaları harika
  • Terminalde man sayfası okumak da güzel
  • En çok arama işlevi ve yarım sayfa kaydırma kullanılıyor
• pinfo, GNU Info sayfalarını görüntülemek içindir, ancak man sayfalarını da gösterebilir
  • Sayfalar arasındaki çapraz başvuruları tanıyıp bunlar arasında gezinebilir
• Belirli bir flag açıklamasına doğrudan gitme özelliği olsa iyi olurdu şeklinde bir görüş var
  • Şu anda flag açıklamalarını bulmak için düzenli ifadeler kullanılıyor
• mandoc projesinin değerlendirilmesi öneriliyor
  • Sayfaları anlamsal olarak işleyerek daha iyi sonuçlar elde edilebilir
• Markdown'ın daha iyi bir çözüm olduğu yönünde bir görüş var
  • Web'de ya da kod editöründe belge okumaya alışıldığı için diğer arayüzler rahatsız edici geliyor
  • Geliştiriciler Markdown'a aşina ve belgelerin çoğu da Markdown ile yazılıyor
  • man sayfaları hem belge yazarları hem de okuyucular için daha aşağıda kalıyor