#81 Generate HTML5 from DocBook 5

#82 Document how to convert from SolBook to DocBook 5

.gitignore

@@ -1,5 +1,4 @@
 output/
 tools/SolBookTrans/dist/javadoc/
 raw/*/solbook.dtd
-raw/*/sun-iso-map.xml
 raw/*/xsolbook.dtd

Makefile

@@ -10,14 +10,63 @@
 #
 
 #
-# Copyright (c) 2012, Joyent, Inc.
+# Copyright 2016, Joyent, Inc.
 #
 
-LINT=xmllint
-DTD=tools/SolBookTrans/resources 
+BUILD_FILES=$(shell find src/xslt src/dblatex)
+WDD_FILES=$(shell find raw/wdd/ -name \*.xml -o -name \*.eps)
+ZFS_FILES=$(shell find raw/zfs-admin/ -name \*.xml)
+MDB_FILES=$(shell find raw/mdb/ -name \*.xml -o -name \*.eps)
+DTRACE_FILES=$(shell find raw/dtrace/ -name \*.xml -o -name \*.eps)
+LGRPS_FILES=$(shell find raw/lgrps/ -name \*.xml -o -name \*.eps)
+
+DBLATEX=dblatex
+DBLATEX_OPTS=-p src/dblatex/params.xsl
+DBLATEX_PRINT_OPTS=${DBLATEX_OPTS} -P latex.page.size=letter
+DBLATEX_EBOOK_OPTS=${DBLATEX_OPTS} -P latex.page.size=ebook
+
+MOGRIFY=mogrify
+MOGRIFY_OPTS=-density 150 -format png
+
+.PHONY:
+all: build/lgrps build/zfs-admin build/wdd build/dtrace build/mdb
+
+.PHONY:
+html: build/lgrps/index.html build/zfs-admin/index.html build/wdd/index.html \
+	build/dtrace/index.html build/mdb/index.html
+
+build/%/index.html:
+	rm -rf build/$*
+	mvn -q -Dtarget.book=$* xml:transform
+	cp src/xslt/style.css build/$*
+	mkdir build/$*/figures; \
+	cp src/xslt/phoenix.svg build/$*/figures
+	if [[ -d raw/$*/figures ]]; then \
+		${MOGRIFY} ${MOGRIFY_OPTS} -path build/$*/figures raw/$*/figures/*.eps; \
+	fi
+
+build/lgrps: ${LGRPS_FILES} ${BUILD_FILES} | build/lgrps/index.html
+	${DBLATEX} ${DBLATEX_PRINT_OPTS} -o build/lgrps/lgrps-print.pdf raw/lgrps/MTPODG.book
+	${DBLATEX} ${DBLATEX_EBOOK_OPTS} -o build/lgrps/lgrps-ebook.pdf raw/lgrps/MTPODG.book
+
+build/zfs-admin: ${ZFS_FILES} ${BUILD_FILES} | build/zfs-admin/index.html
+	${DBLATEX} ${DBLATEX_PRINT_OPTS} -o build/zfs-admin/zfs-admin-print.pdf raw/zfs-admin/ZFSADMIN.book
+	${DBLATEX} ${DBLATEX_EBOOK_OPTS} -o build/zfs-admin/zfs-admin-ebook.pdf raw/zfs-admin/ZFSADMIN.book
+
+build/wdd: ${WDD_FILES} ${BUILD_FILES} | build/wdd/index.html
+	${DBLATEX} ${DBLATEX_PRINT_OPTS} -o build/wdd/wdd-print.pdf raw/wdd/DRIVER.book
+	${DBLATEX} ${DBLATEX_EBOOK_OPTS} -o build/wdd/wdd-ebook.pdf raw/wdd/DRIVER.book
+
+build/dtrace: ${DTRACE_FILES} ${BUILD_FILES} | build/dtrace/index.html
+	${DBLATEX} ${DBLATEX_PRINT_OPTS} -o build/dtrace/dtrace-print.pdf raw/dtrace/DYNMCTRCGGD.book
+	${DBLATEX} ${DBLATEX_EBOOK_OPTS} -o build/dtrace/dtrace-ebook.pdf raw/dtrace/DYNMCTRCGGD.book
+
+build/mdb: ${MDB_FILES} ${BUILD_FILES} | build/mdb/index.html
+	${DBLATEX} ${DBLATEX_PRINT_OPTS} -o build/mdb/mdb-print.pdf raw/mdb/MODDEBUG.book
+	${DBLATEX} ${DBLATEX_EBOOK_OPTS} -o build/mdb/mdb-ebook.pdf raw/mdb/MODDEBUG.book
+
+clean:
+	rm -rf build/
 
 check:
-	$(LINT) --valid --noout --path $(DTD) raw/dtrace/DYNMCTRCGGD.book	
-	$(LINT) --valid --noout --path $(DTD) raw/mdb/MODDEBUG.book	
-	$(LINT) --valid --noout --path $(DTD) raw/wdd/DRIVER.book
-	$(LINT) --valid --noout --path $(DTD) raw/lgrps/MTPODG.book
+	mvn exec:java

README

@@ -4,18 +4,30 @@ for illumos. Currently only a subset of the docbooks that once existed
 are here. Others will be added once someone cares enough about them and
 we make the process for working on them not quite so terrible.
 
-To build them into something useful, first expect pain and then take a
-look at http://hub.opensolaris.org/bin/view/Community+Group+documentation/tools.
-In case that too disappears (like the docbooks), I've included the
-source to the Java build tool which is licensed (according to the
-source) under a combo GPL/CDDL.
+To build them into something useful, you will need to install:
+
+- GNU make (gmake in pkgsrc)
+- Maven (apache-maven in pkgsrc)
+- dblatex (dblatex in pkgsrc)
+- epstopdf conversion tool (tex-epstopdf in pkgsrc)
+- texlive packages (texlive-collection-fontsrecommended,
+  texlive-collection-latexrecommended,
+  texlive-collection-latexextra in pkgsrc)
+- cyrillic fonts (tex-cyrillic in pkgsrc)
+
+The build tools are based on the old Solbook build tools, which were
+licensed under a combo GPL/CDDL.
 
 Building:
 
-To build the currently existing docbooks, use the provided script. The
-quick and easy way to build everything is to use:
+The quick and easy way to build everything is to run:
+
+make all
 
-./tools/build.sh -a
+If you're on a system that doesn't have LaTeX packages available, you can
+build just the HTML files with:
+
+make html
 
 Layout:
 
@@ -24,21 +36,21 @@ Layout:
   The currently maintained and updated docbooks. Each book is in its own
   top level directory.
 
-  - ./stage
+  - ./src
 
-  Original docbooks from Sun that have not been updated.
+  The source files for generating websites and PDFs from the DocBook
+  sources.
 
-  - ./tools
+  - ./stage
 
-  The tools to build the docbooks. This include scripts, the original
-  Java build tools, and the xslt transformations.
+  Original docbooks from Sun that have not been updated.
 
 Adding new books:
 
 As a part of adding a new book, it should be moved from stage to raw.
 Also, when you move it, please change the name to something that is a
-bit more obvious.  dtrace is much better then DYNMCTRCGGD or MODDEBUG.
-Once it is there, you must do the following things:
+bit more obvious.  dtrace is much better than DYNMCTRCGGD, and mdb
+than MODDEBUG. Once it is there, you must do the following things:
 
   o  Add a license appendix that clearly states that this is under the
      PDL. Look at what the mdb or DTrace guides do.
@@ -52,6 +64,57 @@ Once it is there, you must do the following things:
 
   o  Before you are done, add it as a check target in the Makefile.
 
+And convert the sources from SolBook to Docbook 5:
+
+  o  Remove <highlights> tags, but leave their inner content
+  o  Convert all id's to xml:id's
+  o  Convert <olink> tags where remap="internal" to <xref> tags
+  o  Remove the <olink> tags around <citerefentry> tags
+  o  Convert <ulink> tags to <link> tags
+  o  Convert <chapterinfo> and <bookinfo> to just <info>
+  o  Add a <bibliorelation> tag that can be used when creating canonical links
+  o  Move <option> tags out of <command> tags/restructure
+  o  Along the way, as lines are touched, try to reformat
+  o  Assign <partintro> tags IDs, and update any references to the parent
+     <part> to point at the <partintro> instead.
+  o  There are some other minor things that were not specific to SolBook, but
+     were part of DocBook 4 and are gone in DocBook 5. Running the validator
+     will find them for you. Consult the DocBook guide for tips on what to do:
+
+     http://www.docbook.org/tdg5/en/html/ch01.html#introduction-whats-new
+
+
+This should be enough to get the HTML5 version of the book built. To build the
+PDFs though, there are some other things that need to be fixed:
+
+  o  Convert all colspecs' colwidth attributes from inches to proportional
+     measurements. For example, if there are two columns of widths "1.00in"
+     and "4.00in", they should become "1*" and "4*" respectively, which says
+     that the second column should be four times the width of the first
+     column. If there are multiple tables next to each that are similar in
+     number of columns and width, try to make them the same, so that they look
+     better in the PDF.
+  o  On <colspec> tags for columns that contain paragraphs, add an
+     align="justify" attribute.
+  o  On <tbody> tags for tables that contain multi-line text, add
+     valign="top" to ensure that things don't get vertically center-aligned,
+     which can make reading the table more confusing.
+  o  Make sure that the text inside <programlisting> and <screen> tags wrap
+     before 75 characters since monospaced text will be wider in the PDF, and
+     the only two options are the listings environment's poor wrapping with
+     breaklines, or overflowing into (or past) the margins.
+  o  Check for long <example> contents, which get placed inside a float and will
+     therefore overflow the bottom margin if too long.
+
+Additional cleanup worth performing:
+
+  o  Remove the processing instructions (things like <?PubTbl ...?>) left over
+     from the XML editors initially used to write the books (they don't get
+     used for anything).
+
+Adding the document to the check target should help you track many of these
+issues down.
+
 Contributing:
 
 Treat this like you would ON with respect to bugs and the like.
@@ -60,6 +123,10 @@ Before you put back, you should run make check. Furthermore, if you
 change the xslt style, you must check most of the docbooks for
 regressions.
 
+You can check your DocBook changes by running:
+
+make check
+
 Licensing:
 
 All of the documentation is licensed under the Public Documentation

pom.xml

@@ -0,0 +1,81 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+	<groupId>org.illumos.docs</groupId>
+	<artifactId>docbooks</artifactId>
+	<version>1.0-SNAPSHOT</version>
+	<name>${project.artifactId}</name>
+
+	<dependencies>
+		<dependency>
+			<groupId>com.thaiopensource</groupId>
+			<artifactId>jing</artifactId>
+			<version>20091111</version>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<plugins>
+			<!-- Configuration for validating books to RELAX NG schema -->
+			<plugin>
+				<groupId>org.codehaus.mojo</groupId>
+				<artifactId>exec-maven-plugin</artifactId>
+				<version>1.4.0</version>
+				<executions>
+					<execution>
+						<goals>
+							<goal>java</goal>
+						</goals>
+					</execution>
+				</executions>
+				<configuration>
+					<executableDependency>
+						<groupId>com.thaiopensource</groupId>
+						<artifactId>jing</artifactId>
+					</executableDependency>
+					<mainClass>com.thaiopensource.relaxng.util.Driver</mainClass>
+					<arguments>
+						<argument>src/rng/illumos.rng</argument>
+						<argument>raw/dtrace/DYNMCTRCGGD.book</argument>
+						<argument>raw/lgrps/MTPODG.book</argument>
+						<argument>raw/mdb/MODDEBUG.book</argument>
+						<argument>raw/wdd/DRIVER.book</argument>
+						<argument>raw/zfs-admin/ZFSADMIN.book</argument>
+					</arguments>
+				</configuration>
+			</plugin>
+			<!-- Configuration for building HTML using XSL -->
+			<plugin>
+				<groupId>org.codehaus.mojo</groupId>
+				<artifactId>xml-maven-plugin</artifactId>
+				<version>1.0</version>
+				<executions>
+					<execution>
+						<goals>
+							<goal>transform</goal>
+						</goals>
+					</execution>
+				</executions>
+				<configuration>
+					<transformationSets>
+						<transformationSet>
+							<dir>raw/</dir>
+							<includes>
+								<include>${target.book}/*.book</include>
+							</includes>
+							<outputDir>build</outputDir>
+							<stylesheet>src/xslt/transform.xsl</stylesheet>
+						</transformationSet>
+					</transformationSets>
+				</configuration>
+				<dependencies>
+					<dependency>
+						<groupId>net.sf.saxon</groupId>
+						<artifactId>Saxon-HE</artifactId>
+						<version>9.6.0-6</version>
+					</dependency>
+				</dependencies>
+			</plugin>
+		</plugins>
+	</build>
+</project>