Bạn có chắc chắn muốn xóa bài viết này không ?
Bạn có chắc chắn muốn xóa bình luận này không ?
Viết sách với Docbook
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







