ATABB

Zero Relax

Linuxdoc-SGML-NASIL
Gorkem Cetin, e077245@orca.cc.metu.edu.tr
v1.0, 25.1.1997
Orjinali : Matt Welsh

Bu dokumanin amaci kullanicilara SGML-tabanli bir yazi formati olan ve
LaTeX, duz metin ve HTML cikti alabilmeyi saglayan linux-doc yapisi
hakkinda bilgi vermektedir.


Giris

Linuxdoc-sgml , genel kullanimdan cok Linux HOWTO, FAQ ve LDP (Linux
Documentation Project) belgelerinin olusturulmasina yonelik gelistirilmis
bir yazim formatidir. Bu yuzden atasi olan DTD formatindan bicimsel olarak
uzaklasarak pek cok ozelligi kirpilmistir. linuxdoc-sgml 'nin amaci
cesitli kullanicilar tarafindan hazirlanan linux belgelerinin tek yapida
ve tek gorunuste formatlanabilmesidir.

Simdiye kadar Linux dokumanlari hep ASCII metin dosyasi yapisinda
hazirlaniyordu. Bu sistemin en buyuk ozelliklerinden biri de tek kaynak
dosya hazirlanarak diger formatlarin bu dosya yardimiyla
cevirilebilmesidir. SGML'nin tanidigi dosya yapilarindan biri olan LaTex,
hos gorunumlu yazici ciktilarinin alinmasina izin verir. Kullanici
acisindan getirilen en onemli yenilik, birkac komutun yardimiyla ve
kolayca birden fazla dosya yapisinin halihazirda uretilebilmesidir.

Bu dokuman linuxdoc-sgml DTD kullanilarak hazirlanmistir. SGML
dosyalarinin hazirlanabilmesi icin en gerekli temel komutlari anlatir.


SGML

SGML (Standard Generalized Markup Language) sistemi, bir formattan
digerine ceviri yapabilmek icin ozellikle hazirlanmistir. SGML altinda
dokumanin yapisi, tipi belirtilebilir. Bunun icin DTD (Document Type
Definition) kullanilir. Bir DTD cesidi, Linux HOWTO ve diger dokumanlarin
hazirlandigi linuxdoc-sgml yapisi, bir digeri de QWERTZ'dir. SGML
standardi, DTD yapisinin kitap, makale ve diger genel dokuman tiplerini
hazirlamasina izin verir.


Dokumanlarin hazirlanmasi

DTD yapisinin ne oldugunu ve nasil calistigini bilmenize gerek yoktur.
DTD, hazirladiginiz bir dokumanin nasil formatlanmasi gerektigini veya
yazici ciktisinin nasil gorundugu ile ilgilenmez. Sadece dokumani
olusturan ara bolumlerin veya basliklarin varligiyla ilgilenir.

SGML, kaynak dokumanini diger bir formata (ornegin LaTeX veya nroff)
cevirmek icin sirayla sgmls ve sgmlsasp programlarini kullanir. sgmlsasp
gorevini yapinca orjinal SGML dosyasina es bir LaTeX dosyaniz olacaktir.

__________________

Zero Relax

Kurulumdan once

linuxdoc-sgml.tar.gz dosyasi: SGML dokumani yazmak ve bunlari LaTeX, nroff
ve HTML dosya yapilarina cevirmek icin tum ihtiyaclari karsilayan yazilim
arsivine sahiptir. Bu dosyaya ek olarak asagidaki paketlerin biri veya her
ikisinin de sistemde kurulmus olmasi gerekir.

groff: 1.08 veya 1.09 surumu gereklidir. linuxdoc-sgml.tar.gz daha eski
surumlerle birlikte calismayacaktir. groff'un ELF calistirilabilir dosyasi
ftp://ftp.metu.edu.tr/pub/linux/sunsite/utils/text adresinden temin
edilebilir.

TeX ve LaTeX: Hemen her yerde bulunabilen bu dosyalarin kurulumu sorun
yaratmayacaktir. Bu paket, SGML dosyasini LaTeX formatina cevirmek
isterseniz gerekli olur. ftp://ftp.metu.edu.tr/pub/linux/sunsite/apps/tex
adresinden temin edilebilir.


Kuruluma giris

