BlueGit

timfa posprint

Normalize README.md to LF line endings.

Co-authored-by: Cursor <cursoragent@cursor.com>

timfa Tim Falken · pushed by timfa

Authored 2026-07-16 · 4 months ago

Hash
12fa4878bae3e54e7bc0a51ec6972d654a330a49
Parent
67300a28
1 file changed +104 −104
README.md +104 −104
@@ -1,104 +1,104 @@
1 # posprint
2
3 Cross-platform designer for POS (point-of-sale) receipt documents. Edit templates in a markdown-like syntax, preview output live, substitute runtime parameters, and print directly to USB serial POS printers via raw ESC/POS bytes.
4
5 **Target platforms:** Windows and Linux (x64).
6
7 ## Status
8
9 **v0.1.0 MVP** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and USB-serial printing.
10
11 ## Build and run
12
13 Requires **Rust 1.88+** ([rustup](https://rustup.rs/) or `pacman -S rust` on Arch). See [docs/BUILD.md](docs/BUILD.md) for OS libraries and package scripts.
14
15 ```bash
16 cargo test # 31 unit tests
17 cargo run # launch the designer
18 cargo build --release
19 ```
20
21 **Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`
22
23 ### Command-line printing
24
25 ```bash
26 # Windows
27 posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42
28
29 # Linux
30 posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
31 ```
32
33 All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails.
34
35 **Linux:** add your user to the `dialout` group for USB-serial printer access.
36
37 ## Releases (GitLab CI)
38
39 | Platform | Artifact | Install |
40 |----------|----------|---------|
41 | Linux (Debian/Ubuntu) | `.deb` (amd64) | `sudo dpkg -i posprint_*_amd64.deb` then `sudo apt-get install -f` |
42 | Linux (Arch) | `.pkg.tar.zst` (x86_64) | `sudo pacman -U posprint_*_x86_64.pkg.tar.zst` |
43 | Windows | `posprint.exe` | Download from GitLab release job artifacts |
44
45 Tag a version (e.g. `v0.1.0`) to trigger release builds.
46
47 ## Features
48
49 - Markdown-like template editor with live preview
50 - Page width: auto-scale or fixed width (mm)
51 - Save and load `.pos` files
52 - Parameter tokens (`${DocumentNumber}`) with print-time popup and value reuse
53 - Barcodes, QR codes, and images (including parameterized content)
54 - Print to USB-serial POS printers via raw ESC/POS bytes
55 - In-app **Help** tab (from [docs/HELP.md](docs/HELP.md))
56
57 ## Dependencies (minimal)
58
59 | Crate | Why |
60 |-------|-----|
61 | `eframe` / `egui` | Native UI |
62 | `serde` / `serde_json` | `.pos` file format |
63 | `serialport` | USB-serial printer I/O |
64 | `image` | Load PNG/JPEG for `@image` |
65 | `rfd` | Native open/save dialogs |
66 | `barcoders` | Raster barcode rendering |
67 | `qrcode` | Raster QR rendering |
68 | `clap` | CLI `print` subcommand |
69
70 ESC/POS encoding is implemented in-tree.
71
72 ## Design documents
73
74 | Document | Description |
75 |----------|-------------|
76 | [FEASIBILITY.md](docs/FEASIBILITY.md) | Feasibility assessment, complexity estimate, risks |
77 | [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) | Language and framework recommendation |
78 | [HELP.md](docs/HELP.md) | **User reference** (mirrored in-app Help tab) |
79 | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and module breakdown |
80 | [DSL-SPEC.md](docs/DSL-SPEC.md) | Document markup language (`.pos` body syntax) |
81 | [FILE-FORMAT.md](docs/FILE-FORMAT.md) | `.pos` file envelope (metadata + body) |
82 | [PRINTING.md](docs/PRINTING.md) | Printer discovery, transport, ESC/POS pipeline |
83 | [BUILD.md](docs/BUILD.md) | Local build scripts and Linux package formats |
84
85 Documentation must stay aligned with the codebase; see `.cursor/rules/documentation.mdc`.
86
87 ## Planned features
88
89 - Bluetooth printer support (deferred)
90
91 ## Quick feasibility summary
92
93 **Verdict: feasible** for a small team or solo developer, with the printing layer as the main engineering risk.
94
95 | Area | Complexity | Notes |
96 |------|------------|-------|
97 | Editor + preview UI | Medium | Well-trodden path |
98 | DSL parser + renderer | Medium | Custom grammar, bounded scope |
99 | Parameters | Low | Straightforward substitution |
100 | Barcodes / QR / images | Low–Medium | Mature libraries exist |
101 | USB / BT printer I/O | **High** | OS differences, device quirks |
102 | **Overall (MVP)** | **Medium–High** | ~6–10 weeks for one experienced dev |
103
104 Stack: **Rust + egui** (single language, minimal dependencies). USB-serial printing only in v1. See [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) and [docs/HELP.md](docs/HELP.md).
1 # posprint
2
3 Cross-platform designer for POS (point-of-sale) receipt documents. Edit templates in a markdown-like syntax, preview output live, substitute runtime parameters, and print directly to USB serial POS printers via raw ESC/POS bytes.
4
5 **Target platforms:** Windows and Linux (x64).
6
7 ## Status
8
9 **v0.1.0 MVP** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and USB-serial printing.
10
11 ## Build and run
12
13 Requires **Rust 1.88+** ([rustup](https://rustup.rs/) or `pacman -S rust` on Arch). See [docs/BUILD.md](docs/BUILD.md) for OS libraries and package scripts.
14
15 ```bash
16 cargo test # 31 unit tests
17 cargo run # launch the designer
18 cargo build --release
19 ```
20
21 **Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`
22
23 ### Command-line printing
24
25 ```bash
26 # Windows
27 posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42
28
29 # Linux
30 posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
31 ```
32
33 All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails.
34
35 **Linux:** add your user to the `dialout` group for USB-serial printer access.
36
37 ## Releases (GitLab CI)
38
39 | Platform | Artifact | Install |
40 |----------|----------|---------|
41 | Linux (Debian/Ubuntu) | `.deb` (amd64) | `sudo dpkg -i posprint_*_amd64.deb` then `sudo apt-get install -f` |
42 | Linux (Arch) | `.pkg.tar.zst` (x86_64) | `sudo pacman -U posprint_*_x86_64.pkg.tar.zst` |
43 | Windows | `posprint.exe` | Download from GitLab release job artifacts |
44
45 Tag a version (e.g. `v0.1.0`) to trigger release builds.
46
47 ## Features
48
49 - Markdown-like template editor with live preview
50 - Page width: auto-scale or fixed width (mm)
51 - Save and load `.pos` files
52 - Parameter tokens (`${DocumentNumber}`) with print-time popup and value reuse
53 - Barcodes, QR codes, and images (including parameterized content)
54 - Print to USB-serial POS printers via raw ESC/POS bytes
55 - In-app **Help** tab (from [docs/HELP.md](docs/HELP.md))
56
57 ## Dependencies (minimal)
58
59 | Crate | Why |
60 |-------|-----|
61 | `eframe` / `egui` | Native UI |
62 | `serde` / `serde_json` | `.pos` file format |
63 | `serialport` | USB-serial printer I/O |
64 | `image` | Load PNG/JPEG for `@image` |
65 | `rfd` | Native open/save dialogs |
66 | `barcoders` | Raster barcode rendering |
67 | `qrcode` | Raster QR rendering |
68 | `clap` | CLI `print` subcommand |
69
70 ESC/POS encoding is implemented in-tree.
71
72 ## Design documents
73
74 | Document | Description |
75 |----------|-------------|
76 | [FEASIBILITY.md](docs/FEASIBILITY.md) | Feasibility assessment, complexity estimate, risks |
77 | [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) | Language and framework recommendation |
78 | [HELP.md](docs/HELP.md) | **User reference** (mirrored in-app Help tab) |
79 | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and module breakdown |
80 | [DSL-SPEC.md](docs/DSL-SPEC.md) | Document markup language (`.pos` body syntax) |
81 | [FILE-FORMAT.md](docs/FILE-FORMAT.md) | `.pos` file envelope (metadata + body) |
82 | [PRINTING.md](docs/PRINTING.md) | Printer discovery, transport, ESC/POS pipeline |
83 | [BUILD.md](docs/BUILD.md) | Local build scripts and Linux package formats |
84
85 Documentation must stay aligned with the codebase; see `.cursor/rules/documentation.mdc`.
86
87 ## Planned features
88
89 - Bluetooth printer support (deferred)
90
91 ## Quick feasibility summary
92
93 **Verdict: feasible** for a small team or solo developer, with the printing layer as the main engineering risk.
94
95 | Area | Complexity | Notes |
96 |------|------------|-------|
97 | Editor + preview UI | Medium | Well-trodden path |
98 | DSL parser + renderer | Medium | Custom grammar, bounded scope |
99 | Parameters | Low | Straightforward substitution |
100 | Barcodes / QR / images | Low–Medium | Mature libraries exist |
101 | USB / BT printer I/O | **High** | OS differences, device quirks |
102 | **Overall (MVP)** | **Medium–High** | ~6–10 weeks for one experienced dev |
103
104 Stack: **Rust + egui** (single language, minimal dependencies). USB-serial printing only in v1. See [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) and [docs/HELP.md](docs/HELP.md).
@@ -1,104 +1,104 @@
1# posprint
1# posprint
2
2
3Cross-platform designer for POS (point-of-sale) receipt documents. Edit templates in a markdown-like syntax, preview output live, substitute runtime parameters, and print directly to USB serial POS printers via raw ESC/POS bytes.
3Cross-platform designer for POS (point-of-sale) receipt documents. Edit templates in a markdown-like syntax, preview output live, substitute runtime parameters, and print directly to USB serial POS printers via raw ESC/POS bytes.
4
4
5**Target platforms:** Windows and Linux (x64).
5**Target platforms:** Windows and Linux (x64).
6
6
7## Status
7## Status
8
8
9**v0.1.0 MVP** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and USB-serial printing.
9**v0.1.0 MVP** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and USB-serial printing.
10
10
11## Build and run
11## Build and run
12
12
13Requires **Rust 1.88+** ([rustup](https://rustup.rs/) or `pacman -S rust` on Arch). See [docs/BUILD.md](docs/BUILD.md) for OS libraries and package scripts.
13Requires **Rust 1.88+** ([rustup](https://rustup.rs/) or `pacman -S rust` on Arch). See [docs/BUILD.md](docs/BUILD.md) for OS libraries and package scripts.
14
14
15```bash
15```bash
16cargo test # 31 unit tests
16cargo test # 31 unit tests
17cargo run # launch the designer
17cargo run # launch the designer
18cargo build --release
18cargo build --release
19```
19```
20
20
21**Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`
21**Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`
22
22
23### Command-line printing
23### Command-line printing
24
24
25```bash
25```bash
26# Windows
26# Windows
27posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42
27posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42
28
28
29# Linux
29# Linux
30posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
30posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
31```
31```
32
32
33All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails.
33All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails.
34
34
35**Linux:** add your user to the `dialout` group for USB-serial printer access.
35**Linux:** add your user to the `dialout` group for USB-serial printer access.
36
36
37## Releases (GitLab CI)
37## Releases (GitLab CI)
38
38
39| Platform | Artifact | Install |
39| Platform | Artifact | Install |
40|----------|----------|---------|
40|----------|----------|---------|
41| Linux (Debian/Ubuntu) | `.deb` (amd64) | `sudo dpkg -i posprint_*_amd64.deb` then `sudo apt-get install -f` |
41| Linux (Debian/Ubuntu) | `.deb` (amd64) | `sudo dpkg -i posprint_*_amd64.deb` then `sudo apt-get install -f` |
42| Linux (Arch) | `.pkg.tar.zst` (x86_64) | `sudo pacman -U posprint_*_x86_64.pkg.tar.zst` |
42| Linux (Arch) | `.pkg.tar.zst` (x86_64) | `sudo pacman -U posprint_*_x86_64.pkg.tar.zst` |
43| Windows | `posprint.exe` | Download from GitLab release job artifacts |
43| Windows | `posprint.exe` | Download from GitLab release job artifacts |
44
44
45Tag a version (e.g. `v0.1.0`) to trigger release builds.
45Tag a version (e.g. `v0.1.0`) to trigger release builds.
46
46
47## Features
47## Features
48
48
49- Markdown-like template editor with live preview
49- Markdown-like template editor with live preview
50- Page width: auto-scale or fixed width (mm)
50- Page width: auto-scale or fixed width (mm)
51- Save and load `.pos` files
51- Save and load `.pos` files
52- Parameter tokens (`${DocumentNumber}`) with print-time popup and value reuse
52- Parameter tokens (`${DocumentNumber}`) with print-time popup and value reuse
53- Barcodes, QR codes, and images (including parameterized content)
53- Barcodes, QR codes, and images (including parameterized content)
54- Print to USB-serial POS printers via raw ESC/POS bytes
54- Print to USB-serial POS printers via raw ESC/POS bytes
55- In-app **Help** tab (from [docs/HELP.md](docs/HELP.md))
55- In-app **Help** tab (from [docs/HELP.md](docs/HELP.md))
56
56
57## Dependencies (minimal)
57## Dependencies (minimal)
58
58
59| Crate | Why |
59| Crate | Why |
60|-------|-----|
60|-------|-----|
61| `eframe` / `egui` | Native UI |
61| `eframe` / `egui` | Native UI |
62| `serde` / `serde_json` | `.pos` file format |
62| `serde` / `serde_json` | `.pos` file format |
63| `serialport` | USB-serial printer I/O |
63| `serialport` | USB-serial printer I/O |
64| `image` | Load PNG/JPEG for `@image` |
64| `image` | Load PNG/JPEG for `@image` |
65| `rfd` | Native open/save dialogs |
65| `rfd` | Native open/save dialogs |
66| `barcoders` | Raster barcode rendering |
66| `barcoders` | Raster barcode rendering |
67| `qrcode` | Raster QR rendering |
67| `qrcode` | Raster QR rendering |
68| `clap` | CLI `print` subcommand |
68| `clap` | CLI `print` subcommand |
69
69
70ESC/POS encoding is implemented in-tree.
70ESC/POS encoding is implemented in-tree.
71
71
72## Design documents
72## Design documents
73
73
74| Document | Description |
74| Document | Description |
75|----------|-------------|
75|----------|-------------|
76| [FEASIBILITY.md](docs/FEASIBILITY.md) | Feasibility assessment, complexity estimate, risks |
76| [FEASIBILITY.md](docs/FEASIBILITY.md) | Feasibility assessment, complexity estimate, risks |
77| [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) | Language and framework recommendation |
77| [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) | Language and framework recommendation |
78| [HELP.md](docs/HELP.md) | **User reference** (mirrored in-app Help tab) |
78| [HELP.md](docs/HELP.md) | **User reference** (mirrored in-app Help tab) |
79| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and module breakdown |
79| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and module breakdown |
80| [DSL-SPEC.md](docs/DSL-SPEC.md) | Document markup language (`.pos` body syntax) |
80| [DSL-SPEC.md](docs/DSL-SPEC.md) | Document markup language (`.pos` body syntax) |
81| [FILE-FORMAT.md](docs/FILE-FORMAT.md) | `.pos` file envelope (metadata + body) |
81| [FILE-FORMAT.md](docs/FILE-FORMAT.md) | `.pos` file envelope (metadata + body) |
82| [PRINTING.md](docs/PRINTING.md) | Printer discovery, transport, ESC/POS pipeline |
82| [PRINTING.md](docs/PRINTING.md) | Printer discovery, transport, ESC/POS pipeline |
83| [BUILD.md](docs/BUILD.md) | Local build scripts and Linux package formats |
83| [BUILD.md](docs/BUILD.md) | Local build scripts and Linux package formats |
84
84
85Documentation must stay aligned with the codebase; see `.cursor/rules/documentation.mdc`.
85Documentation must stay aligned with the codebase; see `.cursor/rules/documentation.mdc`.
86
86
87## Planned features
87## Planned features
88
88
89- Bluetooth printer support (deferred)
89- Bluetooth printer support (deferred)
90
90
91## Quick feasibility summary
91## Quick feasibility summary
92
92
93**Verdict: feasible** for a small team or solo developer, with the printing layer as the main engineering risk.
93**Verdict: feasible** for a small team or solo developer, with the printing layer as the main engineering risk.
94
94
95| Area | Complexity | Notes |
95| Area | Complexity | Notes |
96|------|------------|-------|
96|------|------------|-------|
97| Editor + preview UI | Medium | Well-trodden path |
97| Editor + preview UI | Medium | Well-trodden path |
98| DSL parser + renderer | Medium | Custom grammar, bounded scope |
98| DSL parser + renderer | Medium | Custom grammar, bounded scope |
99| Parameters | Low | Straightforward substitution |
99| Parameters | Low | Straightforward substitution |
100| Barcodes / QR / images | Low–Medium | Mature libraries exist |
100| Barcodes / QR / images | Low–Medium | Mature libraries exist |
101| USB / BT printer I/O | **High** | OS differences, device quirks |
101| USB / BT printer I/O | **High** | OS differences, device quirks |
102| **Overall (MVP)** | **Medium–High** | ~6–10 weeks for one experienced dev |
102| **Overall (MVP)** | **Medium–High** | ~6–10 weeks for one experienced dev |
103
103
104Stack: **Rust + egui** (single language, minimal dependencies). USB-serial printing only in v1. See [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) and [docs/HELP.md](docs/HELP.md).
104Stack: **Rust + egui** (single language, minimal dependencies). USB-serial printing only in v1. See [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) and [docs/HELP.md](docs/HELP.md).