Docbook on Linux

A Note of DocBook XML Env Setup

Da-Juan Chou

<nomail@no.mail>

Abstract

This is a note for DocBook XML

This is a note for DocBook XML environment setup.

---

Table of Contents

Tools

Install DocBook DTD

Install DSSSL style sheet

Install XSL style sheet

Use xsltproc transform documents

Resources

Tools

The tools I used to produce and transform XML document includes

• OASIS DocBook DTD

• DSSSL style sheet

• XSL style sheet

Install DocBook DTD

If you are using Fedora Core2 with apt
installed, run the following commands:

#apt-get install docbook-dtd 

If you are using debian Linux run the following commands ...

#apt-get install docbook docbook-xml

Install DSSSL style sheet

If you are using Fedora Core2 with apt
installed, run the following commands:

#apt-get install docbook-style-dsssl

If you are using debian Linux run the following commands ...

#apt-get install docbook-dsssl 

Install XSL style sheet

If you are using Fedora Core2 with apt
installed, run the following commands:

#apt-get install docbook-style-xsl

#apt-get install libxslt

#apt-get install libxml

#apt-get install libxml2

If you are using debian Linux run the following commands ...

#apt-get install docbook-xsl ldp-docbook-xsl

#apt-get install libxslt1 libxml2	

#apt-get install xsltproc 

Use xsltproc transform documents

I am only a rookie of DocBook, I choose to use xslproc to transform XML file to the
format I want. There is no special reason. I made the choice just because it seems to me
the most easy way to do that.

You can run the following commands to validate your XML document

$xmllint --valid --noout in.xml

Run the following command to transform XML document to a
single HTML file:

$xsltproc -o output.html $STYLESHEET_FILE in.xml

Note

$STYLESHEET is a file with name docbook.xsl. In my system, it is
/usr/share/sgml/docbook/xsl-stylesheets-1.65.1-1/html/docbook.xsl

If you want to output a segmented HTML document, run the following commands:

$xsltproc $STYLESHEET_FILE_CHUNK in.xml

Note

$STYLESHEET_FILE_CHUNK is a file with name chunk.xsl.
In my system, it is /usr/share/sgml/docbook/xsl-stylesheets-1.65.1-1/html/chunk.xsl

Resources

There are a lot of links and HOWTOs that may help

LDP author site

Installing and Using DocBook

DocBook Demystification HOWTO

DocBook: The Definitive Guide

Single Source Publishing with DocBook XML

You can download a Sample HOWTO
from LDP or download xml source of HOWTO from
LDP CVS of DocBook

Here is a good chinese TLDP-HOWTO.
The document contains lots useful informations including Traditional Chinese Support.

APT command

周大鈞 (Da-Juan Chou)

<nomail@no.mail>

2009-12-01

Revision History
Revision 0.1	2005-02-01	djchou
first draft, Debian好用指令
Revision 0.2	2009-12-01	djchou
Remove cscope

Abstract

Hi all, here is a note for apt command. I hope that will be helpful to everybody.

---

Table of Contents

Debian套件安裝指令 - APT

apt

dpkg

其他套件安裝的秘訣

Debian套件安裝指令 - APT

APT is the kernel of debian linux distribution. It is useful and once you can surf on net,
you can download (almost) all the free software you want. The best of APT is that you no
longer need to worry about the dependencies of software packages. It makes your life better
in Linux.

apt

Debian的套件以dpkg為核心, 此外,
其管理機制交由apt來管理, 除此之外, 還有
許多前端的程式例如aptitude或dselect幫助我們使用;
使用apt之前我們要先指定來源,
因此我們要編輯系統中的/etc/apt/sources.list檔案.
以下是我的sources.list

deb http://debian.linux.org.tw/debian sarge main non-free contrib

deb-src http://debian.linux.org.tw/debian sarge main non-free contrib

deb http://debian.linux.org.tw/debian-non-US sarge/non-US main non-free contrib

deb-src http://debian.linux.org.tw/debian-non-US sarge/non-US main non-free contrib





deb http://security.debian.org/ stable/updates main contrib non-free

在這裡就先不提sarge, main, non-free, contrib的意義了, 有興趣的人可以去看

debian無痛起步, 裡面有詳細的說明

Note

如果你不知道sources.list檔案要怎麼生出來的話,
可以使用apt-setup來加入來源

以下是一些apt當中常用的指令

• apt-get update - 更新資料庫

