phpDocumentor · wouterj · Nov 28, 2024 · Nov 30, 2024 · Dec 1, 2024 · Dec 1, 2024
diff --git a/composer.lock b/composer.lock
diff --git a/packages/guides-graphs/resources/template/html/body/uml.html.twig b/packages/guides-graphs/resources/template/html/body/uml.html.twig
@@ -1,9 +1,8 @@
-{% apply spaceless %}
-    <figure
-        class="uml-diagram{% if node.classesString %} {{ node.classesString }}{% endif %}"
-        {% if node.hasOption('width') %}style="width: {{ node.option('width') }}"{% endif %}
-    >
-        {{ uml(node.value) }}
-    {% if node.caption %}<figcaption>{{ node.caption }}</figcaption>{% endif %}
-    </figure>
-{% endapply %}
+<figure class="uml-diagram{% if node.classesString %} {{ node.classesString }}{% endif %}"
+    {%- if node.hasOption('width') %} style="width: {{ node.option('width') }}"{% endif -%}
+>
+    {{ uml(node.value) }}
+    {% if node.caption %}
+    <figcaption>{{ node.caption }}</figcaption>
+    {% endif %}
+</figure>
diff --git a/packages/guides-markdown/src/Markdown/Parsers/InlineParsers/EmphasisParser.php b/packages/guides-markdown/src/Markdown/Parsers/InlineParsers/EmphasisParser.php
@@ -18,6 +18,7 @@
 use phpDocumentor\Guides\Nodes\Inline\EmphasisInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use Psr\Log\LoggerInterface;
 
 /** @extends AbstractInlineTextDecoratorParser<EmphasisInlineNode> */
@@ -39,7 +40,7 @@ protected function getType(): string
     /** @param InlineNodeInterface[] $children */
     protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content, array $children = []): InlineNodeInterface
     {
-        return new EmphasisInlineNode($content ?? '', $children);
+        return new EmphasisInlineNode($content ? [new PlainTextInlineNode($content)] : $children);
     }
 
     protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

diff --git a/packages/guides-markdown/src/Markdown/Parsers/InlineParsers/LinkParser.php b/packages/guides-markdown/src/Markdown/Parsers/InlineParsers/LinkParser.php
@@ -18,6 +18,7 @@
 use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use Psr\Log\LoggerInterface;
 
 use function assert;
@@ -48,13 +49,12 @@ protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null
     {
         assert($commonMarkNode instanceof Link);
 
-        $content ??= $commonMarkNode->getUrl();
         $url =  $commonMarkNode->getUrl();
         if (str_ends_with($url, '.md') && filter_var($url, FILTER_VALIDATE_URL) === false) {
             $url = substr($url, 0, -3);
         }
 
-        return new HyperLinkNode($content, $url, $children);
+        return new HyperLinkNode($content ? [new PlainTextInlineNode($content)] : $children, $url);
     }
 
     protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

diff --git a/packages/guides-markdown/src/Markdown/Parsers/InlineParsers/StrongParser.php b/packages/guides-markdown/src/Markdown/Parsers/InlineParsers/StrongParser.php
@@ -17,6 +17,7 @@
 use League\CommonMark\Node\Node as CommonMarkNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\StrongInlineNode;
 use Psr\Log\LoggerInterface;
 
@@ -39,7 +40,7 @@ protected function getType(): string
     /** @param InlineNodeInterface[] $children */
     protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content, array $children = []): InlineNodeInterface
     {
-        return new StrongInlineNode($content ?? '', $children);
+        return new StrongInlineNode($content ? [new PlainTextInlineNode($content)] : $children);
     }
 
     protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/ImageDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/ImageDirective.php
@@ -77,21 +77,21 @@ public function processNode(
     private function resolveLinkTarget(string $targetReference): LinkInlineNode
     {
         if (filter_var($targetReference, FILTER_VALIDATE_EMAIL)) {
-            return new HyperLinkNode('', $targetReference);
+            return new HyperLinkNode([], $targetReference);
         }
 
         if (filter_var($targetReference, FILTER_VALIDATE_URL)) {
-            return new HyperLinkNode('', $targetReference);
+            return new HyperLinkNode([], $targetReference);
         }
 
         if (preg_match(self::REFERENCE_REGEX, $targetReference, $matches)) {
-            return new ReferenceNode($matches[1], '');
+            return new ReferenceNode($matches[1]);
         }
 
         if (preg_match(self::REFERENCE_ESCAPED_REGEX, $targetReference, $matches)) {
-            return new ReferenceNode($matches[1], '');
+            return new ReferenceNode($matches[1]);
         }
 
-        return new DocReferenceNode($targetReference, '');
+        return new DocReferenceNode($targetReference);
     }
 }
