Viết sách với Docbook
documentation
4
White

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

Bình luận


White
{{ comment.user.name }}
Bỏ hay Hay
{{comment.like_count}}
Male avatar
{{ comment_error }}
Hủy
   

Hiển thị thử

Chỉnh sửa

White

Ngoc Dao

102 bài viết.
252 người follow
Kipalog
{{userFollowed ? 'Following' : 'Follow'}}
Cùng một tác giả
White
56 6
Làm thế nào để nâng cấp trang web mà không làm gián đoạn dịch vụ? Đây là câu hỏi phỏng vấn các công ty lớn thường hỏi khi bạn xin vào vị trí làm lậ...
Ngoc Dao viết 2 năm trước
56 6
White
32 0
Bài viết này giải thích sự khác khác nhau giữa hai ngành khoa học máy tính (computer science) và kĩ thuật phần mềm (software engineering), hi vọng ...
Ngoc Dao viết gần 2 năm trước
32 0
White
28 1
Nếu là team leader, giám đốc công ty hay tướng chỉ huy quân đội, vấn đề cơ bản bạn gặp phải là “hướng mọi người đi theo con đường bạn chỉ ra”. Thử...
Ngoc Dao viết gần 2 năm trước
28 1
Bài viết liên quan
White
43 4
Hiện nay, các ứng dụng viết theo mô hình RESTful API và SoftwareasaService (SaaS) ngày càng bùng nổ. Thế nên việc có 1 trang quản lý các api của mì...
Nguyễn Hoàng Hüy viết 11 tháng trước
43 4
White
1 0
Để viết tài liệu ngắn, ví dụ ngắn như bài viết này, ta. có thể dùng công cụ nhỏ xinh như Markdown. Tuy nhiên để viết tài liệu dài hơn, ví dụ dài nh...
Ngoc Dao viết gần 2 năm trước
1 0
White
21 6
Giới thiệu chung Devdocs là một tài liệu rất hữu ích cho lập trình viên dùng để tra cứu các API của các ngôn ngữ lập trình hay các framework cũng ...
Julian Dong viết hơn 2 năm trước
21 6
{{like_count}}

kipalog

{{ comment_count }}

bình luận

{{liked ? "Đã kipalog" : "Kipalog"}}


White
{{userFollowed ? 'Following' : 'Follow'}}
102 bài viết.
252 người follow

 Đầu mục bài viết

Vẫn còn nữa! x

Kipalog vẫn còn rất nhiều bài viết hay và chủ đề thú vị chờ bạn khám phá!