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, a folder images with the image files inside and a folder inline-files with files inside.

sdox-file
├── sd.xml
└── inline-files
    ├── my_file.pdf
    └── another_file.pdf
└── 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.25.0.

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.25.0">
  <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
Division Separator

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.

When exported with document version comparison version-node of image, formula and table sections will have attributes @ins="1" or @del="1". This attributes indicate the state of section itself:

Section state	Number of history entries	Attribute values
Section was created Section was deleted Section was changed Section wasn’t changed	1 1 2 1	`@ins="1"` `@del="1"` `@del="1"` on first entry and `@ins="1"` on second nothing added

In addition to @ins and @del attributes in history there will be @ins or @del attribute on the image, formula and table nodes if section was created or deleted.

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
        <!-- index number of version entry as non-negative integer -->
        idx %string
        <!-- Optional comparison attributes -->
        del (0|1) #IMPLIED
        ins (0|1) #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>
        <redline>
            <p>i am a paragraph</p>
        </redline>
    </latest>
</paragraph>

The only mandatory child of the latest-node is the p-node, which contains the text of the section. There also optionally can be redline-node, which is present only in version comparison export. This node contains text of the section with all redline tags (e.g. ins or del) which may be not present in latest.p-node.

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" idx="0">
            <p>i am a paragraph</p>
        </version>
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902410" type="VERSION" idx="1">
            <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" idx="2">
            <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"/ idx="3">
        <version author="1e1db22d-3fc6-4133-8800-edab01a9df96" created_date="1582902434" type="VERSION" idx="4">
            <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" idx="5">
            <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" idx="6">
            <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" idx="7"/>
    </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" idx="0">
            <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" idx="1">
            <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" table-type = "layout_table" table-name="table" 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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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" idx="0">
            <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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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" idx="1">
            <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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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" idx="2">
            <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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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" cell-type="standard" 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 @cell-type is used. Which values are valid for @cell-type 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.

@cell-type can be used to assign a specific type, including: standard, standard_1 … standard_5, header, currency_dollar, currency_euro, number, percent, leader_column_1 … leader_column_6. This cell types represent different styles in which cells are displayed.

Note: for currency_dollar, currency_euro the $/€ sign is NOT included in the table content but for the percent cell-type % IS included.

Example in sd-xml:

<tr min-height="6.3mm">
    <td font-size="11pt"
        border-right="0.8pt #000000 solid" i_r="0" i_c="0"
        ...
        cell-type="standard | header | currency_euro | leader_column_1 | ..." <--- new field (optional)
    />
        <p/>
    </td>
    ...
</tr>

@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" cell-type="header" 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" cell-type="standard"><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" idx="0">
            <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" idx="1">
            <caption>i am the formula caption</caption>
            <tex>c^2=a^2+b^2</tex>
        </version>
    </history>
</formula>

Division Separator ¶

A Division Separator can be inserted with division-separator-element.

Example:

<division-separator id="9a8e29e4-a674-f5ce-73d6-21db7df9c787" name="F-pages custom"
                    key="f_pages_with_dot" frame="1" oncePerDoc="1" numberingRule="restart"
                    numberingPrefix="F-" numberingSuffix="." numberingFormat="arabic" numberingPosition="right"/>

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.

@table-type can be set to data_table, layout_table, financial_table or text_table and can be used only for tables.

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.

@data-pagenumber-enabled (can be 0 or 1) sets, whether the page number of the target is displayed. The cross-reference will be displayed in the document via a corresponding icon with a number of page.

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" idx="0">
                <p>footnote content</p>
            </version>
            <version author="c3196b0b-c733-45f0-8f98-9d5f789b210c" created_date="1590388471" type="VERSION" idx="1">
                <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. <sidenote>This is my sidenote-text.</sidenote></paragraph>
<paragraph><sidenote>test<br/>sidenote<br/>with<br/>multiple<br/>lines</sidenote></paragraph>

Weblink ¶

In order to insert a weblink, the anchor-tag with @href can be used. The anchor-tag itself can contain only #PCDATA.

Example:

<paragraph>You will find at <a href="http://myurl.com">click here</a></paragraph>

Citation Link ¶

A citation link can be created via citation-link-tag.

Id of the citation is placed in @data-citation-id attribute.
Id of the bibliography is placed in @data-bibliography-id attribute.
A link to load citation information is placed in @public-link attribute.

Example:

<paragraph>
    the temperature was lower <citation-link data-citation-id="a56cdca8-99bc-4ecf-ace2-d07102323019" data-bibliography-id="6a176b87-eee9-7acb-ac98-6e501c3b90bc" public-link="https://develop2.smashdocs.net/document/915c222a-ee4d-4132-977a-b8bdd2784dd8/bibliography-modal?bibliography-id=6a176b87-eee9-7acb-ac98-6e501c3b90bc&amp;citation-id=a56cdca8-99bc-4ecf-ace2-d07102323019"></citation-link>
