Asciidoc: Create PDFs from multi-page guides

Using Asciidoctor Maven, we now produce PDFs (which are also linked to
from the main documentation index page) for
  - Programming Guide,
  - AspectJ 5 Developer's Notebook,
  - Development Environment Guide,
  - Problem Diagnosis Guide,
  - AspectJ Design Overview.

Attention! PDF generation alone takes 3+ minutes, almost 4 minutes
including asciidoc to HTML conversion. Just deactivate the 'create-docs'
profile if you do not need docs during the build.

Closes #272.

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

diff --git a/docs/index.adoc b/docs/index.adoc
index 0b74470384687982af4de8b37e678c82bcd49f3d..21ffd5136ab449460a7126057191a2406d4c9e77 100644 (file)
--- a/docs/index.adoc
+++ b/docs/index.adoc
@@ -40,13 +40,19 @@ mailto:aspectj-users@eclipse.org[users] and mailto:aspectj-dev@eclipse.org[devel
 |xref:quickref/quick.pdf[AspectJ Quick Reference]
 |Two-page quick reference for the AspectJ language
 
-|xref:adk15notebook/index.adoc[AspectJ 5 Developer's Notebook] +
-(xref:adk15notebook/adk15notebook.adoc[single page])
+a|AspectJ 5 Developer's Notebook
+
+* xref:adk15notebook/index.adoc[HTML multi-page]
+* xref:adk15notebook/adk15notebook.adoc[HTML single page]
+* xref:adk15notebook/adk15notebook.pdf[PDF]
 |Describes the changes to the AspectJ language and tools introduced in the AspectJ 5 Development Kit. These changes are
 additive, and are not yet reflected in the programming guide or quick reference.
 
-|xref:progguide/index.adoc[Programming Guide] +
-(xref:progguide/progguide.adoc[single page])
+a|Programming Guide
+
+* xref:progguide/index.adoc[HTML multi-page]
+* xref:progguide/progguide.adoc[HTML single page]
+* xref:progguide/progguide.pdf[PDF]
 |Introduces AOP and the AspectJ language. xref:progguide/gettingstarted.adoc[Getting Started] describes basic semantics
 and shows development- and production-time applications. xref:progguide/language.adoc[The AspectJ Language] describes
 join points, pointcuts, advice, and introduction, all features new to AOP. xref:progguide/examples.adoc[Examples] walks
@@ -57,13 +63,19 @@ syntax, the xref:progguide/semantics.adoc[Language Semantics] best describes Asp
 xref:progguide/implementation.adoc[Implementation Notes] describes how the current version is limited to code the
 compiler controls.
 
-|xref:devguide/index.adoc[Development Environment Guide] +
-(xref:devguide/devguide.adoc[single page])
+a|Development Environment Guide
+
+* xref:devguide/index.adoc[HTML multi-page]
+* xref:devguide/devguide.adoc[HTML single page]
+* xref:devguide/devguide.pdf[PDF]
 |Guide to the command-line compiler xref:devguide/ajc.adoc[ajc] and the xref:devguide/antsupport.adoc[Ant tasks] for
 building AspectJ programs
 
-|xref:pdguide/index.adoc[Problem Diagnosis Guide] +
-(xref:pdguide/pdguide.adoc[single page])
+a|Problem Diagnosis Guide
+
+* xref:pdguide/index.adoc[HTML multi-page]
+* xref:pdguide/pdguide.adoc[HTML single page]
+* xref:pdguide/pdguide.pdf[PDF]
 |Guide to various debugging features available, such as messages and trace to help you both solve problems with you own
 programs and report bugs to the AspectJ team
 
@@ -117,8 +129,11 @@ xref:release/README-1.2.adoc[1.2], xref:release/README-1.1.adoc[1.1].
 |AspectJ code to demonstrate some language features and implement JavaBean properties, the Observer pattern, a tracing
 library, and a game application where aspects handle display updating
 
-| xref:developer/index.adoc[AspectJ Design Overview] +
-(xref:developer/design-overview.adoc[single page])
+a|AspectJ Design Overview
+
+* xref:developer/index.adoc[HTML multi-page]
+* xref:developer/design-overview.adoc[HTML single page]
+* xref:developer/design-overview.pdf[PDF]
 |Introductory information about AspectJ language design, developer guides, module structure
 |===
 

diff --git a/docs/pom.xml b/docs/pom.xml
index e6c256dd9b102711bf3d62bfadb75a65b6f91150..cb6aa61c39ba3588da4e19cb2110545e5dac6c15 100644 (file)
--- a/docs/pom.xml
+++ b/docs/pom.xml
@@ -25,18 +25,137 @@
           <plugin>
             <groupId>org.asciidoctor</groupId>
             <artifactId>asciidoctor-maven-plugin</artifactId>
+            <configuration>
+              <sourceDirectory>${project.basedir}</sourceDirectory>
+              <preserveDirectories>true</preserveDirectories>
+              <relativeBaseDir>true</relativeBaseDir>
+              <resources>
+                <resource>
+                  <!-- Mandatory, even though identical to 'sourceDirectory' -->
+                  <directory>${project.basedir}</directory>
+                  <excludes>
+                    <!-- Generally excluded file extensions -->
+                    <exclude>**/*.doc</exclude>
+                    <exclude>**/*.vsd</exclude>
+                    <!-- Files excluded in root directory -->
+                    <exclude>*.iml</exclude>
+                    <exclude>pom.xml*</exclude>
+                    <exclude>build.xml</exclude>
+                    <exclude>docs.build.properties</exclude>
+                    <!-- Files excluded in subdirectories -->
+                    <exclude>developer/*.txt</exclude>
+                    <exclude>developer/ajdt/**</exclude>
+                    <exclude>developer/ram-disk/**</exclude>
+                    <exclude>developer/traces/**</exclude>
+                    <exclude>install/**</exclude>
+                    <exclude>sandbox/**</exclude>
+                    <exclude>src/**</exclude>
+                    <exclude>target/**</exclude>
+                    <exclude>teaching/**</exclude>
+                    <exclude>test/**</exclude>
+                  </excludes>
+                </resource>
+              </resources>
+            </configuration>
             <executions>
               <execution>
-                <id>create-asciidoc</id>
+                <id>create-html-from-asciidoc</id>
                 <phase>generate-resources</phase>
                 <goals>
                   <goal>process-asciidoc</goal>
                 </goals>
+              </execution>
+              <execution>
+                <id>generate-pdf-adk15notebook</id>
+                <phase>generate-resources</phase>
+                <goals>
+                  <goal>process-asciidoc</goal>
+                </goals>
+                <configuration>
+                  <backend>pdf</backend>
+                  <sourceDocumentName>adk15notebook/adk15notebook.adoc</sourceDocumentName>
+                  <skip>false</skip>
+                </configuration>
+              </execution>
+              <execution>
+                <id>generate-pdf-devguide</id>
+                <phase>generate-resources</phase>
+                <goals>
+                  <goal>process-asciidoc</goal>
+                </goals>
+                <configuration>
+                  <backend>pdf</backend>
+                  <sourceDocumentName>devguide/devguide.adoc</sourceDocumentName>
+                  <skip>false</skip>
+                </configuration>
+              </execution>
+              <execution>
+                <id>generate-pdf-pdguide</id>
+                <phase>generate-resources</phase>
+                <goals>
+                  <goal>process-asciidoc</goal>
+                </goals>
+                <configuration>
+                  <backend>pdf</backend>
+                  <sourceDocumentName>pdguide/pdguide.adoc</sourceDocumentName>
+                  <skip>false</skip>
+                </configuration>
+              </execution>
+              <execution>
+                <id>generate-pdf-progguide</id>
+                <phase>generate-resources</phase>
+                <goals>
+                  <goal>process-asciidoc</goal>
+                </goals>
+                <configuration>
+                  <backend>pdf</backend>
+                  <sourceDocumentName>progguide/progguide.adoc</sourceDocumentName>
+                  <skip>false</skip>
+                </configuration>
+              </execution>
+              <execution>
+                <id>generate-pdf-design-overview</id>
+                <phase>generate-resources</phase>
+                <goals>
+                  <goal>process-asciidoc</goal>
+                </goals>
+                <configuration>
+                  <backend>pdf</backend>
+                  <sourceDocumentName>developer/design-overview.adoc</sourceDocumentName>
+                  <skip>false</skip>
+                </configuration>
+              </execution>
+            </executions>
+          </plugin>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-resources-plugin</artifactId>
+            <executions>
+              <execution>
+                <id>copy-docs-to-dist</id>
+                <phase>package</phase>
+                <goals>
+                  <goal>copy-resources</goal>
+                </goals>
                 <configuration>
-                  <sourceDirectory>${project.basedir}</sourceDirectory>
-                  <outputDirectory>${project.build.directory}/html</outputDirectory>
-                  <preserveDirectories>true</preserveDirectories>
-                  <relativeBaseDir>true</relativeBaseDir>
+                  <outputDirectory>${project.basedir}/../aj-build/dist/docs/doc</outputDirectory>
+                  <resources>
+                    <resource>
+                      <directory>${project.build.directory}/generated-docs</directory>
+                      <!-- Exclude HTML content created from asciidoc files irrelevant for the distribution -->
+                      <excludes>
+                        <!-- Files excluded in root directory -->
+                        <exclude>readme-docs-module.html</exclude>
+                        <!-- Files excluded in subdirectories -->
+                        <exclude>developer/ajdt/**</exclude>
+                        <exclude>developer/traces/**</exclude>
+                        <exclude>install/**</exclude>
+                        <exclude>sandbox/**</exclude>
+                        <exclude>teaching/**</exclude>
+                        <exclude>test/**</exclude>
+                      </excludes>
+                    </resource>
+                  </resources>
                 </configuration>
               </execution>
             </executions>

diff --git a/pom.xml b/pom.xml
index 99c73736f92bb788bca4406990d60ac3d6b5217e..d62e3b9bf43c199cfcb048efe01c223a7c2ec315 100644 (file)
--- a/pom.xml
+++ b/pom.xml
@@ -429,8 +429,13 @@
                                                        <icons>font</icons>
                                                </attributes>
                                        </configuration>
-                                       <!-- TODO: Remove dependency after https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/553 fix -->
                                        <dependencies>
+                                               <dependency>
+                                                       <groupId>org.asciidoctor</groupId>
+                                                       <artifactId>asciidoctorj-pdf</artifactId>
+                                                       <version>2.3.10</version>
+                                               </dependency>
+                                               <!-- TODO: Remove dependency after https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/553 fix -->
                                                <dependency>
                                                        <groupId>org.jruby</groupId>
                                                        <artifactId>jruby</artifactId>