BlueGit

timfa posprint

Files

posprint / docs / HELP.md

HELP.md

HELP.md 4.6 KiB Download Raw

posprint Help

Built-in reference for the template editor and POS markup language.

---

Application tabs

TabPurpose
EditorWrite and edit template source
PreviewLive preview of rendered output
HelpThis documentation

Toolbar actions

ActionDescription
NewEmpty template with defaults
OpenLoad a .pos file
Save / Save AsWrite JSON .pos file (metadata + body)
InsertMenu to insert images, barcodes, QR codes, @feed, @cut
PrintSubstitute parameters, pick USB printer, send ESC/POS bytes

Editor assistance

  • Type @ at the start of a line to see directive autocomplete (feed, cut, image, barcode, qr).
  • Use Insert → Barcode / QR code to pick native or raster type before inserting a snippet.

Page settings

SettingDescription
Page width (mm)Paper width, typically 58 or 80
Preview modeAuto-scale fits preview to panel; Fixed uses exact mm width
Code pageCharacter encoding sent to printer (default CP437)
Cut after printAppend paper feed + cut if template has no @cut

---

Template language

A template is plain text: paragraphs, headings, directives, and inline markup.

Paragraphs

Consecutive non-empty lines form one paragraph.

Headings

# Large heading
## Bold heading

Alignment

:left:, :center:, or :right: before a paragraph.

Inline markup

SyntaxEffect
**text**Bold
*text*Italic
text Monospace
${Name}Parameter (filled at print time)

Horizontal rule

---

Comments

<!-- not printed -->

---

Directives

Directives start with @ at the beginning of a line.

Paper feed / cut

@feed 3
@cut

Image

@image logo.png
@image ${LogoPath} width=50% align=center

Barcode

Native (printer draws barcode via ESC/POS):

@barcode CODE128 ${OrderId}
@barcode UPC-A 012345678905
@barcode ITF 12345678 height=80

Raster (rendered as bitmap — works with any symbology below). Raster barcodes are stretched horizontally to the full paper width for reliable scanning; height follows the height attribute.

@barcode RASTER CODE128 ${OrderId}
@barcode RASTER CODE93 ABC-1234
Native symbologyNotes
CODE128Alphanumeric
EAN13, EAN8Numeric
CODE39Alphanumeric
UPC-A, UPC-ENumeric
ITFInterleaved 2 of 5; even digit count
CODABARNumeric + A-D start/stop
Raster-only symbologyUse RASTER prefix
CODE93, CODE11No native ESC/POS in firmware
AttributeDescription
heightHeight in dots (default 64; raster PNG height)
alignleft, center, right
show_textNative only: human-readable text under barcode

QR code

Native (ESC/POS QR, model 2):

@qr https://example.com/${Id}
@qr ${Url} size=6 ecc=H align=center

Raster (bitmap; supports QR versions 1–40):

@qr RASTER https://example.com/${Id}
@qr RASTER ${Url} version=5 scale=4 ecc=M
AttributeNativeRaster
sizeModule dot size 1–16—
scale—Pixels per module (default 4)
version—QR version 1–40 (optional; auto if omitted)
eccL, M, Q, HSame
alignleft, center, rightSame

---

Parameters

${ParameterName} in text, barcode data, QR data, or image paths.

  • Same name → one input at print time (GUI or CLI).
  • CLI requires every parameter via --set Name=Value.

---

Example receipt

# ${StoreName}
:center:

Receipt: ${DocumentNumber}

@barcode CODE128 ${DocumentNumber}
@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4

@feed 4
@cut

---

GUI printing (USB)

1. Print → enter parameters → choose serial port → Print.

Linux: dialout group. Windows: printer appears as COMx.

---

.pos file format

JSON with version, metadata, and body (template source).

MIME type: application/x-posprint (extension *.pos). On Linux, after installing the package, set posprint as the default opener if needed:

