_     __   ___    ___    _         _____
   / \   / /  /   \  /   \  | |       |  __ \
   \  \_/ /   | |\ \/ /| |  | |       | |  \ \          1.0
    \    /    | | \  / | |  | |       | |   \ \   __    ____
     \   \    | |  \/  | |  | |       | |   | |  /  \  / ___\
     /    \   | |      | |  | |       | |   / / | /\ | | |
    /  /\  \  | |      | |  | |____   | |__/ /  | \/ | | |___
    \_/  \_/  |_|      |_|  |______\  |_____/    \__/  \____/


          (C) Tomas Siegl (c) Orcave Inc. (c) 20002 - 20003
                    
Content:

  XML Documentation system manual

History:

  05/15/2003 Sigi        - initial version


1.0 General phylosophy
----------------------
The idea is separate documenation data into to 2 distinquish parts 'text' and 'design'. Text is enclosed
between xml tags <object> ... </object> which specifies which type is data these types will be explained 
later, (see 2.0 documentation objects). Design specifie how will be data displayed.

Because we specify data contents, we are able to use it to generate additional information like automatical
'Indexes' and Documentation 'trees'and 'link and pages tracking'. 

Sometimes it is necessary to 'mark' words or sentences or enforcing new line or insert link to another
documentation part.  folowing symbols has this meaning

    <b></b> - generaly used to bold text inside this 2 symbols. 

        Example: This is normal text and 'this is bolded text' and this is normal text again. 

    <i></i> - generaly used to itallic text inside this 2 symbols. 

        Example: This is normal text and 'this is italic text' and this is normal text again. 

    <u></u> - generaly used to underline text inside this 2 symbols. 

        Example: This is normal text and 'this is underlined text' and this is normal text again. 

    <br/> - Used to enforce new line.

        Example: <br/>This is first line.<br/>This is on Second line.

        Will look like:

        This is first line.
        This is on Second line.

If you need use this symbols %,@ in documentation text, you can put before 'backslash /' and these 2 
symbols are interpreted as text character only.

    Example: /%This is stil normale text/%. Will be displayed as: %This is still normal text%.

Because xml is very simmilar to hmtl language you can use in text located inside 2 tags another special 
characters like '& < >' but you have to use html constants: '&amp; &lt; &gt;'

Link to different page or page section has following format: '<xlink pageId='' refid=''>Link description</xlink>'

    PageId:  this specify which page is destination. If this attribute is missing or is empty it means that
             you are referencing element on current page.

    refId: Specify elemen on a page. 

if you want link external web site use <ulink href="http://www.orcave.com">Orcave</ulink>


    1.1 Documentation Pages 
    -----------------------
    Every documentation page is one separated file. which starts with valid xml tag <?xml version="1.0"?>. 
    This tag is not pair tag, that means that this tag doesn't have close tag </?>.

    Documetation page is xml object <docpage> .. </docpage> Where contents are another xml objects located
    between this to tags.

    example:

    <docpage>
        <someobject1>
        </someobject1>

        <someobject2>
        </someobject2>
    </docpage>

    Some of this objects (all object are described later in 2.1) can be presented more times, but generaly 
    this depends of type of the object, etc. page title has reasonable meaning only if this object is 
    presented only once, because page can have only one title, the same is valid for link, overview and
    remark.

    Object can be inserted in other objects, we say they are inner object of other object, but this mechanism
    has strict rules, and not every object can have inserted object or no object can contains itselfs.


    1.2 Documentation Tree
    ----------------------
    Every page is located somewhere in a tree. Tree represent whole documentation of project.
    Documentation is also object which is stored in file 'documentation.xml' which is parsed and from 
    this file is created Page order.

    <documentation>

        This object has following inner objects (tags):

        <docroot>Page where documentation start</docroot>
            
        <document>
            <name> 
              Contains path and file name (without .xml extension) of document page.
            </name>
            
            <prev>
              Previous page which will be in navigation   
            </prev>

            <next>
              Next page which will be in navigation   
            </next>
            
            <parent>
              Root page in tree, keyword 'root' has special meaning and situates page in root of the tree
            </parent>
        </document>

     </documentation>

     example:

     documentation.xml:

     <?xml version="1.0"?>
     <!DOCTYPE documentation SYSTEM "../xmlDocDocumentation.dtd">

     <documentation>
        <docroot>Sdk/Enigma</docroot>
            <document>
                <name>Sdk/Enigma</name>
                <link>Sdk/Enigma</name>
                <parent>root</parent>
            </document>

        <document>
            <name>Sdk/EnigmaPreview</name>
            <link>Sdk/EnigmaPreview</name>
        </document>

     </documentation>
  
          
