Linux'ta bir adam Sayfası Nasıl Oluşturulur

Yeni Linux programınızın profesyonel görünmesini mi istiyorsunuz? Bir man sayfası verin. Size bunu yapmanın en kolay ve en hızlı yolunu göstereceğiz.

adam sayfaları

Eski Unix şakasında bir gerçek payı var, “bilmeniz gereken tek komut man ”. man sayfaları zengin bilgi içerir ve bir komut hakkında bilgi edinmek istediğinizde ilk başvuracağınız yer bunlar olmalıdır.

Yazdığınız bir yardımcı program veya komut için bir man sayfası sağlamak, onu kullanışlı bir kod parçasından tam biçimli bir Linux paketine yükseltir. man , Linux için yazılmış bir program için bir kılavuz sayfasının sağlanmasını bekler. Yerel olarak Linux'u destekliyorsanız, programınızın ciddiye alınmasını istiyorsanız bir man sayfası zorunludur.

Tarihsel olarak man sayfaları bir dizi biçimlendirme makrosu kullanılarak yazılmıştır. Bir sayfayı açması için man çağırdığınızda, dosyadaki makrolara göre dosyayı okumak ve biçimlendirilmiş çıktı oluşturmak için groff çağırır. Çıktı, less içine aktarılır ve ardından sizin için görüntülenir.

Sık sık kılavuz sayfaları oluşturmadığınız sürece, bir tane yazıp makroları man olarak eklemek zor bir iştir. Doğru şekilde ayrıştırılan ve doğru görünen bir man sayfası oluşturma eylemi, komutunuzun kısa, ancak kapsamlı bir açıklamasını sağlama amacınızı aşabilir.

Belirsiz bir makro kümesiyle savaşmamalı, içeriğinize odaklanmalısınız.

İLGİLİ: Linux'un adamı Komutu Nasıl Kullanılır: Gizli Sırlar ve Temel Bilgiler

kurtarmaya pandoc

pandoc programı, işaretleme dosyalarını okur ve man sayfasınınki de dahil olmak üzere yaklaşık 40 farklı biçimlendirme dilinde ve belge biçiminde yenilerini oluşturur. Hiyerogliflerle boğuşmak zorunda man için kılavuz sayfası yazma sürecini tamamen değiştirir.

Başlamak için pandoc Ubuntu'ya şu komutla yükleyebilirsiniz:

 sudo apt-get kurulum pandoc 

Fedora'da ihtiyacınız olan komut şudur:

 sudo dnf pandoc'u kurun 

Manjaro'da şunu yazın:

 sudo pacman -Syu pandoc 

İLGİLİ: Linux Komut Satırında Dosyaları Dönüştürmek için pandoc Nasıl Kullanılır

Bir adam sayfasının bölümleri

man sayfaları, standart bir adlandırma kuralına uyan bölümler içerir. man sayfanızın ihtiyaç duyduğu bölümler, tanımladığınız komutun karmaşıklığına göre belirlenir.

En azından, çoğu kılavuz sayfası şu bölümleri içerir:

• Ad : Komutun adı ve işlevini açıklayan özlü bir tek satır.
• Özet : Birinin programı başlatmak için kullanabileceği çağrıların kısa bir açıklaması. Bunlar, kabul edilen komut satırı parametrelerinin türlerini gösterir.
• Açıklama : Komut veya işlevin açıklaması.
• Seçenekler : Komut satırı seçeneklerinin ve yaptıklarının listesi.
• Örnekler : Bazı yaygın kullanım örnekleri.
• Çıkış Değerleri : Olası dönüş kodları ve anlamları.
• Hatalar : Bilinen hataların ve tuhaflıkların listesi. Bazen buna, proje için sorun izleyiciye bir bağlantı eklenir (veya bu bağlantıyla değiştirilir).
• Yazar : Komutu yazan kişi veya kişiler.
• Telif hakkı : Telif hakkı mesajınız. Bunlar genellikle programın yayınlandığı lisans türünü de içerir.

