Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Interactive annotations #195

Merged
merged 2 commits into from
Mar 6, 2025
Merged

Interactive annotations #195

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5d7ff7a
Fixed trailing spaces
derickr Mar 6, 2025
fd8038b
Allow for (nested) annotations elements
derickr Mar 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 27 additions & 2 deletions phpdotnet/phd/Format/Abstract/XHTML.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down Expand Up @@ -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>';
}
Expand Down Expand Up @@ -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);
}
}
67 changes: 42 additions & 25 deletions phpdotnet/phd/Package/Generic/XHTML.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"])) {
Expand All @@ -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 = "";
Expand Down Expand Up @@ -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";
}
Expand Down Expand Up @@ -1753,73 +1770,73 @@ public function format_constant($open, $name, $attrs, $props)
}
return "<strong><code>";
}

if ($this->getRole() === "constant_group") {
$this->popRole();

$value = str_replace(
["<replaceable xmlns=\"http://docbook.org/ns/docbook\">", "</replaceable>"],
["<span class=\"replaceable\">", "</span>"],
strip_tags($this->cchunk["constant"], "<replaceable>")
);

$link = $this->createReplaceableConstantLink(strip_tags($this->cchunk["constant"], "<replaceable>"));
$this->cchunk["constant"] = "";

if ($link === "") {
return $value . '</code></strong>';
}

return '<a href="' . $link . '">' . $value . '</a></code></strong>';
}
return "</code></strong>";
}

/**
* Creates a link to the first constant in the index
* Creates a link to the first constant in the index
* that matches the pattern of a constant containing a <replaceable> tag
* or returns an empty string if no match was found.
*
*
* This works only with one set of <replaceable> tags in a constant
* e.g. CURLE_<replaceable>*</replaceable> or DOM_<replaceable>*</replaceable>_NODE
*/
private function createReplaceableConstantLink(string $constant): string {
$pattern = "/" . preg_replace(
"/<replaceable.*<\/replaceable>/",
".*",
"/<replaceable.*<\/replaceable>/",
".*",
str_replace(
".",
"\.",
".",
"\.",
$this->convertConstantNameToId($constant)
)
) ."/";

$matchingConstantId = "";
foreach ($this->indexes as $index) {
if (preg_match($pattern, $index["docbook_id"])) {
$matchingConstantId = $index["docbook_id"];
break;
}
}

return $matchingConstantId === "" ? "" : $this->createLink($matchingConstantId);
}

private function convertConstantNameToId(string $constantName): string {
$tempLinkValue = str_replace(
array("\\", "_"),
array("-", "-"),
trim($this->normalizeFQN($constantName), "_")
);

if (str_contains($constantName, '::')) {
// class constant
list($extensionAndClass, $constant) = explode("::", $tempLinkValue);
$normalizedLinkFormat = $extensionAndClass . ".constants." . trim($constant, "-");
} else {
$normalizedLinkFormat = 'constant.' . $tempLinkValue;
}

return $normalizedLinkFormat;
}

Expand All @@ -1829,7 +1846,7 @@ public function format_constant_text($value, $tag) {
}

$normalizedLinkFormat = $this->convertConstantNameToId($value);

$link = $this->createLink($normalizedLinkFormat);

if ($link === null) {
Expand All @@ -1844,34 +1861,34 @@ public function format_replaceable($open, $name, $attrs, $props) {
}
return false;
}

public function format_property_text($value, $tag) {
if (! str_contains($value, '::')) {
return $value;
}

$tempLinkValue = str_replace(
["\\", "_", "$"],
["-", "-", ""],
trim($this->normalizeFQN($value), "_")
);

list($extensionAndClass, $property) = explode("::", $tempLinkValue);
$normalizedLinkFormat = $extensionAndClass . ".props." . trim($property, "-");

$link = $this->createLink($normalizedLinkFormat);

if ($link === null || $link === "") {
return $value;
}

return '<a href="' . $link . '">' . $value . '</a>';
}

protected function normalizeFQN(string $fqn): string {
return \ltrim(\strtolower($fqn), "\\");
}

public function admonition_title($title, $lang)
{
return '<strong class="' .(strtolower($title)). '">' .($this->autogen($title, $lang)). '</strong>';
Expand Down
21 changes: 21 additions & 0 deletions phpdotnet/phd/Package/PHP/XHTML.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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 = "";
Expand All @@ -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.'">';
Expand Down