woof-CE-libre/woof-code/rootfs-skeleton/usr/share/examples/xml/docbook.xml

<?xml version="1.0" encoding="UTF-8"?>


<?xml-stylesheet type="text/css" href="docbook.css" ?>

<article>
  <title>Writing DocBook documents using Morphon</title>
  <section>
    <title>Introduction</title>
    <para>This document contains a tutorial to get started with editing XML in Morphon using DocBook as an example. While creating and editing a document, we show you the Morphon way to edit your xml.</para>
    <para>A copy of this document in both HTML and XML format, together with the plugins mentioned here are available in one ZIP file as <ulink url="http://www.morphon.com/xmleditor/docbook-tutorial.zip">docbook-tutorial.zip</ulink></para>
    <para>If you're not familiar with the XML concepts, you might want to read about XML first. The <ulink url="http://www.w3schools.com/xml/default.asp">xml tutorial</ulink> at <ulink url="http://www.w3schools.com">www.w3schools.com</ulink> is a place to start. </para>
    <section>
      <title>What is Docbook?</title>
      <para>From the official DocBook homepage:</para>
      <para><quote>DocBook is a DTD maintained by the DocBook Technical Committee of OASIS. It is particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications). Because it is a large and robust DTD, and because its main structures correspond to the general notion of what constitutes a "book," DocBook has been adopted by a large and growing community of authors writing books of all kinds. DocBook is supported "out of the box" by a number of commercial tools, and there is rapidly expanding support for it in a number of free software environments. These features have combined to make DocBook a generally easy to understand, widely useful, and very popular DTD. Dozens of organizations are using DocBook for millions of pages of documentation, in various print and online formats, worldwide.</quote></para>
    </section>
    <section>
      <title>Contents of the examples directory</title>
      <para>In the <filename>../examples/docbook</filename> directory all the files needed for this tutorial are available. The DocBook material was obtained from the following websites:</para>
      <itemizedlist>
        <listitem>
          <para>You can find the DocBook DTD at the <ulink url="http://www.oasis-open.org/docbook/">official docbook homepage</ulink>.</para>
        </listitem>
        <listitem>
          <para>The XSL stylesheets can be found on the site of <ulink url="http://www.nwalsh.com/docbook/xsl/">Norman Walsh</ulink>.</para>
        </listitem>
      </itemizedlist>
    </section>
  </section>
  <section>
    <title>Editing XML-documents</title>
    <section>
      <title>Create a DocBook article</title>
      <para> To create a docbook article document just follow these steps:</para>
      <procedure>
        <step>
          <para>Start up Morphon ...</para>
        </step>
        <step>
          <para>Choose <menuchoice>
              <shortcut>
                <keycombo>
                  <keycap>Crtl</keycap>
                  <keycap>N</keycap>
                </keycombo>
              </shortcut>
              <guimenu>File</guimenu>
              <guimenuitem>New..</guimenuitem>
            </menuchoice>. from the menu.</para>
        </step>
        <step>
          <para>The <guilabel>Create document</guilabel> dialog is now opened.</para>
          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="shots/create-document-dialog.gif" format="GIF"/>
              </imageobject>
              <imageobject>
                <imagedata fileref="shots/create-document-dialog.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </screenshot>
          <substeps>
            <step>
              <para>Select the file <filename>examples/docbook/dtd/docbookx.dtd</filename> as the DTD to use. Use <guilabel>Browse..</guilabel>. to get to the file selector.</para>
            </step>
            <step>
              <para>Select the file <filename>examples/docbook/docbook.css</filename> as the stylesheet (CSS) to use. To do this, set the <guilabel>method</guilabel> to <guilabel>File</guilabel> and use <guilabel>Browse...</guilabel> again.</para>
            </step>
            <step>
              <para>Click on the <guibutton>New</guibutton> button.</para>
            </step>
          </substeps>
        </step>
        <step>
          <para>XML allows you to select any element from the DTD to be the root element of your document, making it possible that one person writes one chapter of a book while someone else writes another. Unfortunately with a DTD the size of DocBook, it leaves you with quite a long list of elements to choose from. </para>
          <screenshot>
            <mediaobject>
              <imageobject>
                <objectinfo>
                  <title>Choose root element - dialog</title>
                </objectinfo>
                <imagedata fileref="shots/choose-root-element-dialog.gif" format="GIF"/>
              </imageobject>
              <imageobject>
                <objectinfo>
                  <title></title>
                </objectinfo>
                <imagedata fileref="shots/choose-root-element-dialog.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </screenshot>
          <para>Choose <sgmltag class="element">article</sgmltag> as the root element in the <guilabel>Choose root element</guilabel> dialog and click on the <guibutton>Ok</guibutton> button.</para>
          <para>(Other good choices for the document's root element would be <sgmltag class="element">book</sgmltag>, <sgmltag class="element">chapter</sgmltag> or <sgmltag class="element">selection</sgmltag>.)</para>
        </step>
        <step>
          <para>The DocBook DTD requires that the article element contains a child element. Because Morphon intends to keep the document structure valid, you are asked which child element to add when you add an article (or start with the article as the root element).</para>
          <screenshot>
            <mediaobject>
              <imageobject>
                <objectinfo>
                  <title>Choose Structure-dialog</title>
                </objectinfo>
                <imagedata fileref="shots/choose-structure-for-article-dialog.gif" format="GIF"/>
              </imageobject>
              <imageobject>
                <imagedata fileref="shots/choose-structure-for-article-dialog.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </screenshot>
          <substeps>
            <step>
              <para>Choose structure <literal>abstract</literal> in the first <guilabel>Choose structure</guilabel> dialog and click on the <guibutton>Ok</guibutton> button</para>
            </step>
            <step>
              <para>Another <guilabel>Choose structure</guilabel> dialog is openened, now choose <literal>para</literal> and click on the <guibutton>Ok</guibutton> button.</para>
            </step>
          </substeps>
        </step>
      </procedure>
      <para>Once the document is opened the window is split into two parts. The left side or <emphasis>tree pane</emphasis> contains a hiërarchical view of the document structure, the right side or <emphasis>editor pane</emphasis> contains the contents of the document.</para>
    </section>
    <section>
      <title>Edit the DocBook article</title>
      <para>When you have made the new docbook article as mentioned in the previous section, the next thing you probably want to do is add elements and text to it. There are different ways to add elements, each one handy for different types of elements and in different situations. Here are a few examples:</para>
      <section>
        <title>Add a title to the article</title>
        <procedure>
          <step>
            <para>Click on the <literal>article</literal> element in the tree pane with the right mouse button and select <guimenuitem>Insert element</guimenuitem> from the menu.</para>
          </step>
          <step>
            <para>The <guilabel>indicate the element to be created</guilabel> dialog is opened. In this dialog you can choose which element to add and where you want it in the document structure.</para>
            <screenshot>
              <mediaobject>
                <imageobject>
                  <objectinfo>
                    <title>Indicate the element to be created - dialog</title>
                  </objectinfo>
                  <imagedata fileref="shots/element-tobe-created-dialog.gif" format="GIF"/>
                </imageobject>
                <imageobject>
                  <imagedata fileref="shots/element-tobe-created-dialog.png" format="PNG"/>
                </imageobject>
              </mediaobject>
            </screenshot>
            <para>For our example:</para>
            <substeps>
              <step>
                <para>Choose the <guilabel>In</guilabel> radio button.</para>
                <para>With <guilabel>In</guilabel>, <guilabel>Before</guilabel>, <guilabel>After</guilabel>, <guilabel>Replace</guilabel> or <guilabel>Inline</guilabel> you indicate where a new element must be added in the tree relative to the element that had focus when the dialog was opened. Depending on what is chosen here, different possibilities are shown in the lists below. We choose <guilabel>In</guilabel> because title will be a child element of article.</para>
              </step>
              <step>
                <para>Choose <guilabel>At beginning of article</guilabel> from the left-side list.</para>
                <para>In most situations, more specific directives are needed to indicate the postion in the tree for a new element. In our example we need to decide whether we want an element before or after the abstract. Depending on what you choose different possibities are shown in the right-side list, there the actual element to add can be chosen.</para>
              </step>
              <step>
                <para>Choose title from the right-side list.</para>
              </step>
              <step>
                <para>Click on the <guibutton>Ok</guibutton> button.</para>
              </step>
            </substeps>
          </step>
        </procedure>
      </section>
      <section>
        <title>Add a section with a paragraph</title>
        <para>The procedure for adding a section is a lot like adding the title, the section element is needed though for the next examples.</para>
        <procedure>
          <step>
            <para>Click with the right mouse button on the <literal>article</literal> element in the tree pane or use <keycombo>
                <keycap>Alt</keycap>
                <keycap>I</keycap>
              </keycombo>.</para>
          </step>
          <step>
            <para>Select <menuchoice>
                <guimenuitem>Insert element</guimenuitem>
              </menuchoice> from the menu.</para>
          </step>
          <step>
            <para>Choose <guilabel>In</guilabel>, <guilabel>At end of article</guilabel> and <guilabel>section</guilabel> in the <guilabel>Indicate element to be created</guilabel> dialog and then click on the <guibutton>Ok</guibutton> button.</para>
          </step>
          <step>
            <para>Choose <guilabel>para</guilabel> in the <guilabel>Choose structure</guilabel> dialog and then click on the <guibutton>Ok</guibutton> button.</para>
          </step>
          <step>
            <para>Now you can enter the text in the editor pane for the <literal>section/paragraph</literal>.</para>
            <para>When you want to start adding text to a specific element, a fast way to get to the element in the editor pane is to select the element in the tree pane, which gives the element focus in the editor pane, and then press the <keycap>tab</keycap> key, which will activate the cursor.</para>
            <para>See <xref linkend="navigating"/> for a description of the navigation features and behaviour of Morphon.</para>
          </step>
        </procedure>
      </section>
      <section>
        <title>Add another section</title>
        <para>Once you have some elements in the tree there are several ways to make use of the existing structures. Here are some examples:</para>
        <procedure>
          <title>Using the 'add empty copy of current element' - feature (Ctrl-Shift-Enter)</title>
          <step>
            <para>Click with the right mouse button on the <literal>section</literal> element in the tree pane.</para>
          </step>
          <step>
            <para>Select <menuchoice>
                <guimenuitem>Add empty copy of current element</guimenuitem>
              </menuchoice> from the menu.</para>
          </step>
          <step>
            <para>Choose <literal>para</literal> in the <guilabel>Choose structure</guilabel> dialog and then click on the <guibutton>Ok</guibutton> button.</para>
            <para>A new section element is added after the section element that had focus when the command was given.</para>
          </step>
        </procedure>
        <para>The shortcut for the feature is <keycombo>
            <keycap>Ctrl</keycap>
            <keycap>Shift</keycap>
            <keycap>Enter</keycap>
          </keycombo>, and can also be used from the editor pane.</para>
        <procedure>
          <title>Using copy and paste</title>
          <step>
            <para>Click with the right mouse button on the <literal>section</literal> element in the tree pane.</para>
          </step>
          <step>
            <para>Select <guimenuitem>copy</guimenuitem> from the menu. (<keycombo>
                <keycap>Ctrl</keycap>
                <keycap>C</keycap>
              </keycombo>)</para>
          </step>
          <step>
            <para>Again click with the right mouse button on the <literal>section</literal> element.</para>
          </step>
          <step>
            <para>Now select the <guimenuitem>Paste After (Structure only)</guimenuitem> from the menu.(<keycombo>
                <keycap>Ctrl</keycap>
                <keycap>Alt-B</keycap>
              </keycombo>)</para>
          </step>
        </procedure>
        <para>The difference with using 'Add empty copy of current element' is that this way the <literal>para</literal> child element is automatically copied. This way of copying is convenient when for example a new chapter is to be made according to the structure of an existing chapter. </para>
        <procedure>
          <title>Using the Enter key</title>
          <step>
            <para>Put the cursor in the (last) paragraph of a <literal>section</literal> element in the editor pane.</para>
          </step>
          <step>
            <para>Press the enter key.</para>
            <para>A new paragraph is created.</para>
          </step>
          <step>
            <para>Leave the paragraph empty and press return key again,</para>
            <para>A new section element is created for which you get a <guilabel>choose structure : section</guilabel> dialog.</para>
          </step>
          <step>
            <para>Choose para in the <guilabel>choose structure : section</guilabel> dialog</para>
          </step>
        </procedure>
        <para>Also take a look at <xref linkend="using-the-enter-key"/> for a more detailed description of the enter key functionality.</para>
      </section>
      <section id="add-followup">
        <title>Add a 'FollowUp Element' </title>
        <para>The menu under the <mousebutton>right </mousebutton>mouse button when clicking on an element in the tree contains a <guilabel>Add FollowUp Element</guilabel> option. This option is disabled until a FollowUp element is defined for the current element in the CSS editor. If a FollowUp element is defined, it will be inserted after the current element both when you select the option from the menu or use the enter key.</para>
        <para>When you for example want an articleinfo element in the document. The DocBook Articleinfo element is ment to contain metainformation for an article like Author, Copyright, RevHistory, and so on. With defining FollowUp elements for the elements that you want in the articleinfo it can be made easy for the users to sequencially add all the necessary elements and text. </para>
        <para>How a FollowUp element can be configured is explained in <xref linkend="conf-followup-elem"/> part.</para>
        <para>Configuring FollowUp elements also has effect on the behaviour of the enter key in the editor. Take a look at <xref linkend="using-the-enter-key"/> part for a more detailed description of the enter key functionality.</para>
      </section>
      <section>
        <title>Add an inline element</title>
        <procedure>
          <step>
            <para>Select a piece of text in the editor pane.</para>
          </step>
          <step>
            <para>Click on the selected text with you right mouse button. (<keycombo>
                <keycap>Alt</keycap>
                <keycap>I</keycap>
              </keycombo>)</para>
          </step>
          <step>
            <para>select <menuchoice>
                <guimenuitem>insert element</guimenuitem>
              </menuchoice> from the menu.</para>
          </step>
          <step>
            <para>The <guilabel>insert element</guilabel> dialog is opened with the <guilabel>inline</guilabel> radio button selected. </para>
            <para>Select <guilabel>emphasis</guilabel> from the right side list and click on the Ok button.</para>
          </step>
        </procedure>
        <para>An alternative key combination that can be used to add an inline element is <keycombo>
            <keycap>Ctrl</keycap>
            <keycap>G</keycap>
          </keycombo>. When using <keycombo>
            <keycap>Ctrl</keycap>
            <keycap>G</keycap>
          </keycombo> you get an <guilabel>insertion pallete</guilabel> with only the list of inline elements to choose from.</para>
      </section>
      <section id="using-the-enter-key">
        <title>Using the Enter Key</title>
        <para>We already mentioned the enter key twice in the previous examples as a shortcut to easily add elements. The following is a more detailed description of how the enter key behaves and how this behaviour can be changed.</para>
        <para>The enter key behaves according to the following rules: </para>
        <itemizedlist>
          <listitem>
            <para>The editor starts looking at the whitespace configuration in the CSS. When the white-space characteristic for an element is set to preserve the enter key will create a new line, when its value is normal or no wrap the editor will figure out what element to add.</para>
            <para>(See <xref linkend="css-whitespace"/> )</para>
          </listitem>
          <listitem>
            <para>Then the editor will try to find a FollowUp element to add. (FollowUp elements are configured in the CSS.) If the FollowUp element is allowed, the element will be added. </para>
            <para>(See <xref linkend="conf-followup-elem"/> )</para>
          </listitem>
          <listitem>
            <para>If there is no element defined or the element defined is not allowed, the editor checks if there is any text in the current element. If there is text in the current element the editor will, if the grammar allows it, add an empty copy of the current element.</para>
          </listitem>
          <listitem>
            <para> If there is no text, the editor will (again if the grammar allows it) first remove the current element and then insert an empty copy of the current parent as a sibling of that parent.</para>
          </listitem>
        </itemizedlist>
      </section>
      <section role="not ready yet">
        <title>Add special elements </title>
        <para>comment / processing instructions / cdata</para>
        <para>entity references</para>
      </section>
      <section>
        <title>Rearranging the document structure</title>
        <para>It is possible to drag and drop elements in the tree pane, but since Morphon intents to keep the document structure valid, it is not allowed for example to drag the paragraph from a section when that paragraph is the only child element left for that section.</para>
      </section>
    </section>
    <section id="navigating">
      <title>Navigating through the article</title>
      <para>When the number of elements in a document increases, being able to navigate through the document becomes important. The following list contains descriptions of Morphons naviagation behaviour and features that will help you to keep track of the structure. </para>
      <para>(If you would like to have a larger document to experiment with, you can use the XML version of this document. Here you can find it <filename>../manual/getting-started-using-docbook.xml</filename>)</para>
      <itemizedlist>
        <listitem>
          <para>In the status line at the botton of the window, the location of the cursor is displayed as an XPath-expression, both when navigating in the tree pane and when navigating in the editor pane.</para>
        </listitem>
        <listitem>
          <para>When you click on an element in the tree pane, the selection will become visible too in the editor pane and it will scroll to the first position of the selection. The cursor is positioned there but needs to be activated before you can start adding text. The shortest way of activating the cursor is to press the <keycap>tab</keycap> key.</para>
        </listitem>
        <listitem>
          <para>When you are working in the editor pane and want to find the corresponding element in the tree pane, press <keycap>Shift</keycap> and click with the <mousebutton>left</mousebutton> mouse button on the left side outside the specific piece of text. Within the tree pane the tree will unfold and the element is selected.</para>
          <para>If you press <keycap>Shift</keycap> and click inside the specific piece of text, the corresponding <literal>text node</literal> of the element in the tree pane will be selected. (It is necessary for the last feature to have the preference <link linkend="text-nodes">textnodes</link> selected.)</para>
        </listitem>
        <listitem>
          <para>The view of the document structure in the tree pane can be altered a bit by changing the preferences Select Edit -&gt; Preferences ( <keycombo>
              <keycap>Ctrl </keycap>
              <keycap>P</keycap>
            </keycombo>) from the menu and then go to the 'XML UI' tab. The following options are shown.</para>
          <para><itemizedlist>
              <listitem>
                <para id="text-nodes"><guilabel>Text Nodes</guilabel></para>
                <para>If selected, the text pieces are shown as nodes in the tree pane like <literal>[TEXT]</literal>.</para>
              </listitem>
              <listitem>
                <para><guilabel>Comment nodes</guilabel></para>
                <para>Comment nodes like, &lt;!-- this note for the editor is not supposed to appear in a publication --&gt;, are shown in the editor pane, but the corresponding nodes are only shown in the tree pane if this check box is selected.</para>
              </listitem>
              <listitem>
                <para><guilabel>show text fragments</guilabel></para>
                <para>If selected, the first few words of the contents of the element are shown in the tree. (This only if the element can contain PCDATA)</para>
              </listitem>
              <listitem role="not ready yet">
                <para><guilabel>show icons</guilabel> - Whether or not the node icon is shown in the tree pane.</para>
              </listitem>
            </itemizedlist></para>
        </listitem>
        <listitem>
          <para>With the <keycombo>
              <keycap>Ctrl</keycap>
              <keycap>Up</keycap>
            </keycombo> and <keycombo>
              <keycap>Ctrl</keycap>
              <keycap>Down</keycap>
            </keycombo> key combinations you can scroll through the editor pane and tree pane without moving the cursor.</para>
        </listitem>
        <listitem>
          <para>Though Morphon intents to keep the document structure valid, in some situations elements can become invalid. To find all the invalid locations press <keycombo>
              <keycap>Ctrl</keycap>
              <keycap>I</keycap>
            </keycombo> or <keycombo>
              <keycap>Ctrl</keycap>
              <keycap>L</keycap>
            </keycombo> you can invoke the <guilabel>show invalid locations</guilabel> dialog.</para>
        </listitem>
      </itemizedlist>
    </section>
    <section role="">
      <title>XML handling options</title>
      <para>When you open the menu <menuchoice>
          <guimenu>Edit</guimenu>
          <guimenuitem>Preferences</guimenuitem>
        </menuchoice> (<keycombo>
          <keycap>Ctrl</keycap>
          <keycap>P</keycap>
        </keycombo>) and click on the <guilabel>XML</guilabel>-tab you are presented options for the way the editor handles XML. </para>
      <itemizedlist>
        <listitem>
          <para><guilabel>XML parser to use</guilabel>: Here you can select the parser you want Morphon to use when loading the document. (The editor is shipped with two parsers, IBM's XML4J2 and Apache Xerces.)<!--FIXME: add link to a place where is explained how you add another parser--></para>
        </listitem>
        <listitem>
          <para><guilabel>Show only legal actions</guilabel>: If checked the lists with insertable elements do only show elements that, when inserted, leave the parent in a valid state. </para>
          <para>When you need to change the structure of a document it can be useful to first make the structure invalid and repair it afterwards. By default it is not allowed to create invalid structures but when the <guilabel>Show only legal actions</guilabel> preference is deselected you can. </para>
        </listitem>
        <listitem>
          <para><guilabel>Whitespace settings</guilabel>: Sets the whitespace policy the editor uses when <emphasis>saving the XML to a file</emphasis>. Select <guilabel>Generate Indentation</guilabel> if you want to save the XML with indentation. </para>
        </listitem>
      </itemizedlist>
      <para>The above mentioned preferences can be overridden for a specific document. Instead of selecting <menuchoice>
          <guimenu>Edit</guimenu>
          <guimenuitem>Preferences</guimenuitem>
        </menuchoice>, select <menuchoice>
          <guimenu>Edit</guimenu>
          <guimenuitem>Document Preferences</guimenuitem>
        </menuchoice>. The dialog that is openened contains almost the same preferences, which you can set after selecting the <guilabel>Override default settings</guilabel> checkbox. When you now save and open the document again, Morphon will automatically use the preferences set for this document. This is useful when different persons are editing the same XML files. </para>
    </section>
  </section>
  <section>
    <title>The CSS</title>
    <abstract>
      <para>The rendering of the document in the editor pane is determined by the StyleSheet (CSS) you choose when opening or creating the document. (The CSS used can be changed while the document is open.)</para>
      <para>Note that you can also use the editor to just edit a CSS and that the CSS created can be used to render a document in a browser that can render XML. </para>
      <!--Morphon CSS policy...-->
    </abstract>
    <section>
      <title>Alter the CSS on the fly</title>
      <para>The following example explains how the CSS editor works and how you can change the CSS of your document on the fly:</para>
      <procedure>
        <step>
          <para>To open the CSS editor, choose <menuchoice>
              <guimenu>Tools</guimenu>
              <guimenuitem>Edit CSS </guimenuitem>
            </menuchoice>from the menu.(<keycombo>
              <keycap>Ctrl</keycap>
              <keycap>Shift</keycap>
              <keycap>E</keycap>
            </keycombo>)</para>
          <para><screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="shots/css-editor.gif" format="GIF"/>
                </imageobject>
                <imageobject>
                  <imagedata fileref="shots/css-editor.png" format="PNG"/>
                </imageobject>
              </mediaobject>
            </screenshot>In the CSS Editor dialog you find all the stylesheet rules that are defined. In the upper part of the window all the selectors of the rules are shown, and when a rule-selector is selected the declaration part of rule is shown in the bottom part of the window. Within the declaration part on the left side you find a list of and folders and panels and the properties the panel contains are shown on the right side. (In the <ulink url="http://www.morphon.com/manual/">manual</ulink> you find <ulink url="http://www.morphon.com/manual/ch06s24.html">descriptions of all the panels</ulink> including the special ones like Summary, Source and Content. <xref linkend="plugins"/> contains a description of the <guilabel>Plugin View</guilabel> property on the <guilabel>Morphon Specific</guilabel> panel.) </para>
          <para>For those not famliar with CSS, what you see when you scroll through the list with selectors are element names and combinations of element names. For example <guilabel>para</guilabel> and <guilabel>procedure &gt; title</guilabel>. <guilabel>para</guilabel> means that the rule is valid for all para elements in the document, and <guilabel>procedure &gt; title</guilabel> means that the rule is valid only for title elements that are child elements of a procedure. The <guilabel>Rule</guilabel> dialog will help you compose selectors, but if you want more specifications, take a look at chapter 5 (selectors) of the <ulink url="http://www.w3.org/TR/REC-CSS2/">CSS2</ulink> recommendation at the w3c site or look in the <ulink url="http://www.morphon.com/manual/apas09.html">manual for brief descriptions</ulink>. </para>
        </step>
        <step>
          <para>Instead of using CSS rules to change the layout for esthetic reasons, this example shows how to make a rule to support editing the document. For this we use the common attribute <sgmltag class="attribute">role</sgmltag>.</para>
          <para><quote>The Role attribute, found on almost all of the elements in DocBook, is a CDATA attribute that can be used to subclass an element. In applications, it may be useful to modify the definition of role so that authors must choose one of a specific set of possible values</quote> (From: <literal>DocBook: The Definitive Guide</literal>) </para>
          <para>In our example we simply use the role attribute to indicate, that we are not yet finished writing the contents of an element, by setting the value of the role attribute to 'to be finished'. With a rule in the CSS the background for such an element can be given a special colour.</para>
          <para>To set the value of the role attribute for a <sgmltag class="element">section</sgmltag>:</para>
          <procedure>
            <step>
              <para>Give the XML Editor window focus.</para>
            </step>
            <step>
              <para>Choose <guimenuitem>Show Attribute Palette</guimenuitem> from the menu that is openened when you click with the <mousebutton>right</mousebutton> mouse button on a <guilabel>section</guilabel> element. (Or select the <guilabel>section</guilabel> element and type <keycombo>
                  <keycap>Ctrl</keycap>
                  <keycap>K</keycap>
                </keycombo>)</para>
            </step>
            <step>
              <para>In the <guilabel>Attributes</guilabel> dialog first click on the <guilabel>Set</guilabel> checkbox, and then enter <literal>to be finished</literal> as the vaulue.</para>
            </step>
            <step>
              <para>Then click on the <guibutton>Apply</guibutton> button and close the <guilabel>Attributes</guilabel> dialog.</para>
            </step>
          </procedure>
        </step>
        <step>
          <para>To add a rule for <literal>section</literal> elements with the <literal>role</literal> attribute set to <literal>to be finished</literal>:</para>
          <procedure>
            <step>
              <para>Give the CSS Editor window focus.</para>
            </step>
            <step>
              <para>Select <menuchoice>
                  <guimenu>Edit</guimenu>
                  <guimenuitem>Add Rule...</guimenuitem>
                </menuchoice> </para>
            </step>
            <step>
              <para>The <guilabel>Rule</guilabel> dialog is opened.</para>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="shots/rule-dialog.gif" format="GIF"/>
                  </imageobject>
                </mediaobject>
              </screenshot>
              <para>With the Rule dialog the selector for a new rule can be composed. (On the left side of the window all available elements are listed. Theright side shows the selected elements and all possibilities to combine the elements.) </para>
            </step>
            <step>
              <para>Ther are 2 ways to create a selector in this window, the method presented first can be used if you know what the syntax of the selector looks like, the second method supports you composing the selector step by step.</para>
              <procedure>
                <step>
                  <para>Click on the <guibutton>Custom</guibutton> button in the window.</para>
                </step>
                <step>
                  <para>Enter <literal>section[role="to be finished"]</literal> in the popup window presented and click on <guibutton>Ok </guibutton>button.</para>
                  <para>Note that in the <guilabel>Rule</guilabel> dialog the text entered is both shown in the left side list and in the <emphasis>selector preview line</emphasis> at the bottom of the window.</para>
                </step>
                <step>
                  <para>Click on the Ok button.</para>
                  <para>The selector is added to the list in the CSS Editor and you can start adding declarations.</para>
                </step>
              </procedure>
              <para>Or</para>
              <procedure>
                <step>
                  <para>Double click on the section element in the left side list to select it.</para>
                  <para>The element is both copied to the selected elements list on the right side of the window and to the <emphasis>selector preview line</emphasis> at the bottom of the window.</para>
                </step>
                <step>
                  <para>With the <guilabel>options</guilabel> you can specify the relationship between the elements selected or add details.</para>
                  <para>(<ulink url="http://www.morphon.com/manual/apas09.html">Brief descriptions of the possible relationships</ulink> and details you can find in the <ulink url="http://www.morphon.com/manual/">manual</ulink>.) </para>
                  <para>To add the attribute details, click on <guilabel>section</guilabel> in the right side list and choose <guilabel>More</guilabel> from the <guilabel>Options</guilabel> list.</para>
                  <para>The <guilabel>Customize a simple selector</guilabel> dialog is opened.</para>
                </step>
                <step>
                  <para>Click on the <guibutton>add</guibutton> button to open the <guilabel>Add an attribute</guilabel> dialog.</para>
                  <para>Enter the values <literal>role</literal>, <literal>=</literal> and <literal>to be finished</literal>, click on the oke button, and click on close in the <guilabel>Customize a simple selector</guilabel> to return to the <guilabel>Rule</guilabel> dialog.</para>
                </step>
                <step>
                  <para>The text <literal>section[role="to be finished"]</literal> is now displayed in the <emphasis>selector preview line</emphasis> at the bottom of the window.</para>
                </step>
              </procedure>
            </step>
            <step>
              <para>To give the elements another background color, select the property color from the folder visual formatting and select a nice color for the background in the declaration part of the window.</para>
              <para>When you select <guilabel>Source</guilabel> from the properties list after setting the background color for the selector, the complete declaration of the selector is shown in CSS syntax. </para>
            </step>
            <step>
              <para>To see the effect of the rule you declared, select <menuchoice>
                  <guimenu>File </guimenu>
                  <guimenuitem>Apply Style</guimenuitem>
                </menuchoice> from the menu. (<keycombo>
                  <keycap>Ctrl</keycap>
                  <keycap>K</keycap>
                </keycombo>)</para>
            </step>
          </procedure>
        </step>
      </procedure>
    </section>
    <section id="css-whitespace">
      <title>White space in the css</title>
      <para>In the folder <guilabel>Visual Formatting</guilabel> on the panel <guilabel>Text</guilabel> you find the property <guilabel>White-space</guilabel>. This property declares how whitespace inside the element is handled. When the value is set to normal the editor will collapse all sequences of whitespace within the elements.</para>
      <para>The default value of the whitespace property is <literal>preserve</literal>. So that when an existing document is loaded in the editor without specifying a CSS you will not automatically lose whitespace. </para>
      <para>The white space configuration influences the behaviour of the enter key in the editor, see <xref linkend="using-the-enter-key"/>for this.</para>
    </section>
    <section id="conf-followup-elem">
      <title>Configuring a FollowUp element</title>
      <para>The FollowUp element for a selector can be specified in the CSS Editor when the property Morphon is selected in the folder <guilabel>Morphon Specific</guilabel>.</para>
      <para>This feature is added to make it easier to insert element into the XML document. (See <xref linkend="add-followup"/>for this.</para>
    </section>
    <section>
      <title>The default CSS</title>
      <para>If no CSS file was specified while opening the file a default CSS is generated. </para>
      <!--rules for generating the default CSS-->
    </section>
  </section>
  <section id="plugins">
    <title>Plugins</title>
    <abstract>
      <para>When behaviour is wanted for certain element in the editor that is not covered by CSS you can use plugins, for example to view an image. Morphon comes with DocBook plugins for image and audio data.</para>
    </abstract>
</section>
  <section role="">
    <title>Publishing XML-documents</title>
    <section>
      <title>Using XSL/XSLT</title>
      <para>When working with XML it is a logical choice to use XSL/XSLT for publishing. There are already a lot of tools supporting this technique. </para>
      <para>XSL is a language in which you can express stylesheets. It consists of two parts, 1. a language for transforming XML documents, which is actually XSLT. and 2. an XML vocabulary for specifying formatting semantics. (To write a stylesheet for XML to HTML transformation only the first part (XSLT) is needed, but when want to transform the XML to printed output you need both parts.) </para>
      <para>A stylesheet is usually made for a specific DTD and the kind of output you want. </para>
      <para>To perform the actual transformation an XSL-processor is needed besides the stylesheet. </para>
      <section>
        <title>Transformation to HTML</title>
        <para>For the transformation of a document to HTML an XSL-stylesheet and an XSL-processor are needed:</para>
        <itemizedlist>
          <listitem>
            <para>The <filename class="directory">examples/docbook/xsl</filename> directory contains a verbatim copy of Norman Walsh's DocBook XSL stylesheets. You can check for new versions on his site at <ulink url="http://www.nwalsh.com/docbook/xsl/index.html">http://www.nwalsh.com/docbook/xsl/index.html</ulink>.</para>
          </listitem>
          <listitem>
            <para>Morphon comes with Michael Kay's <ulink url="http://users.iclway.co.uk/mhkay/saxon/">Saxon</ulink> as the standard xslt processor, but you can instruct it to use a different XSLT processor of your choosing. See the manual ... for more information.</para>
          </listitem>
        </itemizedlist>
        <procedure>
          <title>To transform a DocBook XML document with these from Morphon, follow the example:</title>
          <step>
            <para>Select <menuchoice>
                <shortcut>
                  <keycombo>
                    <keycap>Crtl</keycap>
                    <keycap>Shift</keycap>
                    <keycap>X</keycap>
                  </keycombo>
                </shortcut>
                <guimenu><accel>F</accel>ile</guimenu>
                <guimenuitem>Process XSL...</guimenuitem>
              </menuchoice></para>
          </step>
          <step>
            <para>Use <filename>examples/docbook/xsl/html/docbook.xsl</filename> as the Stylesheet</para>
          </step>
          <step>
            <para>Press <guibutton>Preview</guibutton> and after a while a window will appear with an HTML rendition of your document.</para>
          </step>
        </procedure>
      </section>
      <section>
        <title>Transformation to printed output</title>
        <para>The transformation tools that we've shown in the previous section are also necessary for printed output, but you'll need some additional tools as well. We'll show you the available options.</para>
        <para>Will described soon.</para>
      </section>
    </section>
    <section>
      <title>Using DSSSL</title>
      <para>DocBook predates XML and so it started as an SGML DTD. There are SGML tools that work with DocBook and, because XML <emphasis>is</emphasis> SGML, they work with XML DocBook documents too.</para>
      <para>Norman Walsh has written a set of DSSSL stylesheets too and you can get them from his site at <ulink url="http://www.nwalsh.com/docbook/dsssl/index.html">http://www.nwalsh.com/docbook/dsssl/index.html</ulink>.</para>
      <para>There is only one DSSSL processor in widespread use, called <application>Jade</application>. Development of Jade has stopped, but a new cooperative project called <ulink url="http://openjade.sourceforge.net/">OpenJade</ulink> was started to maintain and enhance Jade.</para>
      <para>DSSSL defines a model for describing objects on a page. Jade and OpenJade contain several backends that map this model to different file formats:</para>
      <itemizedlist>
        <listitem>
          <para>TeX (using a special style called jadetex)</para>
          <para>From TeX it is possible to produce PDF output with hyperlinks.</para>
        </listitem>
        <listitem>
          <para>RTF</para>
        </listitem>
        <listitem>
          <para>Framemaker MIF</para>
        </listitem>
      </itemizedlist>
      <para>It is not possible to use Jade directly from Morphon.</para>
      <para></para>
    </section>
  </section>
</article>