[DOC-CVS] [phd] master: Make <preface> not produce a new page by default (#242)

Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: Girgias
Date: 2026-02-17T14:30:25Z

Commit: https://github.com/php/phd/commit/8755a928aa2b6272bb90669c4fc469a2743e64fb
Raw diff: https://github.com/php/phd/commit/8755a928aa2b6272bb90669c4fc469a2743e64fb.diff

Make <preface> not produce a new page by default (#242)

Preface elements are now rendered inline in the parent page instead of
being chunked into separate pages. Explicit annotations like
chunk:true or phd:chunk="true" can still force chunking.

Changed paths:
  A  tests/index/data/preface_no_chunk.xml
  A  tests/index/preface_no_chunk.phpt
  M  phpdotnet/phd/Index.php
  M  phpdotnet/phd/Package/PHP/XHTML.php


Diff:

diff --git a/phpdotnet/phd/Index.php b/phpdotnet/phd/Index.php
index e377ed09..8b3a6d36 100644
--- a/phpdotnet/phd/Index.php
+++ b/phpdotnet/phd/Index.php
@@ -330,7 +330,7 @@ public function format_chunk($open, $name, $attrs, $props) {
             } elseif (isset($attrs[Reader::XMLNS_DOCBOOK]['annotations'])) {
                 $this->isChunk[] = !str_contains($attrs[Reader::XMLNS_DOCBOOK]['annotations'], 'chunk:false');
             } else {
-                $this->isChunk[] = true;
+                $this->isChunk[] = ($name !== 'preface');
             }
 
             if (end($this->isChunk)) {
diff --git a/phpdotnet/phd/Package/PHP/XHTML.php b/phpdotnet/phd/Package/PHP/XHTML.php
index 878afb83..fce9f6f7 100644
--- a/phpdotnet/phd/Package/PHP/XHTML.php
+++ b/phpdotnet/phd/Package/PHP/XHTML.php
@@ -935,7 +935,7 @@ public function format_enumidentifier_text($value, $tag) {
 
 
     /*Chunk Functions*/
-    private function isChunkedByAttributes(array $attributes): bool {
+    private function isChunkedByAttributes(array $attributes, string $name = ''): bool {
         /* Legacy way to mark chunks */
         if (isset($attributes[Reader::XMLNS_PHD]['chunk'])) {
             return $attributes[Reader::XMLNS_PHD]['chunk'] != 'false';
@@ -943,8 +943,8 @@ private function isChunkedByAttributes(array $attributes): bool {
             /** Annotations attribute is a standard DocBook attribute and could be used for various things */
             return !str_contains($attributes[Reader::XMLNS_DOCBOOK]['annotations'], 'chunk:false');
         } else {
-            /* Chunked by default */
-            return true;
+            /* Chunked by default, except preface */
+            return $name !== 'preface';
         }
     }
 
@@ -953,7 +953,7 @@ public function format_container_chunk($open, $name, $attrs, $props) {
 
         $this->CURRENT_CHUNK = $this->CURRENT_ID = $id = $attrs[Reader::XMLNS_XML]["id"] ?? '';
 
-        if ($this->isChunkedByAttributes($attrs)) {
+        if ($this->isChunkedByAttributes($attrs, $name)) {
             $this->cchunk = $this->dchunk;
         }
 
@@ -1063,7 +1063,7 @@ public function format_chunk($open, $name, $attrs, $props) {
             }
 
             $this->CURRENT_CHUNK = $this->CURRENT_ID = $id;
-            if ($this->isChunkedByAttributes($attrs)) {
+            if ($this->isChunkedByAttributes($attrs, $name)) {
                 $this->cchunk = $this->dchunk;
                 $this->notify(Render::CHUNK, Render::OPEN);
             }
@@ -1078,7 +1078,7 @@ public function format_chunk($open, $name, $attrs, $props) {
             }
             return '<div id="'.$id.'" class="'.$name.'">';
         }
-        if ($this->isChunkedByAttributes($attrs)) {
+        if ($this->isChunkedByAttributes($attrs, $name)) {
             $this->notify(Render::CHUNK, Render::CLOSE);
         }
         return '</div>';
diff --git a/tests/index/data/preface_no_chunk.xml b/tests/index/data/preface_no_chunk.xml
new file mode 100644
index 00000000..0d6bfc9f
--- /dev/null
+++ b/tests/index/data/preface_no_chunk.xml
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<set xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="index" xml:lang="en">
+ <title>Test Manual</title>
+
+ <book xml:id="test-book">
+  <title>Test Book</title>
+
+  <preface xml:id="preface-default">
+   <info><title>Default Preface</title></info>
+   <para>This preface should not be chunked by default.</para>
+  </preface>
+
+  <preface annotations="chunk:true" xml:id="preface-chunked">
+   <info><title>Chunked Preface</title></info>
+   <para>This preface should be chunked because of the annotation.</para>
+  </preface>
+
+  <preface annotations="chunk:false" xml:id="preface-not-chunked">
+   <info><title>Not Chunked Preface</title></info>
+   <para>This preface should not be chunked because of the annotation.</para>
+  </preface>
+
+  <chapter xml:id="test-chapter">
+   <info><title>Test Chapter</title></info>
+   <para>A regular chapter for comparison.</para>
+  </chapter>
+ </book>
+
+</set>
diff --git a/tests/index/preface_no_chunk.phpt b/tests/index/preface_no_chunk.phpt
new file mode 100644
index 00000000..79f7a626
--- /dev/null
+++ b/tests/index/preface_no_chunk.phpt
@@ -0,0 +1,50 @@
+--TEST--
+Preface is not chunked by default
+--FILE--
+<?php
+namespace phpdotnet\phd;
+
+require_once __DIR__ . "/../setup.php";
+
+$xmlFile = __DIR__ . "/data/preface_no_chunk.xml";
+
+$config->forceIndex = true;
+$config->xmlFile = $xmlFile;
+
+$indexRepository = new IndexRepository(new \SQLite3(":memory:"));
+$indexRepository->init();
+
+$index = new TestIndex($indexRepository, $config, $outputHandler);
+$render = new TestRender(new Reader($outputHandler), $config, null, $index);
+
+$render->run();
+
+$nfo = $index->getNfo();
+
+echo "All IDs stored:\n";
+var_dump(isset($nfo["preface-default"]));
+var_dump(isset($nfo["preface-chunked"]));
+var_dump(isset($nfo["preface-not-chunked"]));
+var_dump(isset($nfo["test-chapter"]));
+
+echo "Chunk status:\n";
+echo "preface-default: ";
+var_dump($nfo["preface-default"]["chunk"]);
+echo "preface-chunked: ";
+var_dump($nfo["preface-chunked"]["chunk"]);
+echo "preface-not-chunked: ";
+var_dump($nfo["preface-not-chunked"]["chunk"]);
+echo "test-chapter: ";
+var_dump($nfo["test-chapter"]["chunk"]);
+?>
+--EXPECT--
+All IDs stored:
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+Chunk status:
+preface-default: bool(false)
+preface-chunked: bool(true)
+preface-not-chunked: bool(false)
+test-chapter: bool(true)