Daha karmaşık kılavuz sayfalarından bazılarına bakarsanız, başka birçok bölüm man da görürsünüz. Örneğin, man man deneyin. Yine de hepsini dahil etmek zorunda değilsiniz - sadece gerçekten ihtiyacınız olanları. man sayfaları kelimelerin yeri değildir.

Oldukça sık göreceğiniz diğer bazı bölümler şunlardır:

• Ayrıca Bakınız : Konuyla ilgili diğer komutlar, bazılarının yararlı veya alakalı bulacağı.
• Dosyalar : Pakette bulunan dosyaların listesi.
• Uyarılar : Bilinmesi veya dikkat edilmesi gereken diğer noktalar.
• Geçmiş : Komut için bir değişiklik geçmişi.

Kılavuzun Bölümleri

Linux kılavuzu, daha sonra şu numaralandırılmış bölümlere ayrılan tüm man sayfalarından oluşur:

1. Yürütülebilir programlar: Veya kabuk komutları.
2. Sistem çağrıları: Çekirdek tarafından sağlanan işlevler.
3. Kitaplık çağrıları: Program kitaplıkları içindeki işlevler.
4. Özel dosyalar.
5. Dosya biçimleri ve kuralları: Örneğin, “/etc/passwd”.
6. Oyunlar.
7. Çeşitli: groff gibi makro paketleri ve kuralları.
8. Sistem yönetim komutları: Genellikle kök için ayrılmıştır.
9. Çekirdek rutinleri: Genellikle varsayılan olarak yüklenmez.

Her man sayfası, hangi bölüme ait olduğunu belirtmeli ve daha sonra göreceğimiz gibi, o bölüm için uygun yerde saklanmalıdır. man ve yardımcı programlar için kılavuz sayfaları birinci bölüme aittir.

Bir adam Sayfasının Formatı

groff makro formatının görsel olarak ayrıştırılması kolay değildir. Buna karşılık, markdown bir esinti.

Aşağıda groff bir man sayfası var.

Aynı sayfa aşağıda markdown'da gösterilmektedir.

Ön Konu

İlk üç satır ön madde adı verilen bir şey oluşturur. Bunların tümü bir yüzde işaretiyle ( % ) başlamalı, başında boşluk bulunmamalı, ardından bir boşluk bırakılmalı ve ardından:

• İlk satır: Komutun adını, ardından parantez içindeki manuel bölümünü boşluksuz içerir. Ad, man sayfası başlığının sol ve sağ bölümleri olur. Kural olarak, komut adı büyük harfle yazılır, ancak olmayan pek çok şey bulacaksınız. Komut adını ve manuel bölüm numarasını izleyen her şey altbilginin sol bölümü olur. Yazılım sürüm numarası için bunu kullanmak uygundur.
• İkinci satır: Yazar(lar)ın ad(lar)ı. Bunlar, man sayfasının otomatik olarak oluşturulan yazarlar bölümünde görüntülenir. "Yazarlar" bölümü eklemeniz gerekmez; buraya en az bir ad eklemeniz yeterlidir.
• Üçüncü satır: Altbilginin de orta kısmı haline gelen tarih.

İsim

Bölümler, markdown'da bir başlığı gösteren işaretleme olan bir sayı işaretiyle ( # ) başlayan çizgilerle belirtilir. Sayı işareti ( #) , satırdaki ilk karakter ve ardından bir boşluk olmalıdır.

Ad bölümü, komutun adını, bir boşluk, bir kısa çizgi ( - ), bir boşluk ve ardından komutun ne yaptığına dair çok kısa bir açıklama içeren hızlı bir tek satırlık içerir.

özet

