SD-XML Documentation

Basic skeleton

The basic skeleton of a SMASHDOCs-xml consists of the smashdoc-element, which contains a document and an indexes-element.

All text, image and table sections are appended to the document-node. The index-nodes are appended to the indexes-node.

The DTD can be downloaded here: sdxml.dtd (Please note that your browser will probably not display the dtd, please use “link save as”)

Example:

<?xml version='1.0' encoding='utf-8'?>
<smashdoc>
  <document>
    <paragraph>this is text</paragraph>
  </document>
  <indexes>
  </indexes>
</smashdoc>

Elements in document node

Paragraph

A normal text paragraph can be created with the <paragraph>-element.

Example:

<paragraph>normal text section</paragraph>

Heading

A heading without numbering can be created with the heading-element with @level-attribute, which determines the heading level (integer between 0 and 5).

Example:

<heading level="0">this is a heading</heading>

Numbered Heading

The heading-element with @enumeration-attribute creates a numbered heading. @enumeration sets the numbering level (integer between 0 and 5).

Example:

<heading enumeration="0">a</heading>

Numbered Paragraph

A paragraph with numbering can be created with a paragraph-element with @enumeration-attribute.

@enumeration sets the numbering level, according to the enumerated heading (integer between 0 and 5).

Example:

<paragraph enumeration="1">b</paragraph>

Ordered List

Ordered Lists are represented as flat structures in SMASHDOCs-xml.

A list entry is created with a ol-li-element. To this ol-li-element, a @indent-attribute can be attached, which indents the list item; this attribute is required. The @alignment-attribute makes the text align to the left; this attribute is optional (left by default). The @enumeration-attribute sets the numbering level, according to the enumerated heading (integer between 0 and 5); this attribute is set on export and is not required on import. It also must have a @list-id-attribute, which indicates to which list it belongs to; this attribute is set on export and is not required on import.

Example:

<ol-li indent="2" alignment="left" list-id="4fea2b5d-cd85-468c-856c-2bdcfc982cf3" enumeration="0">this</ol-li>
<ol-li indent="3" alignment="left" list-id="4fea2b5d-cd85-468c-856c-2bdcfc982cf3" enumeration="1">is</ol-li>
<ol-li indent="3" alignment="left" list-id="4fea2b5d-cd85-468c-856c-2bdcfc982cf3" enumeration="1">a</ol-li>
<ol-li indent="2" alignment="left" list-id="4fea2b5d-cd85-468c-856c-2bdcfc982cf3" enumeration="0">flat</ol-li>
<ol-li indent="2" alignment="left" list-id="4fea2b5d-cd85-468c-856c-2bdcfc982cf3" enumeration="0">list</ol-li>
<ol-li indent="1" alignment="left" list-id="65924d14-b2f4-4401-9169-8dbff231172d" enumeration="0">another</ol-li>
<ol-li indent="1" alignment="left" list-id="65924d14-b2f4-4401-9169-8dbff231172d" enumeration="0">list</ol-li>

Unordered List

Unordered Lists are represented as flat structures in SMASHDOCs-xml.

A list entry is created with a ul-li-element. To this ul-li-element, a @indent-attribute can be attached, which indents the list item. The @enumeration-attribute sets the numbering level, according to the enumerated heading (integer between 0 and 5). The @alignment-attribute makes the text align to the left or right. It also must have a @list-id-attribute, which indicates to which list it belongs to.

Example:

<ul-li indent="2" alignment="left" list-id="4fea2b5d-cd85-468c-856c-2bdcfc982cf3" enumeration="0">this</ul-li>
<ul-li indent="3" alignment="left" list-id="4fea2b5d-cd85-468c-856c-2bdcfc982cf3" enumeration="1">is</ul-li>
<ul-li indent="3" alignment="left" list-id="4fea2b5d-cd85-468c-856c-2bdcfc982cf3" enumeration="1">a</ul-li>
<ul-li indent="2" alignment="left" list-id="4fea2b5d-cd85-468c-856c-2bdcfc982cf3" enumeration="0">flat</ul-li>
<ul-li indent="2" alignment="left" list-id="4fea2b5d-cd85-468c-856c-2bdcfc982cf3" enumeration="0">list</ul-li>
<ul-li indent="1" alignment="left" list-id="65924d14-b2f4-4401-9169-8dbff231172d" enumeration="0">another</ul-li>
<ul-li indent="1" alignment="left" list-id="65924d14-b2f4-4401-9169-8dbff231172d" enumeration="0">list</ul-li>

Image

An image can be inserted with the image-element.

The text-node contains the filename.

The width, caption and whether numbering is enabled can be set via the attributes width, caption and num-enabled.

Example:

<image width="57%" caption="Deutsches Museum München" num-enabled="1">myimage.jpeg</image>

