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-site.git
commit a6405dc7c3fb1b176eda6ed160524b7812ea0a57 Author: Sylwester Lachiewicz <[email protected]> AuthorDate: Sun Nov 1 10:30:23 2026 +0000 Fix snippets and descriptions on the Doxia and plugin guide pages --- content/markdown/doxia/developers/modules.md.vm | 10 +++++----- content/markdown/doxia/developers/sink.md | 18 +++++++++--------- content/markdown/doxia/macros/index.md | 5 +++-- content/markdown/doxia/overview.md | 9 ++++----- content/markdown/doxia/references/apt-format.md | 6 +++--- content/markdown/doxia/references/doxia-apt.md | 3 +-- content/markdown/doxia/references/index.md | 8 ++++---- .../development/guide-plugin-documentation.md.vm | 11 ++++++----- .../guides/plugin/guide-java-plugin-development.md.vm | 2 +- 9 files changed, 36 insertions(+), 36 deletions(-) diff --git a/content/markdown/doxia/developers/modules.md.vm b/content/markdown/doxia/developers/modules.md.vm index 0e934bee..fc9d11de 100644 --- a/content/markdown/doxia/developers/modules.md.vm +++ b/content/markdown/doxia/developers/modules.md.vm @@ -62,7 +62,7 @@ ${esc.h}${esc.h} Parsing } ``` - Depending on the type markup, extending `AbstractTextParser`, `AbstractXmlParser` or `XhtmlBaseParser` may give you more features. + Depending on the type markup, extending `AbstractTextParser`, `AbstractXmlParser` or `Xhtml5BaseParser` may give you more features. - _MyParseException_ class (optional) @@ -95,7 +95,7 @@ ${esc.h}${esc.h} Generating - _MySink_ class ```java - import org.apache.maven.doxia.sink.SinkAdapter; + import org.apache.maven.doxia.sink.impl.SinkAdapter; public class MySink extends SinkAdapter @@ -104,7 +104,7 @@ ${esc.h}${esc.h} Generating } ``` - Depending on the type markup, extending `AbstractTextSink`, `AbstractXmlSink` or `XhtmlBaseSink` may give you more features. + Depending on the type markup, extending `AbstractTextSink`, `AbstractXmlSink` or `Xhtml5BaseSink` may give you more features. - _MySinkFactory_ class @@ -114,13 +114,13 @@ ${esc.h}${esc.h} Generating @Component( role = SinkFactory.class, hint = "my" ) public class MySinkFactory - extends SinkFactory + implements SinkFactory { ... } ``` - Depending on the type markup, extending `AbstractTextSinkFactory`, `AbstractXmlSinkFactory` or `AbstractBinarySinkFactory` may give you more features. + Depending on the type markup, extending `AbstractTextSinkFactory` or `AbstractXmlSinkFactory` may give you more features. ${esc.h}${esc.h} <a id="References"></a>References diff --git a/content/markdown/doxia/developers/sink.md b/content/markdown/doxia/developers/sink.md index de118f69..199856de 100644 --- a/content/markdown/doxia/developers/sink.md +++ b/content/markdown/doxia/developers/sink.md @@ -47,7 +47,7 @@ Doxia can be used to transform an arbitrary input document to any supported outp parser.parse( reader, sink ); ``` -It is recommended that you use [Plexus](http://plexus.codehaus.org/) to look up the parser. In principle you could instantiate the parser directly ( `Parser parser = new AptParser();` ) but then some special features like macros will not be available. +It is recommended that you use [Plexus](https://codehaus-plexus.github.io/) to look up the parser. In principle you could instantiate the parser directly ( `Parser parser = new AptParser();` ) but then some special features like macros will not be available. You could also use the [Doxia Converter Tool](/doxia/doxia-tools/doxia-converter/index.html) to parse a given file/dir to another file/dir. To move a site from APT to Markdown, see [Migrating APT to Markdown](/doxia/migrating-apt-to-markdown.html). @@ -104,7 +104,7 @@ The snippet below gives a simple example of how to generate a document using the } ``` -A more complete example that also shows the 'canonical' order of events to use when generating a document, can be found in the Doxia [SinkTestDocument](./doxia/doxia-core/xref-test/org/apache/maven/doxia/sink/SinkTestDocument.html) class. +A more complete example that also shows the 'canonical' order of events to use when generating a document, can be found in the Doxia [SinkTestDocument](https://github.com/apache/maven-doxia/blob/master/doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/SinkTestDocument.java) class. ## <a id="Passing_attributes_to_Sink_events"></a>Passing attributes to Sink events @@ -124,7 +124,7 @@ The kind of attributes supported depends on the event and the sink implementatio In **Doxia 1\.0** it was a common practice to use sink.rawText() to generate elements that were not supported by the Sink API. For example, the following snippet could be used to generate a styled HTML <div> block: ```java -sink.RawText( "<div style=\"cool\">" ); +sink.rawText( "<div style=\"cool\">" ); sink.text( "A text with a cool style." ); sink.rawText( "</div>" ); ``` @@ -139,12 +139,12 @@ The correct way to generate the above <div> block is now: SinkEventAttributeSet atts = new SinkEventAttributeSet(); atts.addAttribute( SinkEventAttributes.STYLE, "cool" ); -sink.unknown( "div", new Object[]{new Integer( HtmlMarkup.TAG_TYPE_START )}, atts ); +sink.unknown( "div", new Object[]{HtmlMarkup.TAG_TYPE_START}, atts ); sink.text( "A text with a cool style." ); -sink.unknown( "div", new Object[]{new Integer( HtmlMarkup.TAG_TYPE_END )}, null ); +sink.unknown( "div", new Object[]{HtmlMarkup.TAG_TYPE_END}, null ); ``` -Read the javadocs of the unknown() method in the [Sink](./doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html) interface and the [XhtmlbaseSink](./doxia/doxia-core/apidocs/org/apache/maven/doxia/sink/XhtmlBaseSink.html) for information on the method parameters. Note that an arbitrary sink may be expected to ignore the unknown event completely! +Read the javadocs of the unknown() method in the [Sink](../doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html) interface and the [Xhtml5BaseSink](../doxia/doxia-core/apidocs/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.html) for information on the method parameters. Note that an arbitrary sink may be expected to ignore the unknown event completely! **In general, the rawText method should be avoided alltogether when emitting events into an arbitrary Sink.** @@ -161,9 +161,9 @@ String javascriptCode = "\n function javascriptFunction() {...} \n //"; SinkEventAttributeSet atts = new SinkEventAttributeSet(); atts.addAttribute( SinkEventAttributes.TYPE, "text/javascript" ); -sink.unknown( "script", new Object[]{new Integer( HtmlMarkup.TAG_TYPE_START )}, atts ); -sink.unknown( "cdata", new Object[]{new Integer( HtmlMarkup.CDATA_TYPE ), javascriptCode }, null ); -sink.unknown( "script", new Object[]{new Integer( HtmlMarkup.TAG_TYPE_END )}, null ); +sink.unknown( "script", new Object[]{HtmlMarkup.TAG_TYPE_START}, atts ); +sink.unknown( "cdata", new Object[]{HtmlMarkup.CDATA_TYPE, javascriptCode}, null ); +sink.unknown( "script", new Object[]{HtmlMarkup.TAG_TYPE_END}, null ); ``` ## <a id="References"></a>References diff --git a/content/markdown/doxia/macros/index.md b/content/markdown/doxia/macros/index.md index 8ef30b54..ddbcef43 100644 --- a/content/markdown/doxia/macros/index.md +++ b/content/markdown/doxia/macros/index.md @@ -136,6 +136,7 @@ The `id` parameter is not required if you want to include the entire file. If yo |file|The path of the file to include (since doxia-1\.0-alpha-9).| |verbatim|If the content should be output as verbatim escaped text. If this is set to `false` then the content of the snippet will not be escaped. This means that you can use it like Server-Side Includes on a webserver. Default value is `true`.| |encoding|The encoding of the file to read (since Doxia 1\.6). If omitted the default JVM encoding will be used.| + ## <a id="TOC_Macro"></a>TOC Macro The _TOC_ macro prints a Table Of Content of a document. It is useful if you have several sections and subsections in your document. For instance, in an APT file, you could write: @@ -153,8 +154,8 @@ In a xdoc file, it will be: ```xml <macro name="toc"> <param name="section" value="2"/> - <param name="fromDepth" value="0"/> - <param name="toDepth" value="4"/> + <param name="fromDepth" value="2"/> + <param name="toDepth" value="3"/> </macro> ``` diff --git a/content/markdown/doxia/overview.md b/content/markdown/doxia/overview.md index 76d169f7..7898f212 100644 --- a/content/markdown/doxia/overview.md +++ b/content/markdown/doxia/overview.md @@ -54,7 +54,7 @@ To find out more about the Sink API, you could read the Javadoc [here](http://ma ## Doxia Core -The _Core_ is the API to parse a source and populate it in a _Sink_ object. The _Parser_ interface contains only one method: +The _Core_ is the API to parse a source and populate it in a _Sink_ object. The _Parser_ interface's central method is: ```java void parse( Reader source, Sink sink ) @@ -65,7 +65,7 @@ The _ParseException_ class has the responsibility to catch all parsing exception The _AbstractParser_ class is an abstract implementation of the _Parser_. It provides a macro mechanism to give dynamic functionalities for the parsing. For more information on macros, read the [Doxia Macro Guide](./macros/index.html). -Finally, the _SiteModule_ interface is the last part of the puzzle. It provides main definitions of a given Doxia module and it is used by the _doxia-site-renderer_ site tools. +Finally, the _ParserModule_ interface is the last part of the puzzle. It provides main definitions of a given Doxia module and it is used by the _doxia-site-renderer_ site tools. ## Doxia Modules @@ -73,7 +73,7 @@ A Doxia module is an implementation of a given markup language like APT or Xdoc. - _Parser_ interface, more specifically the _AbstractParser_ class -- _SiteModule_ interface +- _ParserModule_ interface Several modules provide also a _Sink_ implementation to handle a specific output markup language. @@ -81,7 +81,6 @@ For more information on modules, read the [Doxia Module Guide](./modules/index.h ## Doxia Site Tools -The _Site Tools_ are a collection of tools to renderer an output. The main tool used by Maven, specifically the [Maven Site Plugin](http://maven.apache.org/plugins/maven-site-plugin/), is the _doxia-site-renderer_ which renders in HTML any documents written with supported markup syntax. It uses [Velocity templates](http://velocity.apache.org/) to customize the renderer and the _site-decoration-model_ tool to decorate the renderer. This component describes the layout of the site defined i [...] +The _Site Tools_ are a collection of tools to renderer an output. The main tool used by Maven, specifically the [Maven Site Plugin](http://maven.apache.org/plugins/maven-site-plugin/), is the _doxia-site-renderer_ which renders in HTML any documents written with supported markup syntax. It uses [Velocity templates](http://velocity.apache.org/) to customize the renderer and the _doxia-site-model_ tool to decorate the renderer. This component describes the layout of the site defined in the [...] -The _doxia-doc-renderer_ tool is used to renderer any document in another document. diff --git a/content/markdown/doxia/references/apt-format.md b/content/markdown/doxia/references/apt-format.md index 6ff45364..00b0e480 100644 --- a/content/markdown/doxia/references/apt-format.md +++ b/content/markdown/doxia/references/apt-format.md @@ -49,7 +49,7 @@ A short APT document is contained in a single text file. A longer document may b <dd>Splitting the APT document in several text files on a section boundary is not mandatory. The split may occur anywhere. However doing so is recommended because a text file containing a section is by itself a valid APT document.</dd> </dl> -A file contains a sequence of paragraphs and \`\`displays'' (non paragraphs such as tables) separated by open lines. +A file contains a sequence of paragraphs and "displays" (non paragraphs such as tables) separated by open lines. A paragraph is simply a sequence of consecutive text lines. @@ -64,7 +64,7 @@ A paragraph is simply a sequence of consecutive text lines. The indentation of the first line of a paragraph is the main method used by an APT processor to recognize the type of the paragraph. For example, a section title must not be indented at all. -A \`\`plain'' paragraph must be indented by a certain amount of space. For example, a plain paragraph which is not contained in a list may be indented by two spaces. +A "plain" paragraph must be indented by a certain amount of space. For example, a plain paragraph which is not contained in a list may be indented by two spaces. ```text My section title (not indented). @@ -453,7 +453,7 @@ Unicode characters may be specified by their codes using the `\u`_NNNN_ notation Text found after two tildes (`~~`) is ignored up to the end of line. -A line of `~` is often used to \`\`underline'' section titles in order to make them stand out of other paragraphs. +A line of `~` is often used to "underline" section titles in order to make them stand out of other paragraphs. <!--~~~~~~~~~~~~~~~~~~~~~~~~~~--> diff --git a/content/markdown/doxia/references/doxia-apt.md b/content/markdown/doxia/references/doxia-apt.md index 10a58bee..50a59d99 100644 --- a/content/markdown/doxia/references/doxia-apt.md +++ b/content/markdown/doxia/references/doxia-apt.md @@ -100,8 +100,7 @@ produces: |Header 1|Header 2| |:---|:---| -|Cell� -1|Cell 2| +|Cell<br />1|Cell 2| ## <a id="Anchors"></a>Anchors <!--~~~~~~~~~~~~~~~~~~~--> diff --git a/content/markdown/doxia/references/index.md b/content/markdown/doxia/references/index.md index bbef98ef..de9e6353 100644 --- a/content/markdown/doxia/references/index.md +++ b/content/markdown/doxia/references/index.md @@ -46,7 +46,7 @@ The source directory is the directory under which Maven expects source documents Note some modules are not included per default with the site plugin. Have a look at the available modules here: [https://repo.maven.apache.org/maven2/org/apache/maven/doxia/](https://repo.maven.apache.org/maven2/org/apache/maven/doxia/). -If you need to add module for the `maven-site-plugin` simply add it as a dependency of the plugin: +If you need to add a module that is not bundled, for example AsciiDoc, add it as a dependency of the plugin: ```xml <plugin> @@ -55,9 +55,9 @@ If you need to add module for the `maven-site-plugin` simply add it as a depende <version>...</version> <dependencies> <dependency> - <groupId>org.apache.maven.doxia</groupId> - <artifactId>doxia-module-markdown</artifactId> - <version>...</version> + <groupId>org.asciidoctor</groupId> + <artifactId>asciidoctor-parser-doxia-module</artifactId> + <version>3.2.0</version> </dependency> </dependencies> </plugin> diff --git a/content/markdown/guides/development/guide-plugin-documentation.md.vm b/content/markdown/guides/development/guide-plugin-documentation.md.vm index c2c884d1..7b9b9b19 100644 --- a/content/markdown/guides/development/guide-plugin-documentation.md.vm +++ b/content/markdown/guides/development/guide-plugin-documentation.md.vm @@ -129,7 +129,7 @@ The comments, annotations and plugin goals parameter names are extracted from th * <complexparameter> * <field1>field 1 value</field1> * [...] - * </complexparameter> + * </complexparameter> * </pre> */ @Parameter @@ -150,7 +150,7 @@ The comments, annotations and plugin goals parameter names are extracted from th */ @Mojo(name = "somegoal", defaultPhase = LifecyclePhase.COMPILE) public class ExampleMojo - extends AbstractWarMojo + extends AbstractMojo { public void execute() throws MojoExecutionException, MojoFailureException @@ -175,7 +175,8 @@ Below is the suggested site descriptor template (with maven-fluido-skin). ```xml <?xml version="1.0" encoding="UTF-8"?> -<project> +<site xmlns="http://maven.apache.org/SITE/2.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/SITE/2.1.0 https://maven.apache.org/xsd/site-2.1.0.xsd"> <skin> <groupId>org.apache.maven.skins</groupId> <artifactId>maven-fluido-skin</artifactId> @@ -195,7 +196,7 @@ Below is the suggested site descriptor template (with maven-fluido-skin). <item name="description2" href="examples/example-two.html"/> </menu> </body> -</project> +</site> ``` #[[#### Navigation Links]]# @@ -350,7 +351,7 @@ There are 2 recommended report plugins to enhance the plugin documentation, Java <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jxr-plugin</artifactId> - <version>3.3.1</version> + <version>3.6.0</version> </plugin> </plugins> </reporting> diff --git a/content/markdown/guides/plugin/guide-java-plugin-development.md.vm b/content/markdown/guides/plugin/guide-java-plugin-development.md.vm index 3b1f1bd9..fa563c97 100644 --- a/content/markdown/guides/plugin/guide-java-plugin-development.md.vm +++ b/content/markdown/guides/plugin/guide-java-plugin-development.md.vm @@ -318,7 +318,7 @@ In the configuration section, the element name ("`greeting`") is the parameter n Using Setters ------------- -You are not restricted to using private field mapping which is helpful if you are trying to make your Mojos reusable outside the context of Maven. In the example above, we could define public setter methods that the configuration mapping mechanism can use. You can also add an `@Parameter` annotation on the setter method (from version 3.7.0 of \`plugin-tools\`) +You are not restricted to using private field mapping which is helpful if you are trying to make your Mojos reusable outside the context of Maven. In the example above, we could define public setter methods that the configuration mapping mechanism can use. You can also add an `@Parameter` annotation on the setter method (from version 3.7.0 of `plugin-tools`) So the Mojo would look like the following:
