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-converter.git

commit 15c4804fc8a9254eb591a5a7f705d7f841923606
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 3 22:12:30 2026 +0000

    Convert a shared source directory with documents of several formats
---
 .../org/apache/maven/doxia/DefaultConverter.java   | 125 ++++++++++++++++++---
 .../org/apache/maven/doxia/cli/CLIManager.java     |   3 +-
 .../org/apache/maven/doxia/cli/ConverterCli.java   |  11 +-
 .../maven/doxia/wrapper/InputFileWrapper.java      |   8 +-
 src/site/markdown/usage.md.vm                      |  22 +++-
 .../java/org/apache/maven/doxia/ConverterTest.java |  64 +++++++++++
 6 files changed, 208 insertions(+), 25 deletions(-)

diff --git a/src/main/java/org/apache/maven/doxia/DefaultConverter.java 
b/src/main/java/org/apache/maven/doxia/DefaultConverter.java
index 0a33920..492c5a0 100644
--- a/src/main/java/org/apache/maven/doxia/DefaultConverter.java
+++ b/src/main/java/org/apache/maven/doxia/DefaultConverter.java
@@ -39,6 +39,7 @@ import java.nio.file.Path;
 import java.nio.file.StandardCopyOption;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collections;
 import java.util.EnumSet;
 import java.util.HashMap;
 import java.util.LinkedHashMap;
