From b9eb060be4f6649162b46477572abcdcd2fcc1aa Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Tue, 4 Nov 2025 00:47:09 +0000
Subject: [PATCH] Make generated example IDs page specific (#210)

* Make example id attribute counter reset on each page (fixes #205)
---
 phpdotnet/phd/PIHandler.php               |  3 +++
 phpdotnet/phd/Package/Generic/XHTML.php   | 31 ++++++++++++++++++++++-
 phpdotnet/phd/Package/PHP/CHM.php         |  1 +
 phpdotnet/phd/Package/PHP/EnhancedCHM.php |  1 +
 phpdotnet/phd/Package/PHP/Epub.php        |  1 +
 phpdotnet/phd/Package/PHP/Web.php         |  2 ++
 phpdotnet/phd/TestPHPChunkedXHTML.php     |  1 +
 7 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/phpdotnet/phd/PIHandler.php b/phpdotnet/phd/PIHandler.php
index dc1ed4c..92b33b4 100644
--- a/phpdotnet/phd/PIHandler.php
+++ b/phpdotnet/phd/PIHandler.php
@@ -2,6 +2,9 @@
 namespace phpdotnet\phd;
 
 abstract class PIHandler {
+    /**
+     * @var \phpdotnet\phd\Format
+     */
     protected $format;
 
     public function __construct($format) {
diff --git a/phpdotnet/phd/Package/Generic/XHTML.php b/phpdotnet/phd/Package/Generic/XHTML.php
index ad9dc32..8c419e4 100644
--- a/phpdotnet/phd/Package/Generic/XHTML.php
+++ b/phpdotnet/phd/Package/Generic/XHTML.php
@@ -548,6 +548,12 @@ abstract class Package_Generic_XHTML extends Format_Abstract_XHTML {
 
     protected int $exampleCounter = 0;
 
+    protected int $perPageExampleCounter = 0;
+
+    protected bool $exampleCounterIsPerPage = false;
+
+    protected array $perPageExampleIds = [];
+
     public function __construct(
         Config $config,
         OutputHandler $outputHandler
@@ -631,7 +637,11 @@ abstract class Package_Generic_XHTML extends Format_Abstract_XHTML {
             $rsl = $this->indexes[$for];
             $retval = $rsl["filename"] . $this->ext;
             if ($rsl["filename"] != $rsl["docbook_id"]) {
-                $retval .= '#' . $rsl["docbook_id"];
+                if (isset($this->perPageExampleIds[$for])) {
+                    $retval .= '#' . $this->perPageExampleIds[$for];
+                } else {
+                    $retval .= '#' . $rsl["docbook_id"];
+                }
             }
             $desc = $rsl["sdesc"] ?: $rsl["ldesc"];
         }
@@ -2538,4 +2548,23 @@ abstract class Package_Generic_XHTML extends Format_Abstract_XHTML {
     public function format_caption($open, $name, $attrs, $props) {
         return $open ? '<div class="caption">' : '</div>';
     }
+
+    public function getGeneratedExampleID($index)
+    {
+        $originalId = parent::getGeneratedExampleID($index);
+        if (! $this->exampleCounterIsPerPage) {
+            return $originalId;
+        }
+        if (preg_match('/^example\-[0-9]+$/', $originalId)) {
+            $this->perPageExampleCounter++;
+            $this->perPageExampleIds[$originalId] = 'example-' . $this->perPageExampleCounter;
+            return $this->perPageExampleIds[$originalId];
+        }
+        return $originalId;
+    }
+
+    public function onNewPage(): void
+    {
+        $this->perPageExampleCounter = 0;
+    }
 }
diff --git a/phpdotnet/phd/Package/PHP/CHM.php b/phpdotnet/phd/Package/PHP/CHM.php
index f172f26..4056244 100644
--- a/phpdotnet/phd/Package/PHP/CHM.php
+++ b/phpdotnet/phd/Package/PHP/CHM.php
@@ -208,6 +208,7 @@ class Package_PHP_CHM extends Package_PHP_ChunkedXHTML
     ) {
         parent::__construct($config, $outputHandler);
         $this->registerFormatName("PHP-CHM");
+        $this->exampleCounterIsPerPage = false;
     }
 
     public function __destruct() {
diff --git a/phpdotnet/phd/Package/PHP/EnhancedCHM.php b/phpdotnet/phd/Package/PHP/EnhancedCHM.php
index 9be101c..25532a1 100644
--- a/phpdotnet/phd/Package/PHP/EnhancedCHM.php
+++ b/phpdotnet/phd/Package/PHP/EnhancedCHM.php
@@ -15,6 +15,7 @@ class Package_PHP_EnhancedCHM extends Package_PHP_CHM
     ) {
         parent::__construct($config, $outputHandler);
         $this->registerFormatName("PHP-EnhancedCHM");
+        $this->exampleCounterIsPerPage = false;
     }
 
     public function update($event, $value = null) {
diff --git a/phpdotnet/phd/Package/PHP/Epub.php b/phpdotnet/phd/Package/PHP/Epub.php
index ef16501..6f15c7c 100644
--- a/phpdotnet/phd/Package/PHP/Epub.php
+++ b/phpdotnet/phd/Package/PHP/Epub.php
@@ -30,6 +30,7 @@ class Package_PHP_Epub extends Package_PHP_ChunkedXHTML
         parent::__construct($config, $outputHandler);
         $this->setExt('.xhtml');
         $this->registerFormatName("PHP-Epub");
+        $this->exampleCounterIsPerPage = false;
     }
 
     public function update($event, $value = null) {
diff --git a/phpdotnet/phd/Package/PHP/Web.php b/phpdotnet/phd/Package/PHP/Web.php
index 31068bb..68cae82 100644
--- a/phpdotnet/phd/Package/PHP/Web.php
+++ b/phpdotnet/phd/Package/PHP/Web.php
@@ -17,6 +17,7 @@ class Package_PHP_Web extends Package_PHP_XHTML {
         $this->setTitle("PHP Manual");
         $this->setChunked(true);
         $this->setExt($this->config->ext === null ? ".php" : $this->config->ext);
+        $this->exampleCounterIsPerPage = true;
     }
 
     public function close() {
@@ -54,6 +55,7 @@ class Package_PHP_Web extends Package_PHP_XHTML {
     }
 
     public function writeChunk($id, $fp) {
+        $this->onNewPage();
         $filename = $this->getOutputDir() . $id . $this->getExt();
 
         rewind($fp);
diff --git a/phpdotnet/phd/TestPHPChunkedXHTML.php b/phpdotnet/phd/TestPHPChunkedXHTML.php
index ef15fbe..7828e12 100644
--- a/phpdotnet/phd/TestPHPChunkedXHTML.php
+++ b/phpdotnet/phd/TestPHPChunkedXHTML.php
@@ -25,6 +25,7 @@ class TestPHPChunkedXHTML extends Package_PHP_ChunkedXHTML {
     }
 
     public function writeChunk($id, $fp) {
+        $this->onNewPage();
         $filename = $this->getOutputDir() . $id . $this->getExt();
 
         rewind($fp);