linuxdoc-sgml paketinin sisteme kurulmasi icin sirayla su islemlerin
yapilmasi gereklidir:

Once, linuxdoc-sgml.tar.gz dosyasini istediginiz bir yere acin.
Bulundugunuz dizin altinda SGML dosyalarinin tutuldugu linuxdoc-sgml
isminde baska bir dizin daha acilacaktir. Buradaki dosyalari baska bir
yere hareket ettirmediginiz surece dosyayi nereye actiginiz onemli
degildir.

sgmls ve diger programlari derleyin. Bunun icin dizini altinda, su komutlari
sirayla calistirmalisiniz :

$ make config.h
$ make
$ make install
$ make install.man

Derleme isleminden sonra sgmls, sgmlsasp, and rast dosyalari dizini altina
kopyalanacaklardir. Paketten cikan format, qroff, ve qtex yardimci
programlarini PATH degiskeninin gosterdigi bir dizine kopyalayin veya
bunlarin dizinini PATH degiskenine ekleyin.

Eger yukaridaki komutlarin isleyisinde sorun cikarsa, sgmls-1.1 dizini
altindaki Makefile dosyasina goz atin. Ozellikle vfork sistem
fonksiyonunun bulundugu satirda, eger sisteminiz vfork yerine fork
destekliyorsa problem olabilir.

__________________

Zero Relax

Gereken tum man dosyalari da linuxdoc-sgml/man dizini altina
yerlestirilecektir. Bu dosyalari /usr/man dizinine kopyalayabilirsiniz.

linuxdoc-sgml/bin dizinindeki format, qroff, ve qtex dosyalarinda bulunan
LINUXDOC kabuk degiskeninin degerini, linuxdoc-sgml dizinini gosterecek
sekilde degistirin.

html-fix dizini altinda, su komutlari calistirin:

$ make
$ make install

Bu iki make komutu, HTML cevirisi icin gerekli olan fixref ve html2html
dosyalarini yaratip bin dizini altina kopyalayacaktir.

Kurulum hatasiz tamamlanmis ise linuxdoc sistemini kullanabilecek duruma
gelmissiniz demektir.


Deneme :-)

format ve qtex programlari bir SGML dosyasini alir ve istenilen
formata cevirir. qroff ise nroff yardimiyla ciktiyi isler.

Ornek olarak elimizde deneme.sgml isimli bir dosya olsun. Bunu once LaTeX,
sonra da dvips yardimiyla PostScript'e cevirmek icin :

$ format -T latex deneme.sgml | qtex > dnm.ps

komutu kullanilabilir. Veya, qtex'in -d opsiyonu ile DVI
dosyasini yaratabilirsiniz:

$ format -T latex deneme | qtex -d > dnm.dvi

Duz metin dosya ciktisi almak icin :

$ format -T ascii deneme > dnm.txt

veya

$ format -T nroff deneme | qroff > dnm.txt

komutlari kullanilabilir. HTML yapisinda dosya elde etmek icin de

$ format -T htmlx deneme.sgml > dnm.html

__________________

Zero Relax

komutunu kullanabilirsiniz. Bu komutun ardindan dosyadaki her bolum icin
deneme.html, deneme-1.html, deneme-2.html gibi dosyalar
olusacaktir. WWW programini deneme.html dosyasini calistiracak sekilde
baslatin.

Sadece olusabilecek hatalari gormek icin su komuttan yararlanin:

$ format -T nroff deneme > /dev/null


linuxdoc-sgml ile birkac ornek

linuxdoc DTD yardimiyla dosya hazirlanmasi gayet kolaydir. SGML ornegi
olmasi acisindan example.sgml dosyasina gozatin. Bu dosyayi bastirirsaniz
elinizin altinda her an bir kaynak bulunacaktir.


Temel komutlar (belirtecler)

Bir belitrtec, <..> harf dizeleri ile baslayip biten SGML komutlaridir.
Her belirtec, baslik, paragraf, liste veya bunlara benzer SGML
elemanlarina isaret eder.

Ornek olarak, koyu yaziyuzleri olusturabilmek icin

<bf> .... </bf>

kullanilir. <bf> , koyu stile gecis icin, </bf> koyu stilden cikis icin
kullanilir. Daha kisa bir formada yazmak isterseniz, su belirteci
yazin:

