DocBook 5.2 class and exception markup migration

phpdotnet/phd/Index.php

@@ -35,7 +35,7 @@ class Index extends Format
     'phpdoc:varentry'       => 'format_chunk',
     'preface'               => 'format_chunk',
     'refentry'              => 'format_refentry',
-    'reference'             => 'format_container_chunk',
+    'reference'             => 'format_reference',
     'sect1'                 => 'format_chunk',
     'section'               => array(
         /* DEFAULT */          false,
@@ -446,4 +446,14 @@ public function setMembership($membership) {
         $this->currentMembership = $membership;
     }
 
+    public function format_reference($open, $name, $attrs, $props) {
+        if (isset($attrs[Reader::XMLNS_DOCBOOK]['role'])) {
+            $name = match ($attrs[Reader::XMLNS_DOCBOOK]['role']) {
+                "class" => "phpdoc:classref",
+                "exception" => "phpdoc:exceptionref",
+                default => $name,
+            };
+        }
+        return $this->format_container_chunk($open, $name, $attrs, $props);
+    }
 }

phpdotnet/phd/Package/Generic/XHTML.php

@@ -1626,8 +1626,22 @@ public function format_programlisting_text($value, $tag) {
     }
     public function format_screen($open, $name, $attrs) {
         if ($open) {
+            if ($this->getRole() !== "examples"
+                && $this->getRole() !== "description"
+                && $this->getRole() !== "notes"
+                && $this->getRole() !== "returnvalues"
+                && $this->getRole() !== "parameters") {
+                $this->pushRole('');
+            }
             return '<div class="example-contents ' .$name. '">';
         }
+        if ($this->getRole() !== "examples"
+            && $this->getRole() !== "description"
+            && $this->getRole() !== "notes"
+            && $this->getRole() !== "returnvalues"
+            && $this->getRole() !== "parameters") {
+            $this->popRole();
+        }
         return '</div>';
     }
     public function format_constant($open, $name, $attrs)

phpdotnet/phd/Package/PHP/XHTML.php

@@ -25,7 +25,7 @@ abstract class Package_PHP_XHTML extends Package_Generic_XHTML {
         'phpdoc:exceptionref'   => 'format_class_chunk',
         'phpdoc:varentry'       => 'format_varentry_chunk',
         'refentry'              => 'format_refentry',
-        'reference'             => 'format_container_chunk',
+        'reference'             => 'format_reference',
         'refpurpose'            => 'format_refpurpose',
         'refsynopsisdiv'        => 'format_refsynopsisdiv',
         'set'                   => 'format_root_chunk',
@@ -152,6 +152,7 @@ abstract class Package_PHP_XHTML extends Package_Generic_XHTML {
             /* DEFAULT */          'format_suppressed_text',
             'phpdoc:classref'   => 'format_grep_classname_text',
             'phpdoc:exceptionref'  => 'format_grep_classname_text',
+            'reference'            => 'format_reference_titleabbrev_text',
             'refentry' => 'format_grep_classname_text',
         ),
          'varname'               => array(
@@ -1061,6 +1062,26 @@ public function format_class_chunk($open, $name, $attrs, $props) {
         return $this->format_container_chunk($open, "reference", $attrs, $props);
     }
 
-}
-
+    public function format_reference($open, $name, $attrs, $props) {
+        if (isset($attrs[Reader::XMLNS_DOCBOOK]['role'])) {
+            if ($attrs[Reader::XMLNS_DOCBOOK]['role'] === "class"
+                || $attrs[Reader::XMLNS_DOCBOOK]['role'] === "exception") {
+                if ($open) {
+                    $this->pushRole($attrs[Reader::XMLNS_DOCBOOK]['role']);
+                } else {
+                    $this->popRole();
+                }
+                return $this->format_class_chunk($open, $name, $attrs, $props);
+            }
+        }
+        return $this->format_container_chunk($open, $name, $attrs, $props);
+    }
 
+    public function format_reference_titleabbrev_text($value, $tag) {
+        if ($this->getRole() === "class"
+            || $this->getRole() === "exception") {
+            return $this->format_grep_classname_text($value, $tag);
+        }
+        return $this->format_suppressed_text($value, $tag);
+    }
+}

tests/package/php/class_rendering_001.phpt