xdg-mime default posprint.desktop application/x-posprint
xdg-mime query filetype ~/Templates/receipt.pos   # should print application/x-posprint
Source
1# posprint Help
2
3Built-in reference for the template editor and POS markup language.
4
5---
6
7## Application tabs
8
9| Tab | Purpose |
10|-----|---------|
11| **Editor** | Write and edit template source |
12| **Preview** | Live preview of rendered output |
13| **Help** | This documentation |
14
15## Toolbar actions
16
17| Action | Description |
18|--------|-------------|
19| **New** | Empty template with defaults |
20| **Open** | Load a `.pos` file |
21| **Save / Save As** | Write JSON `.pos` file (metadata + body) |
22| **Insert** | Menu to insert images, barcodes, QR codes, `@feed`, `@cut` |
23| **Print** | Substitute parameters, pick USB printer, send ESC/POS bytes |
24
25## Editor assistance
26
27- Type `@` at the start of a line to see **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`).
28- Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.
29
30## Page settings
31
32| Setting | Description |
33|---------|-------------|
34| **Page width (mm)** | Paper width, typically `58` or `80` |
35| **Preview mode** | `Auto-scale` fits preview to panel; `Fixed` uses exact mm width |
36| **Code page** | Character encoding sent to printer (default `CP437`) |
37| **Cut after print** | Append paper feed + cut if template has no `@cut` |
38
39---
40
41## Template language
42
43A template is plain text: paragraphs, headings, directives, and inline markup.
44
45### Paragraphs
46
47Consecutive non-empty lines form one paragraph.
48
49### Headings
50
51```markdown
52# Large heading
53## Bold heading
54```
55
56### Alignment
57
58`:left:`, `:center:`, or `:right:` before a paragraph.
59
60### Inline markup
61
62| Syntax | Effect |
63|--------|--------|
64| `**text**` | Bold |
65| `*text*` | Italic |
66| `` `text` `` | Monospace |
67| `${Name}` | Parameter (filled at print time) |
68
69### Horizontal rule
70
71```markdown
72---
73```
74
75### Comments
76
77```markdown
78<!-- not printed -->
79```
80
81---
82
83## Directives
84
85Directives start with `@` at the beginning of a line.
86
87### Paper feed / cut
88
89```markdown
90@feed 3
91@cut
92```
93
94### Image
95
96```markdown
97@image logo.png
98@image ${LogoPath} width=50% align=center
99```
100
101### Barcode
102
103**Native** (printer draws barcode via ESC/POS):
104
105```markdown
106@barcode CODE128 ${OrderId}
107@barcode UPC-A 012345678905
108@barcode ITF 12345678 height=80
109```
110
111**Raster** (rendered as bitmap — works with any symbology below). Raster barcodes are stretched horizontally to the full paper width for reliable scanning; height follows the `height` attribute.
112
113```markdown
114@barcode RASTER CODE128 ${OrderId}
115@barcode RASTER CODE93 ABC-1234
116```
117
118| Native symbology | Notes |
119|----------------|-------|
120| `CODE128` | Alphanumeric |
121| `EAN13`, `EAN8` | Numeric |
122| `CODE39` | Alphanumeric |
123| `UPC-A`, `UPC-E` | Numeric |
124| `ITF` | Interleaved 2 of 5; even digit count |
125| `CODABAR` | Numeric + A-D start/stop |
126
127| Raster-only symbology | Use `RASTER` prefix |
128|-----------------------|---------------------|
129| `CODE93`, `CODE11` | No native ESC/POS in firmware |
130
131| Attribute | Description |
132|-----------|-------------|
133| `height` | Height in dots (default `64`; raster PNG height) |
134| `align` | `left`, `center`, `right` |
135| `show_text` | Native only: human-readable text under barcode |
136
137### QR code
138
139**Native** (ESC/POS QR, model 2):
140
141```markdown
142@qr https://example.com/${Id}
143@qr ${Url} size=6 ecc=H align=center
144```
145
146**Raster** (bitmap; supports QR versions 1–40):
147
148```markdown
149@qr RASTER https://example.com/${Id}
150@qr RASTER ${Url} version=5 scale=4 ecc=M
151```
152
153| Attribute | Native | Raster |
154|-----------|--------|--------|
155| `size` | Module dot size 1–16 | — |
156| `scale` | — | Pixels per module (default `4`) |
157| `version` | — | QR version 1–40 (optional; auto if omitted) |
158| `ecc` | `L`, `M`, `Q`, `H` | Same |
159| `align` | `left`, `center`, `right` | Same |
160
161---
162
163## Parameters
164
165`${ParameterName}` in text, barcode data, QR data, or image paths.
166
167- Same name → **one input** at print time (GUI or CLI).
168- CLI requires **every** parameter via `--set Name=Value`.
169
170---
171
172## Example receipt
173
174```markdown
175# ${StoreName}
176:center:
177
178Receipt: ${DocumentNumber}
179
180@barcode CODE128 ${DocumentNumber}
181@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
182
183@feed 4
184@cut
185```
186
187---
188
189## GUI printing (USB)
190
1911. **Print** → enter parameters → choose serial port → **Print**.
192
193**Linux:** `dialout` group. **Windows:** printer appears as `COMx`.
194
195---
196
197## `.pos` file format
198
199JSON with `version`, `metadata`, and `body` (template source).
200
201**MIME type:** `application/x-posprint` (extension `*.pos`). On Linux, after installing the package, set posprint as the default opener if needed:
202
203```bash
204xdg-mime default posprint.desktop application/x-posprint
205xdg-mime query filetype ~/Templates/receipt.pos # should print application/x-posprint
206```