Opensource.Platon.SK CVS: doc/soft-doc-sys/sgml/sk/user-doc-systems.sgml - diff

   Up to  [Platon] / doc / soft-doc-sys / sgml / sk
Diff for doc/soft-doc-sys/sgml/sk/user-doc-systems.sgml between version 1.1 and 1.2


version 1.1, 2002/12/01 22:56:56
version 1.2, 2002/12/09 22:03:48



Line 1 




Line 1 




 <chapter id="user-doc-sys"><title>Systémy užívateľskej dokumentácie softvéru</title>
 <chapter id="user-doc-sys">


 
 <title>Systémy užívateľskej dokumentácie softvéru</title>


 
 


 <para>
 <para>


 
 


 Najznamejsim a najpouzivanejsim systemom pre tvorbu uzivatelskej dokumentacie je
 Najznámejším a najpoužívanejším systémom pre tvorbu užívateľskej dokumentácie je


 DocBook [LINK].
 <ulink url="http://www.oasis-open.org/docbook/"><productname>DocBook</></ulink>.


 
 Je to otvorený nástroj postavený nad otvorenými technológiami.


 
 


 </para>
 </para>


 
 <para>


 
 


 
 Mnoho známych firiem ako napr. TcX (tvorcovia databázového systému


 
 <productname>MySQL</productname>) alebo TrollTech (tvorcovia grafickej knižnice


 
 <productname>QT2</productname>) používa pre dokumentovanie svojich produktov


 
 vlastné nástroje. Odhliadnuc od ostatných faktorov môže byť výsledkom použitia


 
 vlastného dokumentačného systému pomerne ťažké a komplikované zlepšovanie a


 
 rozširovanie dokumentácie od rôznych prispievateľov. Preto sa používanie


 
 otvorených technológií v procese vytvárania dokumentácie považuje za vysoko


 
 žiadúce a silne produktívne.


 
 


 
 </para>


 
 <para>


 
 


 
 <productname>DocBook</productname> dokument je písaný použitím tzv. značkovacích


 
 jazykov (markup languages) ako je <acronym>SGML</> a <acronym>XML</>.


 
 <productname>DocBook</productname> existuje v oboch týchto verziách. Podobne ako


 
 pri <acronym>HTML</> dokumentoch sa špecálnymi značkami (tagmi) označujú


 
 jednotlivé miesta alebo elementy. V prípade <acronym>HTML</> dokumentu sa však


 
 pomocou značiek definuje dizajn a výzor výsledného dokumentu (zmena farby, zmena


 
 písma, zvýraznenie a pod.). V <productname>DocBook</productname> dokumente


 
 neexistuje žiadna značka manipulujúca priamo s dizajnom. Dokument je


 
 štruktúrovaný <firstterm>logicky</firstterm>, čiže označované sú časti s


 
 rovnakým významom (napr. mená súborov, premenných, produktov, ľudí, atď.).


 
 Výsledný dizajn je komponovaný pomocou jazyka <ulink


 
 url="http://www.jclark.com/dsssl/"><acronym>DSSSL</></ulink> (Document Style


 
 Semantics and Specification Language), ten však nie je pre bežného užívateľa


 
 podstatný.


 
 


 
 </para>


 
 <para>


 
 


 
 <!-- prepisat, moc sa mi to nezda -->


 
 


 
 Rozdiely medzi <acronym>XML</> verziou a <acronym>SGML</> verziou


 
 <productname>DocBook</productname> su minimálne. Okrem odlišnej hlavičky


 
 dokumentu a rôznej implementácii asi dvoch tagov sú obe verzie úplne identické.


 
 Podstatný rozdiel je v samotnom spracovaní dokumentu. Pri <acronym>SGML</>


 
 verzii sa používa <productname>Jade Wrapper</> (<application>jw</>) a pri


 
 <acronym>XML</> verzii nástroje postavené nad knižnicou <productname>libxml2</>.


 
 My vo svojich príkladoch budeme používať <acronym>SGML</> verziu.


 
 


 
 </para>


 
 <para>


 
 


 
 Základný dokument vyzerá nasledovne:


 
 


 
 <example>


 
 <title>Základný <productname>DocBook</productname> <acronym>SGML</> dokument</title>


 
 <programlisting><![CDATA[


 
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ ]>


 
 <book lang="sk">


 
 <bookinfo>


 
         <date>2002-12-09</date>


 
         <title>Môj prvý DocBook dokument</title>


 
         <subtitle>s týmto podnadpisom</subtitle>


 
 </bookinfo>


 
 


 
 <chapter>


 
 <title>Nadpis prvej kapitoly</title>


 
 


 
 <para>Text prvej kapitoly.</para>


 
 


 
 </chapter>


 
 </book>


 
 ]]></programlisting>


 
 </example>


 
 


 
 </para>


 
 <para>


 
 


 
 <productname>DocBook</productname> dokument (<SGMLtag class=StartTag>book</>) sa


 
 delí na kapitoly (<SGMLtag class=StartTag>chapter</>), sekcie v kapitolách


 
 (<SGMLtag class=StartTag>sect1</>) a podsekcie (<SGMLtag


 
 class=StartTag>sect2</>). Podsekcie možu mať ďalšie podsekcie (<SGMLtag


 
 class=StartTag>sect3</>, <SGMLtag class=StartTag>sect4</>). Kapitoly je možné


 
 združovať pomocou tagu <SGMLtag class=StartTag>part</>. Podobne viac kníh je


 
 možné spojiť do kompaktného celku pomocou tagu <SGMLtag class=StartTag>set</>.


 
 


 
 <example>


 
 <title>Základné delenie <productname>DocBook</productname> <acronym>SGML</> dokumentu</title>


 
 <programlisting><![CDATA[


 
 <chapter><title>Nadpis prvej kapitoly</title>


 
         <sect1><title>Prvá sekcia v prvej kapitole</title>>


 
                 <sect2><title>Prvá podsekcia v prvej sekcii</title>


 
                         <para>Text. Text. Text. Text.</para>


 
                 </sect2>


 
                 <sect2><title>Druhá podsekcia v prvej sekcii</title>


 
                 </sect2>


 
         </sect1>


 
         <sect1 ...>


 
                 <para> ... </para>


 
         </sect1>


 
 </chapter>


 
 ]]></programlisting>


 
 </example>


 
 


 
 </para>


 
 <para>


 
 


 
 Ako už bolo spomenuté, <productname>DocBook</> dokument má logickú štruktúru


 
 podľa významu. Značky sa používajú na označovanie výrazov alebo slov rovnakého


 
 typu. Označujú sa teda napríklad mená súborov, premenných, konštánt, funkcií,


 
 príkazov, produktov. Ďalej tiež e-mailové adresy alebo odkazy na webstránky. Je


 
 možné tiež vytvárať zoznamy alebo tabuľky, vkladať obrázky, atď.


 
 


 
 <example>


 
 <title>Ukážka niektorých <productname>DocBook</productname> <acronym>SGML</> tagov</title>


 
 <programlisting><![CDATA[


 
 <filename>/etc/passwd</filename>


 
 <filename class=headerfile>stdio.h</filename>


 
 <varname>$selected_user</varname>


 
 <constant>BUFFER_SIZE</constant>


 
 <function>proctable_init()</function>


 
 <command>grep</command>


 
 <application>jade</application>


 
 <productname>DocBook</productname>


 
 <email>platon@pobox.sk</email>


 
 <ulink url="http://www.platon.sk/">Platon SDG</>


 
 ]]></programlisting>


 
 </example>


 
 


 
 </para>


 
 <para>


 
 


 
 Na poslednom príklade je vidieť možnosť skracovania jednoduchých


 
 <acronym>SGML</> tagov pomocou ukončovacej značky <SGMLtag>&lt;/&gt;</SGMLtag>.


 
 


 
 </para>


 
 <para>


 
 


 
 Medzi najvýznamnejšie výhody <productname>DocBook</productname> dokumentácie


 
 patrí aj veľký počet možných formátov výstupných dokumentov. Sú to najmä


 
 <acronym>HTML</>, <acronym>RTF</>, <acronym>PDF</>, <acronym>PS</>,


 
 <application>TeX</>, čistý text a manuálové stránky. Generovanie prebieha


 
 pomocou programu <application>jade</application> (predpokladáme vygenerovanie


 
 súboru <filename>myfile.html</> zo súboru <filename>myfile.sgml</>).


 
 


 
 <literallayout>


 
 <prompt>$ </><userinput> jade -d /usr/lib/sgml/stylesheets/dbtohtml.dsl -t sgml myfile.sgml > myfile.html</userinput>


 
 </literallayout>


 
 


 
 Nie je nutné používať priamo analyzátor<!-- anglicky: parser -->


 
 <application>jade</application>. Existujú už predpripravené


 
 <foreignphrase>shell</> skripty pre generovanie konkrétnych typov výstupných


 
 súborov. Sú to napr. <application>db2html</>, <application>db2pdf</>, ale aj


 
 <application>docbook2tex</> či <application>docbook2txt</>. Takže pre


 
 vygenerovanie <acronym>HTML</> dokumentácie stačí použiť nasledovný príkaz.


 
 


 
 <literallayout>


 
 <prompt>$ </prompt><userinput> db2html myfile.sgml</userinput>


 
 </literallayout>


 
 


 
 Vzhľad výsledného <acronym>HTML</> dokumentu sa jednoducho prispôsobuje použitím


 
 <acronym>CSS</> (Cascading Style Sheets).


 
 


 
 </para>


 </chapter>
 </chapter>


 
 