<bf/bu satir, koyu basilacaktir.../

Koyu yazilmasi istenen tum kelimeler bolu isareti arasina alinmistir. Bu
formatin kullanilmasi durumunda UNIX dosya isimlerindeki gibi icinde bolu
isareti olan kelimelerden sakinmalidir.

Bazi durumlarda, belirtecin sonunu gosteren kapama belirteci kullanilmayabilir.
Basligi belirtmek icin kapama belirtecinine (</>) gerek yoktur.
Genel olarak bu gibi kucuk detaylarla ilgilenmeyin, example.sgml dosyasindaki
gibi bir yapiyi baz alarak her turlu dokumani rahatlikla yazabilirsiniz.


Ozel karakterler

Kucuktur (<) ve buyuktur (>) isaretlerinin yanisira birkac ozel karakter
SGML dosyasindaki belirtecler yapilarinda kullanildiklarindan dosya icinde
ozel olarak belirtilmeleri gerekir. Bir satirda ornegindeki gibi ozel
isaret kullanabilmek icin &lt yazmalisiniz.

Genel olarak, & karakteri ile baslayan hersey makro kapsamina
girer. Bir makro, ozel karakterleri gostermek icin kullanilir.

__________________

Zero Relax

Yazim formatini korumak

Yazim formatini (kullanilan TAB, bosluklar) aynen korumak ve metnin yazildigi
gibi yazicidan cikmasini saglamak icin belirteci kullanilir.
Asagida bu belirtecin kullanimina bir ornek verilmistir:

<verb>
verb belirtecinin kullanimina ornek...
</verb>

code belirteci verb belirteci ile hemen hemen ayni ozellikleri
tasir, tek farki arada kalan metnin ust ve altina yatay cizgi ceker.


Genel dokuman yapisi

Detaylara girmeden once bir dokumanin nasil baslamasi gerektigini
gorelim. doc dizini altinda yeralan example.sgml ornegi
baslangicta fikir vermesi acisindan idealdir.


Giris

Burada baslik ve dokuman tipi bilgisi verilir. Ornek bir Linux-HOWTO
dokumani asagidaki sekilde baslayabilir.

<tscreen><verb>
<!doctype linuxdoc system>

<article>

<title>Linux Karniyarik-NASIL</title>
<author> Gorkem Cetin</author>, <tt/e077245@orca.cc.metu.edu.tr/
<date> Surum1.0, 26.1.1997 </date>

<abstract>
Bu makalede dunyaca taninan Turk mutfaginin bol proteinli, fosfat baglayici
ve besleyici yemegi olan Karniyarik'in Linux yardimiyla pisirilmesi
anlatilacaktir.
</abstract>

<toc>
</verb></tscreen>

Yazilacak olan dokumanlarin giris sirasi yukaridaki gibi olmalidir. Ilk
satir, SGML sgmlsasp programina bu dosyanin linuxdoc DTD yapisinda
oldugunu soyler. <doctype> belirteci ise dosyanin `article'
(kisa yazi) stilinde yazilacaginin bilgisini verir. `article' yerine
`book' (kitap) veya `report' (rapor) da yazarak denemeler yapabilirsiniz.

Surum numarasi ve dokumanin yazim ve son guncellenme tarihi (date), baslik
(title) ve yazar (author) bilgileri de yaziya baslamadan once
verilir.

abstract yardimiyla dokumanin en ustune bilgilendirici birkac satir
koyabilir, toc ile icindekiler kismini olusturabilirsiniz.

Baslik ve paragraflar

__________________

Zero Relax

Linuxdoc-sgml ile hiyerarsik sirada toplam bes ayri baslik tanimlanabilir.
Asagida yeralan belirtecler ile basliklarinizi kontrol altina alabilirsiniz:

sect : Birinci baslik (1, 2 gibi)
sect1: Ikinci baslik (1.1, 1.2 gibi)
sect2: Ucuncu baslik (1.1.4 , 2.1.2 gibi)
sect3: Dorduncu baslik
sect4: Besinci baslik


sect (veya sect1, sect2.. ) belirtecinin ardindan basligin ismi
yazilir. Baslik girisinden sonra o baslik altinda gorunmesi istenen
paragraflar yazilir. Bir defalik olmak uzere, her basligin altindaki
paragraf belirteci ile baslar:

<tscreen><verb>
<sect>Giris

<tt/linuxdoc-sgml/ , genel kullanimdan cok Linux HOWTO, FAQ ve LDP
(Linux Documentation Project) belgelerinin olusturulmasina yonelik
gelistirilmis bir yazim formatidir.
....
</verb> </screen>

Biten ilk paragrafin ardindan yeni bir paragrafa baslanabilir.
<p> belirtecini her paragraf basinda kullanmaya gerek yoktur.

<tscreen><verb>
Bu da ikinci paragraf
</verb></tscreen>


Dokumanin bitirilmesi

Dokumanin sonunda, bittigini belirtmek icin sunlari yazmalisiniz:

</article>


URL kullanimi

WWW altinda kullanilan html dosyalarinin en onemli ozelliklerinden biri
URL baglantilaridir. linuxdoc-sgml ile hazirlanan dosyalari html'e
cevirirken URL girislerine (ftp, gopher, www, mail gibi) baglanti verilmesi
saglanabilir. Ornegin:

<tscreen> <verb>
Linux-NASIL Turkce dokumanlari
<url url="http://cclub.metu.edu.tr/tr-ldp"
name="Turkce Linux Dokuman Projesi Ana Sayfasi">
adresinden temin edilebilir.
</verb></tscreen>

url belirteci ile tanimlanan ana URL kaynagina, kaynak dosyadan HTML
formatli dosya olusturulurken baglanti verilir. name belirtecinin
kullanimi sart degildir.

__________________

Zero Relax

Fontlar

linuxdoc-sgml, LaTeX tarafindan desteklenen tum fontlari tanir.
Yukarida tanimlanan tt belirteci sabit bosluklu 'daktilo' fontlarini
basar. Bu karakterler yardimiyla sunucu, dizin veya dosya isimleri yazilabilir.
Ornek olarak:

<tt>http://linux.org.tr</tt> makinasinda Linux calisir.

Diger yazi karakterlerinde, koyu yazi icin bf, egik yazi
icin em kullanabilirsiniz. Bunlarin disinda pekcok yazi karakteri
olmasina ragmen ornegin HTML bunlari desteklemeyebilir. Kalin, daktilo
ve egik yazi ile gayet hos gorunumlu dokumanlar hazirlanabilir.


Listeler

linuxdoc-sgml, uc farkli liste turunu destekler. Bunlar:

itemize : Temel listeler
enum : Numarali listeler
descrip : Tanim paragrafi

Temel (itemize) ve numarali (enum) listelerde yeralan
elemanlar item belirteci ile , tanim paragraflarindaki elemanlar
ise tag belirteci ile baslamalidir. Ornegin,

<itemize>
<item>Bakirkoy
<item>Taksim
</itemize>

Asagidaki goruntuyu verir:

* Bakirkoy
* Taksim

Ayni ornek, numarali listelerde (enum) yapilirsa,

<enum>
<item>Bakirkoy
<item>Taksim
</enum>

Listeler ardisil kullanilabilirler ve bir listenin icinde baska tur bir
liste bulunabilir.

Tanim paragraflari, (descrip) diger liste turlerinden biraz
bagimsizdir. Nadiren kullanilir.

<descrip>
<tag/Windows./ Evdeki pencere. Acik kaldiginda cereyan yapar.
<tag/DOS./ Windows'un selefi. Hayati durumlarda ise yarayabilir.
</descrip>

Ekrandaki goruntusu :

Windows.
Evdeki pencere. Acik kaldiginda cereyan yapar.
DOS.
Windows'un selefi. Hayati durumlarda ise yarayabilir.


Son bir soz

linuxdoc-sgml paketini Linux Kullanicilari Grubu ftp adresinden
(ftp://ftp.linux.org.tr) temin edebilirsiniz. Kullanimlari kisitli
oldugu icin yukarida sozu gecen belirteclerin disinda kalan birkac komuan
(tablo, matematik formuller, resimler) hic soz etmedik. Bunlar hakkinda
daha genis bilgi dizini altindaki QWERTZ User's Guide dosyasinda bulunabilir.

__________________