# PrnToPdf 使用手冊

## DosPntGo PRN → PDF 轉換引擎

**版本**：2.0（Harbour 32-bit Console 版）
**編碼**：BIG5（CP950）
**日期**：2026-04-11

---

## 一、概述

PrnToPdf 引擎將 DosPntGo 格式的 PRN 文字列印檔轉換為 PDF 文件。
所有 DosPntGo 控制碼（`~` 開頭）均在 `prn_to_pdf.prg` 中解析並對應到 libharu PDF 繪圖指令。

### 呼叫方式

```
PrnPdf.exe  <PRN檔>  [/紙張]
```

| 參數 | 型別 | 說明 |
|------|------|------|
| PRN檔 | 字串 | 輸入的 DosPntGo PRN 檔案路徑 |
| /紙張 | 字串 | 可選，紙張代號（見下表），例如 `/A4` |

**紙張代號**：
| 代號 | 說明 |
|------|------|
| `/0` | Letter（8.5"×11"） |
| `/2` | A4（預設） |
| `/3` | B4 |
| `/4` | 80 欄報表紙 |
| `/5` | 132 欄報表紙（橫向） |
| `/6` | A3 |
| `/7` | B5 |
| `/W210H297` | 自訂尺寸，W=寬(mm) H=高(mm) |
| `/auto` | 依 PRN 內容寬度自動決定 |

---

## 二、控制碼總覽

所有控制碼以 `~` 開頭（可用 `~~X` 更換），以 `;` 結尾。

---

## 三、版面控制

### 3.1 紙張大小

```
~[?n]
~[?100;長;寬]
~PA4  ~PA3  ~PB4  ~PB5
```

| 參數 | 型別 | 範圍 | 說明 |
|------|------|------|------|
| n | 整數 | 0,2,3,4,5,6,7,100 | 紙張代號 |
| 長 | 整數 | 1000–30000 mil | n=100 時有效，千分之一英吋 |
| 寬 | 整數 | 1000–30000 mil | n=100 時有效，千分之一英吋 |

**範例**：
```
~[?2];           → A4 紙張
~[?100;11000;8500];  → 自訂 11"×8.5"
~PA4;            → A4（同 ~[?2]）
```

---

### 3.2 直印 / 橫印

```
~J6   或  ~PP    → 直印（預設）
~J7   或  ~PL    → 橫印
```

---

### 3.3 邊界設定

```
~[MT;n]   → 上邊界
~[MD;n]   → 下邊界
~[ML;n]   → 左邊界
~[MR;n]   → 右邊界
```

| 參數 | 型別 | 範圍 | 說明 |
|------|------|------|------|
| n | 整數 | 0–5000 | 距紙張邊緣，千分之一英吋 |

**範例**：
```
~[MT;787];~[MD;787];~[ML;787];~[MR;787];   → 各邊約 2 公分
~[MT;500];   → 上邊界 0.5 英吋（127mm）
```

---

### 3.4 縮放比例

```
~[R;rx;ry]
```

| 參數 | 型別 | 範圍 | 說明 |
|------|------|------|------|
| rx | 整數 | 10–500 | 水平縮放百分比，100 = 原始 |
| ry | 整數 | 10–500 | 垂直縮放百分比，100 = 原始 |

**範例**：
```
~[R;100;100];   → 原比例（預設）
~[R;50;50];     → 縮小一半
~[R;200;200];   → 放大一倍
```

---

### 3.5 頁眉頁尾

```
~[UT;text]     → 頁眉（文字）
~[DT;text]     → 頁尾（文字）
~[UF;file]     → 頁眉（從檔案讀取）
~[DF;file]     → 頁尾（從檔案讀取）
~{UT;...}      → 頁眉（括弧語法，支援內含控制碼）
~{DT;...}      → 頁尾（括弧語法，支援內含控制碼）
```

**範例**：
```
~{UT;~[JM];~T16;第~[FPAGE0];頁};
~[MT;787];~[MD;787];~[ML;787];~[MR;787];
```

