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, indexes, bibliographies, section-tags elements.

document node consists of ordered-sections and attached-sections nodes. ordered-sections-node contains sections in the order they appear in the document. attached-sections-node contains sections attached to the sections from the ordered-sections

All text, image, table and formula sections are appended to the ordered-sections-node in a document-node. The index-nodes are appended to the indexes-node. The comment-nodes are appended to the comments-node. Bibliographies are appended to the bibliographies - node and information about section tags is appended to section-tags - node.

The footnotes are appended to the attached-sections-node inside a document-node as paragraphs.

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

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

Additionally, there is a schematron file, which can be downloaded here: sd_xml_schematron.xml

Example:

<?xml version='1.0' encoding='utf-8'?>
<smashdoc version="2.20.2">
  <document>
    <ordered-sections>
        <paragraph>...</paragraph>
    </ordered-sections>
    <attached-sections>
        <paragraph>...</paragraph>
    </attached-sections>
  </document>
  <comments>
    <comment>
    </comment>
  </comments>
  <indexes>
  </indexes>
  <section-tags>
  </section-tags>
  <bibliographies>
  </bibliographies>
</smashdoc>

Elements in document node

All section elements are added as child nodes to the ordered-sections inside document-node. Section types are:

  • Paragraph

  • Image

  • Table

  • Formula

  • Directory Placeholder

Footnote sections are added as a child nodes to the attached-sections-node.

All section elements share a common pattern which relates to the version structure of the section and will be described based on the following example:

<paragraph | image | ...>
    <latest>
            <!-- ... inner elements of latest -->
    </latest>
    <history>
        <version ...>
            <!-- ... inner elements of version -->
        </version>
        <version ...>
            <!-- ... inner elements of version -->
        </version>
    </history>
</paragraph | image | ...>

The DTD extract shows, that:

<!ELEMENT latest (p|caption|source|column_width|tr|math|tex)*>
<!ELEMENT history (version)+>
<!ELEMENT version (p|caption|source|column_width|tr|tex)*>
<!ELEMENT paragraph (latest, history?)>
  • Each section element will have one child latest. Its child node(s) represent the latest state of the section.

  • Each section can have a child history, which contains at least one version that can be of 3 different types: LABEL_REWIND, VERSION or PD_STYLE. Its child nodes represent the history view for a certain version. For paragraph and image sections, the history view shows the diff between the versions. For image and formula sections, the version items do not show the diff, but just the state of the corresponding version.

The comments of the following dtd extract show the attributes of the version attributes.

<!ATTLIST version
        <!-- for paragraph elements: shows up, if action for the version was accept or decline. -->
        <!-- if the action was editing the text, it will not show up -->
        approval_type (accepted|declined) #IMPLIED
        <!-- user id of the author of this version -->
        author CDATA #REQUIRED
        <!-- timestamp in seconds of creation date of the version -->
        created_date CDATA #REQUIRED
        <!-- will be set to "1" if the section was already there, when the review mode started -->
        original CDATA #IMPLIED
        <!-- if @type = LABEL_REWIND: version count from where it was reverted -->
        from_version CDATA #IMPLIED
        to_revision CDATA #IMPLIED
        <!-- if @type = LABEL_REWIND: version id to which it was reverted -->
        type (LABEL_REWIND|PD_STYLE|PD_STYLE) #REQUIRED
        <!-- if @type = PD_STYLE: PD keys of previous PD and new style -->
        prev_style CDATA #IMPLIED
        new_style CDATA #IMPLIED>

Paragraph

Text paragraphs are represented by the paragraph-element.

Example:

<paragraph id="8bfc3cf6-66b2-0af7-42e7-bf5f6c87a691" alignment="left" indent="0" stylename="quick_text_0">
    <latest>
        <p>i am a paragraph</p>
    </latest>
</paragraph>

As only child of the latest-node is the p-node, which contains the text of the section.

With history, every version-element will contain one p-node. It will look like:

<paragraph id="8bfc3cf6-66b2-0af7-42e7-bf5f6c87a691" alignment="left" indent="0" stylename="quick_text_0">
    <latest>
        <p>i am a paragraph</p>
    </latest>
    <history>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902394" type="VERSION"
                 original="1">
            <p>i am a paragraph</p>
        </version>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902410" type="VERSION">
            <p>i am a paragraph<ins user="1e1db22d-3fc6-4133-8800-edab01a9df96"> this is added</ins></p>
        </version>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902419" type="VERSION"
                 approval_type="accepted">
            <p>i am a paragraph <insacc>this is added</insacc></p>
        </version>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902434" type="LABEL_REWIND"
                 from_version="0" to_revision="72b227d0-54d7-47cd-bc9b-ecd5e841e265"/>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902434" type="VERSION">
            <p>i am a paragraph <del user="1e1db22d-3fc6-4133-8800-edab01a9df96">this is added</del></p>
        </version>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902441" type="VERSION"
                 approval_type="accepted">
            <p>i am a paragraph <delacc user="1e1db22d-3fc6-4133-8800-edab01a9df96">this is added</delacc></p>
        </version>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1589453456" type="VERSION">
            <p>i am a <new-style user="1e1db22d-3fc6-4133-8800-edab01a9df96"><sub>paragraph</sub></new-style></p>
        </version>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1589453462" type="PD_STYLE" prev_style="text_1" new_style="uberschrift_1" />
    </history>