Legend:


Removed from v.1.1
 


changed lines


 
Added in v.1.2


















Platon Group <platon@platon.org> http://platon.org/
  Up to  [Platon] / doc / soft-doc-sys / sgml / sk
-version 1.1, 2002/12/01 22:56:56
+version 1.2, 2002/12/09 22:03:48
 Line 1
 Line 1
 Line 1
- <chapter id="user-doc-sys"><title>Systémy užívateľskej dokumentácie softvéru</title>
+ <chapter id="user-doc-sys">
+ <title>Systémy užívateľskej dokumentácie softvéru</title>
  <para>
- Najznamejsim a najpouzivanejsim systemom pre tvorbu uzivatelskej dokumentacie je
+ Najznámejším a najpoužívanejším systémom pre tvorbu užívateľskej dokumentácie je
- DocBook [LINK].
+ <ulink url="http://www.oasis-open.org/docbook/"><productname>DocBook</></ulink>.
+ Je to otvorený nástroj postavený nad otvorenými technológiami.
  </para>
+ <para>
+ Mnoho známych firiem ako napr. TcX (tvorcovia databázového systému
+ <productname>MySQL</productname>) alebo TrollTech (tvorcovia grafickej knižnice
+ <productname>QT2</productname>) používa pre dokumentovanie svojich produktov
+ vlastné nástroje. Odhliadnuc od ostatných faktorov môže byť výsledkom použitia
+ vlastného dokumentačného systému pomerne ťažké a komplikované zlepšovanie a
+ rozširovanie dokumentácie od rôznych prispievateľov. Preto sa používanie
+ otvorených technológií v procese vytvárania dokumentácie považuje za vysoko
+ žiadúce a silne produktívne.
+ </para>
+ <para>
+ <productname>DocBook</productname> dokument je písaný použitím tzv. značkovacích
+ jazykov (markup languages) ako je <acronym>SGML</> a <acronym>XML</>.
+ <productname>DocBook</productname> existuje v oboch týchto verziách. Podobne ako
+ pri <acronym>HTML</> dokumentoch sa špecálnymi značkami (tagmi) označujú
+ jednotlivé miesta alebo elementy. V prípade <acronym>HTML</> dokumentu sa však
+ pomocou značiek definuje dizajn a výzor výsledného dokumentu (zmena farby, zmena
+ písma, zvýraznenie a pod.). V <productname>DocBook</productname> dokumente
+ neexistuje žiadna značka manipulujúca priamo s dizajnom. Dokument je
+ štruktúrovaný <firstterm>logicky</firstterm>, čiže označované sú časti s
+ rovnakým významom (napr. mená súborov, premenných, produktov, ľudí, atď.).
+ Výsledný dizajn je komponovaný pomocou jazyka <ulink
+ url="http://www.jclark.com/dsssl/"><acronym>DSSSL</></ulink> (Document Style
+ Semantics and Specification Language), ten však nie je pre bežného užívateľa
+ podstatný.
+ </para>
+ <para>
+ <!-- prepisat, moc sa mi to nezda -->
+ Rozdiely medzi <acronym>XML</> verziou a <acronym>SGML</> verziou
+ <productname>DocBook</productname> su minimálne. Okrem odlišnej hlavičky
+ dokumentu a rôznej implementácii asi dvoch tagov sú obe verzie úplne identické.
+ Podstatný rozdiel je v samotnom spracovaní dokumentu. Pri <acronym>SGML</>
+ verzii sa používa <productname>Jade Wrapper</> (<application>jw</>) a pri
+ <acronym>XML</> verzii nástroje postavené nad knižnicou <productname>libxml2</>.
+ My vo svojich príkladoch budeme používať <acronym>SGML</> verziu.
+ </para>
+ <para>
+ Základný dokument vyzerá nasledovne:
+ <example>
+ <title>Základný <productname>DocBook</productname> <acronym>SGML</> dokument</title>
+ <programlisting><![CDATA[
+ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ ]>
+ <book lang="sk">
+ <bookinfo>
+         <date>2002-12-09</date>
+         <title>Môj prvý DocBook dokument</title>
+         <subtitle>s týmto podnadpisom</subtitle>
+ </bookinfo>
+ <chapter>
+ <title>Nadpis prvej kapitoly</title>
+ <para>Text prvej kapitoly.</para>
+ </chapter>
+ </book>
+ ]]></programlisting>
+ </example>
+ </para>
+ <para>
+ <productname>DocBook</productname> dokument (<SGMLtag class=StartTag>book</>) sa
+ delí na kapitoly (<SGMLtag class=StartTag>chapter</>), sekcie v kapitolách
+ (<SGMLtag class=StartTag>sect1</>) a podsekcie (<SGMLtag
+ class=StartTag>sect2</>). Podsekcie možu mať ďalšie podsekcie (<SGMLtag
+ class=StartTag>sect3</>, <SGMLtag class=StartTag>sect4</>). Kapitoly je možné
+ združovať pomocou tagu <SGMLtag class=StartTag>part</>. Podobne viac kníh je
+ možné spojiť do kompaktného celku pomocou tagu <SGMLtag class=StartTag>set</>.
+ <example>
+ <title>Základné delenie <productname>DocBook</productname> <acronym>SGML</> dokumentu</title>
+ <programlisting><![CDATA[
+ <chapter><title>Nadpis prvej kapitoly</title>
+         <sect1><title>Prvá sekcia v prvej kapitole</title>>
+                 <sect2><title>Prvá podsekcia v prvej sekcii</title>
+                         <para>Text. Text. Text. Text.</para>
+                 </sect2>
+                 <sect2><title>Druhá podsekcia v prvej sekcii</title>
+                 </sect2>
+         </sect1>
+         <sect1 ...>
+                 <para> ... </para>
+         </sect1>
+ </chapter>
+ ]]></programlisting>
+ </example>
+ </para>
+ <para>
+ Ako už bolo spomenuté, <productname>DocBook</> dokument má logickú štruktúru
+ podľa významu. Značky sa používajú na označovanie výrazov alebo slov rovnakého
+ typu. Označujú sa teda napríklad mená súborov, premenných, konštánt, funkcií,
+ príkazov, produktov. Ďalej tiež e-mailové adresy alebo odkazy na webstránky. Je
+ možné tiež vytvárať zoznamy alebo tabuľky, vkladať obrázky, atď.
+ <example>
+ <title>Ukážka niektorých <productname>DocBook</productname> <acronym>SGML</> tagov</title>
+ <programlisting><![CDATA[
+ <filename>/etc/passwd</filename>
+ <filename class=headerfile>stdio.h</filename>
+ <varname>$selected_user</varname>
+ <constant>BUFFER_SIZE</constant>
+ <function>proctable_init()</function>
+ <command>grep</command>
+ <application>jade</application>
+ <productname>DocBook</productname>
+ <email>platon@pobox.sk</email>
+ <ulink url="http://www.platon.sk/">Platon SDG</>
+ ]]></programlisting>
+ </example>
+ </para>
+ <para>
+ Na poslednom príklade je vidieť možnosť skracovania jednoduchých
+ <acronym>SGML</> tagov pomocou ukončovacej značky <SGMLtag>&lt;/&gt;</SGMLtag>.
+ </para>
+ <para>
+ Medzi najvýznamnejšie výhody <productname>DocBook</productname> dokumentácie
+ patrí aj veľký počet možných formátov výstupných dokumentov. Sú to najmä
+ <acronym>HTML</>, <acronym>RTF</>, <acronym>PDF</>, <acronym>PS</>,
+ <application>TeX</>, čistý text a manuálové stránky. Generovanie prebieha
+ pomocou programu <application>jade</application> (predpokladáme vygenerovanie
+ súboru <filename>myfile.html</> zo súboru <filename>myfile.sgml</>).
+ <literallayout>
+ <prompt>$ </><userinput> jade -d /usr/lib/sgml/stylesheets/dbtohtml.dsl -t sgml myfile.sgml > myfile.html</userinput>
+ </literallayout>
+ Nie je nutné používať priamo analyzátor<!-- anglicky: parser -->
+ <application>jade</application>. Existujú už predpripravené
+ <foreignphrase>shell</> skripty pre generovanie konkrétnych typov výstupných
+ súborov. Sú to napr. <application>db2html</>, <application>db2pdf</>, ale aj
+ <application>docbook2tex</> či <application>docbook2txt</>. Takže pre
+ vygenerovanie <acronym>HTML</> dokumentácie stačí použiť nasledovný príkaz.
+ <literallayout>
+ <prompt>$ </prompt><userinput> db2html myfile.sgml</userinput>
+ </literallayout>
+ Vzhľad výsledného <acronym>HTML</> dokumentu sa jednoducho prispôsobuje použitím
+ <acronym>CSS</> (Cascading Style Sheets).
+ </para>
  </chapter>
 Legend:


Removed from v.1.1
 


changed lines


 
Added in v.1.2
 Legend:


Removed from v.1.1
 


changed lines


 
Added in v.1.2
-Removed from v.1.1
+Added in v.1.2


Copyright © 2002-2006 Platon Group Site powered by Metafox CMS	Go to Top