From c0f175883c7a30df440fd431c3090c265b6d63c5 Mon Sep 17 00:00:00 2001
From: Charles KWON OhJun <charleskwonohjun@gmail.com>
Date: Tue, 31 Mar 2026 11:31:44 +0900
Subject: [PATCH] docs: Add math section to syntax reference + improve example
 comments

- five-syntax-en/ko: Add Math comparison table (Harbour RTL vs Go math)
- go_math_compare.prg: Detailed English comments explaining each section
- Example lists updated with go_math_compare.prg

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/five-syntax-en.md       | 40 ++++++++++++++++++++++++++++++++++++
 docs/five-syntax-ko.md       | 29 ++++++++++++++++++++++++++
 examples/go_math_compare.prg | 27 +++++++++++++++++-------
 3 files changed, 89 insertions(+), 7 deletions(-)

diff --git a/docs/five-syntax-en.md b/docs/five-syntax-en.md
index c4ccc51..838a2f4 100644
--- a/docs/five-syntax-en.md
+++ b/docs/five-syntax-en.md
@@ -384,6 +384,45 @@ dbTarget:Close()
                 20K concurrent goroutines, 5K random fuzz
 ```
 
+## Math: Harbour RTL + Go math Together
+
+Five gives you two math systems in one file:
+
+```prg
+IMPORT "math"
+
+PROCEDURE Main()
+   LOCAL nVal
+
+   // Harbour RTL — simple, no IMPORT needed
+   ? Abs(-42.5)              // 42.5
+   ? Sqrt(144)               // 12
+   ? Round(3.14159, 2)       // 3.14
+   ? Max(10, 20)             // 20
+
+   // Go math — complete, 60+ functions
+   ? math.Sin(math.Pi / 6)  // 0.5
+   ? math.Pow(2, 10)         // 1024
+   ? math.Hypot(3, 4)        // 5
+   ? math.Log2(1024)          // 10
+
+   // Combined — use both freely
+   nVal := (1 / Sqrt(2 * math.Pi)) * Exp(-0.5 * math.Pow(0, 2))
+   ? "Normal PDF at 0:", Round(nVal, 6)
+
+   RETURN
+```
+
+| | Harbour RTL | Go math |
+|---|---|---|
+| Functions | 9 (Abs, Sqrt, Round, Int, Max, Min, Log, Exp, Mod) | 60+ |
+| IMPORT needed | No | `IMPORT "math"` |
+| Best for | Business calculations | Scientific/financial |
+| Precision | Standard | IEEE 754 |
+| Trig/Hyperbolic | No | Sin, Cos, Tan, Sinh, Cosh, ... |
+| Constants | No | Pi, E, Phi, Ln2, Sqrt2 |
+| Special values | No | NaN, Inf, MaxFloat64 |
+
 ## Example Files
 
 | File | Description |
@@ -397,4 +436,5 @@ dbTarget:Close()
 | `examples/go_concurrent.prg` | Parallel data pipeline |
 | `examples/go_websocket.prg` | WebSocket chat server |
 | `examples/go_extensions.prg` | All 9 extension syntax demo |
+| `examples/go_math_compare.prg` | Harbour RTL vs Go math side-by-side |
 | `examples/godump_demo.prg` | HB_FUNC Go API |
diff --git a/docs/five-syntax-ko.md b/docs/five-syntax-ko.md
index 8818bd0..0a5f0e6 100644
--- a/docs/five-syntax-ko.md
+++ b/docs/five-syntax-ko.md
@@ -366,6 +366,34 @@ dbTarget:Close()
 9. **PARALLEL FOR** — 대량 데이터 자동 병렬 처리
 10. **Nil-safe `?:`** — 안전한 체이닝, 런타임 에러 방지
 
+## 수학: Harbour RTL + Go math 동시 사용
+
+```prg
+IMPORT "math"
+
+PROCEDURE Main()
+   // Harbour RTL — 간단, IMPORT 불필요
+   ? Abs(-42.5)              // 42.5
+   ? Sqrt(144)               // 12
+   ? Round(3.14159, 2)       // 3.14
+
+   // Go math — 완전, 60개+ 함수
+   ? math.Sin(math.Pi / 6)  // 0.5
+   ? math.Pow(2, 10)         // 1024
+   ? math.Hypot(3, 4)        // 5
+
+   // 조합 사용
+   ? (1 / Sqrt(2 * math.Pi)) * Exp(-0.5 * math.Pow(0, 2))
+   RETURN
+```
+
+| | Harbour RTL | Go math |
+|---|---|---|
+| 함수 수 | 9개 | 60개+ |
+| IMPORT | 불���요 | `IMPORT "math"` |
+| 삼각함수 | 없음 | Sin, Cos, Tan, ... |
+| 상수 | 없음 | Pi, E, Phi, ... |
+
 ## 예제 파일
 
 | 파일 | 설명 |
@@ -379,4 +407,5 @@ dbTarget:Close()
 | `examples/go_concurrent.prg` | 병렬 데이터 파이프라인 |
 | `examples/go_websocket.prg` | WebSocket 채팅 서버 |
 | `examples/go_extensions.prg` | 9가지 확장 문법 데모 |
+| `examples/go_math_compare.prg` | Harbour RTL vs Go math 비교 |
 | `examples/godump_demo.prg` | HB_FUNC Go API |
diff --git a/examples/go_math_compare.prg b/examples/go_math_compare.prg
index 80d70c1..7c4068f 100644
--- a/examples/go_math_compare.prg
+++ b/examples/go_math_compare.prg
@@ -1,12 +1,25 @@
-// Five Math Comparison: Harbour RTL vs Go math package
+// Five Math Comparison: Harbour RTL vs Go math Package
 //
-// Five has BOTH:
-//   1. Harbour built-in: Abs(), Sqrt(), Round(), Int(), Max(), Min(), Log(), Exp(), Mod()
-//   2. Go math package: math.Sqrt(), math.Sin(), math.Cos(), math.Pow(), math.Pi, ...
+// Five gives you BOTH math systems in ONE file:
 //
-// Harbour RTL = simple, familiar.
-// Go math    = complete, IEEE 754 precise, 60+ functions.
-// Five       = use BOTH in the same PRG file!
+//   Harbour RTL (9 functions):
+//     Abs(), Sqrt(), Round(), Int(), Max(), Min(), Log(), Exp(), Mod()
+//     - Familiar to every xBase developer
+//     - No IMPORT needed, always available
+//     - Perfect for business calculations
+//
+//   Go math package (60+ functions):
+//     math.Sin(), math.Cos(), math.Pow(), math.Pi, math.Hypot(), ...
+//     - Full IEEE 754 precision
+//     - Trigonometry, statistics, special values
+//     - Just add IMPORT "math"
+//
+// Why this matters:
+//   - Daily work: use Harbour RTL (shorter, simpler)
+//   - Scientific/financial: use Go math (complete, precise)
+//   - Mix both freely in the same function!
+//
+// This example compares them side-by-side and shows combined usage.
 
 IMPORT "math"