From ee71a5cc560e41bb670dc05eff8df5445633887c Mon Sep 17 00:00:00 2001
From: gitlost <burmartke@gmail.com>
Date: Thu, 26 Feb 2026 22:56:04 +0000
Subject: [PATCH] manual: clarify API GS1 flags require `GS1_MODE`

---
 docs/manual.html | 7 +++++--
 docs/manual.pmd  | 6 ++++--
 docs/manual.txt  | 6 ++++--
 3 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/docs/manual.html b/docs/manual.html
index 18e6362a..a9d74a33 100644
--- a/docs/manual.html
+++ b/docs/manual.html
@@ -3062,7 +3062,9 @@ GS1 Composite input that is not in the GS1 encodable character set 82
 character set 82”), otherwise encodation would fail. In “Unbracketed AI”
 and raw mode, overlong AI data will also fail.</p></li>
 </ul>
-<p>All the GS1 options imply <code>--gs1</code>.</p>
+<p>All the GS1 options imply <code>--gs1</code> (unlike their API
+equivalents, for which see <a href="#setting-the-input-mode">5.11
+Setting the Input Mode</a>).</p>
 <h2 id="batch-processing">4.12 Batch Processing</h2>
 <p>Data can be batch processed by reading from a text file and producing
 a separate barcode image for each line of text in that file. To do this
@@ -4288,7 +4290,8 @@ in <a href="#standard-code-128-iso-15417">6.1.10.1 Standard Code 128
 <code>--gs1strict</code>) and <code>GS1RAW_MODE</code> (CLI
 <code>--gs1raw</code>) are described in <a
 href="#gs1-data-entry-and-options">4.11.3 GS1 Data Entry and
-Options</a>.</p>
+Options</a>. Note that unlike the CLI options, they must be OR-ed with
+<code>GS1_MODE</code> to take effect.</p>
 <p>For <code>HEIGHTPERROW_MODE</code>, see <code>--heightperrow</code>
 in section <a href="#adjusting-height">4.4 Adjusting Height</a>. The
 <code>height</code> member should be set to the desired per-row value on
diff --git a/docs/manual.pmd b/docs/manual.pmd
index f0bcc006..51b26a76 100644
--- a/docs/manual.pmd
+++ b/docs/manual.pmd
@@ -1581,7 +1581,8 @@ General Specifications 26.0 Table 7-2 "GS1 AI encodable character set 82"),
 otherwise encodation would fail. In "Unbracketed AI" and raw mode, overlong AI
 data will also fail.
 
-All the GS1 options imply `--gs1`.
+All the GS1 options imply `--gs1` (unlike their API equivalents, for which see
+[5.11 Setting the Input Mode]).
 
 ## 4.12 Batch Processing
 
@@ -2564,7 +2565,8 @@ escape sequences are given in [6.1.10.1 Standard Code 128 (ISO 15417)].
 
 The GS1 options `GS1PARENS_MODE` (CLI `--gs1parens`) , `GS1NOCHECK_MODE` (CLI
 `--gs1nocheck`), `GS1SYNTAXENGINE_MODE` (CLI `--gs1strict`) and `GS1RAW_MODE`
-(CLI `--gs1raw`) are described in [4.11.3 GS1 Data Entry and Options].
+(CLI `--gs1raw`) are described in [4.11.3 GS1 Data Entry and Options]. Note that
+unlike the CLI options, they must be OR-ed with `GS1_MODE` to take effect.
 
 For `HEIGHTPERROW_MODE`, see `--heightperrow` in section [4.4 Adjusting Height].
 The `height` member should be set to the desired per-row value on input (it will
diff --git a/docs/manual.txt b/docs/manual.txt
index 98cb1256..8956f251 100644
--- a/docs/manual.txt
+++ b/docs/manual.txt
@@ -1616,7 +1616,8 @@ GS1 options.
   82”), otherwise encodation would fail. In “Unbracketed AI” and raw mode,
   overlong AI data will also fail.
 
-All the GS1 options imply --gs1.
+All the GS1 options imply --gs1 (unlike their API equivalents, for which see
+5.11 Setting the Input Mode).
 
 4.12 Batch Processing
 
@@ -2516,7 +2517,8 @@ given in 6.1.10.1 Standard Code 128 (ISO 15417).
 
 The GS1 options GS1PARENS_MODE (CLI --gs1parens) , GS1NOCHECK_MODE (CLI
 --gs1nocheck), GS1SYNTAXENGINE_MODE (CLI --gs1strict) and GS1RAW_MODE (CLI
---gs1raw) are described in 4.11.3 GS1 Data Entry and Options.
+--gs1raw) are described in 4.11.3 GS1 Data Entry and Options. Note that unlike
+the CLI options, they must be OR-ed with GS1_MODE to take effect.
 
 For HEIGHTPERROW_MODE, see --heightperrow in section 4.4 Adjusting Height. The
 height member should be set to the desired per-row value on input (it will be