</paragraph>

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

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

Image

An image can be inserted with the image-element.

It contains two child nodes in each of the elements latest and version: The caption-node contains the image-caption. The source-node contains the filename of the image-file.

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

Example:

<image id="0c3f693a-2753-bf3d-05d3-c45d7495b4ac" alignment="center" indent="0" num-enabled="1" level="0"
       is-first-in-current-level="0" width="31.00%" numbering-value="1">
    <latest>
        <caption>i am the image caption</caption>
        <source>122b3090-17ef-47c5-a88b-69c8cfad518d.png</source>
    </latest>
    <history>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902355" type="VERSION"
                 original="1">
            <caption>i am the image caption</caption>
            <source>e06e386a-2d7b-4b3d-a4ba-91f42eda3511.png</source>
        </version>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902502" type="VERSION">
            <caption>i am the image caption</caption>
            <source>122b3090-17ef-47c5-a88b-69c8cfad518d.png</source>
        </version>
    </history>
</image>

Table

A table can be inserted with the table-element.

First child of latest/version 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 latest/version 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.

When exporting from SMASHDOCs, each table cell (td or th) will have the implied attributes i_r or i_c which represent the indexes of row/column where the cell is located in order to make calculations with merged cells more easy in further processing. For importing sd-xml to SMASHDOCs, these are not necessary.

Example:

<table id="061baac5-0fce-d726-f2d6-37f6194529c8" alignment="center" indent="0" num-enabled="1" level="0"
       is-first-in-current-level="0" width="100.00%" border-color="#000000" numbering-value="1">
    <latest>
        <caption>i am the table caption</caption>
        <column_width>
            <item>29.02097902097902%</item>
            <item>40.909090909090914%</item>
            <item>30.069930069930066%</item>
        </column_width>
        <tr min-height="6.3mm">
            <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                <p>i</p>
            </td>
            <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                <p>really</p>
            </td>
            <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                <p>am</p>
            </td>
        </tr>
        <tr min-height="6.3mm">
            <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                <p>a</p>
            </td>
            <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                <p>big</p>
            </td>
            <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                <p>table</p>
            </td>
        </tr>
    </latest>
    <history>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902323" type="VERSION"
                 original="1">
            <caption>i am the table caption</caption>
            <column_width>
                <item>50%</item>
                <item>50%</item>
            </column_width>
            <tr min-height="6.3mm">
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                    <p>i</p>
                </td>
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                    <p>am</p>
                </td>
            </tr>
            <tr min-height="6.3mm">
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                    <p>a</p>
                </td>
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                    <p>table</p>
                </td>
            </tr>
        </version>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902484" type="VERSION">
            <caption>i am the table caption</caption>
            <column_width>
                <item>29.02097902097902%</item>
                <item>40.909090909090914%</item>
                <item>30.069930069930066%</item>
            </column_width>
            <tr min-height="6.3mm">
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                    <p>i</p>
                </td>
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid" ins="1">
                    <p><ins>really</ins></p>
                </td>
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                    <p>am</p>
                </td>
            </tr>
            <tr min-height="6.3mm">
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                    <p>a</p>
                </td>
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid" ins="1">
                    <p><ins>big</ins></p>
                </td>
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                    <p>table</p>
                </td>
            </tr>
        </version>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902484" type="VERSION">
            <caption>i am the table caption</caption>
            <column_width>
                <item>29.02097902097902%</item>
                <item>40.909090909090914%</item>
                <item>30.069930069930066%</item>
            </column_width>
            <tr min-height="6.3mm">
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                    <p>i</p>
                </td>
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid" ins="1">
                    <p><ins>really</ins></p>
                </td>
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                    <p>am</p>
                </td>
            </tr>
            <tr min-height="6.3mm">
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                    <p>a</p>
                </td>
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid" ins="1">
                    <p><ins>big</ins></p>
                </td>
                <td font-size="11pt" stylename="table_cell_1" text-align="left" vertical-align="top" border-right="1.5pt #000000 solid" border-bottom="1.5pt #000000 solid"
                    border-top="1.5pt #000000 solid" border-left="1.5pt #000000 solid">
                    <p><new-style><b>table</b></new-style></p>
                </td>
            </tr>
        </version>
    </history>
