This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-doxia-sitetools.git


The following commit(s) were added to refs/heads/master by this push:
     new 5e71a7f  Document that getRelativePath treats from as a directory
5e71a7f is described below

commit 5e71a7fbee73bd2ed174c5e1a16012ba1b11196d
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 3 01:54:04 2026 +0000

    Document that getRelativePath treats from as a directory
    
    Every caller passes a site or distribution URL, usually without a trailing 
slash, so a page name in from counts
    as a directory name: from index.html to download.html gives 
../download.html. Treating from as a file would
    change the result for all those callers.
    
    Closes #395
---
 .../src/main/java/org/apache/maven/doxia/tools/SiteTool.java | 10 ++++++++--
 .../org/apache/maven/doxia/tools/DefaultSiteToolTest.java    | 12 ++++++++++++
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git 
a/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/SiteTool.java
 
b/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/SiteTool.java
index b3863d4..ac426ee 100644
--- 
a/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/SiteTool.java
+++ 
b/doxia-integration-tools/src/main/java/org/apache/maven/doxia/tools/SiteTool.java
@@ -186,7 +186,13 @@ public interface SiteTool {
 
     /**
      * Calculate the relative path between two URLs or between two files.
-     *
+     * <p>
+     * <code>from</code> is always treated as a directory, with or without a 
trailing slash, since callers pass
+     * site and distribution URLs. To link from a page, pass the page's 
directory: from
+     * <code>http://maven.apache.org/index.html</code> to 
<code>http://maven.apache.org/download.html</code> the
+     * result is <code>../download.html</code>, from 
<code>http://maven.apache.org/</code> it is
+     * <code>download.html</code>.
+     * </p>
      * For example:
      * <dl>
      * <dt>to = "http://maven.apache.org"; and from = 
"http://maven.apache.org";</dt>
@@ -203,7 +209,7 @@ public interface SiteTool {
      * <code>scm:svn:https://svn.apache.org/repos/asf</code>.
      *
      * @param to the <code>to</code> url of file as string
-     * @param from the <code>from</code> url of file as string
+     * @param from the <code>from</code> url of the base directory as string
      * @return a relative path from <code>from</code> to <code>to</code>.
      */
     String getRelativePath(String to, String from);
diff --git 
a/doxia-integration-tools/src/test/java/org/apache/maven/doxia/tools/DefaultSiteToolTest.java
 
b/doxia-integration-tools/src/test/java/org/apache/maven/doxia/tools/DefaultSiteToolTest.java
index 1c2ce85..b8b31ec 100644
--- 
a/doxia-integration-tools/src/test/java/org/apache/maven/doxia/tools/DefaultSiteToolTest.java
+++ 
b/doxia-integration-tools/src/test/java/org/apache/maven/doxia/tools/DefaultSiteToolTest.java
@@ -74,6 +74,18 @@ class DefaultSiteToolTest {
                 tool.getRelativePath("http://example.com/foo/bar.html";, 
"http://example.com/foo/baz.html";));
     }
 
+    @SuppressWarnings("deprecation")
+    @Test
+    void getRelativePathTreatsFromAsDirectory() {
+        // a page name in from is a directory name: callers pass site and 
distribution URLs
+        assertEquals(
+                ".." + File.separator + "download.html",
+                tool.getRelativePath("http://maven.apache.org/download.html";, 
"http://maven.apache.org/index.html";));
+        assertEquals(
+                "download.html",
+                tool.getRelativePath("http://maven.apache.org/download.html";, 
"http://maven.apache.org/";));
+    }
+
     @SuppressWarnings("deprecation")
     @Test
     void getRelativePathSame() {

Reply via email to