---

### 3.6 頁碼

```
~[FPAGEn]
```

| n | 型別 | 輸出格式 | 範例 |
|---|------|---------|------|
| 0 | 整數 | 半形阿拉伯數字（預設） | `1`、`12`、`123` |
| 1 | 整數 | 全形阿拉伯數字 | `１`、`１２` |
| 2 | 整數 | 中文數字（逐位）| `一`、`一二`、`一二三` |
| 4 | 整數 | 中文大寫數字 | `壹`、`壹貳` |
| 5 | 整數 | 中文組合數字 | `一百二十三` |

**範例**：
```
~[FPAGE];        → 半形數字頁碼（同 ~[FPAGE0]）
~[FPAGE2];       → 中文數字頁碼
第~[FPAGE0];頁   → 「第 3 頁」
```

---

### 3.7 重置頁碼

```
~IP;
```

> ⚠️ 注意：`~IP;` 必須單獨使用，後面跟分號。

---

### 3.8 指定印表機

```
~[ZN;印表機名稱]
```

**範例**：
```
~[ZN;HP LaserJet 1100 (MS)];
```

---

## 四、字型字體

### 4.1 字體代碼（倚天相容）

```
~FM    → 明朝體（細明體，預設）
~FG    → 黑體
~FE    → 英文字型模式
```

---

### 4.2 字型大小

```
~Tnn      → 字型大小（寬高相同）
~TXnn     → 字型寬度
~TYnn     → 字型高度
```

| 參數 | 型別 | 範圍 | 預設 | 說明 |
|------|------|------|------|------|
| nn | 整數 | 4–200 | 24 | 點陣單位（1/180 英吋） |

**範例**：
```
~T24;      → 預設大小（約 10pt）
~T48;      → 雙倍大小
~TX32;~TY24;  → 寬加大，高維持
```

---

### 4.3 水平 / 垂直放大

```
~Wnn    → 水平放大（倍數，整數）
~Znn    → 垂直放大（倍數，整數）
```

| 參數 | 型別 | 範圍 | 預設 |
|------|------|------|------|
| nn | 整數 | 1–8 | 1 |

---

### 4.4 行距 / 字距

```
~Lnn    → 行距（1/180 英吋）
~Xnn    → 字距（1/180 英吋）
```

| 參數 | 型別 | 預設 |
|------|------|------|
| 行距 nn | 整數 | 6 |
| 字距 nn | 整數 | 12 |

---

### 4.5 文字修飾

```
~S2 / ~S1     → 加粗 / 還原
~U2 / ~U1     → 底線 / 還原
~U4 / ~U3     → 上線 / 還原
~U6 / ~U5     → 刪除線（單線）/ 還原
~U8 / ~U7     → 刪除線（雙線）/ 還原
~U9 / ~U0     → 加框 / 還原
~R2 / ~R1     → 反白 / 還原
~C            → 半型字用中文字型（預設）
~E            → 半型字用英文字型
~I            → 還原所有字型設定
```

---

### 4.6 垂直對齊

```
~GT    → 文字齊頂
~GM    → 文字齊中
~GB    → 文字齊底（預設）
```

---

### 4.7 絕對字體

```
~[CF;中文字體名稱]
~[EF;英文字體名稱]
```

**支援中文字體（CJK）**：

| 字體名稱 | 說明 |
|---------|------|
| MingLiU | 細明體（預設）|
| MHei-Medium | 中黑體 |

**支援英文字體（ASCII/PDF 內建）**：

| 字體名稱 | 說明 |
|---------|------|
| Courier | 等寬體（預設）|
| Helvetica | 無衬線體 |
| Times-Roman | 有衬線體 |
| Courier-Bold | 等寬粗體 |
| Helvetica-Bold | 無衬線粗體 |
| Times-Bold | 有衬線粗體 |
| Times-Italic | 斜體 |

**範例**：
```
~[CF;MingLiU];~[EF;Helvetica];
~E;Hello World ~C;
```