</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.

Each SMASHDOCs system has configured paragraph styles. In order to apply a certain style on the table cell element (td or th), the attribute @stylename is used. Which values are valid for @stylename depends on the configuration of the SMASHDOCs system.

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

Borders pattern: {width} {color} {style}, supported border styles: solid, dotted, dashed, double, none.

@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" stylename="table_heading_1" vertical-align="middle" border-bottom="1.5pt #FFFFFF double"><p>This is the content of a table header field</p></th>
    <td font-size="10px" stylename="table_cell_1"><p><sd-sc><b><i><u><s>This is the content of normal table cell</s></u></i></b></sd-sc></p></td>
</tr>

Inside the history, the td/th-elements can have the attribute @ins="1"/@del="1", which means, that the cell is inserted or deleted.

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

  • Bibliography placeholder

Example:

<directory type="content"/>
<directory type="weblinks"/>
<directory type="bibliography" target-id="793e18e8-f56b-4c5a-9fa0-cd3d9752d9d8"/>

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

@target-id is used only by bibliography placeholder type to specify exact bibliography

Formulas

A Formula can be inserted with formula-element.

First child of the latest/version element is the caption element, which itself contains caption of the formula.

The body of the formula is described according to the MathML 1998 format in the second child element of the latest - math.

The last child element of latest/version is the tex-element, which contains exactly the tex-code entered by the user.

Example:

<formula id="1553202d-7ee2-0042-bb18-f3a14e7498fe" alignment="center" indent="0" num-enabled="1" level="0"
         is-first-in-current-level="0" numbering-value="1">
    <latest>
        <caption>i am the formula caption</caption>
        <math xmlns="http://www.w3.org/1998/Math/MathML">
            <mrow>
                <msup>
                    <mi>c</mi>
                    <mn>2</mn>
                </msup>
                <mo>=</mo>
                <msup>
                    <mi>a</mi>
                    <mn>2</mn>
                </msup>
                <mo>+</mo>
                <msup>
                    <mi>b</mi>
                    <mn>2</mn>
                </msup>
            </mrow>
        </math>
        <tex>c^2=a^2+b^2</tex>
    </latest>
    <history>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902376" type="VERSION"
                 original="1">
            <caption>i am the formula caption</caption>
            <tex>e=mc^2</tex>
        </version>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902516" type="VERSION">
            <caption>i am the formula caption</caption>
            <tex>c^2=a^2+b^2</tex>
        </version>
    </history>
</formula>

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

@level

specifies the numbering level for this section. Possible are 0 (standard) and 1

@is_first_in_current_level

possible values are 0 and 1

@numbering-value

defines current numbering value for this section

@xref-numbering-value

defines current numbering value for all cross-refs referring to this section, if different from @numbering-value

@xref-numbering-value is not required, and currently available only for some styles in text sections.

There are also two attributes, which can be used in order to store external information to a section and retrieve it after the export of the document:

@external_id

external id, which can be stored (optional)

@supplemental

field for storing any external data (optional)

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:

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

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

Footnote is a text section which is used for footnote content. A footnote can be created via the footnote-tag with href to a text section with a footnote content which is placed in the attached-sections-tag. Section with footnotes has child latest. It can has a child history, which contains at least one version that can be of 2 different types: VERSION or PD_STYLE. Elements that are allowed in footnote text sections are:

  • <a></a> - weblink

  • <xref></xref> - cross reference

  • <index></index> - index

  • <inline-file><inline-file> - inline file

  • <inline-image></inline-image> - inline image

  • <citation-link></citation-link> - citation links

  • <inline-formula></inline-formula> - inline formula

  • <br /> - soft return

  • <b></b> - inline styles

Elements that are not allowed in footnote text sections are:

  • <footnote></footnote> - footnote

  • <inline-checkbox></inline-checkbox> - checkbox

  • <sidenote></sidenote> - sidenote

Also, conversation can be added to a footnote section.

Example:

<ordered-sections>
    <paragraph id="50a97ce9-fa9d-bb81-2123-1316f1038a55" alignment="left" indent="0" stylename="text_1">
        <latest>
            <p>section with footnote <footnote href="08ba55b1-8c06-8ceb-bea7-08740143f867"></footnote>
            </p>
        </latest>
    </paragraph>
</ordered-sections>
<attached-sections>
    <paragraph id="08ba55b1-8c06-8ceb-bea7-08740143f867" alignment="left" indent="0" stylename="null">
        <latest>
            <p>footnote content added text </p>
        </latest>
        <history>
            <version author="c3196b0b-c733-45f0-8f98-9d5f789b210c" created_date="1590388463" type="VERSION" original="1">
                <p>footnote content</p>
            </version>
            <version author="c3196b0b-c733-45f0-8f98-9d5f789b210c" created_date="1590388471" type="VERSION">
                <p>footnote content<ins user="c3196b0b-c733-45f0-8f98-9d5f789b210c"> added text </ins></p>
            </version>
        </history>
    </paragraph>