@@ -373,7 +374,11 @@ public class DefaultConverter implements Converter {
 
         outputRenameMap.clear();
         if (input.getFile().isFile()) {
-            convert(input.getFile(), input.getEncoding(), input.getFormat(), 
output);
+            DoxiaFormat format =
+                    input.getFormat() != null ? input.getFormat() : 
DoxiaFormat.autoDetectFormat(input.getFile());
+            convert(input.getFile(), input.getEncoding(), format, output);
+        } else if (input.getFormat() == null) {
+            convertSharedSourceDirectory(input, output);
         } else {
             List<File> files;
             try {
@@ -407,6 +412,108 @@ public class DefaultConverter implements Converter {
         }
     }
 
+    /**
+     * The file extensions that Doxia parser modules declare. In a shared 
source directory, such as
+     * <code>src/site/source</code>, Doxia Sitetools picks the parser by these 
extensions.
+     */
+    static final Map<String, DoxiaFormat> SOURCE_EXTENSIONS;
+
+    static {
+        Map<String, DoxiaFormat> extensions = new LinkedHashMap<>();
+        extensions.put("apt", DoxiaFormat.APT);
+        extensions.put("fml", DoxiaFormat.FML);
+        extensions.put("xml", DoxiaFormat.XDOC);
+        extensions.put("xhtml", DoxiaFormat.XHTML);
+        extensions.put("md", DoxiaFormat.MARKDOWN);
+        extensions.put("markdown", DoxiaFormat.MARKDOWN);
+        SOURCE_EXTENSIONS = Collections.unmodifiableMap(extensions);
+    }
+
+    /**
+     * Converts a directory that holds documents of several formats, the 
format of each picked by its extension as in
+     * {@link #SOURCE_EXTENSIONS}. Documents already in the output format are 
left alone, and so is an XML document
+     * whose root element does not match its format, such as a 
<code>site.xml</code>. Fails before converting anything
+     * if two documents would be written to the same output file.
+     */
+    private void convertSharedSourceDirectory(InputFileWrapper input, 
OutputFileWrapper output)
+            throws ConverterException, UnsupportedFormatException {
+        List<File> files;
+        try {
+            files = FileUtils.getFiles(
+                    input.getFile(),
+                    getFileNamePatterns(
+                            new ArrayList<>(SOURCE_EXTENSIONS.keySet()), 
!input.isExcludeVelocityTemplates()),
+                    StringUtils.join(FileUtils.getDefaultExcludes(), ", "));
+        } catch (IOException e) {
+            throw new ConverterException("IOException: " + e.getMessage(), e);
+        }
+
+        Map<File, DoxiaFormat> formats = new LinkedHashMap<>();
+        Map<File, File> outputs = new HashMap<>();
+        for (File f : files) {
+            String name = f.getName();
+            if (name.endsWith(VELOCITY_TEMPLATE_EXTENSION)) {
+                name = name.substring(0, name.length() - 
VELOCITY_TEMPLATE_EXTENSION.length());
+            }
+            DoxiaFormat format =
+                    
SOURCE_EXTENSIONS.get(FileUtils.getExtension(name).toLowerCase(Locale.ENGLISH));
+            if (format == output.getFormat()) {
+                LOGGER.debug("Skipping \"{}\", already in format {}", f, 
format);
+                continue;
+            }
+            if (format.isXml()
+                    && !f.getName().endsWith(VELOCITY_TEMPLATE_EXTENSION)
+                    && !format.firstElement.equals(getFirstTag(f))) {
+                LOGGER.warn("Skipping \"{}\", its root element is not <{}>", 
f, format.firstElement);
+                continue;
+            }
+            File relativeOutputDirectory =
+                    new 
File(PathTool.getRelativeFilePath(input.getFile().getAbsolutePath(), 
f.getParent()));
+            File outputFile = new File(
+                    new File(output.getFile(), 
relativeOutputDirectory.getPath()),
+                    getOutputFileName(f, output.getFormat()));
+            File other = outputs.put(outputFile.getAbsoluteFile(), f);
+            if (other != null) {
+                throw new ConverterException("ConverterException: \"" + other 
+ "\" and \"" + f
+                        + "\" would both be converted to \"" + outputFile + 
"\"");
+            }
+            formats.put(f, format);
+        }
+        if (formats.isEmpty()) {
+            throw new ConverterException("ConverterException: No files to 
convert to " + output.getFormat()
+                    + " found in directory " + input.getFile());
+        }
+        for (Map.Entry<File, DoxiaFormat> entry : formats.entrySet()) {
+            File f = entry.getKey();
+            File relativeOutputDirectory =
+                    new 
File(PathTool.getRelativeFilePath(input.getFile().getAbsolutePath(), 
f.getParent()));
+            convert(f, input.getEncoding(), entry.getValue(), output, 
relativeOutputDirectory);
+        }
+        if (postProcess == PostProcess.NONE
+                && 
input.getFile().getAbsoluteFile().equals(output.getFile().getAbsoluteFile())) {
+            LOGGER.warn(
+                    "The converted documents sit next to their sources in {}; 
remove the sources, or Doxia Sitetools"
+                            + " reports each pair as a duplicate page",
+                    input.getFile());
+        }
+    }
+
+    /**
+     * @param inputFile the input file, a Velocity template when its name ends 
with <code>.vm</code>
+     * @param outputFormat the output format
+     * @return the name of the output file: the input file name with the 
output format's extension
+     */
+    static String getOutputFileName(File inputFile, DoxiaFormat outputFormat) {
+        String name = inputFile.getName();
+        if (name.endsWith(VELOCITY_TEMPLATE_EXTENSION)) {
+            return FileUtils.removeExtension(name.substring(0, name.length() - 
VELOCITY_TEMPLATE_EXTENSION.length()))
+                    + "."
+                    + outputFormat.getExtension()
+                    + VELOCITY_TEMPLATE_EXTENSION;
+        }
+        return FileUtils.removeExtension(name) + "." + 
outputFormat.getExtension();
+    }
+
     static String getFileNamePatterns(List<String> extensions, boolean 
includeVelocityTemplates) {
         StringJoiner patterns = new StringJoiner(",");
         for (String extension : extensions) {
@@ -525,7 +632,7 @@ public class DefaultConverter implements Converter {
     /**
      * @param inputFile a not null existing file.
      * @param inputEncoding a not null supported encoding or {@link 
InputFileWrapper#AUTO_ENCODING}
-     * @param parserFormat  a not null supported format or {@link 
InputFileWrapper#AUTO_FORMAT}
+     * @param parserFormat  a not null supported format
      * @param output not null OutputFileWrapper object
      * @throws ConverterException if any
      * @throws UnsupportedFormatException if any
@@ -576,19 +683,7 @@ public class DefaultConverter implements Converter {
                 || relativeOutputDirectory != null) {
             // assume it is a directory
             outputDirectoryOrFile.mkdirs();
-            final String outputFileName;
-            if (isVelocityTemplate) {
-                outputFileName = FileUtils.removeExtension(inputFile
-                                .getName()
-                                .substring(0, inputFile.getName().length() - 
VELOCITY_TEMPLATE_EXTENSION.length()))
-                        + "."
-                        + output.getFormat().getExtension()
-                        + VELOCITY_TEMPLATE_EXTENSION;
-            } else {
-                outputFileName = 
FileUtils.removeExtension(inputFile.getName()) + "."
-                        + output.getFormat().getExtension();
-            }
-            outputFile = new File(outputDirectoryOrFile, outputFileName);
+            outputFile = new File(outputDirectoryOrFile, 
getOutputFileName(inputFile, output.getFormat()));
         } else {
             outputDirectoryOrFile.getParentFile().mkdirs();
             outputFile = output.getFile();
diff --git a/src/main/java/org/apache/maven/doxia/cli/CLIManager.java 
b/src/main/java/org/apache/maven/doxia/cli/CLIManager.java
index 9e94efa..ccdbdaa 100644
--- a/src/main/java/org/apache/maven/doxia/cli/CLIManager.java
+++ b/src/main/java/org/apache/maven/doxia/cli/CLIManager.java
@@ -113,7 +113,8 @@ class CLIManager {
                 .hasArg()
                 .build());
         OPTIONS.addOption(Option.builder(FROM)
-                .desc("From format. If not specified, try to autodetect it 
(only works if input is a single file).")
+                .desc("From format. If not specified, autodetect it: for a 
directory, per file by extension, such as"
+                        + " .md, .apt, .xml (xdoc), .xhtml or .fml, skipping 
files already in the target format.")
                 .hasArg()
                 .build());
         OPTIONS.addOption(Option.builder(TO).desc("To 
format.").hasArg().build());
diff --git a/src/main/java/org/apache/maven/doxia/cli/ConverterCli.java 
b/src/main/java/org/apache/maven/doxia/cli/ConverterCli.java
index ba82212..f46533a 100644
--- a/src/main/java/org/apache/maven/doxia/cli/ConverterCli.java
+++ b/src/main/java/org/apache/maven/doxia/cli/ConverterCli.java
@@ -123,9 +123,14 @@ public class ConverterCli {
             final DefaultConverter.DoxiaFormat parserFormat;
             if (CLIManager.AUTO_FORMAT.equalsIgnoreCase(sourceFormat)) {
                 File inputFile = new 
File(commandLine.getOptionValue(CLIManager.IN));
-                parserFormat = 
DefaultConverter.DoxiaFormat.autoDetectFormat(inputFile);
-                if (debug) {
-                    System.out.println("Auto detected input format: " + 
parserFormat);
+                if (inputFile.isDirectory()) {
+                    // detected per file, by extension
+                    parserFormat = null;
+                } else {
+                    parserFormat = 
DefaultConverter.DoxiaFormat.autoDetectFormat(inputFile);
+                    if (debug) {
+                        System.out.println("Auto detected input format: " + 
parserFormat);
+                    }
                 }
             } else {
                 parserFormat = 
DefaultConverter.DoxiaFormat.valueOf(sourceFormat.toUpperCase());
diff --git a/src/main/java/org/apache/maven/doxia/wrapper/InputFileWrapper.java 
b/src/main/java/org/apache/maven/doxia/wrapper/InputFileWrapper.java
index cc9b80a..56912a4 100644
--- a/src/main/java/org/apache/maven/doxia/wrapper/InputFileWrapper.java
+++ b/src/main/java/org/apache/maven/doxia/wrapper/InputFileWrapper.java
@@ -40,7 +40,7 @@ public class InputFileWrapper extends AbstractFileWrapper {
      * Private constructor.
      *
      * @param absolutePath not null
-     * @param format not null
+     * @param format the format, or null to detect it per file
      * @param charsetName could be null
      * @param excludeVelocityTemplates {@code true} to not consider velocity 
templates (ending with .vm) (only relevant when absolutePath is a directory)
      * @throws UnsupportedEncodingException if the encoding is unsupported.
@@ -63,7 +63,7 @@ public class InputFileWrapper extends AbstractFileWrapper {
 
     /**
      * @param absolutePath for a file or a directory not null.
-     * @param format not null
+     * @param format the format, or null to detect it per file
      * @return a type safe input reader
      * @throws UnsupportedEncodingException if the encoding is unsupported.
      * @throws FileNotFoundException if the file for absolutePath is not found.
@@ -76,7 +76,7 @@ public class InputFileWrapper extends AbstractFileWrapper {
 
     /**
      * @param absolutePath for a wanted file or a wanted directory, not null.
-     * @param format not null
+     * @param format the format, or null to detect it per file
      * @param charsetName could be null
      * @return a type safe input reader
      * @throws UnsupportedEncodingException if the encoding is unsupported.
@@ -89,7 +89,7 @@ public class InputFileWrapper extends AbstractFileWrapper {
 
     /**
      * @param absolutePath for a wanted file or a wanted directory, not null.
-     * @param format not null
+     * @param format the format, or null to detect it per file
      * @param charsetName could be null
      * @param excludeVelocityTemplates {@code true} to not consider velocity 
templates (ending with .vm)
      * @return a type safe input reader
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index e0bd346..a2c46fb 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -42,7 +42,8 @@ usage: doxia-converter [-e] [-f] [-from <arg>] [-h] [-in 
<arg>] [-inEncoding <ar
 Options:
  -e,--errors           Produce execution error messages.
  -f,--format           Format the output (actually only xml based outputs) to 
be human readable.
- -from <arg>           From format. If not specified, try to autodetect it.
+ -from <arg>           From format. If not specified, autodetect it: for a 
directory, per file by extension, such as .md,
+                       .apt, .xml (xdoc), .xhtml or .fml, skipping files 
already in the target format.
  -h,--help             Display help information.
  -in,--input <arg>     Input file or directory.
  -inEncoding <arg>     Input file encoding. If not specified, try to 
autodetect it (only works if input is a single file)
@@ -76,7 +77,24 @@ Command Line Execution
     -to markdown
 ```
 
-**Note**: The `from` parameter can be empty. In that case, Doxia converter 
tries to autodetect the `from` input from the `in` file parameter, this only 
works when the input is a file (and not a directory).
+**Note**: The `from` parameter can be empty. In that case, Doxia converter 
autodetects the format of the `in` file, or of each file in the `in` directory.
+
+Shared Source Directory
+-----------------------
+
+Doxia Sitetools can read documents of any format from one directory, 
`src/site/source`, where the file extension picks the parser. Without `-from`, 
the converter reads such a directory the same way: `.apt` is APT, `.md` and 
`.markdown` are Markdown, `.xml` is XDoc, `.xhtml` is XHTML and `.fml` is FML, 
each optionally followed by `.vm`. Files already in the target format are left 
alone, and so is an `.xml` file whose root element is not `<document>`.
+
+To convert every remaining document to Markdown in place, keeping the history 
in Git:
+
+```
+# java -jar target/doxia-converter-${project.version}-shaded.jar \
+    -in src/site/source \
+    -out src/site/source \
+    -to markdown \
+    -gitMvInputToOutput
+```
+
+Use `-removeIn` instead outside Git. Without either, each source stays next to 
its converted document, and Doxia Sitetools reports the pair as a duplicate 
page. The conversion stops before writing anything if two documents, such as 
`usage.apt` and `usage.xml`, would produce the same output file.
 
 Java Usage
 ----------
diff --git a/src/test/java/org/apache/maven/doxia/ConverterTest.java 
b/src/test/java/org/apache/maven/doxia/ConverterTest.java
index 61354a1..11404c6 100644
--- a/src/test/java/org/apache/maven/doxia/ConverterTest.java
+++ b/src/test/java/org/apache/maven/doxia/ConverterTest.java
@@ -48,7 +48,9 @@ import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertLinesMatch;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.junit.jupiter.api.Assertions.fail;
 
@@ -484,4 +486,66 @@ class ConverterTest extends InjectedTest {
             assertTrue(markdown.contains("Text after the object."), "text 
after object missing from:\n" + markdown);
         }
     }
+
+    /**
+     * Converts a shared source directory, such as 
<code>src/site/source</code>, in place: every document not yet in
+     * Markdown is converted next to its source, picking the parser by its 
extension.
+     */
+    @Test
+    void sharedSourceDirectoryInPlace() throws Exception {
+        File dir = new File(getBasedir(), "target/unit/shared/source");
+        FileUtils.deleteDirectory(dir);
+        String markdown = "# Index\n\nAlready Markdown.\n";
+        write(new File(dir, "index.md"), markdown);
+        write(new File(dir, "guide/usage.apt"), "Usage\n\n* APT\n\n  Text.\n");
+        write(
+                new File(dir, "about.xml"),
+                "<document><body><section 
name=\"About\"><p>XDoc</p></section></body></document>");
+        write(
+                new File(dir, "faq.fml"),
+                "<faqs title=\"FAQ\"><part id=\"p\"><faq 
id=\"q\"><question>Q?</question>"
+                        + "<answer><p>A.</p></answer></faq></part></faqs>");
+        write(new File(dir, "notes.apt.vm"), "Notes\n\n* Version\n\n  
${project.version}\n");
+        write(new File(dir, "site.xml"), "<site><body/></site>");
+
+        converter.convert(
+                InputFileWrapper.valueOf(dir.getPath(), null),
+                OutputFileWrapper.valueOf(dir.getPath(), DoxiaFormat.MARKDOWN, 
StandardCharsets.UTF_8.name()));
+
+        assertTrue(new File(dir, "guide/usage.md").isFile());
+        assertTrue(readFile(new File(dir, "about.md")).contains("XDoc"));
+        assertTrue(readFile(new File(dir, "faq.md")).contains("Q?"));
+        assertTrue(readFile(new File(dir, 
"notes.md.vm")).contains("${project.version}"));
+        assertEquals(markdown, readFile(new File(dir, "index.md")));
+        assertFalse(new File(dir, "site.md").exists());
+
+        FileUtils.deleteDirectory(dir);
+    }
+
+    @Test
+    void sharedSourceDirectoryRejectsTwoSourcesForOneOutput() throws Exception 
{
+        File dir = new File(getBasedir(), 
"target/unit/shared-duplicate/source");
+        FileUtils.deleteDirectory(dir);
+        write(new File(dir, "usage.apt"), "Usage\n\n* APT\n\n  Text.\n");
+        write(new File(dir, "usage.xml"), "<document><body><section 
name=\"Usage\"/></body></document>");
+
+        ConverterException e = assertThrows(
+                ConverterException.class,
+                () -> converter.convert(
+                        InputFileWrapper.valueOf(dir.getPath(), null),
+                        OutputFileWrapper.valueOf(dir.getPath(), 
DoxiaFormat.MARKDOWN, StandardCharsets.UTF_8.name())));
+        assertTrue(e.getMessage().contains("usage.md"), e.getMessage());
+        assertFalse(new File(dir, "usage.md").exists());
+
+        FileUtils.deleteDirectory(dir);
+    }
+
+    private static void write(File file, String content) throws IOException {
+        file.getParentFile().mkdirs();
+        Files.write(file.toPath(), content.getBytes(StandardCharsets.UTF_8));
+    }
+
+    private static String readFile(File file) throws IOException {
+        return new String(Files.readAllBytes(file.toPath()), 
StandardCharsets.UTF_8);
+    }
 }

Reply via email to