Star Document Markup Specifications

All Star Document Markup tags have exactly the same structure, which makes it easy to parse them.

Each tag is enclosed in square brackets [ / ], with a command name followed by a number of parameter names and values.

Star Document Markup Format

The general structure of Star Document Markup tags is as follows:

[<tag>: <parameter>: <value>; <parameter>: <value>; <parameter>: <value>; ....]

`<tag>`	Indicates a markup tag. If parameters need to be specified, a tag must be followed by a single colon `:`.
`<parameter>`	Each parameter has a single name (without spaces). For readability, it may optionally be followed by a colon `:`. Any space (including carriage returns) before a parameter name is ignored.
`<value>`	A parameter value contains all characters, including spaces, up to a semicolon `;` or tag terminating square bracket `]`.

Samples

Simple tags

The simplest tag is simply a command name enclosed in square brackets. It can be mixed with UTF8-encoded plain text.
In the following example, the text "Hello World!" is printed with the paper cut:

Hello World!
 [cut]

Adding parameters

Most tags support additional parameters.
For example, you can specify an alignment tag as follows:

[align: right]Right aligned text
 [align: left]Left aligned text

Parameters with values

Parameters can sometimes be specified alone but usually require a value.
Each value can be provided after a parameter name and separated from the parameter name by one or more spaces.
For example, you can set the text width magnification as follows:

[magnify: width 2]Double Width Text [magnify: width 1]Single Width Text

Multiple parameters

It is possible to supply several parameters as needed.
Each parameter/value set is separated by a semicolon ;.
Example:

[magnify: width 2; height 2]Double Width and Double Height text

Readability

Simply for readability purposes, a colon : can be placed after a parameter name. This must still be followed by a space. It has no operating effect.
This can make the functionality clearer when a value contains text with spaces.
The following is an example when performing a two-column layout:

[column: left Large Vegetable Soup; right £4.50]

Placing a colon after a parameter name increases readability.

[column: left: Large Vegetable Soup; right: £4.50]

It is also acceptable to put an additional space before a parameter name. Any space before a parameter name is ignored.

[column: left: Large Vegetable Soup;              right: £4.50]
 [column: left: Garlic Bread;                      right: £3.00]
 [column: left: Olives; right:                            £1.50]

A space can also include a line break.

[image: url https://star-emea.com/wp-content/uploads/2015/01/logo.jpg;
         width 60%;
         min-width 48mm]

Escaping

Some characters cannot be included in print text due to a conflict between the Star Document Markup tag syntax and the word wrapping feature.
Therefore, these can be escaped with a backslash \.

Escaping print characters

Escapable print characters are:

Open square bracket [. To print this character, use \[.
Close square bracket ]. To print this character, use \].
Backslash \. To print this character, use \\.
Space . To print this character, use \ followed by a single space, like \ .

Example:

This will print a markup command, instead of acting on it.
 \[cut\]

Escaping line breaks

If \ is used at the end of a line (example: immediately before a carriage return or line feed), it will prevent any line break from being output.
This is used to insert a line break into markup data without interrupting the word-wrapping flow.

This method is also useful for placing markup tags in a single line without causing a line break.

Example:

[align: middle]\
 [barcode: type code39;
           data 123456789012;
 		  height 15mm;
 		  module 0;
  		  hri]
 [align]\
 Thank you for trying the new Star Document Markup Language\
 we hope you will find it useful. Please let us know!
 [cut: feed; partial]

Note:
Since escaped line breaks always cause a word break, you cannot span a single long word into multiple rows.

Word Wrapping

To make the paper size, printable area, resolution, and font size easily adjustable among different output devices, Star Document Markup automatically performs word wrapping when outputting a document.

Word wrapping allows developers to manage the content of a document without the need to manage the layout for each device.

Note:
Word Wrapping feature with Unicode character is only supported on mC-Print2 / mC-Print3 / mC-Label3 / TSP100IV / TSP100IVSK /TSP650II.

Word wrapping results

The following text is used as test data:

This is a test of word wrapping when targeting point of sale printers of varying size, and print widths. Star Markup language makes this easy to manage automatically.

The following tabs show the output results when sending normal plain text and when sending a print job generated using Star Document Markup to Star printers with different paper widths:

Text Star Markup 58 mm Star Markup 80 mm Star Markup 112 mm

This is the result when sending plain text directly to an mC-Print2 58mm (2inch) printer without using Star Document Markup.

Sample01 Output

This is the result when sending a print job generated using Star Document Markup to a mC-Print2 58mm (2inch) printer.

Sample01 Output

This is the result when sending a print job generated using Star Document Markup to an mC-Print3 80mm (3inch) printer.

Sample01 Output

This is the result when sending a print job generated using Star Document Markup to a Star TSP800II 122mm (4inch) printer.

Sample01 Output

Mixing the font and magnification

When a Star Document Markup document is rendered into printer native commands, the font size and magnification are tracked by the engine.
This makes it possible to mix different fonts and character magnifications in a single row while maintaining word wrapping.

