The Maven plugin docs have XML snippets inline with the Asciidoc content, which provides no syntax help and makes it much easier to make mistakes in the XML. Extracting the XML snippets into separate files that are included in the adoc files would make it easier to validate the XML.
Comment From: robert-smith-911
@scottfrederick Mind if I work on this one?
Comment From: robert-smith-911
@scottfrederick Should this apply to all xml snippets in all of the adoc files? Not just maven plugin docs?
Comment From: scottfrederick
Should this apply to all xml snippets in all of the adoc files? Not just maven plugin docs?
This issue should be limited to just the Maven plugin docs. There is a separate effort underway to extract code snippets/samples from the main Boot docs into separate files, so we should keep the efforts separate to avoid conflicts. We can look at extracting the XML from the main docs after the code extraction effort is complete.
After further discussion, we'd like to use the same approach for including XML snippets that was used to include Gradle build file snippets in the Gradle plugin documentation. For example this file is a fully formed Gradle build file that can be tested, with the relevant section tagged with comments. The Asciidoctor include directive references the tag so that only a portion of the file is included in the documentation. This is a feature of Asciidoctor that can also be used with XML files.
Following this approach, we'd need to create a fully formed Maven pom.xml file for each example in the docs, copy each snippet from the Asciidoctor files to a tagged section in a pom.xml file, then include the pom.xml files in the adoc files with a tag. The extracted pom.xml files should be in a directory structure that mirrors the names of the adoc files that include them, as was done with the Gradle include files.
@robert-smith-911 Thanks for the offer to work on this. If you're willing to take it on with that scope, we can assign the issue to you. If not, we understand that too.
Comment From: robert-smith-911
@scottfrederick That makes the scope so much larger, but sure, you can assign to me, thanks!
Comment From: scottfrederick
Thank you @robert-smith-911. We'll just make this change on the master branch so I've assigned it to the 2.5.x milestone.
Comment From: scottfrederick
Closing in favor of #25534.