</paragraph>

Mention ¶

A mention can be created with <mention>.

Example:

``<mention user="12345"></mention>``

A mention can be used to:

Select users as assignees.
Mention users in comment.

All comment types have this functionality. Also user names from mentions are shown in exports.

Indexes ¶

Index(publishing) - is a list of words or phrases (headings/titles) and associated pointers (references) 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>

Due Date Change Message ¶

Message to inform all users about the changed .

Additional fields:

<actor_id> - id of the user who changed the due date
<new_value> - new due date

Example:

<message>
    <_cls>ConversationMessage.DueDateChangeMessage</_cls>
    <created_date>1618489408</created_date>
    <actor_id>971f77a8-3ae4-4c01-a58c-e25d41570edc</actor_id>
    <new_value>None</new_value>
</message>

Assignees Change Message ¶

Message to inform about change of assignees.

Additional fields:

<actor_id> - id of the user who changed the assignees
<old_value> - old assignees user IDs
<new_value> - new assignees user IDs

Example:

<message>
    <_cls>ConversationMessage.AssigneesChangeMessage</_cls>
    <created_date>1618492233</created_date>
    <actor_id>971f77a8-3ae4-4c01-a58c-e25d41570edc</actor_id>
    <new_value>
        <user_id>371f77a8-3ae4-4c01-a58c-e25d41570edc</user_id>
        <user_id>971f77a8-3ae4-4c01-a58c-e25d41570edc</user_id>
        <user_id>171f77a8-3ae4-4c01-a58c-e25d41570edc</user_id>
    </new_value>
    <old_value>
        <user_id>371f77a8-3ae4-4c01-a58c-e25d41570edc</user_id>
        <user_id>971f77a8-3ae4-4c01-a58c-e25d41570edc</user_id>
    </old_value>
</message>

Invitation Message ¶

Message to inform about an invitation.

Additional fields:

<actor_id> - id of the user who was inviting
<invitee_ids> - IDs of users who was invited

<message>
    <_cls>ConversationMessage.InvitationMessage</_cls>
    <created_date>1618489398</created_date>
    <actor_id>971f77a8-3ae4-4c01-a58c-e25d41570edc</actor_id>
    <invitee_ids>
        <user_id>371f77a8-3ae4-4c01-a58c-e25d41570edc</user_id>
        <user_id>171f77a8-3ae4-4c01-a58c-e25d41570edc</user_id>
    </invitee_ids>
</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>

Division Separators ¶

Information about all available for document division separators is placed in <division-separators>-element. Every division separator is a separate inner <division-separators>-element.

Example:

<division-separators>
    <division-separator key="f_pages" presetKey="ipo_prospectus_us"
                        frame="0" oncePerDoc="0" numberingRule="restart"
                        numberingPrefix="F-" numberingFormat="arabic"
                        numberingPosition="centered">
        <translatedName>
            <item lang="de_DE">F-pages</item>
            <item lang="en_EN">F-pages</item>
            <item lang="es_ES">F-pages</item>
            <item lang="fr_BE">F-pages</item>
            <item lang="fr_CA">F-pages</item>
            <item lang="fr_FR">F-pages</item>
            <item lang="nl_BE">F-pages</item>
            <item lang="ru_RU">F-pages</item>
        </translatedName>
    </division-separator>
    <division-separator key="f_pages_with_dot" frame="1" oncePerDoc="1"
                        numberingRule="restart" numberingPrefix="F-"
                        numberingSuffix="." numberingFormat="arabic"
                        numberingPosition="right">
        <translatedName>
            <item lang="de_DE">F-pages custom</item>
            <item lang="en_EN">F-pages custom</item>
            <item lang="es_ES">F-pages custom</item>
            <item lang="fr_BE">F-pages custom</item>
            <item lang="fr_CA">F-pages custom</item>
            <item lang="fr_FR">F-pages custom</item>
            <item lang="nl_BE">F-pages custom</item>
            <item lang="ru_RU">F-pages custom</item>
        </translatedName>
    </division-separator>
    <division-separator key="cover_outside_back_prospectus" frame="0"
                        presetKey="ipo_prospectus_us" oncePerDoc="0"
                        numberingFormat="none">
        <translatedName>
            <item lang="de_DE">Back Cover</item>
            <item lang="en_EN">Back Cover</item>
            <item lang="es_ES">Back Cover</item>
            <item lang="fr_BE">Back Cover</item>
            <item lang="fr_CA">Back Cover</item>
            <item lang="fr_FR">Back Cover</item>
            <item lang="nl_BE">Back Cover</item>
            <item lang="ru_RU">Back Cover</item>
        </translatedName>
    </division-separator>
</division-separators>

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>