Linux Türevi Sistemlerde Man Sayfası Nasıl Yazılır?

Giriş

Bu makalede tüm kullanıcıların anlayabileceği şekilde bir man sayfasının nasıl hazırlanacağına değineceğim. Linux tabanlı sistemlerde hali hazırdaki araçların man sayfaları olmasına rağmen, bazen olmayan bir uygulamanın man sayfasını yazma ihtiyacımız olabiliyor. Bir uygulamanın man sayfası o uygulamanın daha fazla kullanılmasını sağlayacaktır.

 

Man Nedir ve Faydaları

Dökümantasyon, genellikle programın kendisinden daha fazla önem taşımaktadır, özellikle de program yalnızca geliştirici tarafandından kullanılmayacaksa. Yayınlamayı amaçladığımız bir program bile yazsak, bu programın dökümantasyonu da yazmamız gerekir. Çünkü birkaç ay sonra programın nasıl kullanılacağını unutmuş olabiliriz veya bu programı kullanacak kullanıcılar nasıl kullanacaklarını bilmiyor olabilirler, iyi bir dökümantasyon bir programın nasıl kullanılacağını size saniyeler içinde gösterebilir.

Geleneksel linux komut satırı araçları her zaman man sayfaları ile dökümante edilmektedir. Basit bir man nano komutu size nano aracının nasıl kullanacağını gösterir.

Man sayfaları diğer dökümantasyon biçimlerine göre şu üstünlüklere sahiptir;

  • Herhangi bir linux komut satırından saniyeler içerisinde görüntülenebilir.
  • Kolaylıkla diğer biçimlere dönüştürülebilir; HTML, PDF, Postscript, Text…
  • Man sayfası yalnızca uçbirim pencelerinden değil, aynı zamanda windows gibi diğer programlardan da görüntülenebilir.
  • Man sayfası size bir programın nasıl kullanılacağını saniyeler içerisinde göstermektedir.

 

Man Sistemi Neden Var ?

Bildiğiniz üzere UNIX komut satırın da yazılabilecek 1500 ‘den fazla komut vardır. Bu komutların birçok parametre (option) seçenekleri vardır. Dolayısıyla bu araçların ve komutların her birini, her bir parametre kombinasyonunu hatırlamak çok zordur.

Örneğin, dosya sistemi üzerinde işlem yapma komutu olan ls komutunun -l parametresi uzun listeleme anlamında iken diğer dosya sistemi komutlarında aynı anlama gelmeyebilir. Ayrıca bu parametre belkide hiç olmayabilir. Komutlar buna çözüm olarak –help parametresi ile komutun bir özetini sağlar ama çoğu zaman bu özet bilgi, bizim yapmak istediğimiz işi yapmakta yeterli olmayabilir. Özet bir şekilde geçmek gerekirse tüm bu problemler den dolayı, UNIX online referans sistemi yapılmıştır.

 

Man Sistemi Nasıldır ?

UNIX man sistemi, iki kısımdan oluşturulmuştur. Birincisi online referans sistemi ikincisi de bu sistemdeki referans sayfalarını okuyabilen bir okuyucudur. Sayfalara ise man page (manuel page) denir. Okuyucu programın man sayfasına man komutuyla ulaşabilir.

Bir programın man sayfasına eğer var ise aşağıdaki komutu kullanarak ulaşabilirsiniz.

root# man cd
root# man dpkg
root# man man

Bir sistemde yüklü olan bir aracın kendisine ait bir man sayfası var ise genellikle aşağıdaki dizinler altında tutulur. Sistemde yüklü olan araçların man sayfaları aşağıdaki dizinler altında tutulmaktadır.

/usr/share/man
/usr/local/share/man

Bir MAN Sayfasının Anotomisi

MAN sayfalarının yapıları birbirlerine çok benzer. Bu yapı ise bir gelenek haline gelmiştir.

Bir man sayfası en az aşağıdaki bölümlerden oluşmaktadır. Aynı zamanda eklemek istediğiniz ekstra başlık var ise ekleyebilirsiniz.

  • Name : İsim.
  • Synopsis : Özet.
  • Description : Açıklama.
  • Examples : Örnek.
  • Author : Yazar.
  • Reporting Bugs : Hata bildirimi.
  • Copyrıght : Telif hakkı.
  • See also : Bu komut ile ilgili diğer referanslar.

