Viết sách với Docbook

documentation

4

Ngoc Dao viết ngày 21/03/2016

Bài này ghi chú cách dùng Dockbook để viết tài liệu dài, ví dụ viết sách. Dùng Dockbook rất vất vả, nên dùng Sphinx

Qui trình chung

Giả sử có mã nguồn Docbook master.xml. Có nhiều cách chuyển thành index.html và master.pdf. Cách dưới đây có lẽ dễ thực hiện nhất:

• Để chuyển thành index.html: Tìm trên mạng tập tin XSL cần thiết, rồi dùng xsltproc để chuyển master.xml thành index.html dựa trên qui luật định nghĩa ở tập tin XSL. Nếu tìm hiểu về XML và XSL thì bạn sẽ thấy mục đích của XSL là biến đổi XML, biến thành HTML chính là bài tập đơn giản nhất bất kì ai học XSL cũng phải làm qua.
• Để chuyển thành master.pdf: Tương tự như trên, dựa trên XSL để chuyển master.xml thành master.fo, rồi dùng Apache FOP để chuyển master.fo thành master.pdf.

Các Linux distro thường đều có sẵn gói xsltproc và FOP. Việc cài 2 cái này nằm ngoài phạm vi bài viết này. Tập tin XSL có thể download từ SourceForge, tuy nhiên xem ví dụ ở dưới thì thật ra cũng không cần phải download.

Chú ý FOP dùng tính năng ngắt từ khi xuống dòng (hyphenation) của thư viện OFFO như vì giấy phép không tương thích nên FOP không kèm sẵn OFFO, cần tự cài thêm. Ví dụ trên MacOS sau khi cài xsltproc và FOP, download fop-hyph.jar về rồi:

sudo mv fop-hyph.jar /opt/local/share/java/fop/0.94/build/

Chuyển thành HTML

xsltproc http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl master.xml

xsltproc sẽ tự tham khảo tập tin XSL nằm trên mạng rồi tạo ra index.html. Hãy mò vào thư mục http://docbook.sourceforge.net/release/xsl/current/ để thí nghiệm với các tập tin XSL khác.

Chuyển thành PDF

xsltproc -o master.fo http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl master.xml
fop -fo master.fo -pdf master.pdf

Dùng style của JBoss cho PDF

Tập tin .pdf tạo ra ở trên trông chưa bắt mắt lắm. Bạn có thể đọc sách về XSL để tự tạo style của riêng mình y như thiết kế CSS cho web. Tài liệu của các thư viện mã nguồn mở của JBoss đều dùng Docbook và theo cùng một style thông qua jDocbook plugin cho Maven2. Phần dưới đây hướng dẫn cách dùng style của JBoss.

Trước hết tạo cấu trúc thư mục theo qui ước của Maven2 bắt chước Netty:

my_book
+- pom.xml
\- src
   \- docbook
      +- en-US
      |  \- master.xml
      \- xslt
         \- pdf.xsl

Ta giản lược pom.xml của Netty thành như ở dưới. Sau đó chạy MAVEN_OPTS=-Xmx1024m mvn jdocbook:generate sẽ thu được master.pdf. Mặc định Java chỉ dùng 64 MB bộ nhớ, tham số MAVEN_OPTS trên để tránh lỗi thiếu bộ nhớ.

pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<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>com.mycompany.app</groupId>
    <artifactId>my-app</artifactId>
    <packaging>jar</packaging>
    <version>1.0-SNAPSHOT</version>
    <name>Maven Quick Start Archetype</name>
    <url>http://maven.apache.org</url>

  <build>
    <plugins>
      <plugin>
        <groupId>org.jboss.maven.plugins</groupId>
        <artifactId>maven-jdocbook-plugin</artifactId>
        <extensions>true</extensions>
        <version>2.2.0</version>
        <executions>
          <execution>
            <id>generate-docbook</id>
            <phase>package</phase>
            <goals>
              <goal>resources</goal>
              <goal>generate</goal>
            </goals>
          </execution>
        </executions>
        <dependencies>
          <dependency>
            <groupId>org.jboss</groupId>
            <artifactId>jbossorg-docbook-xslt</artifactId>
            <version>1.1.0</version>
            <exclusions>
              <exclusion>
                <groupId>org.eclipse.wst.css</groupId>
                <artifactId>core</artifactId>
              </exclusion>
              <exclusion>
                <groupId>org.eclipse.wst.sse</groupId>
                <artifactId>core</artifactId>
              </exclusion>
            </exclusions>
          </dependency>
          <dependency>
            <groupId>org.jboss</groupId>
            <artifactId>jbossorg-jdocbook-style</artifactId>
            <version>1.1.0</version>
            <type>jdocbook-style</type>
            <exclusions>
              <exclusion>
                <groupId>org.eclipse.wst.css</groupId>
                <artifactId>core</artifactId>
              </exclusion>
              <exclusion>
                <groupId>org.eclipse.wst.sse</groupId>
                <artifactId>core</artifactId>
              </exclusion>
            </exclusions>
          </dependency>
          <dependency>
            <groupId>org.jboss</groupId>
            <artifactId>jbossorg-fonts</artifactId>
            <version>1.0.0</version>
            <type>jdocbook-style</type>
          </dependency>
        </dependencies>
        <configuration>
          <sourceDocumentName>master.xml</sourceDocumentName>
          <sourceDirectory>${basedir}/src/docbook</sourceDirectory>
          <cssResource>
            <directory>${basedir}/src/docbook</directory>
            <includes>
              <include>css/**/*</include>
            </includes>
          </cssResource>
          <imageResource>
            <directory>${basedir}/src/docbook</directory>
            <includes>
              <include>images/**/*</include>
            </includes>
          </imageResource>
          <formats>