</attached-sections>

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">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.

Inline Formula

An Inline Formula can be inserted with inline-formula-tag.

First child of the inline-formula element is the caption element, which itself contains caption of the formula.

The body of the formula is described according to the MathML 1998 format in the second child element - math.

@data-tex attribute is used to describe formula’s body in the TeX format

Example:

<paragraph indent="0" alignment="left" stylename="quick_text_0"
           id="5fd60994-2d84-fc4a-1614-98c8d5766bdd">paragraph
    <inline-formula data-tex="a^2">
        <caption/>
        <math xmlns="http://www.w3.org/1998/Math/MathML">
            <msup>
                <mi>a</mi>
                <mn>2</mn>
            </msup>
        </math>
    </inline-formula>
</paragraph>

Inline Image

An inline image can be inserted with the inline-image-tag.

The @src attribute contains the filename.

The caption can be set via the nested caption element.

Example:

<paragraph indent="0" alignment="left" stylename="quick_text_0"
           id="c7fb294b-eeee-ed7b-6e30-408e8936c213">second
    <inline-image src="e503bd5f-9fb5-4c75-8fdb-5beeeb0909da.jpg">
        <caption>capito</caption>
    </inline-image>
</paragraph>

Inline File

An inline file can be inserted with the inline-file-tag.

For the inline-file - tag there are nine attributes:

  • @data-file-id - id of the file

  • @id - id of the element

  • @fileDescription - description added on the file creation

  • @fileTitle - file title

  • @hash - hash based on the file data

  • @name - name of the file

  • @content-type - media type of the file

  • @created - date of the file creation

Example:

<paragraph indent="0" alignment="left" stylename="quick_text_0"
           id="dfe873b2-b50a-cd6f-b7c4-2fbac4268b8d">
    <inline-file data-file-id="a8186a12-852a-4ad0-9ca6-97875bddec65"
                 id="df64fd59-7698-fcdb-69d8-7580b2dc175b"
                 fileDescription="a lot of descrtiptip"
                 fileTitle="fiiiiiilelel" filePrefix="prefix"
                 hash="d4d1fc33ac8562032c510c36e2d81949b2ae9454"
                 name="1.docx"
                 content-type="application/vnd.openxmlformats-officedocument.wordprocessingml.document"
                 created="1570800513.952"></inline-file>
</paragraph>

Inline Checkbox

An inline checkbox can be inserted with the inline-checkbox-tag.

@data-state-attribute represents whether checkbox was checked or not and @id is an id of the element.

<paragraph indent="0" alignment="left" stylename="quick_text_0"
           id="60fd8df6-875f-e0a5-5c54-5d771e2edd8a">
    <inline-checkbox data-state="0"
                     id="99a445b7-30ef-0d6e-3fc9-d32dceb48d83"></inline-checkbox>
    checkbox
</paragraph>

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>

Bibliographies

Bibliographies are inserted with <bibliographies> element. They represent all the bibliographies with the citations in a document.

Bibliography

Bibliography is created with <bibliography> element.

Attributes for <bibliography> element:

@name

Bibliography name

@style_key

Key of the bibliography style

@indent

Bibliography id

To represent citations <bibliography> contains additional element - <citations>.

Every citation is represented as a <citation> element in the <citations>.

Citation

Attributes for <citation> element:

@id

id of Citation

@citation-type

Type of the citation

<citation> contains <meta-information> elements with all the citation data inside.

Attributes for <meta-information> element:

@key

name of the citation field

@value

value of the citation field

Complete example of the <bibliographies> element:

<bibliographies>
    <bibliography name="mybib" style_key="ieee" id="793e18e8-f56b-4c5a-9fa0-cd3d9752d9d8">
        <citations>
            <citation id="a56cdca8-99bc-4ecf-ace2-d07102323019" citation-type="book">
                <meta-information key="author" value="Peter Babington"/>
                <meta-information key="title" value="Famous Houses"/>
            </citation>
        </citations>
    </bibliography>
</bibliographies>

Section Tags

Information about section tags is placed in <section-tags>-element. Every section tag is a separate inner <section-tag>-element.

@section-id attribute contains id of the section which is marked by this tag. @tag-type-key - type of the applied tag.

The only child element of section-tag is the tag-field element which contains information about tag itself. @key and @value contain information about name and value of the tag.

Example:

<section-tags>
    <section-tag section-id="115fe017-fe46-2302-d1a8-307d525ff0fb"
                 tag-type-key="priority">
        <tag-field key="priority" value="2"/>
    </section-tag>
</section-tags>