---

### 4.8 條碼字體

透過 `~[EF;字體名稱]` + `~E;` 使用條碼字型：

| DosPntGo 字體名稱 | TTF 檔案 | 條碼類型 |
|-----------------|---------|---------|
| C39P24DlTt | Code39.ttf | Code39 |
| C39HrP24DlTt | Code39Hr.ttf | Code39（含可讀數字）|
| EanP36xTt | EAN13.ttf | EAN-13 |
| EanP36Tt | EAN13hr.ttf | EAN-13（含可讀數字）|

**TTF 字型放置於**：`<EXE目錄>\fonts\` 目錄下

**範例**：
```
~[EF;C39P24DlTt];~E;~T48;
*1234567890*
~FM;~T24;
```

---

## 五、顏色設定

```
~On     → 文字顏色
~OTn    → 表格顏色
~OLn    → 線條顏色（影響 ~H、底線、上線）
~OBn    → 背景底色
```

| 參數 | 型別 | 範圍 | 說明 |
|------|------|------|------|
| n | 整數 | 0–15 | DOS 16 色調色盤 |

**DOS 色碼對應**：

| n | 顏色 | n | 顏色 |
|---|------|---|------|
| 0 | 黑色 | 8 | 深灰 |
| 1 | 深藍 | 9 | 亮藍 |
| 2 | 深綠 | 10 | 亮綠 |
| 3 | 暗青 | 11 | 亮青 |
| 4 | 深紅 | 12 | 亮紅 |
| 5 | 深紫 | 13 | 亮紫 |
| 6 | 褐色 | 14 | 黃色 |
| 7 | 淺灰 | 15 | 白色 |

**範例**：
```
~OB3;~T18;[青色底色文字]~OB0;
~OL4;~H;     → 紅色水平線
~O12;重要提醒~O0;  → 亮紅色文字
```

---

## 六、位置控制

### 6.1 對齊

```
~[JL]    → 靠左對齊（預設）
~[JM]    → 居中
~[JR]    → 靠右對齊
```

---

### 6.2 絕對定位

```
~[P;x;y]    → 絕對位置（180 DPI 點數）
~[PP;x;y]   → 絕對位置（千分之一英吋）
```

| 參數 | 型別 | 說明 |
|------|------|------|
| x | 整數或 `#整數` | X 座標；`#` 前綴表示相對偏移 |
| y | 整數或 `#整數` | Y 座標；`#` 前綴表示相對偏移 |

**範例**：
```
~[P;180;180];    → 距左上各 1 英吋（180 DPI）
~[PP;1000;1500]; → X=1", Y=1.5"（mil 單位）
~[P;#360;#0];    → 向右移 2 英吋
```

---

### 6.3 回到行首

```
~[BOL]
```

---

### 6.4 水平線

```
~Hn    → 畫全幅水平線
```

| 參數 | 型別 | 範圍 | 說明 |
|------|------|------|------|
| n | 整數 | 0–20 | 線寬（1/180 英吋單位），0 = 預設細線 |

**範例**：
```
~OL0;~H;      → 黑色預設粗細水平線
~OL4;~H3;     → 紅色較粗水平線
```

---

## 七、插入圖檔

### 7.1 圖片插入（跟隨文字流）

```
~[G;file]
~[G;file;ev]
~[G;file;x;y]
~[G;file;x;y;ev]
~[G;file;x;y;w;h]
~[G;file;;;w;h]
~[G;file;x;y;w;h;ev]
```

| 參數 | 型別 | 單位 | 說明 |
|------|------|------|------|
| file | 字串 | — | 圖片路徑（相對或絕對） |
| x | 整數 | mil | X 座標；空白 = 目前 X 位置 |
| y | 整數 | mil | Y 座標；空白 = 目前 Y 位置 |
| w | 整數 | mil | 顯示寬度；0 = 原始大小 |
| h | 整數 | mil | 顯示高度；0 = 原始大小 |
| ev | 浮點數 | — | 放大倍數（如 1.5 = 150%）；0 = 不指定 |