@@ -0,0 +1,129 @@
+--TEST--
+Class rendering 001 - phpdoc:classref rendering
+--FILE--
+<?php
+namespace phpdotnet\phd;
+
+require_once __DIR__ . "/../../setup.php";
+
+$xml_file = __DIR__ . "/data/class_rendering_001.xml";
+
+Config::init(["xml_file" => $xml_file]);
+
+$format = new TestPHPChunkedXHTML;
+$render = new TestRender(new Reader, new Config, $format);
+
+$render->run();
+?>
+--EXPECTF--
+Filename: classname.construct.html
+Content:
+<div id="classname.construct" class="refentry">
+     <div class="refnamediv">
+      <h1 class="refname">ClassName::__construct</h1>
+      <p class="verinfo">(No version information available, might only be in Git)</p><p class="refpurpose"><span class="refname">ClassName::__construct</span> &mdash; <span class="dc-title">Returns new ClassName object</span></p>
+
+     </div>
+
+     <div class="refsect1 description" id="refsect1-classname.construct-description">
+      Description
+      <div class="constructorsynopsis dc-description"><span class="modifier">public</span> <span class="methodname"><strong>ClassName::__construct</strong></span>(<span class="methodparam"><span class="type"><a href="language.types.string.html" class="type string">string</a></span> <code class="parameter">$firstParameter</code><span class="initializer"> = &quot;now&quot;</span></span>)</div>
+
+      <p class="para rdfs-comment">
+       Returns new a ClassName object.
+      </p>
+     </div>
+
+
+     <div class="refsect1 parameters" id="refsect1-classname.construct-parameters">
+      <h3 class="title">Parameters</h3>
+      <dl>
+
+        <dt><code class="parameter">firstParameter</code></dt>
+        <dd>
+         <p class="para">
+          The description of the parameter.
+         </p>
+        </dd>
+
+      </dl>
+     </div>
+
+
+     <div class="refsect1 returnvalues" id="refsect1-classname.construct-returnvalues">
+      <h3 class="title">Return Values</h3>
+      <p class="para">
+       Return values of the method.
+      </p>
+     </div>
+
+
+     <div class="refsect1 errors" id="refsect1-classname.construct-errors">
+      <h3 class="title">Errors/Exceptions</h3>
+      <p class="para">
+       Exceptions thrown and/or errors raised by the method.
+      </p>
+     </div>
+
+
+    </div>
+Filename: class.classname.html
+Content:
+<div id="class.classname" class="reference">
+
+ <h1 class="title">The ClassName class</h1>
+
+
+ <div class="partintro"><p class="verinfo">(No version information available, might only be in Git)</p>
+
+  <div class="section" id="classname.intro">
+   <h2 class="title">Introduction</h2>
+   <p class="para">
+    Introductory paragraph about the class.
+   </p>
+  </div>
+
+  <div class="section" id="classname.synopsis">
+   <h2 class="title">Class synopsis</h2>
+
+   <div class="classsynopsis"><div class="classsynopsisinfo">
+
+     <span class="modifier">class</span> <strong class="classname"><strong class="classname">ClassName</strong></strong>
+
+
+
+     <span class="modifier">implements</span>
+      <strong class="interfacename">InterfaceName</strong> {</div>
+
+    <div class="classsynopsisinfo classsynopsisinfo_comment">/* Constants */</div>
+    <div class="fieldsynopsis">
+     <span class="modifier">public</span>
+     <span class="modifier">const</span>
+     <span class="type"><a href="language.types.string.html" class="type string">string</a></span>
+      <var class="fieldsynopsis_varname"><a href=".html#classname.constants.first-constant"><var class="varname">FIRST_CONSTANT</var></a></var><span class="initializer"> = &quot;Initial value&quot;</span>;</div>
+
+
+    <div class="classsynopsisinfo classsynopsisinfo_comment">/* Methods */</div>
+
+
+   }</div>
+
+  </div>
+
+  <div class="section" id="classname.constants.types">
+   <h2 class="title">Predefined Constants</h2>
+   <dl>
+
+     <dt id="classname.constants.first-constant"><strong><code>ClassName::FIRST_CONSTANT</code></strong></dt>
+     <dd>
+      <span class="simpara">
+       The description of the class constant.
+      </span>
+     </dd>
+
+   </dl>
+  </div>
+
+ </div>
+
+</div>

tests/package/php/class_rendering_002.phpt

