Technical Writing's Rule Of Thumb + Local Web based Code Cross Reference (eg. LXR clone)

----- Begin Update Block @ 8th Jun 2008 -----
將以下"/home/user/"開頭的路徑一律改為"~/"開頭，config檔中的路徑除外。
----- End Update Block @ 8th Jun 2008 -----
寫技術文件並非多高深的學問，只需要記住幾個要點就可以寫出易懂的文件。
*永遠假設讀者什麼都不懂（eg. not only rookies but DUMMIES!）
*完整地敘述scenario（eg. what is our goal, where are we, what are the problems, what needs to be done）
*提供可複製的做法，讓dummies看了之後即便不加思索地照做也能得到正確的結果（just like report bugs）

我相信很多人都聽過以上的論點，尤其是寫過論文的人[1]，老闆在review paper的時候還會不停地耳提面命。
然而在opensource界的人大都不太喜歡寫document，"Read the code, everything is in it!" they said。
因此造成一般人，同時也是大部分的人，在嘗試安裝／設定某些opensource package的時候時常覺得不知所措，例如Linux Cross Reference (LXR)採 用的LXRng系統[2]，雖然有善心人士提供安裝文件[3]，但是仍舊不夠直覺，我們在安裝的時候仍然需要花點時間摸索與猜測。接下來的版面將融合 [3]中的兩篇安裝文件（順便中文化），讓想要在本機端建立code cross reference的人可以無痛安裝LXRng。

讓我開始練習本文開頭所提到的幾個要點！

*永遠假設讀者什麼都不懂
-- 什麼是LXRng
LXRng原本是一套用來替Linux原始碼產生網頁介面cross reference（之後簡稱XR）的套件[4]，稍加修改設定之後便可替任何軟體專案產生XR以便trace/browse code，如頁面[2]除了Linux以外也列出如Mac OS X與Perl等專案的XR。LXRng可以直接使用version control的repository（方法一）[5]也可以利用已經存在於本機硬碟上任一存放source code的目錄（方法二）產生XR[6]。

