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

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


version 1.2, 2002/12/11 18:16:12
version 1.3, 2002/12/16 11:48:38



Line 1 




Line 1 




 <!-- $Platon: phpWebFileManager/doc/sgml/changelog.sgml,v 1.3 2002/12/03 20:47:37 nepto Exp $ -->
 <!-- $Platon: Platon.SK/doc-projects/soft-doc-sys/en/user-doc-systems.sgml,v 1.2 2002/12/11 18:16:12 nepto Exp $ -->


 
 


 <chapter id="user-doc-sys"><title>User-oriented software documentation systems</title>
 <chapter id="user-doc-sys">


 
 <title>User-oriented software documentation systems</title>


 
 


 <para>bar foo</para>
 <para>


 
 


 
 The most famous and the most used system for user-oriented documentation


 
 creation and maintaining is <ulink


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


 
 open tool build upon open technologies provides a system for writing structured


 
 documents using <acronym>SGML</> or <acronym>XML</>. It is particularly


 
 well-suited to books and papers about computer hardware and software, though it


 
 is by no means limited to them.  <productname>DocBook</> is an <acronym>SGML</>


 
 document type definition (<acronym>DTD</>).


 
 


 
 </para>


 
 <para>


 
 


 
 Many well-known companies, such as TcX (the developers of database system


 
 <productname>MySQL</>) or TrollTech (the developers of graphical library


 
 <productname>QT2</>) use their own tools for their product documentation.  Not


 
 pointing out other factors, the result of using own documentation system could


 
 be fairly hard and complicated improvement and extensibility of the


 
 documentation by different contributors.  This is the reason why the use of open


 
 technologies in process of creating documentation is highly desirable and


 
 productive.


 
 


 
 </para>


 
 <para>


 
 


 
 <productname>DocBook</> document is written using the so-called markup


 
 languages, such as <acronym>SGML</> and <acronym>XML</>. <productname>DocBook</>


 
 exists in both of these versions.  Very much like in the <acronym>HTML</>


 
 documents, individual parts or elements are marked by special tags.  While in a


 
 <acronym>HTML</> document the tags define the design of the document (change of


 
 color, font, etc.), in <productname>DocBook</> there is no tag that manipulates


 
 directly with design.  The document is structured <firstterm>logically</>, which


 
 means that the parts of the same meaning are tagged (filenames, variables,


 
 products, persons, etc.).  The resultant design can be specified using the


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


 
 Style Semantics and Specification Language), but is not essential for the common


 
 user.


 
 


 
 </para>


 
 <para>


 
 


 
 The differences between the <acronym>XML</> and <acronym>SGML</> versions of


 
 <productname>DocBook</> are minimal.  Apart from different header of the


 
 document and different implementation of perhaps two tags are both versions


 
 identical.  The main difference is in the processing of the document.  The


 
 <acronym>SGML</> version uses <productname>Jade Wrapper</> (<application>jw</>)


 
 while the <acronym>XML</> version uses tools based on the


 
 <productname>libxml2</> library.  In our examples, we will use the


 
 <acronym>SGML</> version.


 
 


 
 </para>


 
 <para>


 
 


 
 The basic document looks like this:


 
 


 
 <example>


 
 <title>The basic <productname>DocBook</productname> <acronym>SGML</> document</title>


 
 <programlisting><![CDATA[


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


 
 <book lang="en">


 
 <bookinfo>


 
         <date>2002-12-16</date>


 
         <title>My first DocBook document</title>


 
         <subtitle>with this subtitle</subtitle>


 
 </bookinfo>


 
 


 
 <chapter>


 
 <title>Title of the first chapter</title>


 
 


 
 <para>Text of the first chapter.</para>


 
 


 
 </chapter>


 
 </book>


 
 ]]></programlisting>


 
 </example>


 
 


 
 </para>


 
 <para>


 
 


 
 <productname>DocBook</> document (<SGMLtag class=StartTag>book</>) is divided


 
 into chapters (<SGMLtag class=StartTag>chapter</>), sections in the chapters


 
 (<SGMLtag class=StartTag>sect1</>) and subsections (<SGMLtag


 
 class=StartTag>sect2</>).  Subsections can have their own subsections (<SGMLtag


 
 class=StartTag>sect3</>, <SGMLtag class=StartTag>sect4</>). Chapters can be


 
 grouped with the <SGMLtag class=StartTag>part</> tag.  Similarly, more books can


 
 be grouped into one compact unit using the <SGMLtag class=StartTag>set</> tag.


 
 


 
 <example>


 
 <title>The basic division of the <productname>DocBook</> <acronym>SGML</> document</title>


 
 <programlisting><![CDATA[


 
 <chapter><title>Title of the first chapter</title>


 
         <sect1><title>First section in the first chapter</title>>


 
                 <sect2><title>First subsection in the fist section</title>


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


 
                 </sect2>


 
                 <sect2><title>Second subsection in the first section</title>


 
                 </sect2>


 
         </sect1>


 
         <sect1 ...>


 
                 <para> ... </para>


 
         </sect1>


 
 </chapter>


 
 ]]></programlisting>


 
 </example>


 
 


 
 As it has already been mentioned, a <productname>DocBook</> document has its


 
 logical structure according to the meaning.  Tags are used to mark expressions


 
 or words of the same type.  Therefore things like filenames, variable names,


 
 constant names, function names, commands, products are tagged accordingly, as


 
 well as e-mail addresses or links to web pages.  It is possible to create


 
 records, tables, insert pictures, etc.


 
 


 
 <example>


 
 <title>Illustration of some <productname>DocBook</> <acronym>SGML</> tags</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>


 
 


 
 You can see how simple <acronym>SGML</> tags can be shortened by using the


 
 <SGMLtag>&lt;/&gt;</SGMLtag> tag on the last example.


 
 


 
 </para>


 
 <para>


 
 


 
 One of the main advantages of <productname>DocBook</> documentation is the big


 
 number of possible output document formats.  The most common are


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


 
 <application>TeX</>, pure text or manual pages.  The generation is done by the


 
 <application>jade</> program (we expect to generate <filename>myfile.html</>


 
 file from <filename>myfile.sgml</> file).


 
 


 
 <literallayout>


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


 
 </literallayout>


 
 


 
 It is not necessary to use the <application>jade</> parser.  Some shell scripts


 
 for generating particular types of output files already exist.  Those include


 
 <application>db2html</>, <application>db2pdf</>, <application>docbook2tex</>, or


 
 <application>docbook2txt</>.  That means that to generate the <acronym>HTML</>


 
 documentation you just need to use the following command.


 
 


 
 <literallayout>


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


 
 </literallayout>


 
 


 
 The design of the generated <acronym>HTML</> document can be simply changed by


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


 
 


 
 </para>


 </chapter>
 </chapter>


 
 









