加入檔名慣例與原則

1 files changed, 34 insertions, 9 deletions

diff --git a/README b/README
index 1c736e5..2bc31f6 100644
--- a/README
+++ b/README
@@ -38,21 +38,46 @@ wspkg - 用 cpp 管理工作站軟體清單
 
 -----------------------------------------------------------------------------
 
-                 +----------------------+    <2>       +-----------------+
-          <1>    | 給 Debian 用的對照表 |    cpp       | Debian 軟體清單 |
-       #include -+      debian.pkg      |----------->>>|   debian.list   |
-               / +----------------------+ 其他簡單處理 +-----------------+
- +------------+                              <3>
+                +----------------------+    <2>       +-----------------+
+          <1>   | 給 Debian 用的對照表 |    cpp       | Debian 軟體清單 |
+       #include +      debian.pkg      |----------->>>|   debian.list   |
+               /+----------------------+ 其他簡單處理 +-----------------+
+ +------------+                             <3>
  | 主要的清單 |
  | packages.h |
  +------------+
-               \ +----------------------+              +-----------------+
-       #include -+ 給 FreeBSD 用的對照表|    cpp       | FreeBSD 軟體清單|
-                 |      freebsd.pkg     |----------->>>|   freebsd.list  |
-                 +----------------------+ 其他簡單處理 +-----------------+
+               \+----------------------+              +-----------------+
+       #include + 給 FreeBSD 用的對照表|    cpp       | FreeBSD 軟體清單|
+                |      freebsd.pkg     |----------->>>|   freebsd.list  |
+                +----------------------+ 其他簡單處理 +-----------------+
 
 -----------------------------------------------------------------------------
 
 <1> 這步驟由 cpp 直接處理，我們不用寫 script。
 <2> 執行 cpp，執行檔名可由 CPP 環境變數設定。
 <3> 因為 packages.h 和 *.pkg 格式自由，需要一些處理才能產生整齊、有規律的清單。
+
+檔名慣例
+--------
+ - *.pkg - 各系統套件名稱不同時使用的對照表。
+ - *.list - 處理過後已排序、不重複的套件清單。
+ - *.sh - 用於產生其他檔案的 script，輸出檔名應該是把 shell script 檔名的 .sh
+   刪除後得到的名稱。例如 debian.control.sh 就是產生 debian.control 的 script。
+ - *.in - 用於生成 meta-package 使用的範本檔案，命名規則同上。
+ - *.out - 儲存輸出的 meta-package 檔案。
+
+原則
+----
+因為軟體清單常常是用在剛安裝好，還缺少很多軟體的系統，所以我們希望使用這份清單
+時，能盡量不依賴外部程式，以避免為了處理清單還需要安裝額外軟體的麻煩。我們認為
+以下軟體是我們可以依賴並假設一定會存在的：
+
+ . POSIX shell (/bin/sh) 與基本的系統指令。
+ . POSIX standard C compiler (/usr/bin/c99)。
+ . POSIX make (/usr/bin/make)，我們的 Makefile 不依賴 GNU 或 BSD make。
+ . C / C\++ 編譯器與前處理器，請用 cc / cpp / c\++ 這類通用的名稱，不要使用
+   gcc / g\++ 或 clang / clang++ 這類與特定編譯器實作有關的名稱。
+
+當然，如果你正在準備你正在寫 debian.\*.sh 或 freebsd.\*.sh 這類只使用在特定平臺
+的 script，你可以使用只在特定平臺才有的程式。例如 debian.\*.sh 內可以使用 bash
+和 perl，而 freebsd.*.sh 內可以使用 csh 和 bsdtar。