Produce working EPUB files

This completes all of the stylesheet updates needed to produce working (but not necessarily particularly attractive) EPUB files. Affects: #13
io7m-com · Jun 26, 2021 · addda2a · addda2a
1 parent 63389e2
commit addda2a
Show file tree

Hide file tree

Showing 14 changed files with 663 additions and 270 deletions.
diff --git a/com.io7m.xstructural.api/src/main/java/com/io7m/xstructural/api/XSProcessorRequestType.java b/com.io7m.xstructural.api/src/main/java/com/io7m/xstructural/api/XSProcessorRequestType.java
@@ -98,6 +98,12 @@ default Path messageFile()
 
   Optional<Path> brandingFile();
 
+  /**
+   * @return The name of the output file, if relevant to the operation
+   */
+
+  Optional<String> outputName();
+
   /**
    * The stylesheet that will be used during processing.
    */

diff --git a/...structural.cmdline/src/main/java/com/io7m/xstructural/cmdline/XSCommandTransformEPUB.java b/...structural.cmdline/src/main/java/com/io7m/xstructural/cmdline/XSCommandTransformEPUB.java
@@ -57,6 +57,13 @@ final class XSCommandTransformEPUB extends XSCommandRoot
   )
   private Path messagesFile;
 
+  @Parameter(
+    required = false,
+    description = "The output file name",
+    names = "--outputFileName"
+  )
+  private String outputFileName;
+
   XSCommandTransformEPUB()
   {
 
@@ -83,6 +90,9 @@ public Status execute()
     if (this.messagesFile != null) {
       requestBuilder.setMessageFile(this.messagesFile.toAbsolutePath());
     }
+    if (this.outputFileName != null) {
+      requestBuilder.setOutputName(this.outputFileName);
+    }
 
     final var request = requestBuilder.build();
     final var processors = XSServices.findProcessors();

diff --git a/com.io7m.xstructural.documentation/pom.xml b/com.io7m.xstructural.documentation/pom.xml
@@ -106,6 +106,42 @@
               </resources>
             </configuration>
           </execution>
+
+          <execution>
+            <id>copy-documentation-resources-epub</id>
+            <goals>
+              <goal>copy-resources</goal>
+            </goals>
+            <phase>generate-resources</phase>
+            <configuration>
+              <outputDirectory>${project.build.directory}/epub/</outputDirectory>
+              <resources>
+                <resource>
+                  <directory>src/main/resources/com/io7m/xstructural/documentation/</directory>
+                  <filtering>true</filtering>
+                </resource>
+              </resources>
+            </configuration>
+          </execution>
+
+          <execution>
+            <id>copy-generated-epub</id>
+            <phase>site</phase>
+            <goals>
+              <goal>copy-resources</goal>
+            </goals>
+            <configuration>
+              <outputDirectory>${project.parent.build.directory}/minisite/documentation/</outputDirectory>
+              <resources>
+                <resource>
+                  <directory>${project.build.directory}/epub/</directory>
+                  <includes>
+                    <include>${project.artifactId}-${project.version}.epub</include>
+                  </includes>
+                </resource>
+              </resources>
+            </configuration>
+          </execution>
         </executions>
       </plugin>
 
@@ -223,6 +259,26 @@
               </arguments>
             </configuration>
           </execution>
+
+          <execution>
+            <id>epub</id>
+            <goals>
+              <goal>java</goal>
+            </goals>
+            <phase>package</phase>
+            <configuration>
+              <mainClass>com.io7m.xstructural.cmdline.MainExitless</mainClass>
+              <arguments>
+                <argument>epub</argument>
+                <argument>--sourceFile</argument>
+                <argument>${project.build.directory}/documentation/main.xml</argument>
+                <argument>--outputDirectory</argument>
+                <argument>${project.build.directory}/epub</argument>
+                <argument>--outputFileName</argument>
+                <argument>${project.artifactId}-${project.version}.epub</argument>
+              </arguments>
+            </configuration>
+          </execution>
         </executions>
       </plugin>
 
@@ -265,9 +321,7 @@
             <configuration>
               <verbose>true</verbose>
               <fileset>
-                <directory>
-                  ${project.build.directory}/${project.name}-${project.version}.zip/${project.name}-${project.version}/
-                </directory>
+                <directory>${project.build.directory}/${project.name}-${project.version}.zip/${project.name}-${project.version}/</directory>
                 <outputDirectory>${project.parent.build.directory}/minisite/documentation/</outputDirectory>
               </fileset>
             </configuration>

diff --git a/...m.xstructural.documentation/src/main/resources/com/io7m/xstructural/documentation/api.xml b/...m.xstructural.documentation/src/main/resources/com/io7m/xstructural/documentation/api.xml
@@ -26,7 +26,7 @@ processor.execute();
 
   <Subsection title="JavaDoc">
     <Paragraph>
-      Please see the included <LinkExternal target="apidocs">JavaDoc</LinkExternal>
+      Please see the included <LinkExternal target="${project.distributionManagement.site.url}/documentation/apidocs">JavaDoc</LinkExternal>
       for API reference documentation.
     </Paragraph>
   </Subsection>

diff --git a/...umentation/src/main/resources/com/io7m/xstructural/documentation/cmdline-epub-example.txt b/...umentation/src/main/resources/com/io7m/xstructural/documentation/cmdline-epub-example.txt
@@ -0,0 +1,66 @@
+$ xstructural epub \
+  --sourceFile com.io7m.xstructural.documentation/target/documentation/main.xml \
+  --outputDirectory out \
+  --outputFileName example.epub
+xstructural: XSValidator: INFO: validate (xstructural) com.io7m.xstructural.documentation/target/documentation/main.xml
+xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e168.xhtml
+xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e311.xhtml
+xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e33.xhtml
+xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/colophon.xhtml
+xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/cover.xhtml
+xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e109.xhtml
+xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e331.xhtml
+xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e14.xhtml
+xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e16.xhtml
+xstructural: XSEPUBCreator: INFO: copy out/d2e168.xhtml out/epub/OEBPS/d2e168.xhtml
+xstructural: XSEPUBCreator: INFO: copy out/d2e311.xhtml out/epub/OEBPS/d2e311.xhtml
+xstructural: XSEPUBCreator: INFO: copy out/d2e33.xhtml out/epub/OEBPS/d2e33.xhtml
+xstructural: XSEPUBCreator: INFO: copy out/colophon.xhtml out/epub/OEBPS/colophon.xhtml
+xstructural: XSEPUBCreator: INFO: copy out/cover.xhtml out/epub/OEBPS/cover.xhtml
+xstructural: XSEPUBCreator: INFO: copy out/d2e109.xhtml out/epub/OEBPS/d2e109.xhtml
+xstructural: XSEPUBCreator: INFO: copy out/d2e331.xhtml out/epub/OEBPS/d2e331.xhtml
+xstructural: XSEPUBCreator: INFO: copy out/toc.xhtml out/epub/OEBPS/toc.xhtml
+xstructural: XSEPUBCreator: INFO: copy out/d2e14.xhtml out/epub/OEBPS/d2e14.xhtml
+xstructural: XSEPUBCreator: INFO: copy out/d2e16.xhtml out/epub/OEBPS/d2e16.xhtml
+xstructural: XSEPUBCreator: INFO: zip entry mimetype
+xstructural: XSEPUBCreator: INFO: zip entry content.opf
+xstructural: XSEPUBCreator: INFO: zip entry META-INF/container.xml
+xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e168.xhtml
+xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e311.xhtml
+xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e33.xhtml
+xstructural: XSEPUBCreator: INFO: zip entry OEBPS/colophon.xhtml
+xstructural: XSEPUBCreator: INFO: zip entry OEBPS/cover.xhtml
+xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e109.xhtml
+xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e331.xhtml
+xstructural: XSEPUBCreator: INFO: zip entry OEBPS/toc.xhtml
+xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e14.xhtml
+xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e16.xhtml
+xstructural: XSEPUBCreator: INFO: zip entry OEBPS/reset.css
+xstructural: XSEPUBCreator: INFO: zip entry OEBPS/structural-epub.css
+xstructural: XSEPUBCreator: INFO: zip entry OEBPS/document.css
+xstructural: XSEPUBCreator: INFO: validating out/example.epub
+xstructural: XSEPUBCreator: INFO: epubcheck: stdout: Validating using EPUB version 3.2 rules.
+xstructural: XSEPUBCreator: INFO: epubcheck: stdout: No errors or warnings detected.
+xstructural: XSEPUBCreator: INFO: epubcheck: stdout: Messages: 0 fatals / 0 errors / 0 warnings / 0 infos
+xstructural: XSEPUBCreator: INFO: epubcheck: stdout:
+xstructural: XSEPUBCreator: INFO: epubcheck: stdout: EPUBCheck completed
+
+$ ls -alF out/
+total 128
+drwxr-xr-x  3 xs xs  4096 Jun 26 12:59 ./
+drwxr-xr-x 15 xs xs  4096 Jun 26 12:59 ../
+-rw-r--r--  1 xs xs   713 Jun 26 12:59 colophon.xhtml
+-rw-r--r--  1 xs xs   566 Jun 26 12:59 cover.xhtml
+-rw-r--r--  1 xs xs  6256 Jun 26 12:59 d2e109.xhtml
+-rw-r--r--  1 xs xs  3572 Jun 26 12:59 d2e14.xhtml
+-rw-r--r--  1 xs xs  4077 Jun 26 12:59 d2e16.xhtml
+-rw-r--r--  1 xs xs 10530 Jun 26 12:59 d2e168.xhtml
+-rw-r--r--  1 xs xs  3767 Jun 26 12:59 d2e311.xhtml
+-rw-r--r--  1 xs xs  7158 Jun 26 12:59 d2e33.xhtml
+-rw-r--r--  1 xs xs 36763 Jun 26 12:59 d2e331.xhtml
+drwxr-xr-x  4 xs xs  4096 Jun 26 12:59 epub/
+-rw-r--r--  1 xs xs     0 Jun 26 12:59 epub-resources.txt
+-rw-r--r--  1 xs xs 19337 Jun 26 12:59 example.epub
+-rw-r--r--  1 xs xs    99 Jun 26 12:59 messages.log
+-rw-r--r--  1 xs xs  2460 Jun 26 12:59 toc.xhtml
+-rw-r--r--  1 xs xs  2501 Jun 26 12:59 trace.xml
diff --git a/...ural.documentation/src/main/resources/com/io7m/xstructural/documentation/cmdline-epub.xml b/...ural.documentation/src/main/resources/com/io7m/xstructural/documentation/cmdline-epub.xml
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<Section xmlns="urn:com.io7m.structural:7:0"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         title="XHTML">
+
+  <Subsection title="Name">
+    <Paragraph>
+      <Term type="command">epub</Term> - Produce an EPUB file
+    </Paragraph>
+  </Subsection>
+
+  <Subsection title="Description">
+    <Paragraph>
+      The <Term type="command">epub</Term> command produces a self-contained EPUB file for the given input document.
+      The produced EPUB file is unconditionally checked with
+      <LinkExternal target="https://github.com/w3c/epubcheck">EPUBCheck</LinkExternal>.
+    </Paragraph>
+    <FormalItem title="Parameters">
+      <Table type="parametersTable">
+        <Columns>
+          <Column>Parameter</Column>
+          <Column>Type</Column>
+          <Column>Required</Column>
+          <Column>Description</Column>
+        </Columns>
+        <Row>
+          <Cell><Term type="parameter">--messagesFile</Term></Cell>
+          <Cell>Path</Cell>
+          <Cell>false</Cell>
+          <Cell>A file that will contain XSLT debugging messages.</Cell>
+        </Row>
+        <Row>
+          <Cell><Term type="parameter">--traceFile</Term></Cell>
+          <Cell>Path</Cell>
+          <Cell>false</Cell>
+          <Cell>A file that will contain XSLT trace messages.</Cell>
+        </Row>
+        <Row>
+          <Cell><Term type="parameter">--sourceFile</Term></Cell>
+          <Cell>Path</Cell>
+          <Cell>true</Cell>
+          <Cell>The path to the input document.</Cell>
+        </Row>
+        <Row>
+          <Cell><Term type="parameter">--outputDirectory</Term></Cell>
+          <Cell>Path</Cell>
+          <Cell>true</Cell>
+          <Cell>The directory to which output files will be written.</Cell>
+        </Row>
+        <Row>
+          <Cell><Term type="parameter">--outputFileName</Term></Cell>
+          <Cell>Path</Cell>
+          <Cell>true</Cell>
+          <Cell>The name of the output file.</Cell>
+        </Row>
+      </Table>
+    </FormalItem>
+  </Subsection>
+
+  <Subsection title="Example">
+    <FormalItem title="Example" type="example">
+      <Verbatim>
+        <xi:include parse="text"
+                    href="cmdline-epub-example.txt"/>
+      </Verbatim>
+    </FormalItem>
+  </Subsection>
+</Section>
diff --git a/...tructural.documentation/src/main/resources/com/io7m/xstructural/documentation/cmdline.xml b/...tructural.documentation/src/main/resources/com/io7m/xstructural/documentation/cmdline.xml
@@ -15,6 +15,7 @@
     </FormalItem>
   </Section>
 
+  <xi:include href="cmdline-epub.xml"/>
   <xi:include href="cmdline-schema.xml"/>
   <xi:include href="cmdline-validate.xml"/>
   <xi:include href="cmdline-xhtml.xml"/>

diff --git a/....xstructural.documentation/src/main/resources/com/io7m/xstructural/documentation/main.xml b/....xstructural.documentation/src/main/resources/com/io7m/xstructural/documentation/main.xml
@@ -9,6 +9,7 @@
     <dc:title>xstructural ${project.version}</dc:title>
     <dc:identifier>d792ce57-6851-415a-b6c9-18550e512136</dc:identifier>
     <dc:description>User documentation for the ${project.groupId} package.</dc:description>
+    <dc:language>en</dc:language>
   </Metadata>
 
   <xi:include href="cmdline.xml"/>

diff --git a/...xstructural.documentation/src/main/resources/com/io7m/xstructural/documentation/usage.txt b/...xstructural.documentation/src/main/resources/com/io7m/xstructural/documentation/usage.txt
@@ -1,55 +0,0 @@
-Usage: xstructural [options] [command] [command options]
-  Options:
-    --verbose
-      Set the minimum logging verbosity level
-      Default: info
-      Possible Values: [trace, debug, info, warn, error]
-  Commands:
-    validate      Validate a structural document
-      Usage: validate [options]
-        Options:
-        * --sourceFile
-            The source document
-          --verbose
-            Set the minimum logging verbosity level
-            Default: info
-            Possible Values: [trace, debug, info, warn, error]
-
-    xhtml      Transform a structural document to XHTML
-      Usage: xhtml [options]
-        Options:
-          --brandingFile
-            The branding XML file
-          --copyResources
-            Should resources (such as CSS) be copied into the output
-            directory?
-            Default: true
-          --messagesFile
-            The output file for XSLT messages
-        * --outputDirectory
-            The output directory
-        * --sourceFile
-            The source document
-          --stylesheet
-            The stylesheet
-            Default: SINGLE_FILE
-            Possible Values: [SINGLE_FILE, MULTIPLE_FILE]
-          --traceFile
-            The output file for trace messages
-          --verbose
-            Set the minimum logging verbosity level
-            Default: info
-            Possible Values: [trace, debug, info, warn, error]
-
-    schema      Export the structural schemas to files
-      Usage: schema [options]
-        Options:
-        * --outputDirectory
-            The output directory
-          --replace
-            Replace output files if they already exist
-            Default: false
-          --verbose
-            Set the minimum logging verbosity level
-            Default: info
-            Possible Values: [trace, debug, info, warn, error]

diff --git a/...structural.vanilla/src/main/java/com/io7m/xstructural/vanilla/internal/XSEPUBCreator.java b/...structural.vanilla/src/main/java/com/io7m/xstructural/vanilla/internal/XSEPUBCreator.java
@@ -83,7 +83,7 @@ public XSEPUBCreator(
     this.request =
       Objects.requireNonNull(inRequest, "request");
     this.epubFile =
-      this.request.outputDirectory().resolve("output.epub");
+      this.request.outputDirectory().resolve(outputName(inRequest));
     this.epubDirectory =
       this.request.outputDirectory().resolve("epub");
     this.metaDirectory =
@@ -94,6 +94,13 @@ public XSEPUBCreator(
       new XSEPUBPackageCreator(this.resources, this.request);
   }
 
+  private static String outputName(
+    final XSProcessorRequest inRequest)
+  {
+    return inRequest.outputName()
+      .orElse("output.epub");
+  }
+
   private static InputStream resource(
     final String name)
     throws IOException