Elyordam Sayfaları Yazmak

ArticleCategory: Hardware

UNIXBasics

AuthorImage:[Here we need a little image from you]

[Photo of the Author]

TranslationInfo:[Author + translation history. mailto: or http://homepage]

original in en Guido Socher

en to tr Baran Ozgul

AboutTheAuthor:[A small biography about the author]

Guido, Linux'u, çok esnek ve herhangi bir başka işletim sisteminden çok daha fazla olanak tanıdığı için seviyor.

Abstract:

UNIX kabuğunda kullanılabilen her iyi program, kendisine ait elyordam sayfaları içerisinde belgelenmelidir. Bu örnek, size elyordam sayfaları yazımına hızlı bir giriş sunacaktır.

ArticleIllustration:

man

ArticleBody:

Giriş

Dokümantasyon, genellikle yazılımın kendisinden daha fazla önem taşır, özellikle de yazılım, yalnızca geliştiricisi tarafından kullanılmayacaksa. Yayınlamayı amaçlamadığım bir program bile yazsam, bu programın dokümantasyonunu da yazarım. Çünkü birkaç ay sonra programın nasıl kullanışacağını unutmuş olabilirim ve iyi yapılandırışmış bir dokümantasyon bana saniyeler içerisinde bunu gösterebilir.

Geleneksel Linux buyruk satırı gereçleri her zaman elyordam sayfaları ile dokümante edilmektedir. Basit bir man buyrukadı size buyruğun nasıl kullanılacağını gösterir.

Elyordam sayfaları diğer dokümantasyon biçimlerine göre şu üstünlüklere sahiptir:

  1. Herhangi bir Linux uçbiriminden saniyeler içerisinde görüntülenebilir
  2. Kolaylıkla diğer biçimlere dönüştürülebilirler: HTML, PDF, Postscript, Text,...
  3. Elyordam sayfaları yalnızca uçbirim pencerelerinden değil, aynı zamanda Konqueror gibi diğer programlardan da görüntülebnebilirler. (Sadece man:buyrukadı yazın)

Bölümler

Elyordam sayfaları bölümler halinde yapılandırılmıştır. Tıpkı bir kitabın bölümleri gibi. Örneğin printf için iki elyordam sayfası bulunmaktadır. Birisi C-kütüphanesi işkevi için, bir diğeri ise kabuk buyruğu olan printf için (bölüm 1): 
> whichman -0 printf
/usr/share/man/man1/printf.1.bz2
/usr/share/man/man3/printf.3.bz2
Farklı bölümler şunlardır: 
Bölüm 
   1    Kullanıcı buyrukları
   2    Sistem çağrıları, yani kernel tarafından sğlanmış işlevler.
   3    Altyöntemler, yani kütüphane işlevleri.
   4    AygıtlarDevices, yani /dev dizinindeki özel dosyalar.
   5    Doysa biçem tanımlamaları, örneğin /etc/passwd.
   6    Oyunlar, kendi açıklamalrını bulunduran.
   7    Çeşitli, örneğin makro paketleri, kabuller.
   8    Sadece root tarafından çalıştırılabilecek sistem yöetin araçları.
   9    Başka bir dokümantasyon:
	   n    daha uygun bir yere taşınabilecek yeni bir dokümantasyon.
	   l    bu sisteme özgü yerel dokümantasyon.

Bu yüzden man 1 printf yazmak, size kabuk buyruğu olan printf hakkında dokümantasyon sunacak ve man 3 printf yazmak ise C-kütüphanesi işlevinin tanımını görüntüleyecektir. Sadece man printf buyruğunu çalıştırmak ise bulunan ilk sayfayı yazdıracaktır (genellikle 1. bölümdeki printf).

Birden fazla elyordam sayfası sürümünün olup olmadığını kontrol etmek için yukarıda gösterildiği gibi whichman'i kullanabilirsiniz (yükleyin) ya da kısaca görüntülemek için Konqueror içerisinde man:printf girin:

MANPATH

man komutu, elyordam sayfalarını MANPATH çevre değişkeninin değerini esas alarak arar. Ne yazık ki bir çok Linux sürümü bu değikenin değeri yanlış atanmıştır. Genellikle, bütün perl işlevleri üzerine zengin bir dokümantasyon setinin yer aldığı /usr/lib/perl5/man, içerilmemektedir. Bunu MANPATH değişkeninize (.bashrc ya da .tcshrc içerisinde) şu şekilde ekleyeblirsiniz: 
Bash: 
  MANPATH="/usr/local/man:/usr/man:/usr/share/man:/usr/X11R6/man:/usr/lib/perl5/man"
  export MANPATH

Tcsh:
  setenv MANPATH "/usr/local/man:/usr/man:/usr/share/man:/usr/X11R6/man:/usr/lib/perl5/man"
MANPATH değikenini atadıktan sonra perl sayfalarından birisini alıp almadığınızı görebilmek için man Pod::Man deneyebilirsiniz.

Biçim Anahtar Sözcükleri

Bir elyordam sayfası yazmak çok basittir. Basit olarak, gösterim diline ait anahtar sözcüklerin bir nokta ile başladığı ve satır başında yer aldığı bir makyaj dilidir. Anahtar sözcükler aynı zamanda da makro olarak adlandırılır. En önemli makrolar şunlardır: 
.TH -> Bu elyordam sayfalarının başını/başlığını başlatır.
.SH -> Bölüm başı
.PP -> Yeni paragraf
."  -> Yorum satırı
.TP -> Bu makrodan iki satır sonra gelen metni içeri kaydır.


.TH sözdizimi:
.TH [program adı] [bölüm numarası] [orta sayfa altnotu] [sol sayfa altnotu] [prta başlık]

.SH sözdizimi:
.SH [Başlık metni]


.PP söz dizimi oldukça yalındır. Bir satır atlanmasını sağlar.

Bazen, program kodu örnekleri için ön-biçimlemdirilmiş metin eklemeyi kullanışlı bulurum. Bu şu şekilde yapılabilir: 
.nf
_sizin_ön_bicimlendirilmis_
_metniniz_burada_bulunacak_____
.fi
Bunların groff/nroff makroları olduğuna ve bu nedenle özel elyordam sayfaları makrolarına ait olmadığına dikkat edin. Ne var ki tüm Unix sistemlerinde sorunsuz çalıyor görünmektedirler.

Tüm biçimlendirici makrolar groff_man(7) adlı elyordam sayfalarında dokümante edilmiştir. (groff_man(7) sayfasının HTML sürümünü görüntülemek için buraya tıklayın.). Ben burada makroları açıklamayacağım, bunun yerine groff_man sayfasını okumanızı öneriyorum. groff_man sayfası oldukça ayrıntılıdır ve bilmeniz gereken herşeyi içerir.

Bölümler

Kendi elyordam sayfalarımızı yazmaya başlamadan önce, normalde elyordam sayfalarının bölümler halinde yapılandırıldığını bilmelisiniz. Genel kabul görmüş kullanımda olası bölüm başlıkları aşağıdaki gibidir: 
İSİM           Ad bölümü, işlevin ya da buyruğun adı.
ÖZET           kullanım.
AÇIKLAMA       Genel tanım.
SEÇENEKLER     Seçenekleri ve parametreleri içermelidir.
DÖNDÜRÜLEN DEĞERLER
               Bölüm iki ve üç işlev çağrıları.
ÇEVRE          Çevre değişkenlerinin tanımı.
DOSYALAR       Konuyla ilişkili dosyalar.
ÖRNEKLER       Örnekler ve öneriler.
SİSTEM KONTROLLERİ
               Normalde kullanılan dördüncü bölüm aygıt 
		   arabirim kontrolleri. 
HATALAR        İkinci ve üçüncü bölüm hata ve işaret kontrölü.
BKZ.           referanslar ve alıntılar.
STANDARTLAR    Söz konusu olduğu durumlarda standartlara uygunluk.
SORUNLAR       Sorunlar ve yanlışlıklar.
GÜVENLİK UNSURLARI
               Bilinmesi gereken güvenlik unsurları.
diğer          İsteğe göre uyarlanmış başlıklar yazarın inisiyatifinde ile eklenebilir.

Örnek Bir Elyordam Sayfası

İşte küçük bir örnek elyordam sayfası. Çizgileri tirelerden ayrı kılmak için \ - kullanmak gerektiğine dikkat edin. Tüm bunları metin düzenleyicinize yazın, ve cdspeed.1 olarak kaydedin. 
.TH cdspeed 1  "Eylül 10, 2003" "sürüm 0.3" "Kullanıcı Komutları"
.SH İSİM
cdspeed \- daha hızlı erişim süreleri elde etmek için CD-ROM sürücünüzün hızını azaltın.
.SH ÖZET
.B cdspeed 
[\-h] [\-d device] \-s speed
.SH AÇIKLAMA
Gelişmiş CD-ROM sürücüleri çok hızlıdır. 60x hızlı bir CD-ROm sürücüyü döndürerek hızlandırmak ve sürücüden 
veri okumak birkaç saniye alabilir. Sonuç olarak bu sürücüler 8x ya da 24x hızlı bir sürücüden 
çok daha yavaştırlar. Bu özellikle kısa aralıklarla (örneğin her 5 saniyede bir) küçük bir dosyayı okuyorsanız geçerlidir. 
Bu gereç, hızı sınırlar be sürücüyü küçük dosyalara erişirken daha duyarlı yapar.
.PP
cdspeed aynı zamanda sürücüyü daha az gürültülü yapar ve bu bilgisayarınızda müzik dinlemek istiyorsanız çok kullanışlıdır.
.SH SEÇENEKLER
.TP
\-h 
kısa bir yardım metni görüntüler
.TP
\-d 
/dev/cdrom yerine belirtilen aygıtı kullanır
.TP
\-s 
Hızı belirler. parametre bir tamsayıdır. 0 hızı en yüksek haline geri getirir.
.SH ÖRNEKLER
.TP 
En yüksek hızı 8x olarak belirle.
.B cdspeed 
\-s 8
.PP
.TP 
en yüksek hıza geri getir:
.B cdspeed 
\-s 0
.PP
.SH ÇIKIŞ DURUMU
cdspeed, CD-ROM sürücünün en yüksek hızını değiştirmeyi başarırsa, 0 çıkış durumu döndürür.
Hata durumunda ise 0 olmayan bir sayı döndürülür.

.SH YAZAR
Guido Socher (guido (at) linuxfocus.org)
.SH BKZ.
eject(1)
Yukarıdaki sayfayı görüntülemek için tıklayın (cdspeed.html) .

Bir Elyordam Sayfasını Görüntülemek ve Biçimlendirmek

Elyordam sayfasını yazarken, zaman zaman görüntüleyerek düzgün olup olmadığına bakmanızda fayda vardır. Bunun için aşağıdakini yazın: 
nroff -man sizin_elyordamdosyaniz.1 | less
ya da 
groff -man -Tascii sizin_elyordamdosyaniz.1 | less
Bir elyordam dosyasını düz ön-biçimlendirilmiş metne dönüştürmek için (örneğin yazım imla kontrolü için) : 
nroff -man sizin_elyordamdosyaniz.1 | col -b > xxxx.txt
kullanabilirsiniz. Postscript'e çevirmek için (yazdırma ya da pdf dönüşümüne taşımak için) : 
groff -man -Tps sizin_elyordamdosyaniz.1 > your_manpagefile.ps
kullanabilirsiniz. Elyordam sayfasını HTML'e çevirmek için: 
man2html sizin_elyordamdosyaniz.1
kullanabilirsiniz.

perl POD Kullanarak Elyordam Sayfaları Oluşturmak

Bir çok insanın elyordam sayfalarının sadece bir metin düzenleyicisi kullanılarak düzenlenmesini alışılmadık bulduklarını biliyorum. Onlar aslında elyordam sayfasını "oluşturmak" istiyorlar. perl POD dokümantasyon biçimi iyi bir seçim. Sayfayı POD söz dizimi ile yazarak 
pod2man sizin_elyordamdosyaniz.pod > sizin_elyordamdosyaniz.1
buyruğunu çalıştırabilirsiniz. perl POD dokümentasyon dilinin söz dizim kuralları perlpod adlı bir elyordam sayfasında açıklanmaktadır. Yukarıdaki elyordam sayfası örneği POD biçimine aşağdaki gibi görünecektir. POD'un boşluk karakterine duyarlı olduğuna ve "=head" etrafındaki boş satırların gerekli olduğuna dikkat edin. 
=head1 İSİM

cdspeed -  daha hızlı erişim süreleri elde etmek için CD-ROM sürücünüzün hızını azaltın.

=head1 ÖZET

cdspeed [-h] [-d device] -s speed

=head1 AÇIKLAMA

Gelişmiş CD-ROM sürücüleri çok hızlıdır. 60x hızlı bir CD-ROm sürücüyü döndürerek hızlandırmak ve sürücüden 
veri okumak birkaç saniye alabilir. Sonuç olarak bu sürücüler 8x ya da 24x hızlı bir sürücüden 
çok daha yavaştırlar. Bu özellikle kısa aralıklarla (örneğin her 5 saniyede bir) küçük bir dosyayı okuyorsanız geçerlidir. 
Bu gereç, hızı sınırlar be sürücüyü küçük dosyalara erişirken daha duyarlı yapar.

cdspeed aynı zamanda sürücüyü daha az gürültülü yapar ve bu bilgisayarınızda müzik dinlemek istiyorsanız çok kullanışlıdır.

=head1 SEÇENEKLER

B<-h> kısa bir yardım metni görüntüler.

B<-d> /dev/cdrom yerine belirtilen aygıtı kullanır.

B<-s> Hızı belirler. parametre bir tamsayıdır. 0 hızı en yüksek haline geri getirir.

=head1 ÖRNEKLER

En yüksek hızı 8x olarak belirle:

          cdspeed -s 8

en yüksek hıza geri getir:

          cdspeed -s 0


=head1 ÇIKIŞ DURUMU

cdspeed, CD-ROM sürücünün en yüksek hızını değiştirmeyi başarırsa, 0 çıkış durumu döndürür.
Hata durumunda ise 0 olmayan bir sayı döndürülür.

=head1 YAZAR

Guido Socher

=head1 BKZ.

eject(1)

Referanslar