V tem razdelku so pokrite naslednje značke:
| LiteralLayout - ovoj za vrstice ločene od glavnega besedila, ki niso označene kot Screen, Example ali ProgramListing, v katerih so prelomi in presledki pomembni |
| Example - zgled računalniškega programa ali sorodne informacije |
| InformalExample - zgled brez naslova |
| ProgramListing - prikaz celotnega ozirma dela programa |
| Screen - besedilo ki ga uporabnik vidi oziroma bi videl na zaslonu |
Mnogo je situacij, ko morate vključiti zglede izvorne kode, ukazov ali GUI akcij v vašem dokumentu. DocBook ima mnogo značk za podporo teh potreb. Kadarkoli želite vključiti zglede preprosto vstavite značko <Example> ali <InformalExample> okoli besedila zgleda ali grafike.
Primer 3.14. Zgled zgleda (Example)
<example> <title>Zgled iz BASIC-a</title> <programlisting> 10 PRINT "HELLO WORLD" 20 GOTO 10 </programlisting> </example> |
V tem prvem zgledu imamo listing preprostega BASIC programa. Koda vsebovana v znački <ProgramListing> je prikazana z neokrnjenimi presledki in prelomi vrstice, kar je zelo uporabno za zglede kode in podobne situacije kjer je potrebna ohranitev dobesednega formatiranja. Znački LiteralLayout in Screen delujeta na enak način, vendar pa se uporabljata za nakazovanje drugane vrste vsebine. Screen vsebuje izpis, ki bi se pojavil na zaslonu, medtem ko se LiteralLayout uporablja za katerokoli drugo besedilo, ki mora biti prikazano s prelomi vrstice in tabulatorji.
Zgled bi po pretvorbi v HTML izgledal nekako tako:
Primer 3.15. Zgled iz BASIC-a
1 10 PRINT "HELLO WORLD" 2 20 GOTO 10 |
Težava, ki se lahko pojavi z značkami LiteralLayout, ProgramListing in Screen: vso besedilo se izpiše dobesedno, vendar pa se DocBook značke še vedno interpretirajo kot značke in ne kot besedilo. Kaj storiti, ko je treba prikazati besedilo, ne da bi se značke interpretirale? Odgovor je v uporabi <![ CDATA [ ]]>, ki označi besedilo znotraj notranjih oklepajev kot podatke tipa character, ki se naj ne interpretira s strani SGML pregledovalnika. Vsako besedilo znotraj oklepajev bo ostalo po pretvorbi takšno kot je, tako da bo zgled uspešno reproduciral svoje značke.
Primer 3.16. Primer označevanja
<example> <title>A Markup Example</title> <screen> <![ CDATA [ <Para>To je DocBook primer.</Para> ]]> </screen> </example> |
Po pretvorbi v HTML bi ta zgled izgledal nekako tako:
Primer 3.17. Primer označevanja
<para>To je odstavek.</para> |
Sledeče značke se uporabljajo za označevanje elementov ukazov:
| Type - klasifikacija vrednosti |
| Literal - dobeseden niz, uporabljen 'in-line', ki je del podatkov v računalniku |
| UserInput - podatki, ki jih vnese uporabnik |
| Symbol - ime, ki je zamenjano z vrednostjo pred procesiranjem |
| Replaceable - vsebina, ki se lahko zamenja v sinopsisu ali ukazni vrstici |
| Filename - ime datoteke, po možnosti z vključeno potjo |
| Prompt - znak, ki nakazuje pričetek polja za vnos na zaslonu |
| ParamDef - informacija o podatkovnem tipu v imenu parametra ki ga zadeva ta informacija |
| Parameter - del navodila računalniku |
| Option - opcija za ukaz računalniškemu programu |
| EnVar - okoljska spremenljivka |
| Command - izvedljiv program oziroma vnos uporabnika izvedljivemu programu |
| CmdSynopsis - sinopsis za ukaz |
| Arg - argument v CmdSynopsis |
| ComputerOutput - podatki, ki jih računalnik predstavi uporabniku |
Ločimo dve situaciji, v katerih želite opisati ukaz: prikazovanje zgleda ukaza vtipkanega v ukazni vrstici in podrobn opis vseh argumentov in opcij ukaza, kot bi to videli v man strani.
DocBook podpira oba konteksta z značkama <Command> and <CmdSynopsis>.
Primer 3.18. Ukaz in njegov izpis
<screen> <prompt>bash$</prompt> <command>twiddle <replaceable>myfile</replaceable> </command> twiddling myfile.....done! </screen> |
bash$ twiddle -c 1 myfile twiddling myfile.....done! |
Ukazna značka se lahko uporablja tudi znotraj besedila za označevanje ukaza. Na primer:
Ukaz <command>twiddle</command> se uporablja za twiddle datoteke. Twiddled datoteke bodo označene z končnico .twid, če torej uporabim <command>twiddle</command> <replaceable>mojadatoteka</replaceable> bo ta postala <replaceable>mojadatoteka.twid</replaceable>. Napake se zapišejo v datoteko <filename>twiddle.err</filename>. |
Značka <Prompt> se uporablja le za označevanje lupine v ukazni vrstici. Replaceable označuje besedilo, ki naj bo zamenjano s strani uporabnika. Ime mojadatoteka je le arbitrarno ime za datoteko saj ne vemo in nas ne briga, kako je ime tej datoteki, želimo le prikazati, kako se uporablja ukaz. Če je ime datoteke v ukazu poznano potem uporabimo namesto tega značko <Filename>.
Označevanje CmdSynopsis je nekoliko težje. Tukaj je zgled iz DocBook Reference:
Primer 3.19. Foo Command Synopsis
<cmdsynopsis>
<!-- This is a synopsis for the command foo.
The options -a and -x are optional and exclusive
The option -c takes a cheese and is optional and repeatable
The options -t and -k are referred to in another fragment
The options -i, -j, and -k are required and exclusive
The option -f takes a filename and is required
The -t and -k options specify the kind of milk and mold in an
optional and repeatable group
-->
<command>foo</command>
<group>
<arg>-a</arg>
<arg>-x</arg>
</group>
<group>
<arg rep="repeat">-c <replaceable>cheese</replaceable></arg>
<synopfragmentref linkend="cheesetype">cheesetype</synopfragmentref>
</group>
<group choice="req">
<arg>-i</arg>
<arg>-j</arg>
<arg>-k</arg>
</group>
<arg choice="req">-f <replaceable>filename</replaceable></arg>
<synopfragment id="cheesetype">
<group rep="repeat">
<arg>-t <replaceable>milk</replaceable></arg>
<arg>-k <replaceable>mold</replaceable></arg>
</group>
</synopfragment>
</cmdsynopsis>
|
foo [-a | -x] [-c cheese(1)cheesetype] {-i | -j | -k} {-f filename}
(1) [-t milk | -k mold...]
CmdSynopsis vsebuje eno značko Command, skupino povezanih Arg, neodvisne Arg in in SynopFragments. <Arg> označuje argumente ukaza. Ima dve lastnosti: choice in rep. Choice se uporablja da nakaže ali je ukaz opcijski (privzeto), zahtevan (req) ali se izpiše brez vsake deklaracije (plain). Značka <Group> se uporablja za grupiranje povezanih Arg. SynopFragment je najbolj zapletena izmed CmdSynopsis značk. Uporablja se, da ponudi bolj podroben opis opcij argumenta. SynopFragment sestoji iz dveh delov: SynopFragment, ki vsebuje dodatne Arg in iz SynopFragmentRef, ki kaže na podroben opis.
| Accel - Keycap ki se uporablja z meta tipko, da aktivira grafični uporabniški vmesnik |
| KeyCap - besedilo napisano na resnični tipkovnici, ni nujno enako KeyCode |
| KeyCode - računalniška numerična predstavitev (designation) tipke na tipkovnici |
| KeyCombo - kombinacija vnosov |
| KeySym - simbolično ime tipke, ki ni nujno enako KeyCap |
| MenuChoice - izbira v menuju ali vrsta takšnih izbir |
| MouseButton - običajno ime gumba miške |
| Interface - element grafičnega uporabniškega vmesnika |
| InterfaceDefinition - polno ali kratko ime formalne specifikacije grafičnega uporabniškega vmesnika |
| GUIButton - besedilo na gumbu v grafičnem uporabniškem vmesniku |
| GUIIcon - grafika in, ali, besedilo, ki se pojavlja kot ikona v grafičnem uporabniškem vmesniku |
| GUILabel - besedilo v grafičnem uporabniškem vmesniku |
| GUIMenu - ime menuja v grafičnem uporabniškem vmesniku |
| GUIMenuItem - ime of a terminal menu item v grafičnem uporabniškem vmesniku |
| GUISubmenu - ime podmenuja v grafičnem uporabniškem vmesniku |
| Action - funkcija ki je vpoklicana kot odziv na uporabniški dogodek |
Lahko bi rekli, da je v DocBook-u značk za opis GUI elementov že preveč. Večino zgoraj naštetih se lahko uporabi v mnogoterih kontekstih, nekaj redkih kot na primer <KeyCap> pa je potrebo uporabiti znotraj drugih značk. Spodnji zgled in razlaga ne bosta pokrila vseh iz gornjega seznama. Seznam je v vaše zadovoljstvo (convinience?), saj DocBook Reference ne grupira značk po po njihovih funkcijah.
Vse GUI značke se lahko uporabljajo znotraj običajnih odstavkov. Če bi torej želel govoriti o ikoni Smetnjak (Trash) ali pa o gumbu Izprazni smetnjak bi uporabil znački <GUIIcon> and <GUIButton>: ikona <GUIIcon>Smetnjak</GUIIcon>, gumb <GUIButton>Izprazni smetnjak</GUIButton>. Upoštevajte, da lahko vse GUI značke vsebujejo inline grafiko.
Spodaj je razmeroma zapleten primer uporabe GUI značk iz predloge.
Primer 3.20. Zgled za GUIMenu in Shortcut
<variablelist> <varlistentry> <term><menuchoice> <shortcut> <keycombo><keycap>Ctrl</keycap><keycap>n</keycap></keycombo> </shortcut> <guimenu>File</guimenu> <guimenuitem>New</guimenuitem> </menuchoice></term> <listitem><para><action>Ustvari nov dokument</action></para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <shortcut> <keycombo><keycap>Ctrl</keycap><keycap>s</keycap></keycombo> </shortcut> <guimenu>File</guimenu> <guimenuitem>Save</guimenuitem> </menuchoice></term> <listitem><para><action>Shrani dokument</action></para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <shortcut> <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo> </shortcut> <guimenu>File</guimenu> <guimenuitem>Quit</guimenuitem> </menuchoice></term> <listitem><para><action>Konča <application>Kapp</application></action></para></listitem> </varlistentry> </variablelist> |
Upam, da ne buljite presenečeno v vse te značke! Najbolj zapleten del tega zgleda je značka <Shortcut>, ki označuje bližnjice s pomočjo tipk za izbire menuja. Pomembno je, da se znotraj Shortcut uporabljata KeyCombo ali pa sam KeyCap, ker je uporaba znakov (besedilo Ctrl-q na primer) nepravilna.
Ostale omembe vredne značke iz zgleda so MenuChoice, Action in Application. MenuChoice označi izbiro v menuju in mora vsebovati bližnjico (Shortcut), če ta obstaja, ime menuja v GUIMenu in ime izbire v GUIMenuItem. Action preprosto označuje frazo, ki opisuje kaj izbira (ali drug element vmesnika) počne. Application je značka, ki se uporablja za označevanje programov.
Po pretvorbi v HTML bi gornji zgled izgledal nekako tako:
Ustvari nov dokument
Shrani dokument
Konča Kapp