Maven Plugin for FlexDoc/XML, Version 1.0

• Content Files
• License
• Installation
  • Installation with DiagramKit
• Running Demos
  • Site 1
  • Site 2
  • Site 3
• Getting Help

Content Files

Note: These files and directories can be found in 'integrations/maven/' subdirectory of FlexDoc/XML installation.

License

• The plugin mojo Java class (FlexDocXMLMojo.java)
• POM files
• Windows batch files
• macOS shell script files
• Linux shell script files

Installation

If you do not have Maven yet, download it from the Apache Maven web-site: http://maven.apache.org/. The download archive will contain exactly the Maven home directory, which you may unpack at any location (e.g. C:\apache-maven-3.8.2).

Further, please follow these steps:

1. Since FlexDoc/XML Maven Plugin stores no FlexDoc/XML Java libraries in the Maven repository, it uses everything directly from the FlexDoc/XML installation whose location must be provided in the plugin POM file:

   {flexdoc-xml}/integrations/maven/plugin/pom.xml

   Please, edit it to specify the absolute pathname of your FlexDoc/XML installation directory in the following lines (highlighted in red):

   <properties>
     <!-- The absolute pathname of FlexDoc/XML home directory -->
     <flexdoc.xml.home>C:/flexdoc-xml-1.13</flexdoc.xml.home>
     ...
   </properties>
   

   Under macOS, to obtain the absolute pathname of a file, drag that file from the Finder into the TextEdit window.

2. On Windows, edit {flexdoc-xml}\integrations\plugin\install.bat to specify 'JAVA_HOME' and 'M2_HOME' variables according to the locations of Java and Maven installed on your system. For example:

   set JAVA_HOME=C:\Program Files\Java\jdk-17
set M2_HOME=C:\apache-maven-3.8.2

   Switch the current directory to {flexdoc-xml}\integrations\maven\plugin and run install.bat.

   Linux

   Equally, edit and run install.sh. Note that you should edit its "Permission" property to allow it to be executed by Linux.

   macOS

   The same edit install.command.

   Since macOS has extremely tight «security control», to be able running install.command, you need to do the following:

   1. First, open install.command with TextEdit (confirm in the warning box that it is OK to open it).

      Then, simply resave that file via File | Save menu.

      With that procedure, you will sign install.command as its owner/creator, which is a precondition to be able running it!

   2. Additionally, you need to assign install.command with the executable privilege: Run the Terminal and type in it 'chmod u+x' followed by a space and the full pathname of the script file (instead of typing it, just drag install.command from the Finder into the Terminal window). Then, press Enter.

   Now, you can run install.command from the Finder just by clicking twice on it.

   If everything is correct, the FlexDoc/XML Maven Plugin will be compiled and installed.

   Note that to pass the installation successfully, you must be connected to Internet during it. You should wait until Maven downloads and installs lots of other plugins it needs.

3. To test the plugin, edit (according to your Java and Maven locations) and run:
   • plugin\test.bat (on Windows)
   • plugin/test.sh (on Linux)
   • plugin/test.command (on macOS)
   The generator dialog should appear.

Installation with DiagramKit

• pom.xml
• install.(bat|sh|command)

• pom_with_DiagramKit.xml
• install_with_DiagramKit.(bat|sh|command)

A demo Maven project that uses DiagramKit (generates XML schema documentation with diagrams) can be found here:

{flexdoc-xml}/DiagramKit/maven/

Running Demos

Site 1

The XML schema to be documented is the "XML Schema for W3C XML Schemas". Its files will be loaded directly from {flexdoc-xml}/lib/resources directory of your FlexDoc/XML installation. (So, you don't need Internet to run this demo.)

In fact, this very schema is used by the "XSDDoc" templates -- the ones which implement the XML Schema documentation generator itself. So, here we have a kind of "bootstrapping". The original "XML Schema for XML Schemas" files can be found by URL: http://www.w3.org/2001/XMLSchema.xsd.

Running the demo is very simple:

1. Switch to {flexdoc-xml}/integrations/maven/site1 directory.
2. Edit (according to your Java and Maven locations) and run:
   • site.bat (on Windows)
   • sile.sh (on Linux) – make it executable by changing its "Permission" properties
   • sile.command (on macOS) – make it executable as described for install.command
   After Maven ends you will see a new 'target' subdirectory.
3. Open target/site/index.html file. Then, go to "Project Reports" and click "XSDDoc". You will see a demo XML Schema documentation generated by FlexDoc/XML XSDDoc.

Site 2

The schemas to be documented are the following:

1. The "XML Schema for XML Schemas", as in the first example. Now, its files will be loaded directly from Internet by the URL:
   • http://www.w3.org/2001/XMLSchema.xsd
2. The "XML Schema for WSDL 1.1". Its initial source files will be loaded by the URLs:
   • http://schemas.xmlsoap.org/wsdl/
   • http://schemas.xmlsoap.org/wsdl/soap/
   • http://schemas.xmlsoap.org/wsdl/http/
   • http://schemas.xmlsoap.org/wsdl/mime/

1. Switch to {flexdoc-xml}/integrations/maven/site2 directory.
2. Edit (according to your Java and Maven locations) and run:
   • site.bat (on Windows)
   • sile.sh (on Linux) – make it executable by changing its "Permission" properties
   • sile.command (on macOS) – make it executable as described for install.command
   After Maven ends you will see a new 'target' subdirectory.
3. Open target/site/index.html file. Then, go to "Project Reports" and click "XMLSchema_xsddoc" or "wsdl11_xsddoc". You will see two different XML Schema documentations generated with FlexDoc/XML XSDDoc.

Site 3

1. One is the XML schema documentation again. It will be generated for {flexdoc-xml}/samples/sales/sales.xsd, the XML schema that describes the data source for the second report.

2. The second is the "Sales Report" report generated with {flexdoc-xml}/samples/sales/sales.tpl template (which uses the sales.xsd schema) from {flexdoc-xml}/samples/sales/sales.xml (which is the source of the report's data). The "Sales Report" itself has nothing to do with XML schemas!

1. Switch to {flexdoc-xml}/integrations/maven/site3 directory.
2. Edit (according to your Java and Maven locations) and run:
   • site.bat (on Windows)
   • sile.sh (on Linux) – make it executable by changing its "Permission" properties
   • sile.command (on macOS) – make it executable as described for install.command
   After Maven ends you will see a new 'target' subdirectory.
3. Open target/site/index.html file. Then, go to "Project Reports" and click "Sales XSDDoc" or "Sales Report".

Getting Help

• Docs | FlexDoc/XML | Integrations | Maven
• www.flexdoc.xyz | FlexDoc/XML | Integrations | Maven