• apt-get upgrade - 更新整個系統

• apt-get install pkg-name - 安裝pkg-name這個套件

• apt-get remove pkg-name - 移除pkg-name這個套件

• apt-get source pkg-name - 安裝pkg-name這個套件的原始檔

• apt-get clean - 清除下載的套件

• apt-get autoclean - 清除不需要的下載套件

• apt-cache search pkg - 搜尋有pkg這個關鍵字的套件

• apt-cache show pkg-name - 顯示pkg-name這個套件的相關資訊

dpkg

dpkg是系統套件的核心, 其套件檔案的結尾通常是.deb, 以下是一些dpkg程式常用指令

• dpkg -i pkg-file - 安裝pkg-file這個套件檔案

• dpkg -i --force-all pkg-file - 強制安裝pkg-file這個套件檔案

• dpkg -r pkg-name - 移除pkg-name

• dpkg -r --purge --force-depends pkg-name - 移除pkg-name以及設定檔

• dpkg -l - 列出系統中所有package

• dpkg -l pkg-names - 和dpkg -l相同, 不過僅列出和pkg-name符合的項目

• dpkg -L pkg-names - 列出pkg-name這個package當中

• dpkg -S file-name - 列出包含file-name這個檔案的套件名稱

• dpkg --get-selections - 列出安裝的檔案

• dpkg-reconfigure pkg-name - 重新設定pkg-name

其他套件安裝的秘訣

以下是其他和套件安裝相關的好用指令:

• 找系統中沒用到的library:

  deborphan

• 
  如何只更新某些套件, 而不安裝其他相依的套件:
  

  
  #dpkg --get-selections > file
  
  	

  
  接下來把file中的install改成hold, 然後
  

  
  #dpkg --set-selections < file
  
  #apt-get upgrade	
  
  	

  
  

Docbook on windows

1. Get the following software from ftp://ftp.zlatkovic.com/pub/libxml/
iconv-1.9.2.win32.zip
libxml2-2.6.27.win32.zip
libxslt-1.1.17.win32.zip
xsldbg-3.1.7.win32.zip
zlib-1.2.3.win32.zip

2. Get docbook style sheets
docbook-xsl-1.71.1.zip

3. Installation
Unzip all the software in step (1).
Copy all the files in the bin directory to c:\docbook\bin\
Add c:\docbook\bin into you PATH
Unzip your style sheets in step (2) to where you want the style sheet to be located (e.g. C:\docbook\docbook-xsl-1.71.1)

4. Test
Now you can use the following example to test if your installation is succesful or not.
Download sample howto from http://www.tldp.org/authors/template/Sample-HOWTO.xml
use the following command to test if there's anything wrong
xsltproc -o Sample-HOWTO.html C:\docbook\docbook-xsl-1.71.1\html\docbook.xsl Sample-HOWTO.xml

Re-entrant and thread-safe

看了一篇文章：
http://www-aix.informatik.uni-tuebingen.de/en_US/a_doc_lib/aixprggd/genprogc/writing_reentrant_thread_safe_code.htm

稍微整理一下:

• Re-entrant表示允許程式碼可以重複進入
• Thread-safe表示同樣一段code可以安全的再多執行緒(multi-thread)之下執行

有點難懂，先來說明一下

1. 重複進入
2. 多執行續

re-entrant code表示該段程式碼可以重複進入（無論是在多執行緒的狀況下），一般而言，re-entrant safe的code只能利用local變數或者是使用caller傳進的記憶體空間作操作，而thread safe的code通常都是利用semaphore之類的lock來保護critical section.

一般來說，interrupt handler，signal handler或是recursive call的時候要考慮到re-ntrant的特性，而thread safe的code需要保護的地方則是在當有公用的資料需要被多個執行緒存取的時候，都只存取local變數的函式通常也都是thread safe的。

舉例來說，c函式庫中的strtok就不是一個re-entrant的function，因為每次呼叫他的時候他都會根據上次的狀態來回傳給你是否還有下個token，這表示了在這個function的實做中英該有利用到static變數。

一個典型的re-entrant function大概是像這樣：
void func_r(int a, int *b)
{
*b = a * a;
}

而一個thread-safe的function大概是這樣：
int func_t()
{
static int aaa[5];
int i;
semaphore_take();
for(i = 0 ; i < 5 ; i++){
aaa[i] = i;
}
semaphore_give();
return 0;
}