Table

A table can be inserted with the table-element.

First child of table is the column_width-element, which itself contains an item for each column. These items contain the percentage of width for each column.

Furthermore, the table contains tr elements that contain td or th cells.

The width, caption and whether numbering is enabled can be set via the attributes width, caption and num-enabled.

Example:

<table indent="0" caption="my table title" width="47.0%" num-enabled="1" border-color="#cccc00">
  <column_width>
    <item>33.33%</item>
    <item>33.33%</item>
    <item>33.33%</item>
  </column_width>
  <tr>
    <th>a</th>
    <th/>
    <th/>
  </tr>
  <tr>
    <th/>
    <td>b</td>
    <td/>
  </tr>
  <tr>
    <th/>
    <td/>
    <td>c</td>
  </tr>
</table>

Styling:

For the whole table the color of the cell-borders can be set via @border-color.

The height of a table-row can be set via the attribute @min-height (unit mm) for the element tr.

The borders of each cell can be set with the attributes @border-bottom @border-right @border-top and @border-left.

@text-align and @vertical-align is possible to set for each cell.

Inside a table cell b, i, u, s, a, kbd, sd-sc, inline, and footnote elements can be used for inline styling. Custom inline styles can be used with the inl element and the attribute @stylename. font-size-element (unit px) can be used for the font-size. All inline style-tags can be applied on partial text.

Example:

<tr min-height="40mm">
    <th text-align="center" vertical-align="middle" border-bottom="1">This is the content of a table header field</th>
    <td font-size="10px"><sd-sc><b><i><u><s>This is the content of normal table cell</s></u></i></b></sd-sc></td>
</tr>

Pagebreak

Pagebreaks are supported with the empty pagebreak-element.

<pagebreak/>

Attributes

General section attributes

@alignment possible values are “left”, “center”, “right” and “justify”
@id possible is any CDATA, needed when xref is used
@indent specifies the indent level for this section. Possible are 0 (standard), 1, 2, 3, 4, 5

Attributes for Headings and numbered Paragraphs

@enumeration Possible for the elements heading and paragraph. When used with heading the result will be a numbered heading. When used with paragraph, the result will be a numbered paragraph. The value sets the level of numbering. Valid values are 0, 1, 2, 3, 4, 5.
@level Can be used with the element heading. Sets the heading level. Valid values are 0, 1, 2, 3, 4, 5.

Attributes for images and tables

The following attributes can be used for the elements image and table.

The width can be set with @width in %.

@num-enabled can be set to 0 or 1. It sets, whether a image or table will have a counter below.

@caption is a text that will be shown below the image or table.

Possible Content in Text Sections

#PCDATA

Heading elements can contain only #PCDATA.

Example:

<heading>This is a heading.</heading>

Mixed Content

Paragraph and List elements can contain #PCDATA and some additional elements.

Styling Elements

To style the words, it’s possible to make them bold, italic, underlined, striked, small caps, inlined, superscripted and subscripted. This is realized via the elements b, i, u, s, sc, inl, sub and sup. A style-tag can of course contain other style-tags. Only sub and sup cannot contain each other. The inline tag has an attribute @stylename which can have a custom style.

<paragraph><inl stylename="my_red_font">My red text</inl></paragraph>

Cross-Reference

To create a Cross-Reference, a xref-tag can be used.

The target of the Cross-Reference is set via the @href-attribute. Possible targets are: Headings, Numbered Paragraphs, Images and Tables. The target element has to contain the according @id-attribute.

For setting the mode of how the cross-reference is displayed, there are two attributes:

@data-num-enabled (can be 0 or 1) sets, whether the number of the target is displayed. The displayed number can be a heading or paragraph number like “1.4.3” or in case of an image “image 2”.

@data-content-enabled (can be 0 or 1) sets, whether the content of the target is displayed. The displayed content is the whole content of a heading or numbered paragraph or the caption of a table or image.

At least one of these attributes has to be 1 for a valid cross-reference.

Example:

<heading enumeration="0" id="65b8b6aa-227e-e1ba-66f0-bd1ccf18f0cf">My Heading</heading>
<paragraph enumeration="1" id="3ff3ea40-a0f4-4f19-d66e-05268c122a98">This is a numbered paragraph</paragraph>
<paragraph enumeration="1" id="d2d2804c-d7d5-b1c0-fb32-49addd640ef8">In paragraph <xref href="3ff3ea40-a0f4-4f19-d66e-05268c122a98" data-num-enabled="1" data-content-enabled="0"/> the assumption is proved.</paragraph>

Footnote

A footnote can be created via the empty footnote-tag. The footnote text is simply placed between the tags.

Example:

<paragraph>This is text. <footnote>This is my footnote-text.</footnote></paragraph>
<paragraph><footnote>test footnote<br/>with another<br/>line</footnote></paragraph>