*完整地敘述scenario
-- what is our goal
常常在登入LXR官方網頁時發現該站正在維護中因而無法使用該網站trace code，而維護時間有時長達兩天，因此想要在Linux環境中安裝LXRng替Linux原始碼產生XR方便隨時查詢原始碼[7]。
-- where are we
本文件中的指令與套件名稱以Ubuntu 8.04 (Hardy)提供的為基準，範例使用的登入帳號為user。
----- Begin Update Block @ 6th Jun 2008 -----
搭配至少512MB的記憶體，有人（moiamond at gmail dot com）反應使用256MB記憶體會無法成功製作XR，程式會在進度到達100%之前就結束並沒有顯示任何錯誤訊息。
----- End Update Block @ 6th Jun 2008 -----
-- what are the problems
該安裝哪些額外的套件？該如何設定？
-- what needs to be done
1) LXRng使由許多package[8]建構而成，因1此想當然爾我們必須安裝相關套件，安裝指令為：
$ sudo aptitude install git-core postgresql-8.3 postgresql-client-8.3 libxapian15 libsearch-xapian-perl apache2 libapache2-mod-perl2 libcgi-simple-perl libcgi-ajax-perl libhtml-parser-perl libtemplate-perl libterm-progressbar-perl libdevel-size-perl libdbd-pg-perl ctags
2) 替資料庫新增擁有最大權限的使用者帳號[9]，指令為：
$ sudo -i
$ su - postgres
$ createuser user # Answer "yes" when asked about superprivileged access
$ exit
$ exit
3) 替即將要產生的XR建立資料庫，並將http服務使用者[10]設定為該資料庫的一般使用者，因此在建立www-data帳號遇到任何問題都回答"N"，指令為：
$ createdb lxrng
$ createuser www-data
4) 由LXR的repository取得LXRng，指令為：
$ cd ~
$ git-clone git://lxr.linux.no/git/lxrng.git
5) 開啟LXRng設定檔，指令為：
$ cd ~/lxrng
$ cp lxrng.conf-dist lxrng.conf
$ vim lxrng.conf
6) 將以下的行數加以註解
use LXRng::Repo::Git;
my $gitrepo = LXRng::Repo::Git
->new('/var/lib/lxrng/repos/linux-2.6/.git',
release_re => qr/^v[^-]*$/,
author_timestamp => 0);
my $search = LXRng::Search::Xapian->new('/var/lib/lxrng/text-db/linux-2.6');
7) 加入以下指令：
use LXRng::Repo::Plain;
my $plainrepo = LXRng::Repo::Plain->new('/home/user/src/linux-source'); [11]
my $search = LXRng::Search::Xapian->new('/home/user/src/linux-source-2.6.24-textdb'); [12]
8) 修改下列行數：
'repository' => $gitrepo, --改為--> 'repository' => $plainrepo,
'base_url' => 'http://lxr-test.linpro.no/lxr', --改為--> 'base_url' => 'http://localhost/lxr', [13]
'cache' => '/var/lib/lxrng/cache', --改為--> 'cache' => '/home/user/lxrng/cache', [14]
'ver_list' => [$gitrepo->allversions], --改為--> 'ver_list' => ['v2.6.24'],
'ver_default' => 'v2.6.20.3', --改為--> 'ver_default' => 'v2.6.24',
9) 存檔後離開編輯器（vim in this example）
10) 取得Linux source code並將目錄結構設定成與步驟7, 8中的設定相符合，指令為：
$ sudo aptitude install linux-source-2.6.24
$ mkdir ~/src
$ cp /usr/src/linux-source-2.6.24.tar.bz2 ~/src
$ cd ~/src
$ tar xjf linux-source-2.6.24.tar.bz2
$ mkdir linux-source
$ mkdir linux-source/v2.6.24
$ mv linux-source-2.6.24/* linux-source/v2.6.24
$ mkdir linux-source-2.6.24-textdb
$ mkdir ~/lxrng/cache
$ chmod 777 ~/lxrng/cache -R
$ chmod 777 ~/lxrng/webroot -R
$ make -C ~/lxrng/webroot/.static/gfx
11) 產生Linux-2.6.24的XR[15]，指令為：
$ cd ~/lxrng
$ ./lxr-db-admin linux --init [16]
$ ./lxr-genxref linux
12) 設置Apache2
$ cp apache2-site.conf-dist-mod_perl apache2-site.conf
$ sudo ln -s ~/lxrng/apache2-site.conf /etc/apache2/sites-enabled/010-lxrng
$ vim apache2-site.conf
將所有@@LXRROOT@@替換成/home/user/lxrng
將@@LXRURL@@替換成lxr
13) 重新啟動Apache2
$ sudo /etc/init.d/apache2 reload
14) 使用瀏覽器開啟http://localhost/lxr即可開始查詢原始碼，如以下screenshots：


----- Begin Update Block @ 10th Jun 2008 -----
如果要更換domain name，如將現有的"localhost"改為"somewhere.com"，只需要將"lxrng.conf"中的"base_url"替換之後再執行./lxr-genxref linux即可，這次的執行時間十分短，因為XR都已經存在，現在就可以使用瀏覽器開啟新的網址"http://somewhere.com/lxr"瀏覽原始碼。
----- End Update Block @ 10th Jun 2008 -----
PS. 目前仍無法產生pdf檔案，待研究


[1] 寫論文要遵守的規則當然不只如此
[2] http://lxr.linux.no/git
[3] Thanks to Ahmed: http://darwish-07.blogspot.com/2008/02/howto-lxrng-on-ubuntu-710.html
Thanks to Fred: http://lxr.linux.no/.static/contrib/lxr-notes-ubuntu.txt
[4] http://lxr.linux.no/git/linux
[5] 目前似乎僅支援GIT，文件中並沒有提及其他的protocol
[6] 我目前僅成功使用本機專案產生XR，直接使用GIT's repository則會得到"Nothing to do"的訊息
[7] 本篇僅說明如何使用方法二產生XR
[8] Perl, CPAN, PostgreSQL, Xapian and Excuberant Ctags
[9] 與目前Linux登入帳戶相同，因此在此範例為user
[10] Ubuntu的預設值為www-data
[11] 存放原始碼的目錄
[12] 存放XR的目錄
[13] XR的URL
[14] XR運作時存放cache的目錄
[15] 在我的VM中跑了將近五個小時
[16] 指令中含有linux是因為lxrng.conf中的標籤設置為linux，設定碼為：'linux' => {