man/text
man · Metin İşleme

$ pod2man

Bölüm 1 · Metin İşleme

POD verilerini biçimlendirilmiş `*roff` girdisine dönüştürür

Özet

pod2man [--center=dize] [--date=dize] [--errors=stil]
        [--fixed=yazı_tipi] [--fixedbold=yazı_tipi] [--fixeditalic=yazı_tipi]
        [--fixedbolditalic=yazı_tipi] [--name=ad] [--nourls]
        [--official] [--release=sürüm] [--section=bölüm_uzantısı]
        [--quotes=tırnaklar] [--lquote=tırnak] [--rquote=tırnak]
        [--stderr] [--utf8] [--verbose] [girdi [çıktı] ...]

pod2man --help

Açıklama

pod2man, POD kaynağından *roff girdisi üretmek için Pod::Man modülünü kullanan bir ön uçtur. Elde edilen *roff kodu normalde man(1) aracılığıyla nroff(1) kullanılarak terminalde görüntülenmeye veya troff(1) kullanılarak yazdırılmaya uygundur.

girdi, POD kaynağı olarak okunacak dosyadır; POD kodun içine gömülü de olabilir. girdi belirtilmezse varsayılan olarak STDIN kabul edilir. çıktı belirtilirse biçimlendirilmiş çıktının yazılacağı dosyadır. çıktı belirtilmezse biçimlendirilmiş çıktı STDOUT üzerine yazılır. Komut satırında birden fazla girdi ve çıktı dosyası çifti verilerek tek bir pod2man çağrısında birden fazla POD dosyası işlenebilir.

Kullanılacak üstbilgileri ve altbilgileri ayarlamak için --section, --release, --center, --date ve --official kullanılabilir. Belirtilmezlerse Pod::Man çeşitli varsayılan değerleri kabul eder. Ayrıntılar için aşağıdaki seçenek açıklamalarına veya Pod::Man sayfasına bakın.

pod2man, *roff biçimlendiricilerinizin CW adında sabit genişlikli bir yazı tipine sahip olduğunu varsayar. Sizdeki yazı tipi başka bir adla tanımlanmışsa, örneğin CR, bunu belirtmek için --fixed seçeneğini kullanın. Bu durum genellikle yalnızca yazdırma amaçlı troff çıktısı için önemlidir. Kalın, yatık ve kalın yatık sabit genişlikli çıktılar için kullanılan yazı tipleri de ayrıca ayarlanabilir.

Belirgin POD dönüştürmelerinin yanı sıra, Pod::Man ve dolayısıyla pod2man; func(), func(n) ifadelerini ve $foo ya da @bar gibi basit değişken referanslarını biçimlendirmeyi de üstlenir. Böylece bunlar için kod kaçışları kullanmak zorunda kalmazsınız. Ancak $fred{'stuff'} gibi karmaşık ifadelerin yine de kaçışlarla korunması gerekir. Ayrıca tire olarak kullanılmayan tireleri en-tireye dönüştürür, --bu şekildeki-- uzun tireleri düzgün em-tireye çevirir, çift tırnakları düzeltir ve troff'a özgü diğer birkaç ince ayarı yapar. Tam bilgi için Pod::Man sayfasına bakın.

