You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2026/08/10 00:04:52 UTC
(maven-checkstyle-plugin) branch faq-to-markdown created (now 7b698a1)
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a change to branch faq-to-markdown
in repository https://gitbox.apache.org/repos/asf/maven-checkstyle-plugin.git
at 7b698a1 Convert the FAQ from FML to Markdown
This branch includes the following new commits:
new a28374d Rename the FAQ ahead of converting it
new 7b698a1 Convert the FAQ from FML to Markdown
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(maven-checkstyle-plugin) 02/02: Convert the FAQ from FML to Markdown
Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch faq-to-markdown
in repository https://gitbox.apache.org/repos/asf/maven-checkstyle-plugin.git
commit 7b698a1b4b6ec5b1c91d7d6ec3e3f016ec1ca72d
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 02:04:42 2026 +0200
Convert the FAQ from FML to Markdown
doxia-converter cannot target FML usefully - the questions come out as
link-reference syntax rather than headings, the [top] back-links become
links to a nonexistent 'top' page, and the contents links lose their #
anchors. The page is written out by hand instead.
Explicit anchors keep the existing deep links working. Every id here is
rewritten at render time, because none of them is a valid XML name:
<faq id="What is the difference between checkstyle:checkstyle and
checkstyle:check"> is served as
#What_is_the_difference_between_checkstyle.3Acheckstyle_and_checkstyle
.3Acheck, since DoxiaUtils.encodeId escapes the colons as well as the
spaces. The <a name> emitted here reproduces those rendered forms, not
the raw attributes, so the live URLs still resolve.
Verified by building the site before and after and comparing the set of
anchors the generated faq.html actually serves. Every anchor present
before is still present after:
before: Where_is_maven_checks.xml_predefined_ruleset,
How_are_the_Checkstyle_properties_set,
How_do_I_set_a_custom_ruleset,
How_do_I_include_the_test_directory_in_Checkstyle,
What_is_the_difference_between_checkstyle.3Acheckstyle_and_
checkstyle.3Acheck, top, bodyColumn
after: the same seven, plus six heading-derived ids
The <head> is byte-identical, so the title and metadata are unchanged.
site.xml needs no edit - src/site/fml/faq.fml and
src/site/markdown/faq.md both render to faq.html.
FML generates a [top] back-link after each answer; those are dropped
rather than hand-written. The question now renders as an h3 heading
instead of a definition term. Those are the only rendering losses.
Generated-by: Claude Opus 5 (1M context)
---
src/site/markdown/faq.md | 110 ++++++++++++++++++++++-------------------------
1 file changed, 52 insertions(+), 58 deletions(-)
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index 35405bd..cec7a37 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -1,4 +1,6 @@
-<?xml version="1.0" encoding="UTF-8"?>
+---
+title: Frequently Asked Questions
+---
<!--
Licensed to the Apache Software Foundation (ASF) under one
@@ -19,60 +21,52 @@ specific language governing permissions and limitations
under the License.
-->
-<faqs xmlns="http://maven.apache.org/FML/1.0.1"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
- id="FAQ" title="Frequently Asked Questions">
- <part id="General">
- <faq id="Where is maven_checks.xml predefined ruleset">
- <question>Where is <code>config/maven_checks.xml</code> predefined ruleset?</question>
- <answer>
- <p>
- Starting with maven-checkstyle-plugin version 2.14, <code>config/maven_checks.xml</code> predefined ruleset
- is not part of the plugin any more but has moved to
- <a href="/shared/maven-shared-resources/">Apache Maven Shared Resources</a>.
- </p>
- </answer>
- </faq>
- <faq id="How are the Checkstyle properties set">
- <question>How are the Checkstyle properties set?</question>
- <answer>
- <p>
- You can set the Checkstyle properties to be used in the plugin configuration of your POM through the
- <code>propertiesLocation</code> parameter. The properties file will be resolved by the plugin based
- on its value.
- </p>
- </answer>
- </faq>
- <faq id="How do I set a custom ruleset">
- <question>How do I set a custom ruleset?</question>
- <answer>
- <p>
- You can set a custom ruleset through the <code>configLocation</code> plugin parameter. If no value is
- specified, the plugin will use a default ruleset, which is the <code>sun_checks.xml</code>, that is bundled with the
- plugin.
- </p>
- </answer>
- </faq>
- <faq id="How do I include the test directory in Checkstyle">
- <question>How do I include the test directory in Checkstyle?</question>
- <answer>
- <p>
- You can include the test directory in the Checkstyle report by setting the
- <code>includeTestSourceDirectory</code> plugin parameter to <code>true</code>.
- </p>
- </answer>
- </faq>
- <faq id="What is the difference between checkstyle:checkstyle and checkstyle:check">
- <question>What is the difference between checkstyle:checkstyle and checkstyle:check?</question>
- <answer>
- <p>
- The checkstyle:checkstyle goal is a <strong>reporting</strong> goal that adds a report
- of Checkstyle violations to the output of the maven-site-plugin. The checkstyle:check goal
- is an ordinary goal that reports violations to the console and/or fails the build when there
- are violations.
- </p>
- </answer>
- </faq>
- </part>
-</faqs>
+<a name="top"></a>
+
+# Frequently Asked Questions
+
+1. [Where is `config/maven_checks.xml` predefined ruleset?](#Where_is_maven_checks.xml_predefined_ruleset)
+1. [How are the Checkstyle properties set?](#How_are_the_Checkstyle_properties_set)
+1. [How do I set a custom ruleset?](#How_do_I_set_a_custom_ruleset)
+1. [How do I include the test directory in Checkstyle?](#How_do_I_include_the_test_directory_in_Checkstyle)
+1. [What is the difference between checkstyle:checkstyle and checkstyle:check?](#What_is_the_difference_between_checkstyle.3Acheckstyle_and_checkstyle.3Acheck)
+
+<a name="Where_is_maven_checks.xml_predefined_ruleset"></a>
+
+### Where is `config/maven_checks.xml` predefined ruleset?
+
+Starting with maven-checkstyle-plugin version 2.14, `config/maven_checks.xml`
+predefined ruleset is not part of the plugin any more but has moved to
+[Apache Maven Shared Resources](/shared/maven-shared-resources/).
+
+<a name="How_are_the_Checkstyle_properties_set"></a>
+
+### How are the Checkstyle properties set?
+
+You can set the Checkstyle properties to be used in the plugin configuration of your
+POM through the `propertiesLocation` parameter. The properties file will be resolved
+by the plugin based on its value.
+
+<a name="How_do_I_set_a_custom_ruleset"></a>
+
+### How do I set a custom ruleset?
+
+You can set a custom ruleset through the `configLocation` plugin parameter. If no
+value is specified, the plugin will use a default ruleset, which is the
+`sun_checks.xml`, that is bundled with the plugin.
+
+<a name="How_do_I_include_the_test_directory_in_Checkstyle"></a>
+
+### How do I include the test directory in Checkstyle?
+
+You can include the test directory in the Checkstyle report by setting the
+`includeTestSourceDirectory` plugin parameter to `true`.
+
+<a name="What_is_the_difference_between_checkstyle.3Acheckstyle_and_checkstyle.3Acheck"></a>
+
+### What is the difference between checkstyle:checkstyle and checkstyle:check?
+
+The checkstyle:checkstyle goal is a **reporting** goal that adds a report of
+Checkstyle violations to the output of the maven-site-plugin. The checkstyle:check
+goal is an ordinary goal that reports violations to the console and/or fails the
+build when there are violations.
(maven-checkstyle-plugin) 01/02: Rename the FAQ ahead of converting it
Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch faq-to-markdown
in repository https://gitbox.apache.org/repos/asf/maven-checkstyle-plugin.git
commit a28374db9da569dcd533f7fb704e1623ea8e3718
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 02:00:32 2026 +0200
Rename the FAQ ahead of converting it
Git records a rename plus a rewrite in one commit as a delete and an
add, which stops 'git log --follow'. Splitting the rename out keeps the
history. Please merge or rebase rather than squash.
Generated-by: Claude Opus 5 (1M context)
---
src/site/{fml/faq.fml => markdown/faq.md} | 0
1 file changed, 0 insertions(+), 0 deletions(-)
diff --git a/src/site/fml/faq.fml b/src/site/markdown/faq.md
similarity index 100%
rename from src/site/fml/faq.fml
rename to src/site/markdown/faq.md