# SD-XML Documentation¶

## Basic skeleton¶

The basic skeleton of a SMASHDOCs-xml consists of the smashdoc-element, which contains a document, comments 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 comment-nodes are appended to the comments-node.

Example:

<?xml version='1.0' encoding='utf-8'?>
<smashdoc>
<document>
<paragraph>this is text</paragraph>
</document>
<comment>
</comment>
<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>


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>


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/>


### 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 indexes
• List of side notes

Example:

<directory type="content"/>


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

## Elements in comment node¶

### Comment¶

Conversation can be created with <comment> - element. <comment> - contains additional elements.

#### Section Id¶

Id of section with conversation, can be created with <section_id> - element

Example:

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


#### Conversation Type Key¶

Key of conversation type, can be created with <conversation_type_key> - element

Example:

<conversation_type_key>comment</conversation_type_key>


#### 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, can be created with <referenced_text> - element

Example:

<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>  #### Metadata¶ Metadata of the conversation contains field-elements with custom @name attribute value, can be inserted with <metadata> - element Example: <metadata> <field name="main_comment">Explain that</field> </metadata>  #### 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 conversation, can be inserted with <created_date> - element. Accepted in two formats. Example 1: <created_date>1536244040692</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>  #### Messages¶ Messages can be inserted with <messages> - element. There are different types of messages: • ConversationMessage.ResolutionMessage • ConversationMessage.UserAnswer • ConversationMessage.CreationMessage • ConversationMessage.ReferencedSectionMessage • ConversationMessage.CreationMessage.CreationPost <messages> - element can contain one or more <message>- elements that contain: <actor_id> or <creator_id> - creator of the message, <_cls> - type of the message, <metadata> - metadata of the message, <new_value> - new value of the resolution message, <content> - content of the message, <referenced_section_text> - referenced section text, <conversation_field_key> - conversation field key, <created_date> - date of the message creation. Example: <messages> <message> <actor_id>1b78083f-6d3b-4674-8e1f-b7441d3fba2c</actor_id> <_cls>ConversationMessage.CreationMessage</_cls> <metadata> <field name="main_comment">Explain that</field> </metadata> <created_date>1536244040699</created_date> </message> </messages>  The full example of <comment> - element: <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>
<field name="main_comment">Explain that</field>
<resolved>0</resolved>
<created_date>1536244040692</created_date>
<scope>
<_cls>ConversationScopeSelected</_cls>
<users>
<user_id>a551b833-d28e-4cdb-969d-7d64f63e08d0</user_id>
</users>
</scope>
<messages>
<message>
<actor_id>1b78083f-6d3b-4674-8e1f-b7441d3fba2c</actor_id>
<_cls>ConversationMessage.CreationMessage</_cls>
<field name="main_comment">Explain that</field>
<created_date>1536244040699</created_date>
</message>
</messages>
</comment>


## 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="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>
`