Yukarıdaki bölümlerin açıklamasına aşağıda değindim.

  • Name : Programın adı ve ne işe yaradığını belirten tek satırlık açıklama girilir.
  • Synopsis : Yazılımın nasıl kullanabileceği konusunda özet yazılır.
  • Description : Komutun işlevinin açıklaması yazılır.
  • Examples : Bu kısma, komut ile ilgili örnekler yazılır.
  • Author : Bu kısma ise, yazılımı yazan kişinin ismi yazılır.
  • Reporting Bugs : Eğer yazılım ile ilgili hata bildirimi yapılması istenir ise, buraya kullanıcıların ulaşabilmesi için gerekli iletişim bilgileri yazılır.
  • Copyrıght : Yazılımın telif hakkı açıklaması buraya yazılır.
  • See also : Bu komut ile ilgili diğer referanslar yazılır. Örneğin, buradan ulaşabildiğiniz gibi buradanda ulaşabilir veya burayada bakabilirsiniz gibi gibi.

^^

UNIX işletim sistemlerinde çoğunlukla man sayfaları ingilizce olarak yazılmaktadır, ama bu illaki ingilizce man sayfası yazmanız gerektiği anlamına gelmez, isterseniz türkçe yazabilirsiniz. İngilizce dünyada kullanılan ortak bir dildir. Eğer herkes tarafından programınızın okunmasını vb. istiyorsanız ingilizce yazmak şart. Temel olarak bir aracın man çıktısını aşağıda paylaştım. Farklı işletim sistemlerinde man sayfaları değişiklik göstermektedir.

NAME : <program name> - <one line description of program>
       <program ismi> - <bir satırlık uygulamanın  açıklaması>
 
SYNOPSIS : <program name> - <grammar for command line>
           <program ismi> - <komut satırı için dil bilgisi>
 
DESCRIPTON : <detailed description of what the program does> 
             <programın ne yaptığı ile ilgili detaylı açıklama>
 
OPTIONS : <a command line switch>
          <bir komut satırı anahtar>
 
SEE ALSO : <a list of related man pages>
           <man sayfası ile ilgili diğer listeler>
 
AUTHOR : <about the author>
         <yazar hakkında bilgi>
 
COPYRIGHT : <about the copyrıght>
            <telif hakkı, hakkında>

NOT : İsteğe göre uyarlanmış başlıklar yazarın insiyatifi ile eklenebilir.

  • OPTIONS
  • EXIT STATUS
  • ENVIRONMENT
  • FILES
  • REPORTING BUGS
  • HISTORY
  • COPYRIGHT
  • NOTES

 

Man Sayfası Yazımı

Bir man sayfasını herhangi bir editör açarak yazabilirsiniz. Man sayfası yazımı oldukça basittir. Aynı zamanda manedit ve gmanedit gibi man sayfası yazmak için yardımcı araçlar bulunmaktadır. Ben man sayfası yazımında gmanedit aracından yararlandım, sizde paket deposundan ( apt-get install gmanedit ) komutunu kullanarak indirebilirsiniz.

NOT : Bir program için yazılan man sayfası programın kullanabilirliğini arttıracaktır.

Aşağıdaki küçük örnek bir man sayfası paylaştım. Tüm bunları gmanedit metin düzenleyicisine yazın ve nuseradd.1 olarak kaydediniz.

.TH man 8  "19 December 2016"  "nuseradd man page"
 
.SH NAME
nuseradd \- create a new LDAP user
 
.SH SYNOPSIS
nuseradd [USERNAME]
 