Seçenekler

  • -c dize, --center=dize: .TH makrosu için ortalanmış sayfa üstbilgisini ayarlar. Varsayılan değer User Contributed Perl Documentationdır; ayrıca --official seçeneğine bakın.

  • -d dize, --date=dize: .TH makrosu için sol altbilgi dizesini ayarlar. Varsayılan olarak girdi dosyasının değiştirilme tarihi kullanılır. Girdi STDIN üzerinden geliyorsa geçerli tarih kullanılır ve UTC temel alınır; böylece çıktı, yerel saat diliminden bağımsız olarak yeniden üretilebilir.

  • --errors=stil: Hata işleme stilini ayarlar. die, herhangi bir POD biçimlendirme hatasında istisna fırlatılmasını söyler. stderr, hataların standart hataya raporlanmasını ancak istisna fırlatılmamasını söyler. pod, elde edilen belgede hataları özetleyen bir POD ERRORS bölümünün dahil edilmesini söyler. none, POD hatalarını mümkün olduğunca göz ardı eder. Varsayılan değer diedır.

  • --fixed=yazı_tipi: Aynen aktarılan metin ve kod için kullanılacak sabit genişlikli yazı tipini ayarlar. Varsayılan değer CWdir. Bazı sistemler bunun yerine CR isteyebilir. Yalnızca troff(1) çıktısı için önemlidir.

  • --fixedbold=yazı_tipi: Sabit genişlikli yazı tipinin kalın sürümünü ayarlar. Varsayılan değer CBdir. Yalnızca troff(1) çıktısı için önemlidir.

  • --fixeditalic=yazı_tipi: Sabit genişlikli yazı tipinin yatık sürümünü ayarlar. Bu adlandırma tam doğru olmayabilir, çünkü çoğu sabit genişlikli yazı tipinin yatık sürümü değil, yalnızca eğik (oblique) sürümü vardır. Varsayılan değer CIdır. Yalnızca troff(1) çıktısı için önemlidir.

  • --fixedbolditalic=yazı_tipi: Sabit genişlikli yazı tipinin kalın yatık, çoğu durumda aslında kalın eğik, sürümünü ayarlar. Pod::Man böyle bir yazı tipinin var olduğunu varsaymaz ve varsayılan olarak CB değerini kullanır. Bazı sistemlerde, örneğin Solaris'te, bu yazı tipi CX olarak bulunur. Yalnızca troff(1) çıktısı için önemlidir.

  • -h, --help: Kullanım bilgisini yazdırır.

  • -l, --lax: Artık kullanılmıyor. pod2man eskiden girdisinin kılavuz sayfası olarak geçerliliğini denetlerdi, ancak bu işlem artık podchecker(1) ile yapılmalıdır. Geriye dönük uyumluluk için kabul edilir; artık hiçbir şey yapmaz.

  • --lquote=tırnak: C<> metinlerini sarmak için kullanılan sol tırnak işaretini ayarlar.

  • --rquote=tırnak: C<> metinlerini sarmak için kullanılan sağ tırnak işaretini ayarlar.

--lquote ve --rquote, özel none değerine ayarlanabilir. Bu durumda C<> metninin ilgili tarafına tırnak işareti eklenmez; ancak troff çıktısı için yazı tipi yine de değiştirilir.

Ayrıca iki tırnağı aynı anda ayarlamak için kullanılabilen --quotes seçeneğine bakın. Hem --quotes hem de --lquote veya --rquote verilirse, --lquote ya da --rquote değeri --quotes değerini geçersiz kılar.

  • -n ad, --name=ad: .TH makrosu için kılavuz sayfasının adını ayarlar. Bu seçenek olmadan kılavuz adı, kılavuz bölümü 3 olmadığı sürece dönüştürülen dosyanın büyük harfe dönüştürülmüş temel adı olarak ayarlanır. Bölüm 3 ise yolun bir Perl modülü yolu olup olmadığına bakılır; örneğin .../lib/Pod/Man.pm yolu Pod::Man adına dönüştürülür. Bu seçenek verilirse otomatik ad belirleme geçersiz kılınır.

Komutlar için UNIX kılavuz sayfalarındaki gelenek, komutun kendisi büyük harfli olmasa bile kılavuz sayfası başlığının tamamen büyük harflerden oluşmasıdır. Bu kurala uymak zorunlu değildir.

Bu seçenek, aynı anda birden fazla POD dosyası dönüştürülürken genellikle kullanışlı değildir. Standart girdiden POD kaynağı dönüştürülürken bu seçenek sağlanmazsa ad STDIN olarak ayarlanır. Anlamlı bir kılavuz sayfası adı belirtmek için bu seçeneğin verilmesi kuvvetle önerilir.

  • --nourls: Normalde, URL'ye ve bağlantı metnine sahip L<> biçimlendirme kodları hem bağlantı metnini hem de URL'yi gösterecek şekilde biçimlendirilir.

Örneğin:

L<foo|http://example.com/>

şu şekilde biçimlendirilir:

foo <http://example.com/>

Bu bayrak verilirse, bağlantı metni sağlandığında URL gizlenir; bu örnek yalnızca foo olarak biçimlendirilir. URL'lerin özellikle önemli olmadığı durumlarda daha sade çıktı üretebilir.

  • -o, --official: --center seçeneği verilmemişse, bu sayfanın standart Perl sürümünün bir parçası olduğunu belirtmek için varsayılan üstbilgiyi ayarlar.

  • -q tırnaklar, --quotes=tırnaklar: C<> metnini sarmak için kullanılan tırnak işaretlerini ayarlar. Değer tek bir karakterden oluşuyorsa hem sol hem sağ tırnak işareti olarak kullanılır. Aksi takdirde değer ortadan ikiye bölünür; ilk yarısı sol tırnak, ikinci yarısı sağ tırnak olarak kullanılır.

tırnaklar özel none değerine de ayarlanabilir. Bu durumda C<> metninin etrafına tırnak işareti eklenmez; ancak troff çıktısı için yazı tipi yine de değiştirilir.

Sol ve sağ tırnakları bağımsız olarak ayarlamak için --lquote ve --rquote seçeneklerine de bakın. Hem --quotes hem de diğer seçeneklerden biri ayarlanmışsa, --lquote veya --rquote seçeneği --quotes seçeneğini geçersiz kılar.

  • -r sürüm, --release=sürüm: .TH makrosu için ortalanmış altbilgiyi ayarlar. Varsayılan olarak bu, pod2man'i çalıştırdığınız Perl sürümüne ayarlanır. Bunu boş bir dizeye ayarlamak, bazı *roff uygulamalarının sistem varsayılan değerini kullanmasına neden olur.

Bazı sistem an makro setleri, ortalanmış altbilginin bir değiştirilme tarihi olacağını varsayar ve başına Last modified: gibi bir metin ekler. Hedef sisteminizde durum buysa, --release seçeneğini son değiştirilme tarihine ve --date seçeneğini sürüm numarasına ayarlamak isteyebilirsiniz.

  • -s dize, --section=dize: .TH makrosu için bölümü ayarlar. Standart bölüm numaralandırma kuralı; kullanıcı komutları için 1, sistem çağrıları için 2, fonksiyonlar için 3, aygıtlar için 4, dosya biçimleri için 5, oyunlar için 6, çeşitli bilgiler için 7 ve yönetici komutları için 8 kullanmaktır. Ancak farklı sistemlerde değişiklikler vardır. Örneğin Solaris dosya biçimleri için 4, çeşitli bilgiler için 5 ve aygıtlar için 7 kullanır. Bazı sistemler 8 yerine 1m veya ikisinin bir karışımını kullanır. Güvenilir biçimde tutarlı olan bölüm numaraları neredeyse yalnızca 1, 2 ve 3'tür.

Varsayılan olarak dosya .pm ile bitmiyorsa bölüm 1 kullanılır; dosya .pm ile bitiyorsa bölüm 3 seçilir.

  • --stderr: Varsayılan olarak POD girdisinde herhangi bir hata tespit edilirse pod2man sonlanır. --stderr seçeneği verilir ve --errors bayrağı bulunmazsa, hatalar standart hataya gönderilir ancak pod2man işlemi iptal etmez. Bu, --errors=stderr seçeneğine eşdeğerdir ve geriye dönük uyumluluk için desteklenir.

  • -u, --utf8: Varsayılan olarak pod2man, mümkün olduğunca çok sayıda farklı *roff uygulamasıyla çalışması için oldukça muhafazakar *roff çıktısı üretir. Birçok *roff uygulaması ASCII dışı karakterleri işleyemez; bu nedenle tüm ASCII dışı karakterler ya aksanlı bir karakter üretmeye çalışan *roff kaçış dizisine ya da X karakterine dönüştürülür.

