Allow for (nested) annotations elements

This allows us to set 'interactive' annotations on books, sets, and chapters to
signal to the WASM code runner that examples in these areas can be run.

The WASM code runner also checks for the 'non-interactive' annotation and
selectively disables running code for that example.

Author: derickr

phpdotnet/phd/Format/Abstract/XHTML.php

@@ -6,6 +6,9 @@ abstract class Format_Abstract_XHTML extends Format {
     /** @var array<?string> Last In First Out stack of roles */
     private array $role = [];
 
+    /** @var array<?string> Last In First Out stack of annotations */
+    private array $annotations = [];
+
     /* XHTMLPhDFormat */
     protected $openPara = 0;
     protected $escapedPara = array();
@@ -44,13 +47,19 @@ public function UNDEF($open, $name, $attrs, $props) {
     }
 
     public function CDATA($value) {
+        $annotations = $this->getAnnotations();
+        $annotationsStr = '';
+        if (count($annotations) > 0) {
+            $annotationsStr = 'annotation-' . join(' annotation-', $annotations) . ' ';
+        }
+
         switch($this->getRole()) {
         case '':
-            return '<div class="cdata"><pre>'
+            return '<div class="' . $annotationsStr . 'cdata"><pre>'
                 . htmlspecialchars($value, ENT_QUOTES, "UTF-8")
                 . '</pre></div>';
         default:
-            return '<div class="' . $this->getRole() . 'code">'
+            return '<div class="' . $annotationsStr . $this->getRole() . 'code' . '">'
                 . $this->highlight(trim($value), $this->getRole(), 'xhtml')
                 . '</div>';
         }
@@ -139,4 +148,20 @@ protected function getRole(): ?string {
     protected function popRole(): ?string {
         return array_pop($this->role);
     }
+
+    protected function pushAnnotations(?string $annotations): void {
+        $this->annotations[] = ($annotations != null ? explode(' ', $annotations) : []);
+    }
+
+    protected function getAnnotations() : ?array {
+        $top = end($this->annotations);
+        if ($top === false) {
+            $top = [];
+        }
+        return $top;
+    }
+
+    protected function popAnnotations() : ?array {
+        return array_pop($this->annotations);
+    }
 }

phpdotnet/phd/Package/Generic/XHTML.php

@@ -820,6 +820,8 @@ public function format_name($open, $name, $attrs) {
     }
 
     public function format_container_chunk_top($open, $name, $attrs, $props) {
+        $hasAnnotations = array_key_exists('annotations', $attrs[Reader::XMLNS_DOCBOOK]);
+
         $this->cchunk = $this->dchunk;
         $this->cchunk["name"] = $name;
         if(isset($attrs[Reader::XMLNS_XML]["id"])) {
@@ -829,12 +831,20 @@ public function format_container_chunk_top($open, $name, $attrs, $props) {
         }
 
         if ($open) {
+            if ($hasAnnotations) {
+                $this->pushAnnotations($attrs[Reader::XMLNS_DOCBOOK]["annotations"]);
+            }
+
             $this->CURRENT_CHUNK = $id;
             $this->notify(Render::CHUNK, Render::OPEN);
 
             return '<div id="' .$id. '" class="' .$name. '">';
         }
 
+        if ($hasAnnotations) {
+            $this->popAnnotations();
+        }
+
         $this->CURRENT_CHUNK = $id;
         $this->notify(Render::CHUNK, Render::CLOSE);
         $toc = "";
@@ -1714,10 +1724,17 @@ public function format_example_content($open, $name, $attrs) {
         return "</p></div>";
     }
     public function format_programlisting($open, $name, $attrs) {
+        $hasAnnotations = array_key_exists('annotations', $attrs[Reader::XMLNS_DOCBOOK]);
         if ($open) {
             $this->pushRole($attrs[Reader::XMLNS_DOCBOOK]["role"] ?? null);
+            if ($hasAnnotations) {
+                $this->pushAnnotations($attrs[Reader::XMLNS_DOCBOOK]["annotations"]);
+            }
             return '<div class="example-contents">';
         }
+        if ($hasAnnotations) {
+            $this->popAnnotations();
+        }
         $this->popRole();
         return "</div>\n";
     }

phpdotnet/phd/Package/PHP/XHTML.php

@@ -914,13 +914,19 @@ private function isChunkedByAttributes(array $attributes): bool {
     }
 
     public function format_container_chunk($open, $name, $attrs, $props) {
+        $hasAnnotations = array_key_exists('annotations', $attrs[Reader::XMLNS_DOCBOOK]);
+
         $this->CURRENT_CHUNK = $this->CURRENT_ID = $id = $attrs[Reader::XMLNS_XML]["id"] ?? '';
 
         if ($this->isChunkedByAttributes($attrs)) {
             $this->cchunk = $this->dchunk;
         }
 
         if ($open) {
+            if ($hasAnnotations) {
+                $this->pushAnnotations($attrs[Reader::XMLNS_DOCBOOK]["annotations"]);
+            }
+
             $this->notify(Render::CHUNK, Render::OPEN);
             if ($name != "reference") {
                 $chunks = Format::getChildren($id);
@@ -937,6 +943,10 @@ public function format_container_chunk($open, $name, $attrs, $props) {
             }
             return '<div id="'.$id.'" class="'.$name.'">';
         }
+        if ($hasAnnotations) {
+            $this->popAnnotations();
+        }
+
         $this->notify(Render::CHUNK, Render::CLOSE);
 
         $content = "";
@@ -957,11 +967,22 @@ public function format_container_chunk($open, $name, $attrs, $props) {
     }
 
     public function format_root_chunk($open, $name, $attrs) {
+        $hasAnnotations = array_key_exists('annotations', $attrs[Reader::XMLNS_DOCBOOK]);
+
         $this->CURRENT_CHUNK = $this->CURRENT_ID = $id = $attrs[Reader::XMLNS_XML]["id"] ?? '';
         if ($open) {
+            if ($hasAnnotations) {
+                $this->pushAnnotations($attrs[Reader::XMLNS_DOCBOOK]["annotations"]);
+            }
+
             $this->notify(Render::CHUNK, Render::OPEN);
             return '<div id="'.$id.'" class="'.$name.'">';
         }
+
+        if ($hasAnnotations) {
+            $this->popAnnotations();
+        }
+
         $this->notify(Render::CHUNK, Render::CLOSE);
         $chunks = Format::getChildren($id);
         $content = '<ul class="chunklist chunklist_'.$name.'">';