**支援格式**：JPG、PNG（原生）、BMP、GIF、TIF、TIFF、WMF、EMF、PCX、ICO（透過 Windows GDI+ 轉換）

---

### 7.2 貼圖（不推擠文字）

```
~[G1;file;...]    → 語法同 ~[G;...]，但圖片浮在文字上
```

---

### 7.3 頁面背景圖

```
~[GV;file;x;y;w;h;ev]    → 每頁均繪製此背景圖
```

---

## 八、QR Code

### 8.1 語法

```
~[QR;data]
~[QR;data;size]
~[QR;data;x;y;size]
```

### 8.2 參數說明

| 參數 | 型別 | 範圍 | 預設 | 說明 |
|------|------|------|------|------|
| data | 字串 | 任意長度 | — | 要編碼的文字，支援 ASCII 及 BIG5 中文 |
| size | 整數 | 500–25400 | 2540 | QR 碼邊長（千分之一英吋）；**QR 碼永遠是正方形** |
| x | 整數 | 0–頁寬 | -1（目前X） | X 座標（千分之一英吋）；省略或 -1 = 目前游標 X |
| y | 整數 | 0–頁高 | -1（目前Y） | Y 座標（千分之一英吋）；省略或 -1 = 目前游標 Y |

### 8.3 size 常用換算

| size (mil) | 公釐 | 說明 |
|-----------|------|------|
| 1000 | 25.4 mm | 約 1 英吋（最小建議） |
| 2540 | 64.5 mm | 預設大小 |
| 3800 | 96.5 mm | 適合放大版 |
| 5080 | 129 mm | 2 英吋（大版面） |

### 8.4 錯誤更正等級

固定使用 **Error Correction Level M**（15% 容錯率），適合一般印刷用途。

### 8.5 相依套件

QR code 生成需要 Python `qrcode` 套件。首次使用時會自動安裝：

```
pip install qrcode[pil]
```

若無法自動安裝，請手動執行上述指令後再使用。

### 8.6 範例

```
[1] 基本用法 - 目前位置，預設大小（1 英吋）：
~[QR;https://www.example.com];

[2] 指定大小（3800 mil ≈ 9.6cm）：
~[QR;1234567890;3800];

[3] 指定位置與大小：
~[QR;P12345678;1000;2000;3000];

[4] 中文內容 QR Code：
~[QR;商品編號：A001 庫存管理;2540];

[5] 搭配文字排版：
~T24;品名：螺絲 M6×30
~[QR;M6X30-STK-001;4000];
~T20;掃描上方 QR Code 查詢庫存
```

---

## 九、日期時間插入

### 9.1 日期

```
~[FDATESHORT]          → 系統短日期，如 1997/8/12
~[FDATELONG]           → 中文長日期，如 1997年8月12日
~[FDATE;格式]          → 自訂格式
```

**自訂格式 Token**：

| Token | 說明 | 範例 |
|-------|------|------|
| `yyyy` | 西元4位年 | 2026 |
| `yy` | 西元2位年 | 26 |
| `MM` | 2位月（補零）| 04 |
| `MMM` | 中文月份 | 四月 |
| `dd` | 2位日（補零）| 11 |
| `ddd` | 中文星期 | 星期六 |

**範例**：
```
~[FDATE;yyyy 年 MMM dd 日 ddd];
→ 「2026 年 四月 11 日 星期六」
```

---

### 9.2 時間

```
~[FTIME]          → 系統時間格式
~[FTIME;格式]     → 自訂格式
```

**自訂格式 Token**：

| Token | 說明 |
|-------|------|
| `HH` | 24小時制（補零）|
| `H` | 24小時制（不補零）|
| `hh` | 12小時制（補零）|
| `h` | 12小時制（不補零）|
| `mm` | 分（補零）|
| `m` | 分（不補零）|
| `ss` | 秒（補零）|
| `s` | 秒（不補零）|
| `tt` | AM/PM |
| `t` | A/P |