Word wrapping and spacing

For Star Document Markup documents, word wrapping is performed in a similar way to HTML. Each word is separated by a space (such as a series of spaces) and identified as a series of printable characters. Spaces are treated as word separators, not as content.
Therefore, it is not possible to insert multiple spaces between words or use spaces to perform formatting (such as a column layout) as commonly done by conventional POS software. This specification is so intentional that documents are automatically reformatted according to the print width or character size.

Star Document Markup provides alternative methods to achieve general layout designs with easy adjustment through various form elements.

If it is necessary to output a specific number of spaces, you can escape the spaces or use the [space] markup tag.

Word wrapping and Star Document Markup tags

Markup tags may or may not cause a word break depending on their function.

Text decoration tags, such as [bold] and [underline], cause a word break.
Therefore, [bold: on]B[bold: off]old renders the text as the single word "Bold" with the character "B" in bold.

Non-text print tags and any type of feed, such as [feed], [image], and [barcode], cause a word break.

Conventions

Abbreviations

The primary purpose of choosing tag and parameter names is readability.
For some tag names and parameter names that are considered to maintain readability, abbreviated versions of names are available.

Example:

[magnification: width 3; height 2]

The following is functionally the same as the above.

[mag: w 3; h 2]

For details, refer to the manual of the corresponding Star Document Markup tag.

Default parameters

Tags that affect the rendering (example: text drawing) state, such as [magnification] and [align], typically require parameters to be specified.
If they are used without parameters, they will be reset to the defaults.

Example:

This is standard sized text
 [mag: w 2]Double Width Text[mag]
 This is standard sized text again.

For details, refer to the manual of the corresponding Star Document Markup tag.

Specifying Sizes

Star Document Markup is intended to help developers by generating output data automatically adjusted according to the printer paper width, emulation, and resolution as much as possible.

To accommodate this purpose, each length tag can be specified relative to the paper width without depending on the printer resolution.

Length types

You can specify the length in the following ways:

Printer dots
Length specified based on printer dots. Specifying only a value is regarded as this format.
This is not recommended because data is not appropriately rendered on output devices with different resolutions or paper widths.
```
[image: url https://website.com/logo.jpg; width 300]
```
This outputs an image resized to 300 dots, regardless of the paper size or printer dot physical size.
Millimeters
You can specify the actual length to be output in millimeters by adding mm when specifying a value.
In this format, the value is calculated so that it is output in the specified size based on the resolution of the set output device.
```
[image: url https://website.com/logo.jpg; width 40mm]
```
This outputs an image of 40 mm in width to all printers, regardless of the paper size or resolution.
Percentage of print width
You can specify the relative length in percentage by adding % when specifying a value.
In this format, the value is calculated relative to the set print area and paper size. This format is useful for adjusting the image element size according to the required layout.
```
[image: url https://website.com/logo.jpg; width 60%]
```
This outputs an image resized to 60% of the print width of the printer.

Note:
Specification with the inch unit is not currently supported.

Combining length types

Some tags allow additional length constraints to be specified. In this case, it is useful for mixing different length unit types in a single tag.
For example, the [image] tag allows the minimum size to be specified.

[image: url https://website.com/logo.jpg; width 60%; min-width 48mm]

This requires the image to be printed at 60% of the printable width, but not less than 48 mm.
The purpose of this function is to print images at an appropriate size on all printers, including 58mm/2inch models, where 60% of the printable area is too small.

Unicode Support

Star Markup language avoids difficulties of limited 8-bit text encodings by being entirely Unicode based. Input data should be from a Unicode compatible data file or strings.

Where a device does support Unicode directly, the Star markup renderer will automatically handle the necessary conversion.

Devices with Unicode support:

Star mC-Print2
Star mC-Print3
Star TSP100IV
Star TSP100IV SK
Star mC-Label3
Star TSP654II

File Format

Start Document Markup source files are plain text files encoded as UTF-8, UTF-16, or plain ASCII data.

When you open a document, the beginning of the file is first checked with a Unicode BOM (Byte Order Mark) to recognize that the file contains UTF-16 (UTF-16BE/UTF-16LE) or UTF-8 data. If no existing BOM is found, the file is treated as an UTF-8 file, unless it contains code points that are invalid in UTF-8. In such cases, the file ends up being opened as plain 7-bit ASCII data.

The extension of a text file written in Star Document Markup format must be ".stm." CPUtil or .NET API in the StarMicronics.CloudPRNT-Utility package checks the ".stm" extension of a file name to confirm that the file is in Star Document Markup format. If the extension is ".txt," it is recognized as a plain text file, preventing Star Document Markup tags from being parsed.

Note:
7-bit ASCII data is 100% compatible with the UTF-8 encoding scheme.
Therefore, the fallback method of using ASCII encoding to read input files causes some degree of information loss because source data is not actually encoded to ASCII.

We strongly recommend that markup input files always be encoded as UTF-8 or UTF-16.