加入簡單的 README，目前只把基本的想法寫出來而已

3 files changed, 67 insertions, 2 deletions

diff --git a/Makefile b/Makefile
index 1fd6170..eee7aef 100644
--- a/Makefile
+++ b/Makefile
@@ -11,12 +11,15 @@ RM_IF_FAIL= || { rm -f "$@" && false; }
 
 include Makefile.at
 
-all: debian freebsd
+all: README.html debian freebsd
 
 .pkg.list: packages.h packages.sh
 	@echo "===> Generating list file $@"
 	$(AT_CPP)./packages.sh `echo "$<" | cut -d . -f 1` | sort | uniq > "$@" $(RM_IF_FAIL)
 
+README.html: README
+	-$(AT_DOC)asciidoc -o "$@" "$<"
+
 DEBIAN_OUTPUT=        debian.out/217-meta.deb
 DEBIAN_OUTPUT_TMPDIR= debian.out/217-meta
 debian: $(DEBIAN_OUTPUT)
@@ -49,4 +52,4 @@ clean:
 	rm -rf *.out
 
 distclean: clean
-	rm -f freebsd.ports.find
+	rm -f freebsd.ports.find README.html
diff --git a/Makefile.at b/Makefile.at
index 35025eb..9abacbd 100644
--- a/Makefile.at
+++ b/Makefile.at
@@ -8,6 +8,10 @@ AT_CPP=$(AT_CPP_$(V))
 AT_CPP_0=@echo "  CPP     "$@;
 AT_CPP_1=
 
+AT_DOC=$(AT_DOC_$(V))
+AT_DOC_0=@echo "  DOC     "$@;
+AT_DOC_1=
+
 AT_GEN=$(AT_GEN_$(V))
 AT_GEN_0=@echo "  GEN     "$@;
 AT_GEN_1=
diff --git a/README b/README
new file mode 100644
index 0000000..1c736e5
--- /dev/null
+++ b/README
@@ -0,0 +1,58 @@
+wspkg - 用 cpp 管理工作站軟體清單
+=================================
+217 工作站實驗室 <217ta@csie.ntu.edu.tw>
+
+目標
+----
+我們系上的工作站使用了兩種以上的作業系統（目前是 Debian 和 FreeBSD），但是因為
+不同系統安裝軟體的方法不同，也不是每個軟體都跨平臺，因而使得以往不同作業系統的
+軟體清單不同步，甚至有很大的差異。我們希望能藉由簡單的方法，讓不同作業系統的工
+作站上安裝的軟體能夠同步。
+
+方法
+----
+統一的軟體列表
+~~~~~~~~~~~~~~
+現在我們只需要一個主要的軟體列表！當然，有些軟體只能在特定作業系統執行，也有些
+軟體在不同系統使用了不同的名稱，因此我們需要一些對照表。也就是說，我們需要準備
+這些檔案：
+
+ . 主要的軟體列表：packages.h，由大家熟悉的 C 語言前處理器（cpp）指令組成。
+   如果軟體在各平臺的名稱相同，那麼就直接寫在這個檔案中；如果不同，那可以
+   定一個 macro，再到各平臺的對照表將這個 macro 對應到真正的軟體名稱。注意
+   這檔案有對軟體分類，新增或修改軟體清單時記得要寫在 #ifdef 和 #endif 中。
+
+ . 各平臺的對應表：*.pkg，同樣由 cpp 指令組成。這個檔案中要定義（#define）
+   在 packages.h 中的使用的 macro 所對應的真正軟體名稱。一般情況下，這個檔
+   案中只會出現 #define 指令。
+
+不同的套件格式
+~~~~~~~~~~~~~~
+有了軟體列表，接著我們就能產生真正的軟體清單了。使用 cpp 處理 packages.h 和
+*.pkg，再加上一些簡單的後續處理，我們就能得到一個每行只有一個軟體名稱，且排序
+好、不重複的清單 *.list。我們只需要將清單檔轉換成最終管理用的 meta-package 就
+行了！
+
+目前看起來長這樣
+~~~~~~~~~~~~~~~~
+
+-----------------------------------------------------------------------------
+
+                 +----------------------+    <2>       +-----------------+
+          <1>    | 給 Debian 用的對照表 |    cpp       | Debian 軟體清單 |
+       #include -+      debian.pkg      |----------->>>|   debian.list   |
+               / +----------------------+ 其他簡單處理 +-----------------+
+ +------------+                              <3>
+ | 主要的清單 |
+ | packages.h |
+ +------------+
+               \ +----------------------+              +-----------------+
+       #include -+ 給 FreeBSD 用的對照表|    cpp       | FreeBSD 軟體清單|
+                 |      freebsd.pkg     |----------->>>|   freebsd.list  |
+                 +----------------------+ 其他簡單處理 +-----------------+
+
+-----------------------------------------------------------------------------
+
+<1> 這步驟由 cpp 直接處理，我們不用寫 script。
+<2> 執行 cpp，執行檔名可由 CPP 環境變數設定。
+<3> 因為 packages.h 和 *.pkg 格式自由，需要一些處理才能產生整齊、有規律的清單。