From 608ebb1b6475244c0e6c9a50c0a8ec4ed02caeeb Mon Sep 17 00:00:00 2001
From: Konrad Windszus <kwin@apache.org>
Date: Sun, 8 Oct 2023 17:10:55 +0200
Subject: [PATCH] Add test for preserving (and not adding additional) URL
 encoding

Make Sink.link(...) javadoc more HTML agnostic by just referencing the
URI RFC
---
 .../doxia/parser/Xhtml5BaseParserTest.java    | 23 ++++++++++++++++++-
 .../org/apache/maven/doxia/sink/Sink.java     |  7 ++++--
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/doxia-core/src/test/java/org/apache/maven/doxia/parser/Xhtml5BaseParserTest.java b/doxia-core/src/test/java/org/apache/maven/doxia/parser/Xhtml5BaseParserTest.java
index 458d2f47e..1f72af99a 100644
--- a/doxia-core/src/test/java/org/apache/maven/doxia/parser/Xhtml5BaseParserTest.java
+++ b/doxia-core/src/test/java/org/apache/maven/doxia/parser/Xhtml5BaseParserTest.java
@@ -695,6 +695,28 @@ public void testFigure() throws Exception {
         assertEquals("figure_", it.next().getName());
     }
 
+    @Test
+    public void testLink() throws Exception {
+        // param1 value = "/&ü" URL encoded twice!
+        String text = "<div>"
+                + "<a href=\"http://www.fo.com/index.html&amp;param1=%252F%2526%25C3%25BC\"></a>"
+                + "</div>";
+
+        parser.parse(text, sink);
+        Iterator<SinkEventElement> it = sink.getEventList().iterator();
+
+        SinkEventElement element = it.next();
+        assertEquals("division", element.getName());
+
+        element = it.next();
+        assertEquals("link", element.getName());
+        assertEquals("http://www.fo.com/index.html&param1=%252F%2526%25C3%25BC", element.getArgs()[0]);
+        assertEquals("link_", it.next().getName());
+
+        element = it.next();
+        assertEquals("division_", element.getName());
+    }
+
     @Test
     public void testAnchorLink() throws Exception {
         String text = "<div><a href=\"\"></a>" + "<a href=\"valid\"></a>"
@@ -748,7 +770,6 @@ public void testAnchorLink() throws Exception {
         element = it.next();
         assertEquals("division_", element.getName());
     }
-
     /**
      * Test entities in attributes.
      *
diff --git a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java b/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
index c89ad68ef..ecabcbee0 100644
--- a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
+++ b/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
@@ -1433,9 +1433,11 @@ public interface Sink extends AutoCloseable {
      * Starts a link.
      *
      * <p>
-     *   The <code>name</code> parameter has to be a valid html <code>href</code>
-     *   parameter, ie for internal links (links to an anchor within the same source
+     *   The <code>name</code> parameter has to be a valid URI according to
+     *   <a href="https://datatracker.ietf.org/doc/html/rfc3986">RFC 3986</a>,
+     *   i.e. for internal links (links to an anchor within the same source
      *   document), <code>name</code> should start with the character "#".
+     *   This also implies that all unsafe characters are already encoded.
      * </p>
      * <p>
      *   Supported attributes are the {@link SinkEventAttributes base attributes} plus:
@@ -1455,6 +1457,7 @@ public interface Sink extends AutoCloseable {
      * @param name the name of the link.
      * @param attributes A set of {@link SinkEventAttributes}, may be <code>null</code>.
      * @since 1.1
+     * @see java.net.URI#toASCIIString()
      */
     void link(String name, SinkEventAttributes attributes);