BlueGit

timfa posprint

Files

posprint / docs / HELP.md

HELP.md

HELP.md 4.3 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)
PrintSubstitute parameters, pick USB printer, send ESC/POS bytes

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.

Thank you for your visit!
Please come again.

Headings

# Large heading (store name)
## Bold heading (section title)

Alignment

Prefix a paragraph with :left:, :center:, or :right: (default is left).

:center:
Your Store Name

Inline markup

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

Horizontal rule

---

Comments (not printed)

<!-- note to designer only -->

---

Directives

Directives start with @ at the beginning of a line.

Paper feed

@feed 3

Feeds three blank lines.

Cut paper

@cut

Partial cut (if the printer supports it).

Image

@image logo.png
@image ${LogoPath} width=50%
@image promo.png width=384 align=center
AttributeDescription
PathFile relative to the .pos file, or ${Parameter}
widthNN% of printable width or dots (e.g. 384)
alignleft, center, right

Barcode

@barcode CODE128 ${OrderId}
@barcode EAN13 5901234123457 height=80 show_text=true
FieldValues
SymbologyCODE128, EAN13, EAN8, CODE39
DataLiteral text or ${Parameter}
heightHeight in dots (default 64)
alignleft, center, right
show_texttrue / false — human-readable text under barcode

QR code

@qr https://example.com/receipt/${DocumentNumber}
@qr ${PaymentUrl} size=6 ecc=M align=center
AttributeDescription
DataURL or text; may include ${Parameter}
sizeModule size 1–16 (default 4)
eccError correction: L, M, Q, H
alignleft, center, right

---

Parameters

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

  • Names: letters, digits, underscore; must start with a letter or _.
  • Same name → one input at print time; all occurrences receive the same value.
  • The print dialog pre-fills values from the last print session.

---

Example receipt

# ${StoreName}
:center:

123 Main Street

---
Receipt: ${DocumentNumber}
Date: ${Date}

${LineItems}

---
:right:
**TOTAL: ${GrandTotal}**

@barcode CODE128 ${DocumentNumber}
@feed 2
@qr https://shop.example.com/r/${DocumentNumber}

Thank you!
@feed 4
@cut

---

Printing (USB)

1. Click Print. 2. Enter parameter values in the dialog. 3. Choose a USB serial printer from the list (refresh if needed). 4. The app sends raw ESC/POS bytes directly to the port (no system print spooler).

Linux: your user must be in the dialout group to access serial devices.

Windows: the printer usually appears as COM3, COM4, etc.

---

.pos file format

JSON file with extension .pos:

  • version — format version (currently 1)
  • metadata — page width, preview mode, code page, etc.
  • body — template source string
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| **Print** | Substitute parameters, pick USB printer, send ESC/POS bytes |
23
24## Page settings
25
26| Setting | Description |
27|---------|-------------|
28| **Page width (mm)** | Paper width, typically `58` or `80` |
29| **Preview mode** | `Auto-scale` fits preview to panel; `Fixed` uses exact mm width |
30| **Code page** | Character encoding sent to printer (default `CP437`) |
31| **Cut after print** | Append paper feed + cut if template has no `@cut` |
32
33---
34
35## Template language
36
37A template is plain text: paragraphs, headings, directives, and inline markup.
38
39### Paragraphs
40
41Consecutive non-empty lines form one paragraph.
42
43```markdown
44Thank you for your visit!
45Please come again.
46```
47
48### Headings
49
50```markdown
51# Large heading (store name)
52## Bold heading (section title)
53```
54
55### Alignment
56
57Prefix a paragraph with `:left:`, `:center:`, or `:right:` (default is left).
58
59```markdown
60:center:
61Your Store Name
62```
63
64### Inline markup
65
66| Syntax | Effect |
67|--------|--------|
68| `**text**` | Bold |
69| `*text*` | Italic |
70| `` `text` `` | Monospace |
71| `${Name}` | Parameter (filled at print time) |
72
73### Horizontal rule
74
75```markdown
76---
77```
78
79### Comments (not printed)
80
81```markdown
82<!-- note to designer only -->
83```
84
85---
86
87## Directives
88
89Directives start with `@` at the beginning of a line.
90
91### Paper feed
92
93```markdown
94@feed 3
95```
96
97Feeds three blank lines.
98
99### Cut paper
100
101```markdown
102@cut
103```
104
105Partial cut (if the printer supports it).
106
107### Image
108
109```markdown
110@image logo.png
111@image ${LogoPath} width=50%
112@image promo.png width=384 align=center
113```
114
115| Attribute | Description |
116|-----------|-------------|
117| Path | File relative to the `.pos` file, or `${Parameter}` |
118| `width` | `NN%` of printable width or dots (e.g. `384`) |
119| `align` | `left`, `center`, `right` |
120
121### Barcode
122
123```markdown
124@barcode CODE128 ${OrderId}
125@barcode EAN13 5901234123457 height=80 show_text=true
126```
127
128| Field | Values |
129|-------|--------|
130| Symbology | `CODE128`, `EAN13`, `EAN8`, `CODE39` |
131| Data | Literal text or `${Parameter}` |
132| `height` | Height in dots (default `64`) |
133| `align` | `left`, `center`, `right` |
134| `show_text` | `true` / `false` — human-readable text under barcode |
135
136### QR code
137
138```markdown
139@qr https://example.com/receipt/${DocumentNumber}
140@qr ${PaymentUrl} size=6 ecc=M align=center
141```
142
143| Attribute | Description |
144|-----------|-------------|
145| Data | URL or text; may include `${Parameter}` |
146| `size` | Module size 1–16 (default `4`) |
147| `ecc` | Error correction: `L`, `M`, `Q`, `H` |
148| `align` | `left`, `center`, `right` |
149
150---
151
152## Parameters
153
154Write `${ParameterName}` anywhere in text, barcode data, QR data, or image paths.
155
156- Names: letters, digits, underscore; must start with a letter or `_`.
157- **Same name → one input** at print time; all occurrences receive the same value.
158- The print dialog pre-fills values from the last print session.
159
160---
161
162## Example receipt
163
164```markdown
165# ${StoreName}
166:center:
167
168123 Main Street
169
170---
171Receipt: ${DocumentNumber}
172Date: ${Date}
173
174${LineItems}
175
176---
177:right:
178**TOTAL: ${GrandTotal}**
179
180@barcode CODE128 ${DocumentNumber}
181@feed 2
182@qr https://shop.example.com/r/${DocumentNumber}
183
184Thank you!
185@feed 4
186@cut
187```
188
189---
190
191## Printing (USB)
192
1931. Click **Print**.
1942. Enter parameter values in the dialog.
1953. Choose a USB serial printer from the list (refresh if needed).
1964. The app sends raw ESC/POS bytes directly to the port (no system print spooler).
197
198**Linux:** your user must be in the `dialout` group to access serial devices.
199
200**Windows:** the printer usually appears as `COM3`, `COM4`, etc.
201
202---
203
204## `.pos` file format
205
206JSON file with extension `.pos`:
207
208- `version` — format version (currently `1`)
209- `metadata` — page width, preview mode, code page, etc.
210- `body` — template source string