From: Alexander Kriegisch <Alexander@Kriegisch.name>
Date: Fri, 5 Jan 2024 04:28:07 +0000 (+0700)
Subject: Asciidoc: Create PDFs from multi-page guides
X-Git-Tag: V1_9_21_1~46
X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=66fffe032f2fda4851e83c55385199feeeee31be;p=aspectj.git

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 0b7447038..21ffd5136 100644
--- 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 e6c256dd9..cb6aa61c3 100644
--- 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 99c73736f..d62e3b9bf 100644
--- 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>