**範例**：
```
~[FTIME;HH:mm:ss];        → 「14:50:25」
~[FTIME;hh:mm:ss tt];     → 「02:50:25 PM」
```

---

### 9.3 檔名

```
~[FNAME]    → 輸出目前 PRN 檔案路徑
```

---

## 十、更換控制字元

```
~~X
```

**說明**：將控制字元從 `~` 改為指定字元 `X`。

**範例**：
```
~~^    → 之後改用 ^ 作為控制字元
^T24;  → 等同原來的 ~T24;
```

---

## 十一、完整範例

### 範例一：含公司抬頭、頁碼、頁尾的標準報表

```
~{UT;~[JM];~S2;~T20;庫存管理系統  列印日期：~[FDATESHORT]};
~{DT;~[JR];~T16;第~[FPAGE0];頁};
~[MT;787];~[MD;1000];~[ML;787];~[MR;787];
~T24;

~[JL];~S2;~T20;廠商名稱：ABC 貿易公司~S1;~T24;
~OL0;~H;
~T18;品號        品名                  庫存量   單位
~H;
~T18;M6X30-001  螺絲 M6×30           1,250    個
~T18;M8X50-002  螺絲 M8×50             380    個
~H;
~[JR];~T18;合計：1,630 個
```

---

### 範例二：含 QR Code 的出貨單

```
~[MT;500];~[ML;500];~[MR;500];~[MD;500];
~T24;
~S2;~T22;出貨單~S1;~T18;
單號：SH-20260411-001    日期：~[FDATESHORT];

收貨廠商：春陽實業有限公司
品    項：螺絲 M6×30  × 500 個

~[JL];~T16;掃描 QR Code 確認本批出貨：
~[QR;SH-20260411-001|M6X30|500;3800];
~T14;~[FDATE;yyyy/MM/dd ddd] ~[FTIME;HH:mm];
```

---

### 範例三：多顏色文字 + 底色

```
~T20;
~OB3;~T18;  庫存警示報告  ~OB0;

~O4;庫存不足項目（低於安全庫存）：~O0;
~T16;  品號 A001 — 目前庫存 5 個，安全庫存 20 個
~T16;  品號 B012 — 目前庫存 0 個，安全庫存 10 個

~OB14;~O0;~T14;  請立即補貨！  ~OB0;
```

---

## 附錄A：常見問題

### Q1：QR Code 無法產生

請確認已安裝 Python 及 qrcode 套件：
```
python -m pip install qrcode[pil]
```

### Q2：中文字顯示為亂碼

PRN 檔案必須使用 **BIG5（CP950）** 編碼儲存。

### Q3：圖片 BMP/GIF 無法顯示

確認 Windows 系統已有 PowerShell 5.0+（Windows 10/11 均內建）。
BMP/GIF/WMF/PCX 會透過 Windows GDI+ 自動轉換為 PNG。

### Q4：PDF 打開後沒有 QR Code

查看 Debug 日誌（`Debug_Type.txt`）中的 `QR:` 項目，確認 Python 是否正確執行。

---

## 附錄B：技術細節

| 項目 | 說明 |
|------|------|
| PDF 引擎 | libharu 2.3（hbhpdf） |
| 中文字型 | ETen-B5-H 編碼（繁體中文）|
| 圖片原生支援 | JPG、PNG |
| 圖片擴充支援 | BMP/GIF/WMF/PCX（GDI+/PowerShell 轉換）|
| QR Code 產生 | Python qrcode + Pillow 套件 |
| QR 錯誤更正 | Level M（15%）|
| 座標系統 | 頁面左上為原點（內部轉換為 PDF 左下）|
| 座標單位 | 千分之一英吋（mil）= 0.0254 mm |
| 字型大小單位 | DosPntGo 點陣（1 unit = 1/180 英吋 ≈ 0.141 mm）|