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() {