Legend:


Removed from v.1.2
 


changed lines


 
Added in v.1.3


















Platon Group <platon@platon.org> http://platon.org/
  Up to  [Platon] / doc / soft-doc-sys / sgml / en
-version 1.2, 2002/12/11 18:16:12
+version 1.3, 2002/12/16 11:48:38
 Line 1
 Line 1
 Line 1
- <!-- $Platon: phpWebFileManager/doc/sgml/changelog.sgml,v 1.3 2002/12/03 20:47:37 nepto Exp $ -->
+ <!-- $Platon: Platon.SK/doc-projects/soft-doc-sys/en/user-doc-systems.sgml,v 1.2 2002/12/11 18:16:12 nepto Exp $ -->
- <chapter id="user-doc-sys"><title>User-oriented software documentation systems</title>
+ <chapter id="user-doc-sys">
+ <title>User-oriented software documentation systems</title>
- <para>bar foo</para>
+ <para>
+ The most famous and the most used system for user-oriented documentation
+ creation and maintaining is <ulink
+ url="http://www.oasis-open.org/docbook/"><productname>DocBook</></ulink>. This
+ open tool build upon open technologies provides a system for writing structured
+ documents using <acronym>SGML</> or <acronym>XML</>. It is particularly
+ well-suited to books and papers about computer hardware and software, though it
+ is by no means limited to them.  <productname>DocBook</> is an <acronym>SGML</>
+ document type definition (<acronym>DTD</>).
+ </para>
+ <para>
+ Many well-known companies, such as TcX (the developers of database system
+ <productname>MySQL</>) or TrollTech (the developers of graphical library
+ <productname>QT2</>) use their own tools for their product documentation.  Not
+ pointing out other factors, the result of using own documentation system could
+ be fairly hard and complicated improvement and extensibility of the
+ documentation by different contributors.  This is the reason why the use of open
+ technologies in process of creating documentation is highly desirable and
+ productive.
+ </para>
+ <para>
+ <productname>DocBook</> document is written using the so-called markup
+ languages, such as <acronym>SGML</> and <acronym>XML</>. <productname>DocBook</>
+ exists in both of these versions.  Very much like in the <acronym>HTML</>
+ documents, individual parts or elements are marked by special tags.  While in a
+ <acronym>HTML</> document the tags define the design of the document (change of
+ color, font, etc.), in <productname>DocBook</> there is no tag that manipulates
+ directly with design.  The document is structured <firstterm>logically</>, which
+ means that the parts of the same meaning are tagged (filenames, variables,
+ products, persons, etc.).  The resultant design can be specified using the
+ <ulink url="http://www.jclark.com/dsssl/"><acronym>DSSSL</></ulink> (Document
+ Style Semantics and Specification Language), but is not essential for the common
+ user.
+ </para>
+ <para>
+ The differences between the <acronym>XML</> and <acronym>SGML</> versions of
+ <productname>DocBook</> are minimal.  Apart from different header of the
+ document and different implementation of perhaps two tags are both versions
+ identical.  The main difference is in the processing of the document.  The
+ <acronym>SGML</> version uses <productname>Jade Wrapper</> (<application>jw</>)
+ while the <acronym>XML</> version uses tools based on the
+ <productname>libxml2</> library.  In our examples, we will use the
+ <acronym>SGML</> version.
+ </para>
+ <para>
+ The basic document looks like this:
+ <example>
+ <title>The basic <productname>DocBook</productname> <acronym>SGML</> document</title>
+ <programlisting><![CDATA[
+ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ ]>
+ <book lang="en">
+ <bookinfo>
+         <date>2002-12-16</date>
+         <title>My first DocBook document</title>
+         <subtitle>with this subtitle</subtitle>
+ </bookinfo>
+ <chapter>
+ <title>Title of the first chapter</title>
+ <para>Text of the first chapter.</para>
+ </chapter>
+ </book>
+ ]]></programlisting>
+ </example>
+ </para>
+ <para>
+ <productname>DocBook</> document (<SGMLtag class=StartTag>book</>) is divided
+ into chapters (<SGMLtag class=StartTag>chapter</>), sections in the chapters
+ (<SGMLtag class=StartTag>sect1</>) and subsections (<SGMLtag
+ class=StartTag>sect2</>).  Subsections can have their own subsections (<SGMLtag
+ class=StartTag>sect3</>, <SGMLtag class=StartTag>sect4</>). Chapters can be
+ grouped with the <SGMLtag class=StartTag>part</> tag.  Similarly, more books can
+ be grouped into one compact unit using the <SGMLtag class=StartTag>set</> tag.
+ <example>
+ <title>The basic division of the <productname>DocBook</> <acronym>SGML</> document</title>
+ <programlisting><![CDATA[
+ <chapter><title>Title of the first chapter</title>
+         <sect1><title>First section in the first chapter</title>>
+                 <sect2><title>First subsection in the fist section</title>
+                         <para>Text. Text. Text. Text.</para>
+                 </sect2>
+                 <sect2><title>Second subsection in the first section</title>
+                 </sect2>
+         </sect1>
+         <sect1 ...>
+                 <para> ... </para>
+         </sect1>
+ </chapter>
+ ]]></programlisting>
+ </example>
+ As it has already been mentioned, a <productname>DocBook</> document has its
+ logical structure according to the meaning.  Tags are used to mark expressions
+ or words of the same type.  Therefore things like filenames, variable names,
+ constant names, function names, commands, products are tagged accordingly, as
+ well as e-mail addresses or links to web pages.  It is possible to create
+ records, tables, insert pictures, etc.
+ <example>
+ <title>Illustration of some <productname>DocBook</> <acronym>SGML</> tags</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>
+ You can see how simple <acronym>SGML</> tags can be shortened by using the
+ <SGMLtag>&lt;/&gt;</SGMLtag> tag on the last example.
+ </para>
+ <para>
+ One of the main advantages of <productname>DocBook</> documentation is the big
+ number of possible output document formats.  The most common are
+ <acronym>HTML</>, <acronym>RTF</>, <acronym>PDF</>, <acronym>PS</>,
+ <application>TeX</>, pure text or manual pages.  The generation is done by the
+ <application>jade</> program (we expect to generate <filename>myfile.html</>
+ file from <filename>myfile.sgml</> file).
+ <literallayout>
+ <prompt>$ </><userinput> jade -d /usr/lib/sgml/stylesheets/dbtohtml.dsl -t sgml myfile.sgml > myfile.html</userinput>
+ </literallayout>
+ It is not necessary to use the <application>jade</> parser.  Some shell scripts
+ for generating particular types of output files already exist.  Those include
+ <application>db2html</>, <application>db2pdf</>, <application>docbook2tex</>, or
+ <application>docbook2txt</>.  That means that to generate the <acronym>HTML</>
+ documentation you just need to use the following command.
+ <literallayout>
+ <prompt>$ </prompt><userinput> db2html myfile.sgml</userinput>
+ </literallayout>
+ The design of the generated <acronym>HTML</> document can be simply changed by
+ using <acronym>CSS</> (Cascading Style Sheets).
+ </para>
  </chapter>
 Legend:


Removed from v.1.2
 


changed lines


 
Added in v.1.3
 Legend:


Removed from v.1.2
 


changed lines


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


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