.SH DESCRIPTION
nuseradd is high level shell program for adding users to LDAP server. On debian, administrators should usually use nuseradd.debian(8) instead.
.PP
When you add a LDAP user that so easiest way you can change the LDAP user’s password with ( nuseradd pass [username]
 
.SH OPTIONS
The nuseradd does not take any options. However, you can supply username.
 
.SH SEE ALSO
useradd(8), passwd(5), nuseradd.debian(8)
 
.SH BUGS
No known bugs.
 
.SH AUTHOR
İbrahim UÇAR - ( [email protected] )

Daha sonra nuseradd.1 olarak kaydettiğimiz dosyayı aşağıdaki komutu kullanarak sıkıştıralım. Hemen ardından ikinci komutu kullanarak /usr/share/man/man1 dizini içerisine sıkıştırılmış dosyayı kopyalıyoruz. Unutmayınız man dosyaları sistemde sıkıştırılmış olarak bulunurlar.

root# gzip -c nuseradd.1 > nuseradd.1.gz
root# cp -p nuseradd.1.gz /usr/share/man/man1/ ; cd /usr/share/man/man1  

hemen ardından /usr/share/man/man1 dizini içerisindeyken aşağıdaki komutu çalıştıralım.

[email protected]:/usr/share/man/man1#  mandb
 
Purging old database entries in /usr/share/man...
Processing manual pages under /usr/share/man...
Processing manual pages under /usr/share/man/gl...
Purging old database entries in /usr/share/man/pt_BR...
Processing manual pages under /usr/share/man/pt_BR...
Purging old database entries in /usr/share/man/zh_CN...
Processing manual pages under /usr/share/man/zh_CN...
Processing manual pages under /usr/local/man...
1 man subdirectories contained newer manual pages.
98 manual pages were added.
0 stray cats were added.
0 old database entries were purged.

Yukarıdaki komut sonrası komut satırında man nuseradd komutunu kullanarak hazırlamış olduğumuz man sayfasına erişebiliriz.

 

Man Sayfası Oluşturmak İçin Kullanılan Komutlar

Man sayfası oluşturma sırasında kullanılan komutlar ve ne oldukları aşağıdaki şekilde sıralanabilir. Birkaç örnek man sayfası yaptığınızda, neyin nereye koyulacağı, nasıl olacağı vb. komutları daha iyi anlayacaksınız.

  • .TH <isim> <bölüm> <zaman> : Bu komutla ana başlık yazılır. Komutun veya dosyasının ismi, hangi bölümde olduğu ve en son değişiklik yapıldığı zaman belirtilir.
  • .SH “<metin>” : Bu komut bölüm başlığı yapmak için kullanılır. Tüm başlıkları bu komut ile yazabilirsiniz. ( “AUTHOR”, “OPTIONS”, “NAME” vb.. )
  • .SS “<metin>” : Alt başlık hazırlar.
  • .P : Yeni paragraf başlatmak için kullanılır.
  • .HP : İç içe paragraf oluşturulmasında kullanılır.
  • .PP : Birden fazla paragraf yazmak için kullanılır.
  • .TP : <sütun> : Yazılacak metne kaç sütun yer ayırılacağını belirtir.
  • .\”  : Yorum satırlarını belirtmek için kullanılır. Bir satırı yorum olarak göstermek isterseniz kullanabilirsiniz.

 

Man Sayfası Vurgu Tipleri

Yazım sırasında vurgu yapılması farklı formatlarda yazılması için özel komutlar bulunmaktadır. Bu komutlar aşağıdaki gibidir.

.B    : Kalın yazar.

.BI   : Kalın ve yatık yazar.

.BR : Kalın ve roman font ile yazar.

.I     : Yatık yazar.

.IB   : Yatık ve kalın yazar.

.IR   : Yatık roman fontlu yazar.

.R    : Roman fontlu yazar.

.RI   : Roman fontlu ve yatık yazar.

.RB  : Roman fontlu kalın yazar.

.SB  : Küçük ve kalın yazar.

.SM  : Küçük yazar. ( Kısaltmalar için yararlıdır. )

 

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

Man sayfası yazarken, zaman zaman görüntüleyerek düzgün olup olmadığına bakmamızda fayda vardır.

Bir man sayfasını önizlemek isterseniz aşağıdaki komutu kullanabilirsiniz.

root# nroff -man nuseradd.1 | less  

Bir man sayfasını düz ön-biçimlendirilmiş metne dönüştürmek için aşağıdaki komut kullanılabilir.

root# nroff -man nuseradd.1 | col -b > xxxx.txt  

Postscript’e çevirmek için,

root# groff -man -Tps nuseradd.1 > mansayfa.ps  

Man sayfasını HTML’e çevirmek için ise aşağıdaki komutu kullanabilirsiniz.

root# man2html nuseradd.1
root# man2html nuseradd.1 > nuseradd.1.html  

 

Örnek Man Sayfası

Bir man sayfası hazırlarken aşağıdaki siteye bakabilirsiniz. Aşağıdaki sitede türkçe örnek bir man sayfası bulunmaktadır.

http://man.cx/mv(1)/tr

Bu dökümana aynı zamanda slideshare hesabımdanda ulaşabilirsiniz.

Tagged with: , , , , ,

Leave a Reply

Your email address will not be published. Required fields are marked *

*

2 + nine =

Archives

Tweets