<!--
            <format>
              <formatName>html</formatName>
              <stylesheetResource>file:///${basedir}/src/docbook/xslt/xhtml.xsl</stylesheetResource>
              <finalName>index.html</finalName>
            </format>
-->
            <format>
              <formatName>pdf</formatName>
              <stylesheetResource>file:///${basedir}/src/docbook/xslt/pdf.xsl</stylesheetResource>
              <finalName>fermium.pdf</finalName>
            </format>
          </formats>
          <options>
            <xincludeSupported>true</xincludeSupported>
            <xmlTransformerType>saxon</xmlTransformerType>
            <docbookVersion>1.72.0</docbookVersion>
            <localeSeparator>-</localeSeparator>
            <autoDetectFonts>true</autoDetectFonts>
          </options>
        </configuration>
      </plugin>
    </plugins>
  </build>

  <repositories>
    <repository>
      <snapshots>
        <enabled>false</enabled>
        <updatePolicy>never</updatePolicy>
      </snapshots>
      <releases>
        <enabled>true</enabled>
        <updatePolicy>interval:10080</updatePolicy>
      </releases>
      <id>jboss.release</id>
      <name>JBoss releases</name>
      <url>http://repository.jboss.org/maven2</url>
    </repository>
  </repositories>

  <pluginRepositories>
    <pluginRepository>
      <snapshots>
        <enabled>false</enabled>
        <updatePolicy>never</updatePolicy>
      </snapshots>
      <releases>
        <enabled>true</enabled>
        <updatePolicy>interval:10080</updatePolicy>
      </releases>
      <id>jboss.release</id>
      <name>JBoss releases</name>
      <url>http://repository.jboss.org/maven2</url>
    </pluginRepository>
  </pluginRepositories>
</project

Hiển thị font unicode

Khi export PDF có chứa unicode, nếu ta không chỉ định đúng font, phần chữ unicode sẽ thành symbol kiểu ###. Cách đơn giản nhất để hiển thị font unicode là dùng font unicode default của hệ thống, và chỉ cần thêm tên font chính xác vào stylesheet. Ví dụ trong pdf.xsl, ta sửa chỉ định font:

<xsl:template name="pickfont-serif">
    <xsl:variable name="font">
      <xsl:call-template name="pickfont"/>
    </xsl:variable>
    <xsl:copy-of select="$font"/>
    <xsl:text>MS Gothic, VL Gothic, sans-serif</xsl:text>
</xsl:template>

Lưu ý: còn vấn đề khi dùng hỗn hợp font tiếng anh + tiếng Nhật, baseline bị lệch. Nên tạm thời ta dùng chữ tiếng Anh default của font tiếng Nhật.

Lưu ý

1. Kích thước và độ phân giải của ảnh

Để ảnh hiển thị đúng kích thước thực khi xuất ra file PDF, ta cần:

• Save file với resolution 96dpi (bằng độ phân giải của PDF)
• Không để kích thước ảnh quá lớn. Ví dụ với khổ A4 poitrait, kích thước chỉ trong khoảng 650x850. Ảnh có kích thước quá lớn thì phần thừa ra sẽ bị cắt bỏ đi.

2. Nested list

Dùng inheritnum = "inherit" và numeration = "arabic" để tạo ordered list có dạng 1.1 -> 1.1.1, 1.1.2, ...

3. Spanning table

Table trong docbook có thể là CALS table (dùng tag như HTML tr, td, ...) hoặc db table. Nếu dùng db table, ta bắt buộc phải định nghĩa:

• <tgroup cols="num_of_columns">
• <colspec colname="column_name"> cho từng cột
• <row> thay cho <tr>
• <entry> thay cho <td>, <th>

Span theo chiều dọc (rowspan):

<entry morerows="number_of_spanning_rows">

Span theo chiều ngang (colspan):

<entry namest="start_colname" nameend="end_colname" align="center">

4. Linebreak

Định nghĩa template trong pom.xml

<xsl:template match="processing-instruction('linebreak')">
  <fo:block/>
</xsl:template>

Và sử dụng: <?linebreak?>

Đọc thêm

• Thắc mắc thường gặp về Docbook
• Tham khảo toàn diện về Docbook XLS
• Cách viết Docbook
• Mã nguồn của SVN Book
• Cách dùng font Unicode