diff --git a/...es-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/EmphasisRule.php b/...es-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/EmphasisRule.php
@@ -15,6 +15,7 @@
 
 use phpDocumentor\Guides\Nodes\Inline\EmphasisInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
@@ -45,7 +46,7 @@ public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNod
 
                     $lexer->moveNext();
 
-                    return new EmphasisInlineNode($text);
+                    return new EmphasisInlineNode([new PlainTextInlineNode($text)]);
 
                 default:
                     $text .= $token->value;

diff --git a/...s-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/ReferenceRule.php b/...s-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/ReferenceRule.php
@@ -16,6 +16,7 @@
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
 use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 
 use function filter_var;
@@ -39,13 +40,17 @@ protected function createReference(BlockContext $blockContext, string $reference
         if (str_ends_with($reference, '.rst') && filter_var($reference, FILTER_VALIDATE_URL) === false) {
             $reference = substr($reference, 0, -4);
 
-            return new DocReferenceNode($reference, $text ?? $reference);
+            $text ??= $reference;
+
+            return new DocReferenceNode($reference, $text !== '' ? [new PlainTextInlineNode($text)] : []);
         }
 
         if ($registerLink && $text !== null) {
             $blockContext->getDocumentParserContext()->setLink($text, $reference);
         }
 
-        return new HyperLinkNode($text ?? $reference, $reference);
+        $text ??= $reference;
+
+        return new HyperLinkNode($text !== '' ? [new PlainTextInlineNode($text)] : [], $reference);
     }
 }
diff --git a/...ides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/StrongRule.php b/...ides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/StrongRule.php
@@ -14,6 +14,7 @@
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
 use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\StrongInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
@@ -45,7 +46,7 @@ public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNod
 
                     $lexer->moveNext();
 
-                    return new StrongInlineNode($text);
+                    return new StrongInlineNode([new PlainTextInlineNode($text)]);
 
                 default:
                     $text .= $token->value;

diff --git a/packages/guides-restructured-text/src/RestructuredText/TextRoles/ApiClassTextRole.php b/packages/guides-restructured-text/src/RestructuredText/TextRoles/ApiClassTextRole.php
@@ -14,6 +14,7 @@
 namespace phpDocumentor\Guides\RestructuredText\TextRoles;
 
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
 use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
@@ -49,6 +50,6 @@ protected function createNode(string $referenceTarget, string|null $referenceNam
         $reference = $this->anchorReducer->reduceAnchor($interlinkData->reference);
         $prefix = $this->genericLinkProvider->getLinkPrefix($role);
 
-        return new ReferenceNode($reference, $referenceName ?? '', $interlinkData->interlink, self::TYPE, $prefix);
+        return new ReferenceNode($reference, $referenceName ? [new PlainTextInlineNode($referenceName)] : [], $interlinkData->interlink, self::TYPE, $prefix);
     }
 }
diff --git a/packages/guides-restructured-text/src/RestructuredText/TextRoles/DocReferenceTextRole.php b/packages/guides-restructured-text/src/RestructuredText/TextRoles/DocReferenceTextRole.php
@@ -15,6 +15,7 @@
 
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
 
 /**
@@ -51,6 +52,6 @@ protected function createNode(string $referenceTarget, string|null $referenceNam
     {
         $interlinkData = $this->interlinkParser->extractInterlink($referenceTarget);
 
-        return new DocReferenceNode($interlinkData->reference, $referenceName ?? '', $interlinkData->interlink);
+        return new DocReferenceNode($interlinkData->reference, $referenceName ? [new PlainTextInlineNode($referenceName)] : [], $interlinkData->interlink);
     }
 }
diff --git a/...ages/guides-restructured-text/src/RestructuredText/TextRoles/GenericReferenceTextRole.php b/...ages/guides-restructured-text/src/RestructuredText/TextRoles/GenericReferenceTextRole.php
@@ -14,6 +14,7 @@
 namespace phpDocumentor\Guides\RestructuredText\TextRoles;
 
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
 use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
@@ -48,6 +49,12 @@ protected function createNode(string $referenceTarget, string|null $referenceNam
         $reference = $this->anchorReducer->reduceAnchor($interlinkData->reference);
         $prefix = $this->genericLinkProvider->getLinkPrefix($role);
 
-        return new ReferenceNode($reference, $referenceName ?? '', $interlinkData->interlink, $linkType, $prefix);
+        return new ReferenceNode(
+            $reference,
+            $referenceName ? [new PlainTextInlineNode($referenceName)] : [],
+            $interlinkData->interlink,
+            $linkType,
+            $prefix,
+        );
     }
 }
diff --git a/packages/guides-restructured-text/src/RestructuredText/TextRoles/ReferenceTextRole.php b/packages/guides-restructured-text/src/RestructuredText/TextRoles/ReferenceTextRole.php
@@ -14,6 +14,7 @@
 namespace phpDocumentor\Guides\RestructuredText\TextRoles;
 
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
 
 final class ReferenceTextRole extends AbstractReferenceTextRole
@@ -34,6 +35,6 @@ public function getAliases(): array
     /** @return ReferenceNode */
     protected function createNode(string $referenceTarget, string|null $referenceName, string $role): AbstractLinkInlineNode
     {
-        return new ReferenceNode($referenceTarget, $referenceName ?? '');
+        return new ReferenceNode($referenceTarget, $referenceName ? [new PlainTextInlineNode($referenceName)] : []);
     }
 }