Özet, komut satırının alabileceği farklı biçimleri içerir. Bu komut, bir arama düzenini veya bir komut satırı seçeneğini kabul edebilir. Komut adının her iki yanındaki iki yıldız işareti ( ** ), adın man sayfasında kalın olarak görüntüleneceği anlamına gelir. Bazı metinlerin her iki tarafında tek bir yıldız işareti ( * ), kılavuz sayfasının altı man olarak görüntülenmesine neden olur.

Varsayılan olarak, bir satır sonunu boş bir satır izler. Boş bir satır olmadan tam bir kesmeyi zorlamak için, sonunda ters eğik çizgi ( \ ) kullanabilirsiniz.

Açıklama

Açıklama, komutun veya programın ne yaptığını açıklar. Önemli detayları kısa ve öz bir şekilde kapsamalıdır. Unutmayın, bir kullanıcı kılavuzu yazmıyorsunuz.

Bir satırın başında iki sayı işareti ( ## ) kullanmak, ikinci düzey bir başlık oluşturur. Açıklamanızı daha küçük parçalara ayırmak için bunları kullanabilirsiniz.

Seçenekler

Seçenekler bölümü, komutla kullanılabilecek tüm komut satırı seçeneklerinin açıklamasını içerir. Kural olarak, bunlar kalın olarak gösterilir, bu nedenle onlardan önce ve sonra iki yıldız işareti ( ** ) ekleyin. Seçeneklerin metin açıklamasını bir sonraki satıra ekleyin ve iki nokta üst üste ( : ) ve ardından bir boşluk ile başlayın.

Açıklama yeterince kısaysa, man bunu komut satırı seçeneğiyle aynı satırda görüntüler. Çok uzunsa, komut satırı seçeneğinin altındaki satırda başlayan girintili bir paragraf olarak görüntülenir.

Örnekler

Örnekler bölümü, farklı komut satırı biçimlerinin bir seçimini içerir. Seçenekler bölümünde yaptığımız gibi açıklama satırlarına iki nokta üst üste ( : ) ile başladığımızı unutmayın.

Çıkış Değerleri

Bu bölüm, komutunuzun çağıran sürece geri gönderdiği dönüş değerlerini listeler. Bu, komut satırından çağırdıysanız kabuk veya bir kabuk komut dosyasından başlattıysanız bir komut dosyası olabilir. Bu bölümde de açıklama satırlarına iki nokta üst üste ( : ) ile başlıyoruz.

Hatalar

Hatalar bölümü, insanların bilmesi gereken bilinen hataları, ele geçirmeleri veya tuhaflıkları listeler. Açık kaynaklı projelerde, hataların durumunu kontrol etmek veya yenilerini bildirmek için buraya projenin sorun izleyicisine bir bağlantı eklemek yaygındır.

Telif hakkı

Telif hakkı bölümü, telif hakkı beyanınızı ve genellikle yazılımın altında yayınlandığı lisans türünün açıklamasını içerir.

Verimli Bir İş Akışı

man sayfanızı favori düzenleyicinizde düzenleyebilirsiniz. Sözdizimi vurgulamayı destekleyenlerin çoğu, işaretlemenin farkında olacak ve metni başlıkları vurgulamak için renklendirecek ve kalınlaştıracak ve altını çizecektir. Olabildiğince harika, ancak pudingin gerçek kanıtı man işlenmiş bir kılavuz sayfasına bakmıyorsunuz.

Markdown dosyanızı içeren dizinde bir terminal penceresi açın. Düzenleyicinizde açıkken, dosyanızı düzenli olarak sabit sürücünüze kaydedin. Bunu her yaptığınızda, terminal penceresinde aşağıdaki komutu çalıştırabilirsiniz:

 pandoc ms.1.md -s -t adam | /usr/bin/man -l - 

Bu komutu kullandıktan sonra, tekrarlamak için Yukarı oka basabilir ve ardından Enter'a basabilirsiniz.

Bu komut ayrıca pandoc dosyasında pandoc'u da çağırır (burada buna “ms.1.md” denir):

• -s (bağımsız) seçeneği, yalnızca man biçimindeki bazı metinler yerine, yukarıdan aşağıya tam bir man sayfası oluşturur.
• “Man” operatörlü -t (çıkış tipi) seçeneği, pandoc çıktısını man formatında oluşturmasını söyler. pandoc çıktısını bir dosyaya göndermesini söylemedik, bu yüzden stdout gönderilecek.

Ayrıca bu çıktıyı -l (yerel dosya) seçeneğiyle man aktarıyoruz. man , man sayfasını arayan man veritabanında arama yapmamasını söyler. Bunun yerine, adlandırılmış dosyayı açmalıdır. Dosya adı - ise, man girdisini stdin alacaktır.

Bunun özeti, editörünüzden kaydedebilir ve terminal penceresinde çalışıyorsa man kapatmak için Q tuşuna basabilirsiniz. Ardından, man sayfanızın işlenmiş bir sürümünü görmek için Yukarı oka ve ardından Enter'a basabilirsiniz man .

İLGİLİ: Linux'ta stdin, stdout ve stderr nedir?

Erkek Sayfanızı Oluşturmak

man sayfanızı tamamladıktan sonra, bunun son bir sürümünü oluşturmanız ve ardından sisteminize yüklemeniz gerekir. Aşağıdaki komut, pandoc “ man ” adında bir kılavuz sayfası oluşturmasını söyler:

 pandoc ms.1.md -s -t adam -o ms.1 

Bu, kılavuz sayfasını açıkladığı man sonra adlandırma ve kılavuz bölüm numarasını bir dosya uzantısıymış gibi ekleme kuralına uyar.

Bu, yeni kılavuz sayfamız man bir “ms.1” dosyası oluşturur. Nereye koyacağız? Bu komut bize man sayfalarını nerede aradığını man :

 yol 

Sonuçlar bize aşağıdaki bilgileri verir:

• /usr/share/man: man sayfalarının standart kitaplığının konumu. Bu kitaplığa sayfa eklemiyoruz.
• /usr/local/share/man: Bu sembolik bağlantı “/usr/local/man” öğesini gösterir.
• /usr/local/man: Burası yeni man sayfamızı yerleştirmemiz gereken yer.

Farklı kılavuz bölümlerinin kendi dizinlerinde bulunduğunu unutmayın: man1, man2, man3, vb. Bölümün dizini yoksa, onu oluşturmamız gerekir.

Bunu yapmak için aşağıdakileri yazıyoruz:

 sudo mkdir /usr/local/man/man1

Ardından “ms.1” dosyasını doğru dizine kopyalarız:

 sudo cp ms.1 /usr/local/man/man1

man , man sayfalarının sıkıştırılmasını bekliyor, bu yüzden sıkıştırmak için gzip kullanacağız:

 sudo gzip /usr/local/man/man1/ms.1

man yeni dosyayı veritabanına eklemesini sağlamak için aşağıdakini yazın:

 sudo mandb 

Bu kadar! Artık yeni man sayfamızı diğerleriyle aynı şekilde yazarak çağırabiliriz:

 adam ms 

Yeni man sayfamız bulundu ve görüntülendi.

Uygun yerlerde kalın, altı çizili ve girintili metin bulunan diğer herhangi bir man sayfasına benziyor.

Tanımladıkları seçeneğin yanına uyan açıklama satırları aynı satırda görünür. Sığamayacak kadar uzun çizgiler, tanımladıkları seçeneğin altında görünür.

Ayrıca otomatik olarak bir "Yazarlar" bölümü oluşturduk. Alt bilgi ayrıca, ön maddede tanımlandığı gibi yazılım sürüm numarasını, tarihini ve komut adını içerir.

İsterseniz . . .

pandoc man oluşturduktan sonra, dosyayı kılavuz sayfası dizinine man önce doğrudan groff makro biçiminde düzenleyebilir ve gzip edebilirsiniz.