SD-XML Documentation

SDOX File Structure

An sdox file contains a SMASHDOCs document. It is a zip file, which contains one xml-file sd.xml and a folder images with the image files inside.

sdox-file
├── sd.xml
└── images
    ├── my_image.jpg
    └── another_image.png

Basic skeleton

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

Important is the attribute @version of the <smashdoc>-element. For proper import it should have the value 2.13.2.

All text, image and table sections are appended to the document-node. The index-nodes are appended to the indexes-node. The comment-nodes are appended to the comments-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 version="2.13.2">
  <document>
    <paragraph>this is text</paragraph>
  </document>
  <comments>
    <comment>
    </comment>
  </comments>
  <indexes>
  </indexes>
</smashdoc>

Elements in document node

Paragraph

Text paragraphs are represented by the <paragraph>-element.

Example:

<paragraph>normal text section</paragraph>

Each SMASHDOCs system has configured paragraph styles. In order to apply a certain style on the paragraph element, the attribute @stylename is used.

Example:

<paragraph stylename="quick_text_2_numbered">A non-disclosure agreement is used by companies</paragraph>

Which values are valid for @stylename depends on the configuration of the SMASHDOCs system.

Following standard styles for headings and numbered paragraphs are present on most SMASHDOCs systems:

  • @stylename for Headings
    • quick_heading_1_numbered
    • quick_heading_2_numbered
    • quick_heading_3_numbered
    • quick_heading_4_numbered
    • quick_heading_5_numbered
    • quick_heading_6_numbered
  • @stylename for Numbered Headings
    • quick_heading_1
    • quick_heading_2
    • quick_heading_3
    • quick_heading_4
    • quick_heading_5
    • quick_heading_6
  • @stylename for Numbered Paragraphs
    • quick_text_1_numbered
    • quick_text_2_numbered
    • quick_text_3_numbered
    • quick_text_4_numbered
    • quick_text_5_numbered
    • quick_text_6_numbered

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.

Each line in a table cell is wrapped with a p-element.

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><p>a</p></th>
    <th/>
    <th/>
  </tr>
  <tr>
    <th/>
    <td><p>b</p></td>
    <td/>
  </tr>
  <tr>
    <th/>
    <td/>
    <td><p>c</p><p>this is the second line</p></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"><p>This is the content of a table header field</p></th>
    <td font-size="10px"><p><sd-sc><b><i><u><s>This is the content of normal table cell</s></u></i></b></sd-sc></p></td>
</tr>

Pagebreak

Pagebreaks are supported with the empty pagebreak-element.

<pagebreak/>

Directories

Directories are represented by the directory-element. There are different types of directories:

  • Table of content
  • List of figures
  • List of tables
  • List of footnotes
  • List of weblinks
  • List of indexes
  • List of side notes

Example:

<directory type="content"/>
<directory type="weblinks"/>

Possible values for @type are: content, images, tables, footnotes, weblinks, indexes, sidenotes

Attributes

General section attributes

@alignment possible values are “left”, “center”, “right” and “justify”
@id possible is any CDATA, needed when xref or conversation is used
@indent specifies the indent level for this section. Possible are 0 (standard), 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 describe a Cross-Reference, the xref-tag is used.

The target of the Cross-Reference is set via the @href-attribute. Possible targets are:

  • Paragraphs, where the @stylename belongs to a style, which can be referenced
  • Images
  • Tables
  • Formulas

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:

<paragraph stylename="quick_heading_1_numbered" id="65b8b6aa-227e-e1ba-66f0-bd1ccf18f0cf">My Heading</heading>
<paragraph stylename="quick_text_2_numbered" id="3ff3ea40-a0f4-4f19-d66e-05268c122a98">This is a numbered paragraph</paragraph>
<paragraph stylename="quick_text_2_numbered" 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>

Comments

Comments are represented by the <comment>-element. The <comment>-element contains required inner elements.

Section Id

The id of section with conversation is represented by the <section_id>-element. The id needs to be the same id which is put to the @id-attribute of a paragraph-node.

Background information:

When the xml-document is imported, all ids will be replaced. That is why importing the same document more than once will be possible without id collisions. The replacement takes place in a way that will preserve links between sections.

Example:

<section_id>4deaa723-27db-cb11-dfcd-b40fa87caf9a</section_id>

Creator Id

Id of creator of the conversation, can be created with <creator_id> - element

Example:

<creator_id>1b78083f-6d3b-4674-8e1f-b7441d3fba2c</creator_id>

Referenced text

Referenced text of the conversation is represented by the <referenced_text>-element. It contains the complete clean text of the section, where the marked words are inside a <mark>-element. The <mark>-element is optional. If it is not there, it means that the comment refers to the whole section.

Example:

<referenced_text>Unilateral Contract: Karen wants someone to <mark>wash her car</mark>.</referenced_text>

Resolved

Mark conversation whether it is resolved or not, can be created with <resolved> - element

Example 1:

<resolved>0</resolved>

Example 2:

<resolved>1</resolved>

Created date

Date of creation of is set with the <created_date>-element. Accepted in two formats.

Example 1 (timestamp in seconds):

<created_date>1554909832</created_date>

Example 2:

<created_date>2018-08-30T13:56:00Z</created_date>`

Scope

Scope of the conversation can be inserted with <scope> - element.

First child of the <scope> is the <_cls>, which contains the type of scope of the conversation. There are two possible types:

  • ConversationScopeAll
  • ConversationScopeSelected

If ConversationScopeSelected type specified, <scope> - element should contain few more child elements: <users> which contains list of <user_id> - elements and <includeAdmins> - element

Example 1:

<scope>
    <_cls>ConversationScopeAll</_cls>
</scope>

Example 2:

<scope>
    <_cls>ConversationScopeSelected</_cls>
    <users>
        <user_id>a551b833-d28e-4cdb-969d-7d64f63e08d0</user_id>
    </users>
    <includeAdmins>0</includeAdmins>
</scope>

Conversation Type Key

In SMASHDOCs different types of conversations can be configured. Each conversation type has certain configured fields, which can be text-fields, dropdown-fields (data is also text) or checkbox-fields (data is boolean).

Each conversation type is identified with the conversation type key. The corresponding element is <conversation_type_key>.

Example:

<conversation_type_key>comment</conversation_type_key>

Metadata

Metadata of the conversation are represented via field-elements with custom @name attribute value. These are inserted in the <metadata>-element.

As values of the metadata-fields can be changed after the creation of the conversation, distinguishing between the original and current state is required. The <metadata>-element represents the current state of the field-values.

Example:

<metadata>
    <field name="main_comment">Explain that</field>
</metadata>

Messages

Messages are inserted with <messages> - element. They represent everything which is displayed inside inside the conversation like any user answers or notifications about the resolution of the conversation.

There are different types of messages.

Some child-elements are required for all types of messages:

  • <_cls> - type of message
  • <created_date> - date of the message creation as timestamp in seconds

Creation Message

The creation message is required as first child of the messages. It represents the initial state of the conversation’s metadata field values.

Additional fields:

  • <actor_id> - id of the user who created the conversation
  • <metadata> - initial state of metadata

Example:

<message>
    <actor_id>1dc2dbce-1f8d-4f10-afe8-85c48f354270</actor_id>
    <created_date>1554909798</created_date>
    <metadata>
        <field name="main_comment">Sure, it should not be a car?</field>
    </metadata>
    <_cls>ConversationMessage.CreationMessage</_cls>
</message>

User Answer

The user answer message type represents answers to the initial comment.

Additional fields:

  • <creator_id> - id of the user who appended the answer to the conversation
  • <content> - text of the user message

Example:

<message>
    <created_date>1554909831</created_date>
    <creator_id>1dc2dbce-1f8d-4f10-afe8-85c48f354270</creator_id>
    <content>Yes, car will be better!</content>
    <_cls>ConversationMessage.UserAnswer</_cls>
</message>

Resolution Message

A comment can be marked as resolved. When this happens, a message will appear in order to inform all users about the event.

Additional fields:

  • <actor_id> - id of the user who marked the conversation as resolved/unresolved
  • <new_value> - gives information whether the conversation has been resolved (1) or reopened (0)

Example:

<message>
    <actor_id>1dc2dbce-1f8d-4f10-afe8-85c48f354270</actor_id>
    <created_date>1554909914</created_date>
    <new_value>1</new_value>
    <_cls>ConversationMessage.ResolutionMessage</_cls>
</message>

Full example

<comment>
    <section_id>4deaa723-27db-cb11-dfcd-b40fa87caf9a</section_id>
    <conversation_type_key>comment</conversation_type_key>
    <creator_id>1b78083f-6d3b-4674-8e1f-b7441d3fba2c</creator_id>
    <referenced_text>Unilateral Contract: Karen wants someone to wash
    her car. She puts up a flyer saying that anyone who washes her car will receive $20.
    </referenced_text>
    <!--The metadata element as child of <comment> show the current state of the metadata-->
    <metadata>
        <field name="main_comment">Should we take it?</field>
    </metadata>
    <resolved>1</resolved>
    <created_date>1536244040</created_date>
    <!--The scope tells for which users the conversation is visible to.-->
    <scope>
        <_cls>ConversationScopeSelected</_cls>
        <users>
            <user_id>a551b833-d28e-4cdb-969d-7d64f63e08d0</user_id>
        </users>
        <includeAdmins>0</includeAdmins>
    </scope>
    <messages>
        <message>
            <actor_id>1b78083f-6d3b-4674-8e1f-b7441d3fba2c</actor_id>
            <_cls>ConversationMessage.CreationMessage</_cls>
            <!--The metadata element as child of the creation message show the initial state of the metadata-->
            <metadata>
                <field name="main_comment">Should we take it?</field>
            </metadata>
            <created_date>1536244040</created_date>
        </message>
        <!--With the following object, an answer of another user is shown-->
        <message>
            <created_date>1554909831</created_date>
            <creator_id>1dc2dbce-1f8d-4f10-afe8-85c48f354270</creator_id>
            <content>Yes</content>
            <_cls>ConversationMessage.UserAnswer</_cls>
        </message>
        <!--User 1b7... marks the conversation as resolved.-->
        <message>
            <actor_id>1b78083f-6d3b-4674-8e1f-b7441d3fba2c</actor_id>
            <created_date>1554909914</created_date>
            <new_value>1</new_value>
            <_cls>ConversationMessage.ResolutionMessage</_cls>
        </message>
    </messages>
</comment>