diff --git a/packages/guides-theme-rst/resources/template/rst/inline/emphasis.rst.twig b/packages/guides-theme-rst/resources/template/rst/inline/emphasis.rst.twig
@@ -1 +1 @@
-*{{- node.value|raw -}}*
+*{{- node|plaintext -}}*
diff --git a/packages/guides-theme-rst/resources/template/rst/inline/link.rst.twig b/packages/guides-theme-rst/resources/template/rst/inline/link.rst.twig
@@ -1,7 +1,7 @@
 {%- if node.url -%}
-    `{{ node.value|raw }} <{{- node.url -}}>`__
+    `{{ node|plaintext }} <{{- node.url -}}>`__
 {%- elseif node.targetReference -%}
-    :doc:`{{ node.value|raw }} <{{- node.targetReference -}}>`
+    :doc:`{{ node|plaintext }} <{{- node.targetReference -}}>`
 {%- else -%}
-    {{- node.value -}}
+    {{- node|plaintext -}}
 {%- endif -%}
diff --git a/packages/guides-theme-rst/resources/template/rst/inline/strong.rst.twig b/packages/guides-theme-rst/resources/template/rst/inline/strong.rst.twig
@@ -1 +1 @@
-**{{- node.value|raw -}}**
+**{{- node|plaintext -}}**
diff --git a/packages/guides-theme-rst/src/RstTheme/Twig/RstExtension.php b/packages/guides-theme-rst/src/RstTheme/Twig/RstExtension.php
@@ -14,6 +14,8 @@
 namespace phpDocumentor\Guides\RstTheme\Twig;
 
 use phpDocumentor\Guides\NodeRenderers\NodeRenderer;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
+use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 use phpDocumentor\Guides\Nodes\Table\TableColumn;
 use phpDocumentor\Guides\Nodes\Table\TableRow;
 use phpDocumentor\Guides\Nodes\TableNode;
@@ -57,14 +59,24 @@ public function getFunctions(): array
     public function getFilters(): array
     {
         return [
-            new TwigFilter('clean_content', [$this, 'cleanContent']),
+            new TwigFilter('clean_content', $this->cleanContent(...)),
+            new TwigFilter('plaintext', $this->plaintext(...)),
         ];
     }
 
+    public function plaintext(InlineNodeInterface $node): string
+    {
+        if ($node instanceof InlineCompoundNode) {
+            return implode('', array_map($this->plaintext(...), $node->getChildren()));
+        }
+
+        return $node->toString();
+    }
+
     public function cleanContent(string $content): string
     {
         $lines = explode("\n", $content);
-        $lines = array_map('rtrim', $lines);
+        $lines = array_map(rtrim(...), $lines);
         $content = implode("\n", $lines);
 
         $content = preg_replace('/(\n){2,}/', "\n\n", $content);
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		{{- node.value\|raw -}}
		{{- node\|plaintext -}}
Copy link Member jaapio Dec 1, 2024 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. When I introduced the inline nested nodes I did use the value because that would not require a change in the templates. As templates can be overwritten by consuming projects. I did see that as a backward compatibility issue. This was the reason to try to be backwards compatible and accept the issues in our pipeline. How do you see that? Bc in templates is a very complex problem as I experienced in the past. But maybe I will try to be too strict about this project? Copy link Contributor Author wouterj Dec 2, 2024 • edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. I'm not sure I can follow you. The original content still works, but triggers a deprecation. Are you thinking of a case where the user overrides `getValue()` of a node that now has a BC break because it isn't called anymore? You can use `Deprecation::triggerIfCalledFromOutside()` in `getValue()` then (or the Symfony tactic: add a virtual new boolean parameter to `getValue()` that determines whether the deprecation should be triggered). This should not produce a deprecation when called from a Guides template, but does when called by a user. In general, deprecations are most useful if all of them can be fixed by a user without upgrading the package triggering the deprecation. If Guides triggers a deprecation from itself, I would never know if I can safely upgrade to 2.0.
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		{{- node.value\|raw -}}
		{{- node\|plaintext -}}