From 902e0bff9ca4c10ed5b30b09b5a0b7fb3324c9bc Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 13:52:57 +0200 Subject: [PATCH 1/2] Rename the site documents ahead of converting them A pure rename, so that git records it and `git log --follow` and `git blame` still reach the history of each page after the conversion that follows. The content is still APT at this point and the site does not build between the two commits. --- src/site/{apt/filemappers.apt => markdown/filemappers.md} | 0 src/site/{apt/fileselectors.apt => markdown/fileselectors.md} | 0 src/site/{apt/index.apt => markdown/index.md} | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename src/site/{apt/filemappers.apt => markdown/filemappers.md} (100%) rename src/site/{apt/fileselectors.apt => markdown/fileselectors.md} (100%) rename src/site/{apt/index.apt => markdown/index.md} (100%) diff --git a/src/site/apt/filemappers.apt b/src/site/markdown/filemappers.md similarity index 100% rename from src/site/apt/filemappers.apt rename to src/site/markdown/filemappers.md diff --git a/src/site/apt/fileselectors.apt b/src/site/markdown/fileselectors.md similarity index 100% rename from src/site/apt/fileselectors.apt rename to src/site/markdown/fileselectors.md diff --git a/src/site/apt/index.apt b/src/site/markdown/index.md similarity index 100% rename from src/site/apt/index.apt rename to src/site/markdown/index.md From 8fc5a91f55eef7c1033caf9dc7794ac3456b165f Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 13:52:57 +0200 Subject: [PATCH 2/2] Port the site documentation from APT to Markdown 3 page(s) converted with doxia-converter and then cleaned up by hand: - <<>> becomes backticks, <> becomes **bold**, {{{url}text}} becomes [text](url) - the ASF license header becomes a single block HTML comment - a page whose only Velocity reference was ${project.name} is now a plain .md with the title spelled out - a page that keeps a reference stays a .vm. Velocity reads ## as a line comment and would silently swallow every ATX heading below level one, so subsections use setext underlines and anything deeper is wrapped in #[[ ... ]]# - references APT rendered literally are escaped, so they do not resolve Verified by building the site before and after and comparing every generated page: the visible text and the link targets are unchanged apart from / becoming / and quotes in prose picking up the Markdown module's typographic substitution. --- src/site/markdown/filemappers.md | 148 +++++++++++------------------ src/site/markdown/fileselectors.md | 81 +++++++--------- src/site/markdown/index.md | 30 ++---- 3 files changed, 93 insertions(+), 166 deletions(-) diff --git a/src/site/markdown/filemappers.md b/src/site/markdown/filemappers.md index c4de00d4..e47aa92d 100644 --- a/src/site/markdown/filemappers.md +++ b/src/site/markdown/filemappers.md @@ -1,122 +1,84 @@ +# File Mappers - ------------ - File Mappers - ------------ +A file mapper is a plexus component, which allows to convert file names. File mappers are used when creating files. For example, the [XML Maven Plugin](https://www.mojohaus.org/xml-maven-plugin) allows to specify a file mapper when creating files by XSLT transformation. -File Mappers +File mappers are implementing the interface [FileMapper](./apidocs/org/codehaus/plexus/components/io/filemappers/FileMapper.html). The idea of file mappers is borrowed from the [Ant FileMapper](https://ant.apache.org/manual/Types/mapper.html), which serves the same purpose within Ant. - A file mapper is a plexus component, which allows to convert file - names. File mappers are used when creating files. For example, - the {{{https://www.mojohaus.org/xml-maven-plugin}XML Maven Plugin}} - allows to specify a file mapper when creating files by XSLT - transformation. +Available file mappers are - File mappers are implementing the interface - {{{./apidocs/org/codehaus/plexus/components/io/filemappers/FileMapper.html}FileMapper}}. - The idea of file mappers is borrowed from the - {{{https://ant.apache.org/manual/Types/mapper.html}Ant FileMapper}}, - which serves the same purpose within Ant. +- The [Identity Mapper](#Identity_Mapper); it uses the role hints "default", or "identity". +- The [File Extension Mapper](#File_Extension_Mapper); its role hint is "fileExtension". +- The [Flattening File Mapper](#Flattening_File_Mapper) with the role hint of "flatten". +- The [Merging File Mapper](#Merging_File_Mapper); its role hint is "merge". +- The [Suffix File Mapper](#Suffix_File_Mapper); its role hint is "suffix". - Available file mappers are +## Identity Mapper - * The {{{#Identity Mapper}Identity Mapper}}; it uses the role hints - "default", or "identity". +The [identity mapper](./apidocs/org/codehaus/plexus/components/io/filemappers/IdentityMapper.html) maps any file name to itself. This may be handy, where you want to avoid the value null for file mappers. The identity takes no configuration parameters. - * The {{{#File Extension Mapper}File Extension Mapper}}; its role hint - is "fileExtension". +For example, to use the identity mapper within the XML Maven Plugins `transform` goal, you would use the following configuration snipped: - * The {{{#Flattening File Mapper}Flattening File Mapper}} with the role - hint of "flatten". +``` + +``` - * The {{{#Merging File Mapper}Merging File Mapper}}; its role hint is - "merge". +The identity mapper uses the role hints "identity", or "default". - * The {{{#Suffix File Mapper}Suffix File Mapper}}; its role hint is - "suffix". +## File Extension Mapper -* {Identity Mapper} +The [file extension mapper](./apidocs/org/codehaus/plexus/components/io/filemappers/FileExtensionMapper.html) changes the extension of the created files. For example, if you would use the XML Maven Plugin to convert Docbook into FOP or PDF files, then you would want the generated files to have the extension ".fo", or ".pdf". - The {{{./apidocs/org/codehaus/plexus/components/io/filemappers/IdentityMapper.html}identity mapper}} - maps any file name to itself. This may be handy, where you want to avoid the value null for - file mappers. The identity takes no configuration parameters. +A configuration snippet for using the identity mapper within the XML Maven Plugins `transform` goal would look like this: - For example, to use the identity mapper within the XML Maven Plugins <<>> - goal, you would use the following configuration snipped: +``` + + .pdf + +``` ------------------------------------------------------------------------------ - ------------------------------------------------------------------------------ +The file extension mapper uses the role hints "fileExtension". - The identity mapper uses the role hints "identity", or "default". +## Flattening File Mapper -* {File Extension Mapper} +The [flattening file mapper](./apidocs/org/codehaus/plexus/components/io/filemappers/FlattenFileMapper.html) is used to flatten a directory structure: It removes all directory components. For example, it would convert the name `META-INF/MANIFEST.MF` to `MANIFEST.MF`. - The {{{./apidocs/org/codehaus/plexus/components/io/filemappers/FileExtensionMapper.html}file - extension mapper}} changes the extension of the created files. For example, if you - would use the XML Maven Plugin to convert Docbook into FOP or PDF files, then you would - want the generated files to have the extension ".fo", or ".pdf". +The flattening file mapper takes no configuration parameters. Consequently, a typical configuration snippet would look like this: - A configuration snippet for using the identity mapper within the XML Maven - Plugins <<>> goal would look like this: +``` + +``` ------------------------------------------------------------------------------ - - .pdf - ------------------------------------------------------------------------------ +The flattening file mapper uses the role hint "flatten". - The file extension mapper uses the role hints "fileExtension". +## Merging File Mapper -* {Flattening File Mapper} +The [merging file mapper](./apidocs/org/codehaus/plexus/components/io/filemappers/MergeFileMapper.html) merges all possible file names into one file name. In other words, it performs a constant mapping. For example, a merging file mapper, which maps all possible file names to `theOneAndOnlyFile` would be configured as follows: - The {{{./apidocs/org/codehaus/plexus/components/io/filemappers/FlattenFileMapper.html}flattening - file mapper}} is used to flatten a directory structure: It removes all directory - components. For example, it would convert the name <<>> to - <<>>. +``` + + theOneAndOnlyFile + +``` - The flattening file mapper takes no configuration parameters. Consequently, - a typical configuration snippet would look like this: +The merging file mapper uses the role hint "merge". ------------------------------------------------------------------------------ - ------------------------------------------------------------------------------ +## Suffix File Mapper - The flattening file mapper uses the role hint "flatten". +The [suffix file mapper](./apidocs/org/codehaus/plexus/components/io/filemappers/SuffixFileMapper.html) adds the given suffix to the filename. The suffix will be added before the file extension. Examples : -* {Merging File Mapper} +``` +theFile.txt => theFileNiceSuffix.txt +dir/file.java => dir/fileNiceSuffix.java +fileWithoutExtension => fileWithoutExtensionNiceSuffix +dir/archive.tar.gz => dir/archiveNiceSuffix.tar.gz +``` - The {{{./apidocs/org/codehaus/plexus/components/io/filemappers/MergeFileMapper.html}merging - file mapper}} merges all possible file names into one file name. In other words, it - performs a constant mapping. For example, a merging file mapper, which maps all - possible file names to <<>> would be configured as follows: +It would be configured as follows: ------------------------------------------------------------------------------ - - theOneAndOnlyFile - ------------------------------------------------------------------------------ +``` + + NiceSuffix + +``` - The merging file mapper uses the role hint "merge". - -* {Suffix File Mapper} - - The {{{./apidocs/org/codehaus/plexus/components/io/filemappers/SuffixFileMapper.html}suffix - file mapper}} adds the given suffix to the filename. The suffix will be added before the file - extension. Examples : - ------------------------------------------------------------------------------ - theFile.txt => theFileNiceSuffix.txt - dir/file.java => dir/fileNiceSuffix.java - fileWithoutExtension => fileWithoutExtensionNiceSuffix - dir/archive.tar.gz => dir/archiveNiceSuffix.tar.gz ------------------------------------------------------------------------------ - - It would be configured as follows: - ------------------------------------------------------------------------------ - - NiceSuffix - ------------------------------------------------------------------------------ - - The suffix file mapper uses the role hint "suffix". +The suffix file mapper uses the role hint "suffix". diff --git a/src/site/markdown/fileselectors.md b/src/site/markdown/fileselectors.md index 62e81f6d..57b7216f 100644 --- a/src/site/markdown/fileselectors.md +++ b/src/site/markdown/fileselectors.md @@ -1,63 +1,46 @@ +# File Selectors - -------------- - File Selectors - -------------- +A file selector is a plexus component, which allows to select certain files out of a given set. For example, the [Plexus Archiver](http://plexus.codehaus.org/plexus-archiver) uses file selectors to select the files being archived out of a base directory. Its counterpart, the Plexus Unarchiver allows to restrict the files to unarchive. -File Selectors +File mappers are implementing the interface [FileSelector](./apidocs/org/codehaus/plexus/components/io/fileselectors/FileSelector.html). - A file selector is a plexus component, which allows to select certain - files out of a given set. For example, the {{{http://plexus.codehaus.org/plexus-archiver}Plexus Archiver}} - uses file selectors to select the files being archived out of a base directory. - Its counterpart, the Plexus Unarchiver allows to restrict the files to unarchive. +Available file selectors are - File mappers are implementing the interface - {{{./apidocs/org/codehaus/plexus/components/io/fileselectors/FileSelector.html}FileSelector}}. +- The [All Files Selector](#All_Files_Selector); it uses the role hints "default", or "all". +- The [Standard File Selector](#Standard_File_Selector); its role hint is "standard". - Available file selectors are +## All Files Selector - * The {{{#All Files Selector}All Files Selector}}; it uses the role hints - "default", or "all". +The [selector for all files](./apidocs/org/codehaus/plexus/components/io/fileselectors/AllFilesFileSelector.html) doesn't exclude any files. It is mainly useful when you want to avoid the value null for a file selector. - * The {{{#Standard File Selector}Standard File Selector}}; its role hint - is "standard". +A configuration snippet for using the selector for all files would look like this: -* {All Files Selector} +``` + +``` - The {{{./apidocs/org/codehaus/plexus/components/io/fileselectors/AllFilesFileSelector.html}selector - for all files}} doesn't exclude any files. It is mainly useful when you want to avoid the - value null for a file selector. +The selector for all files uses the role hints "all", or "default". - A configuration snippet for using the selector for all files would look like this: +## Standard File Selector ------------------------------------------------------------------------------ - ------------------------------------------------------------------------------ +The [standard file selector](./apidocs/org/codehaus/plexus/components/io/fileselectors/IncludeExcludeFileSelector) selects files based on include/exclude patterns. - The selector for all files uses the role hints "all", or "default". +A configuration snippet for using the standard file selector would look like this: -* {Standard File Selector} +``` + + + **/*.gif + **/*.png + **/*.jpg + **/*.jpeg + + + bar/ + + true + false + +``` - The {{{./apidocs/org/codehaus/plexus/components/io/fileselectors/IncludeExcludeFileSelector} - standard file selector}} selects files based on include/exclude patterns. - - A configuration snippet for using the standard file selector would look like this: - ------------------------------------------------------------------------------ - - - **/*.gif - **/*.png - **/*.jpg - **/*.jpeg - - - bar/ - - true - false - ------------------------------------------------------------------------------ - - This would include all image files, with the exception of those in the - directory <<>>. The default excludes (for example <<>>) would - apply and file names would be treated case insensitive. +This would include all image files, with the exception of those in the directory `bar`. The default excludes (for example `CVS/`) would apply and file names would be treated case insensitive. diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index b0b7dd14..572af1ab 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -1,28 +1,10 @@ - ------ - Introduction - ------ +# Plexus IO -Plexus IO +Plexus IO is a set of plexus components, which are designed for use in I/O operations. These I/O operations are doing nothing spectacular. For example, [Commons IO](http://jakarta.apache.org/commons/io) is a much more powerful library in the same area. However, the implementation as a plexus component allows reuse in Maven. - Plexus IO is a set of plexus components, which are designed for use - in I/O operations. These I/O operations are doing nothing spectacular. - For example, {{{http://jakarta.apache.org/commons/io}Commons IO}} is - a much more powerful library in the same area. However, the implementation - as a plexus component allows reuse in Maven. +The following component groups are currently available: - The following component groups are currently available: +- [File Mappers](./filemappers.html) +- [File Selectors](./fileselectors.html) - * {{{./filemappers.html}File Mappers}} - - * {{{./fileselectors.html}File Selectors}} - - [] - - Plexus IO components are typically very simple components, who could - very well live as part of the {{{http://plexus.codehaus.org/plexus-utils} - Plexus Utils}}. They do not, because Plexus Utils is a dependency of the - {{{http://plexus.codehaus.org/plexus-containers/plexus-container-default}Plexus Component API}}, - which is in turn a dependency of the Plexus IO test suite (of course, - a Plexus container is required to test components, even if they are - POJO's). In other words, Plexus Utils cannot contain components, because - that would introduce a circular dependency. +Plexus IO components are typically very simple components, who could very well live as part of the [Plexus Utils](http://plexus.codehaus.org/plexus-utils). They do not, because Plexus Utils is a dependency of the [Plexus Component API](http://plexus.codehaus.org/plexus-containers/plexus-container-default), which is in turn a dependency of the Plexus IO test suite (of course, a Plexus container is required to test components, even if they are POJO's). In other words, Plexus Utils cannot contain components, because that would introduce a circular dependency.