Bu seçenek, bunun yerine tam anlamıyla UTF-8 karakterleri çıktı olarak vermeyi söyler. *roff uygulamanız bunu işleyebiliyorsa bu en iyi çıktı biçimidir ve ASCII dışı karakterler içeren belgelerin bozulmasını önler. Ancak tam anlamıyla UTF-8 karakterleri içeren *roff kaynak kodlarının birçok uygulama tarafından desteklenmediğini, hatta segmentasyon hatası ve başka istenmeyen davranışlara yol açabileceğini unutmayın.

Bu seçeneği kullanırken, POD kaynağınızın girdi kodlamasının US-ASCII olmadığı sürece düzgün biçimde bildirilmesi gerekir. Pod::Simple kodlamayı tahmin etmeye çalışır ve Latin-1 veya UTF-8 ise başarılı olabilir, ancak bir uyarı verir; bu da varsayılan olarak pod2man'in başarısız olmasıyla sonuçlanır. Kodlamayı bildirmek için =encoding komutunu kullanın. Daha fazla bilgi için perlpod(1) sayfasına bakın.

  • -v, --verbose: Üretilmekte olan her çıktı dosyasının adını yazdırır.

Çıkış Durumu

İşlenen tüm belgeler çıktı ürettiği sürece, bu çıktı hatalar içerse bile pod2man 0 durum koduyla çıkar. Buna --errors=pod ile üretilen bir POD ERRORS bölümü de dahildir.

İşlenen belgelerden herhangi biri bir çıktı belgesiyle sonuçlanmazsa pod2man 1 durum koduyla çıkar.

İşlenen bir POD belgesinde söz dizimi hataları varsa ve hata işleme stili varsayılan die olarak ayarlanmışsa, pod2man hemen iptal edilir ve 255 çıkış durumuyla sonlanır.

Tanılama

pod2man hatalarla başarısız olursa, bu hataların ne anlama gelebileceği hakkında bilgi için Pod::Man ve Pod::Simple sayfalarına bakın.

Örnekler

Bir program dosyasından kılavuz sayfası üretmek:

pod2man program > program.1

Bir Perl modülünü bölüm 3 kılavuz sayfasına dönüştürmek:

pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3

Bir POD dosyasını bölüm 7 kılavuz sayfası olarak üretmek:

pod2man --section=7 note.pod > note.7

Sürekli olarak çok sayıda kılavuz sayfasını yazdırmak istiyorsanız, en azından man(7) sayfasının bazı sürümlerinde kesintisiz sayfa numaralandırması ve tek/çift sayfa düzeni ayarlamak için C ve D yazmaçlarını (register) ayarlamak isteyebilirsiniz:

troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...

STDERR üzerinde dizin girişleri almak için F yazmacını açın:

troff -man -rF1 perl.1

Dizin oluşturma işlemi; her ana sayfa, bölüm, alt bölüm, öğe ve her türlü X<> yönergesi için yalnızca .tm aracılığıyla mesajlar çıktı olarak verir. Daha fazla ayrıntı için Pod::Man sayfasına bakın.

Hatalar

Bu belgenin büyük bir kısmı Pod::Man sayfasından alınmıştır.

Yazar

Russ Allbery <rra@cpan.org>. Program büyük ölçüde Larry Wall ve Tom Christiansen tarafından yazılan özgün pod2man programına dayanmaktadır.

Telif Hakkı ve Lisans

Telif Hakkı 1999-2001, 2004, 2006, 2008, 2010, 2012-2019 Russ Allbery <rra@cpan.org>

Bu program özgür bir yazılımdır; Perl'ün kendi koşulları altında yeniden dağıtabilir ve/veya değiştirebilirsiniz.

Ayrıca Bakınız

Pod::Man, Pod::Simple, man(1), nroff(1), perlpod(1), podchecker(1), perlpodstyle(1), troff(1), man(7)

Sisteminizde an makro setini belgeleyen kılavuz sayfası, man(7) yerine man(5) olabilir.

Bu betiğin güncel sürümü her zaman https://www.eyrie.org/~eagle/software/podlators/ adresinden edinilebilir. Ayrıca 5.6.0 sürümünden itibaren Perl çekirdek dağıtımının bir parçasıdır.