Sidenote

A sidenote can be created via the empty sidenote-tag. The sidenote text is simply placed between the tags.

Example:

<paragraph> This is text. <sidenot>This is my sidenote-text.</sidenote></paragraph>
<paragraph><sidenote>test<br/>sidenote<br/>with<br/>multiple<br/>lines</sidenote></paragraph>

Indexes

Index(publishing) - is a list of words or phrases (headings/titles) and associated pointers (references) o where useful material relating to that heading can be found in a document or collection of documents. A document can have any number of indices.

Examples are an index in the back matter of a book.

Each index consists of terms and optionally any number of nested narrower terms to a term.

A term is also valid if it has no narrower terms.

A term can also be a reference to another terms in the same index. In that case narrows there are no longer relevant but they can exist.

Example of using index elements in paragraph:

<paragraph indent="0" alignment="left" id="dcc4b746-902e-e59b-777f-e0787b7962e3"
                origin_ids="dcc4b746-902e-e59b-777f-e0787b7962e3">Lorem ipsum
         <index data-id="e85bdebd-afac-2b8a-1b08-809efd7ce879"/>
          dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
           dolor sit amet, magna aliqua
           <index data-id="1407c84b-6786-794d-2a49-e9c04280c394"/>
           adipiscing elit, sed do eiusmod tempor
            reference to another term.
         Lorem ipsum dolor sit amet, consectetur adipiscing elit
         <index data-id="00418fb2-dafc-f3b4-d59c-f00d62b17ac9"/>
         et dolore ipsum dolor sit amet ipsum dolor sit amet.
         <index data-id="312ea82b-0115-5489-9a94-3e74051330da"/>
     </paragraph>

Indexes are defined in a corresponding element <indexes>...<`\indexes`> with at least one <index-node> term.

Terms are represented by <index-node> element.

Attributes for index-node element

  • id (required) - index element unique id as uuid string
    160DCA53-7D1F-4596-9A99-3CA3F349701A
  • title (required) - word or phrase
  • target-reference-id (optional) - optional attribute, reference to another
    term (not narrower term!) in the same index which is not a synonym term.
  • sorting-key (optional) - optional attribute, custom sorting criteria.

sorting-key

Index entries will always be sorted in ascending alphabetical order within a node. In general the sorting criteria is the name of the index entry. If an index entry has a separate information to “sort string”, that string has to be used for sorting calculation. If new entries will be created or renamed the order will not be updated immediately but is always when a parent node will be folded out.

target-reference-id

Term can additionally have a reference to another term (not narrower term!) in the same index which is not a synonym term. A synonym term can have references to multiple terms in the same index. A synonym term can have narrower terms but they are actually useless.

An usage example would be:

  • Main term (to be referenced) is: car
  • Synonym terms could be: vehicle, automobile, auto, motor vehicle … etc.

A user can delete any existing reference at any time and create a new one if required and if the term itself is not referenced by other synonym terms.

Example of indexes element definition in sd-xml:

<indexes>
    <index-node id="8a62adc6-714d-5ee3-b70e-baa7d6251ce0" title="TERMS">
        <index-node id="00418fb2-dafc-f3b4-d59c-f00d62b17ac9" title="Lorem"
                    target-reference-id="b3b6701a-7db3-a907-21d9-d56da60987ff"/>
        <index-node id="b20f0e0a-3aa7-1a63-b786-5ea0db123f3f" title="magna aliqua"
                    sorting-key="manga"/>
        <index-node id="e85bdebd-afac-2b8a-1b08-809efd7ce879" title="ipsum"
                    sorting-key="term" target-reference-id="b3b6701a-7db3-a907-21d9-d56da60987ff"/>
        <index-node id="de4e5d75-5781-399c-6a77-379eb431a53f" title="Car"  />
        <index-node id="b3b6701a-7db3-a907-21d9-d56da60987ff" title="automobile">
            <index-node id="fd1e72e0-b08f-55f3-50f9-47c90f014ede" title="auto" >
                <index-node id="312ea82b-0115-5489-9a94-3e74051330da" title="motor vehicle"/>
            </index-node>
        </index-node>
        <index-node id="1407c84b-6786-794d-2a49-e9c04280c394" title="NewTerm" sorting-key="term"/>
    </index-node>

    <index-node id="c62216a4-4af1-d442-58dc-4f86e5c49fc6" title="IPSUM INDEX"  >
        <index-node id="476e5ba7-df8b-4db9-854f-de1e5f3ef776" title="magna aliqua"  />
        <index-node id="24cb1ca3-958a-f0c6-f6cd-7b0704bf8747" title="blueocean"
                    target-reference-id="476e5ba7-df8b-4db9-854f-de1e5f3ef776"/>
    </index-node>
</indexes>