@@ -0,0 +1,129 @@
+--TEST--
+Class rendering 002 - reference element with role="class" rendering
+--FILE--
+<?php
+namespace phpdotnet\phd;
+
+require_once __DIR__ . "/../../setup.php";
+
+$xml_file = __DIR__ . "/data/class_rendering_002.xml";
+
+Config::init(["xml_file" => $xml_file]);
+
+$format = new TestPHPChunkedXHTML;
+$render = new TestRender(new Reader, new Config, $format);
+
+$render->run();
+?>
+--EXPECTF--
+Filename: classname.construct.html
+Content:
+<div id="classname.construct" class="refentry">
+     <div class="refnamediv">
+      <h1 class="refname">ClassName::__construct</h1>
+      <p class="verinfo">(No version information available, might only be in Git)</p><p class="refpurpose"><span class="refname">ClassName::__construct</span> &mdash; <span class="dc-title">Returns new ClassName object</span></p>
+
+     </div>
+
+     <div class="refsect1 description" id="refsect1-classname.construct-description">
+      Description
+      <div class="constructorsynopsis dc-description"><span class="modifier">public</span> <span class="methodname"><strong>ClassName::__construct</strong></span>(<span class="methodparam"><span class="type"><a href="language.types.string.html" class="type string">string</a></span> <code class="parameter">$firstParameter</code><span class="initializer"> = &quot;now&quot;</span></span>)</div>
+
+      <p class="para rdfs-comment">
+       Returns new a ClassName object.
+      </p>
+     </div>
+
+
+     <div class="refsect1 parameters" id="refsect1-classname.construct-parameters">
+      <h3 class="title">Parameters</h3>
+      <dl>
+
+        <dt><code class="parameter">firstParameter</code></dt>
+        <dd>
+         <p class="para">
+          The description of the parameter.
+         </p>
+        </dd>
+
+      </dl>
+     </div>
+
+
+     <div class="refsect1 returnvalues" id="refsect1-classname.construct-returnvalues">
+      <h3 class="title">Return Values</h3>
+      <p class="para">
+       Return values of the method.
+      </p>
+     </div>
+
+
+     <div class="refsect1 errors" id="refsect1-classname.construct-errors">
+      <h3 class="title">Errors/Exceptions</h3>
+      <p class="para">
+       Exceptions thrown and/or errors raised by the method.
+      </p>
+     </div>
+
+
+    </div>
+Filename: class.classname.html
+Content:
+<div id="class.classname" class="reference">
+
+ <h1 class="title">The ClassName class</h1>
+
+
+ <div class="partintro"><p class="verinfo">(No version information available, might only be in Git)</p>
+
+  <div class="section" id="classname.intro">
+   <h2 class="title">Introduction</h2>
+   <p class="para">
+    Introductory paragraph about the class.
+   </p>
+  </div>
+
+  <div class="section" id="classname.synopsis">
+   <h2 class="title">Class synopsis</h2>
+
+   <div class="classsynopsis"><div class="classsynopsisinfo">
+
+     <span class="modifier">class</span> <strong class="classname"><strong class="classname">ClassName</strong></strong>
+
+
+
+     <span class="modifier">implements</span>
+      <strong class="interfacename">InterfaceName</strong> {</div>
+
+    <div class="classsynopsisinfo classsynopsisinfo_comment">/* Constants */</div>
+    <div class="fieldsynopsis">
+     <span class="modifier">public</span>
+     <span class="modifier">const</span>
+     <span class="type"><a href="language.types.string.html" class="type string">string</a></span>
+      <var class="fieldsynopsis_varname"><a href=".html#classname.constants.first-constant"><var class="varname">FIRST_CONSTANT</var></a></var><span class="initializer"> = &quot;Initial value&quot;</span>;</div>
+
+
+    <div class="classsynopsisinfo classsynopsisinfo_comment">/* Methods */</div>
+
+
+   }</div>
+
+  </div>
+
+  <div class="section" id="classname.constants.types">
+   <h2 class="title">Predefined Constants</h2>
+   <dl>
+
+     <dt id="classname.constants.first-constant"><strong><code>ClassName::FIRST_CONSTANT</code></strong></dt>
+     <dd>
+      <span class="simpara">
+       The description of the class constant.
+      </span>
+     </dd>
+
+   </dl>
+  </div>
+
+ </div>
+
+</div>

tests/package/php/class_rendering_003.phpt

@@ -0,0 +1,35 @@
+--TEST--
+Class rendering 003 - compare output of phpdoc:classref and reference element with role="class" rendering
+--FILE--
+<?php
+namespace phpdotnet\phd;
+
+require_once __DIR__ . "/../../setup.php";
+
+$xml_filePhpdoc = __DIR__ . "/data/class_rendering_001.xml";
+
+Config::init(["xml_file" => $xml_filePhpdoc]);
+
+$formatPhpdoc = new TestPHPChunkedXHTML;
+$renderPhpdoc = new TestRender(new Reader, new Config, $formatPhpdoc);
+
+ob_start();
+$renderPhpdoc->run();
+$phpdocOutput = ob_get_clean();
+
+
+$xml_fileReferenceWithRole = __DIR__ . "/data/class_rendering_002.xml";
+
+Config::init(["xml_file" => $xml_fileReferenceWithRole]);
+
+$formatReferenceWithRole = new TestPHPChunkedXHTML;
+$renderReferenceWithRole = new TestRender(new Reader, new Config, $formatReferenceWithRole);
+
+ob_start();
+$renderReferenceWithRole->run();
+$referenceWithRoleOutput = ob_get_clean();
+
+var_dump($phpdocOutput === $referenceWithRoleOutput);
+?>
+--EXPECT--
+bool(true)