[LinuxFocus-icon]
<--  | Ana Sayfa  | Eri�imd�zeni  | ��indekiler  | Arama
Duyumlar | Belgelikler | Ba�lant�lar | LF Nedir
Bu makalenin farkl� dillerde bulundu�u adresler: English  Castellano  Deutsch  Francais  Italiano  Nederlands  Russian  Turkce  

[Photo of the Author]
Guido Socher (homepage)

Yazar hakk�nda:

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



T�rk�e'ye �eviri:
Baran Ozgul (homepage)

��erik:

 

Elyordam Sayfalar� Yazmak

man

�zet:

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.

_________________ _________________ _________________

 

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

 

Bu yaz� i�in g�r�� bildiriminde bulunabilirsiniz

Her yaz� kendi g�r�� bildirim sayfas�na sahiptir. Bu sayfaya yorumlar�n�z� yazabilir ve di�er okuyucular�n yorumlar�na bakabilirsiniz.
 talkback page 
<--, Bu say�n�n ana sayfas�na gider
G�rsely�re sayfalar�n�n bak�m�, LinuxFocus Edit�rleri taraf�ndan yap�lmaktad�r
© Guido Socher, FDL
LinuxFocus.org 		�eviri bilgisi:
en --> -- : Guido Socher (homepage)
en --> tr: Baran Ozgul (homepage)

2003-10-28, generated by lfparser version 2.43