2011年12月12日

再談電子書原始碼製作:程式設計教學篇

過去我們在製作程式設計書籍時,總是遇到兩個困難:
  1. 程式碼
  2. 示意圖(流程、類別、...)
使用一般的 WYSIWYG 工具編輯內容時,程式碼經常帶來麻煩:(1)不易保留原有的對齊(indent);(2)不易顯示固定寬度(mono)文字;(3)不易呈現語法著色(syntax highlight)。

編輯器提供一些格式化的功能,我們可以花點時間將程式碼排版變成理想的樣子。可是,有許多問題會重複浪費時間:(1)程式碼的修改,必須在外部經過編譯及測試,沒問題才能放到書裡面,因此必須維護外部程式碼檔案及書籍內容的同步;(2)書籍提供的程式碼愈多,浪費在編排的時間也就愈多。

我們對程式設計書籍製作的理想,是希望可以自動處理這些程式碼,用程式碼的方式來處理。

舉例來說,以原始碼製作電子書時,我們只需要加入一段代碼:

[code-include: "ex01/Main.java"]

就可以將 Main.java 的原始內容嵌入,並顯示成最佳化的 Java 程式碼編排。

如此一來,Main.java 程式碼就可以利用其它開發工具進行修改、編譯及測試,並將最終結果自動呈現到書裡面。(程式碼還沒完成之前,就可以開始寫書的內容。)

若此種語法加以擴充,也可以「只顯示」其中的某幾行,以減少篇幅的浪費。

[code-include: "ex02/Main.java 15-20]

另一種我們實際碰到的問題,是程式教學有許多「概念」不易用文字說明,例如物件導向類別之間的關係、程式處理的流程。

過去的作法,通常是以圖形繪製的工具,完成 SVG(向量)或 PNG(去背的點陣圖)格式,再貼(嵌)到書籍內容中。

但程式教學需要的圖形,除了螢幕擷圖外,大多都是不需要華麗外觀的簡單圖形。螢幕截圖只要配合適當的工具,就可以很方便地處理(例如 Mac OS X 的 Shift + Command + 4 快速鍵)。用於「概念」說明的圖形,我們則需要一種更簡單、易修改的方式來處理。

這種簡便、快速,容易嵌在電子書的原始碼,也容易修改的「圖形」製作方式,就是透過「圖形的原始碼」。

以原始碼來呈現圖形,並不是什麼新個概念。這種做法行之有年,例如 yUML 就是一種可以利用原始碼描述、產生 UML 圖形的線上服務。

Graphviz 是這類工具的傑出之作,它最早由 AT&T 實驗室開發,後來也被廣泛運用在許多軟體,例如 ArgoUML 等。它從簡易的流程圖、到複雜的網路圖或 UML 圖形,都能夠以純文字代碼描述。

安裝 Graphviz 很簡單,在 Ubuntu Linux 只需要使用:「sudo apt-get install graphviz」指令;而 Mac 也可以用 MacPorts 安裝:「sudo port install graphviz」。

以下是一段 Graphviz 的簡單範例,可以儲存成「job.dot」檔案。這段代碼用於描述 Job、Fulltime、Parttime 三個節點(node)的關係。

digraph G {
  node [ shape = "box" ]
  edge [ arrowtail = "empty", dir = "back" ]
  Job -> Fulltime
  Job -> Parttime
}

利用 Graphviz 提供的 dot 指令,可以將這個「圖形原始碼」轉換成 PNG 格式。

dot -Tpng -ojob.png job.dot


當日後書籍內容有所改變,需要修改內容、程式碼,以致這些圖形也需要修改,我們就不必大費周章找出圖形檔、用外部繪圖工具修改、再重新貼回書籍。

如此一來,程式設計教學書籍的主要組成元素:(1)書籍內容、(2)程式碼及(3)簡易圖形,就可以各自用純文字的「原始碼」描述。

我們採用以下的格式來分別撰寫書籍內容。
  1. 書籍內容:Markdown
  2. 程式碼:Java(或其他語言)
  3. 簡易圖形:Graphviz

透過自動化建置工具,如 Make(Makefile),這些書的元素可以分別被處理、測試。
  1. 將程式碼編譯成執行檔 make binary
  2. 測試程式碼 make test
  3. 產生圖形檔案 make graphviz
  4. 產生電子書 make ebook

由於大部分的書籍內容,都以原始碼描述,因此得到許多好處:
  1. 多位作者(程式設計師、測試工程師、編輯、校稿、助理、工讀生)可以線上協同工作。
  2. 書的「風格」可以用 Template 定義,只需要改一次宣告,就可以改變整本書,例如圖形外觀的微調、程式碼的色彩等。
  3. 很容易建立標準作業程序,並簡單地客製量化生產書籍的工具程式(僅需要以簡易的表單提供文字內容輸入,並將結果組合成電子書原始碼)。
我們嘗試使用 ContPub 製作一本程式設計教學書籍的範本,其 PDF 版本的檢視結果如下圖。


電子書的原始碼如下,程式碼及類別繼承示意圖皆以原始碼方式撰寫。

我們使用 ContPub 實驗電子書原始碼的概念,利用原始碼自動產生(1)電子書及(2)電子題庫,未來也會將產出透過新版 PLWeb(程式設計練習系統)。

這種作法大幅提高程式設計教材製作的效率,可以協助作者(及教師)輕鬆製作 Learning by Doing 的數位教材。歡迎有興趣製作教材,或有意願體驗、參與我們研習活動的教師(及作者),利用回應功能留言或 E-Mail(lyhcode 小老鼠 gmail.com)給我。

下載電子書範例檔(PDF及EPUB):http://contpub.org/read/demo2

沒有留言:

張貼留言

lyhcode by lyhcode
歡迎轉載,請務必註明出處!