2.0 List of Document objects
----------------------------        

    2.1 Docpage
    -----------
    This object represents arbitrary documentation page. Object starts with tag
    <docpage> and ends with tag </docpage>.

    This object has folowing inner tags. With following meaning.


        2.1.1 Chapter
        -------------
        <chapter>Name of documentation page</chapter>


        2.1.2 Overview
        --------------
        <overview>Page overview</overview>


        2.1.3 Link
        ----------
        <link>Page Id for links from other pages</link>
  

        2.1.4 Explain
        -------------
        General text which explains something or describes picture. Title can be also referenced by links

        <explain>
          <title>Title for this explain</title>
          <pic>Path and filename for picture, this path is absolute from documentation root</pic>
          <text>
            Explain text itselfs and can contains any of text strings including formating and links.</text>
        </explain>


        2.1.5 List
        ----------
        List of items, where items can be links or documentation text. 'Title' tag can be also referenced by links
        this list can contains one or more 'items' objects

        <list>
          <title>Title of list</title>
          <item>Any text which an has link or formating characters.</item>
        </list>


        2.1.6 Feature
        -------------
        <feature>
          Text describing feature. This can contains any of text strings including formating and links.
        </feature>


        2.1.7 SuperTip
        --------------
        <supertip>
          Super cool text. This can contains any of text strings including formating and links.
        </supertip>


        2.1.8 Important
        ---------------
        <important>
          Text which can't user miss. This can contains any of text strings including formating and links.
        </important>


        2.1.9 Question
        --------------
        <question>
          Speakers question for stimulation documentation writer Ego :) .
          This can contains any of text strings including formating and links.
        </question>


        2.1.10 Iface
        ------------
        This object describes arbitrary C++ interface. 'title' can be referenced by links.
        'title' can be referenced in links. '?Text' and 'overviews' and 'remark'tags 
        can contains any of text strings including formating and links.
        This object contains one or more inner objects 'method'. 

        <iface>
          <title>Name of interface</title>
          <over>short description of interface</over>
          <text>Long exhaustive description of interface.</text>

          <method>
            <title>Prototype of method</title>
            <over>short description of method</over>
            <text>Long exhaustive description of interface.</text>

            <param>Parametr of method</param>
            <ptext>
              Parametr description.
            </ptext>
            
            <return>Return value of method</return>
            <rtext>
              Describtion this returned value.  
            </rtext>

            <remark>Remart for this method</remark>
          </method>
        </iface>


        2.1.11 Struct
        -------------
        This object describes arbitrary data structure for programing languages.
        'title' can be referenced in links. '?Text' and 'overviews' and 'remark'tags 
        can contains any of text strings including formating and links.

        <struct>
          <title>Name of structure</title>
          <over>short description</over>
          <text>
            long description
          </text>

          <member>             
            <title>structure member with type</title>
            <text>
              Text describing amd explaning these type.
            </text>
          </member>
        </struct>
 

        2.1.12 Code
        -----------
        This object represent example of code. 'Title' can be referenced in links.

        <code>
          <title>Name of example</title>
          <text>
           Example text, or code
          </text>
        </code>


        2.1.13 DelphiObject
        -------------------
        This object Represents delphi object. All 'title' tags can be referendced in links.
        '?texts' and 'overviews' and 'remark' tags can contains any of text strings including formating and 
        links. This object can contain followind inner objects 'method' 'property' 'pubproperty' 'event'.

        <dobj>
          <title>Name of delhi object</title>
          <over>Short description</over>
          <text>
           Long exhaustive description.
          </text>

          <dmethod>
            <title>Name of method</title>
            <over>short describtions</over>
            <text>
              Long exhaustive description
            </text>

            <param>Parametr of method</param>
            <ptext>
              Parametr description.
            </ptext>
            
            <return>Return value of method</return>
            <rtext>
              Describtion this returned value.  
            </rtext>

            <remark>Remart for this method</remark>
          </dmethod>

          <property>
            <title>Name of property</title>
       
            <over>short describtions of property</over>
            <text>
              Long exhaustive description
            </text>

            <return>Return value of method</return>
            <rtext>
              Describtion this returned value.  
            </rtext>

            <remark>Remart for this property</remark>
          </property>

          <pubproperty>
            <title>Name of published property</title>
            <over>short describtions</over>
            <text>
              Long exhaustive description
            </text>

            <return>Return value of method</return>
            <rtext>
              Describtion this returned value.  
            </rtext>

            <remark>Remart for this published property</remark>
          </pubproperty>

          <event>
            <title>Event function prototype</title>
            <over>short describtions</over>
            <text>
              Long exhaustive description
            </text>

            <param>Parametr of event function</param>
            <ptext>
              Parametr description.
            </ptext>

            <remark>Remart for this event</remark>
          </event>
        </dobj>


        2.1.14 Contents
        ---------------
        Put tree of documentation into page.

        <contents>
          <title>Title for this contents</title>
          <root>Page which will be used as root in tree. (only pages in this branch will be shown)</root>
        </contents>


        2.1.15 Final
        ------------
        <finale>Final remark on page</final>