docs: intro

cl-qob · Nov 24, 2024 · 574e4fa · 574e4fa
1 parent 9df37fc
commit 574e4fa
Show file tree

Hide file tree

Showing 3 changed files with 63 additions and 214 deletions.
diff --git a/docs/content/Getting-Started/Basic-Usage/images/scopes.png b/docs/content/Getting-Started/Basic-Usage/images/scopes.png
diff --git a/docs/content/Getting-Started/Introduction/_index.en.md b/docs/content/Getting-Started/Introduction/_index.en.md
@@ -3,144 +3,60 @@ title: 🚪 Introduction
 weight: 0
 ---
 
-Eask was built to use as a package development tool in your Elisp packages. But
-now, Eask supports various types of Emacs Lisp tasks. It can be used in three
-major ways:
-
-1. Dev tool for Elisp packages
-2. Dependency management for your configuration
-3. Run elisp programs for all other purposes
-
-So what are the major differences between Eask and other build tools like
-[Cask][], [makem.sh][], and [Eldev][], other than the things above?
-
-Good question! Eask is more than a build tool now, it can be used for various
-purposes! But here are Eask aims to be:
-
-- **Consistent** enough to sandbox across all systems
-- **General** enough to have Emacsers frequently used commands (`byte-compile`, `checkdoc`, etc)
-- **Robust** enough to provide useful results even in the presence of user errors
-- **Dependency-free** so that the tool can be run on any platform
-
-*P.S. See [Why Eask?](https://emacs-eask.github.io/#-why-eask) for more detailed
-information.*
-
-## ❓ Why Eask?
-
-`Eask` has the same philosophy as Cask, see their site [Why Cask?](https://cask.readthedocs.io/en/latest/guide/introduction.html#introduction-why-cask)
-to understand why you should use Eask (or Cask).
-
-Many tools like [Cask][], [makem.sh][], or [Eldev][] don't **"really"** support
-Windows. `Cask` has dropped support for Legacy Windows, `makem.sh` runs on bash,
-`Eldev` does support Windows, but the author doesn't use it on Windows (not
-having full tests, see their
-[CI workflows](https://github.com/doublep/eldev/actions/workflows/test.yml)).
-`Eask` aims to adapt all platforms, including `Linux`, `macOS`, and `Windows`.
-It focuses on the cross-platform capability and the consistency between each
-OS. If Eask works on your machine, then it will work on any platform.
-
-Here are our suggestions; if you plan to work on an OS-specific package (never
-going to other platforms), go for other tools. On the other hand, Eask aims to
-provide the best consistency between each OS. Alternatively, if you want to
-learn a tool that works everywhere, Eask is one of the best choices.
-
-## ⚖️ Comparisons
-
-The table was compiled by reading these projects’ documentation and source code,
-but the author is not an expert on these tools. Corrections are welcome.
-
-### 🔍 Project Wise
-
-The table shows what technology has been chosen by their author and how the
-project is being constructed. Furthermore, what technical decisions have they
-made? Drop support? Project's layout? Etc.
-
-|                | Eask              | Cask                       | Eldev          | makem.sh                   |
-|----------------|-------------------|----------------------------|----------------|----------------------------|
-| bin folder     | binary, bash, bat | bash, bat                  | bash, bat, ps1 | bash                       |
-| Cross-Platform | ✅                | ❌, no [Windows][] support | ✅             | ❌, no [Windows][] support |
-| Emacs version  | 26.1+             | 24.5+                      | 24.4+          | 26.1+                      |
-| Size           | 9,000+ lines      | 3,000+ lines               | 8,000+ lines   | 1,200+ lines               |
-| Executable     | ✅                | ❌                         | ❌             | ❌                         |
-| Pure Elisp     | ❌, JavaScript    | ✅                         | ✅             | ✅                         |
-| CLI Parser     | [yargs][]         | [commander][]              | built-in       | built-in                   |
-
-{{< hint info >}}
-💡 **makem.sh** has a good comparisons document as well, visit their [site](https://github.com/alphapapa/makem.sh#comparisons)
-{{< /hint >}}
-
-### 🔍 Feature Wise
-
-This is the feature comparison between each tool. Every tool has its advantages;
-choose the right tool that works for you!
-
-If the features are not listed below, either it is forgotten or simply
-considered too essential, so every tool has it; hence we don't add them to the
-list.
-
-|                           | Eask                                    | Cask                     | Eldev          | makem.sh |
-|---------------------------|-----------------------------------------|--------------------------|----------------|----------|
-| Elisp configuration       | ✅, [DSL][DSL-Eask] is optional         | ❌, [DSL][DSL-Cask] only | ✅, pure elisp | ❌       |
-| Handle `archives` failure | ✅, see [archives][emacs-eask/archives] | ❌                       | ❌             | ❌       |
-| `create` project, etc     | ✅                                      | ❌                       | ❌             | ❌       |
-| `link` local dependencies | ✅                                      | ✅                       | ✅             | ❌       |
-| `exec` program            | ✅                                      | ✅                       | ❌             | ❌       |
-| `eval` expressions        | ✅                                      | ✅                       | ✅             | ❌       |
-| `emacs` execution         | ✅                                      | ✅                       | ❌             | ❌       |
-| Built-in `linters`        | ✅                                      | ❌                       | ✅             | ❌       |
-| Built-in `tests`          | ✅                                      | ❌                       | ✅             | ❌       |
-| Run script                | ✅                                      | ❌                       | ❌             | ❌       |
-| Self-defined commands     | ✅                                      | ❌                       | ✅             | ❌       |
-| Subcommand                | ✅                                      | ❌                       | ❌             | ❌       |
+Qob attempts to be good at these things:
+
+- Play nicely with [ASDF][] and [Quicklisp][].
+- Support project local like [Qlot][] and support global scope facilities.
+- Works on all modern operating systems: [Linux][], [macOS][], and [Windows][].
+
+We aim to make Qob an all-in-one tool so users no longer need to install
+tools like [Roswell][] and [Qlot][], which only serve specific goals.
+
+## ❓ Why Qob?
+
+Qob is an Common Lisp project management tool, similar to Maven or Leiningen.
+It aims to control and automate the entire life cycle of an Common Lisp system,
+including dependency management, packaging, distribution and testing.
+
+- Ruby projects have a `gemspec` file?
+- Node.js projects have a `package.json` file?
+- Clojure projects have a `project.clj` file?
+- Common Lisp projects have a `Qob` file?
 
 ## 📰 News
 
-- `0.9.x` - Improve UX in general
-- `0.8.x` - Add `link` command
-- `0.7.x` - Fix `default-directory` isn't honored by **-g** option
-- `0.6.x` - You can now use `eask create` to create an Elisp project
-- `0.5.x` - Handle error for failed archive
-- `0.4.x` - Add color logger
-- `0.3.x` - Add verbosity level and timestamps
-- `0.2.x` - Done basic error handling with exit code at the end of executions
-- `0.1.39` - Use `spawn` instead `exec`; now messages will be printed immediately
 - `0.1.x` - Project bare-bones are pretty much complete!
 
 ## 📝 Todo list
 
-### 🔍 Development
-
-- [ ] [DEV] Publish package to [winget]()
-
 ### 🔍 Core commands
 
-- [ ] [FEAT] Add `publish` command; to publish the package to the eask archive?
+- [ ] [FEAT] Add `publish` command; to publish the system to the Quciklisp dist?
 
-### 🔍 Eask-file commands
+### 🔍 Qob-file commands
 
 - N/A
 
 ## 📂 Underlying Projects
 
-The design of Eask was greatly influenced by the following projects:
+The design of Qob was greatly influenced by the following projects:
 
-* [Cask][] - Project management tool for Emacs
-* [makem.sh][] - Makefile-like script for building and testing Emacs Lisp packages
-* [epm](https://github.com/xuchunyang/epm) - Emacs Package Manager
-* [Eldev][] - Elisp Development Tool
+- [Roswell][] - Common Lisp environment setup Utility
+- [Qlot][] - A project-local library installer for Common Lisp
 
 
 <!-- Links -->
 
-[emacs-eask/archives]: https://github.com/emacs-eask/archives
-[Cask]: https://github.com/cask/cask
-[makem.sh]: https://github.com/alphapapa/makem.sh
-[Eldev]: https://github.com/doublep/eldev
+[Linux]: https://en.wikipedia.org/wiki/Linux
+[macOS]: https://en.wikipedia.org/wiki/MacOS
+[Windows]: https://en.wikipedia.org/wiki/Microsoft_Windows
+
+[SBCL]: https://www.sbcl.org/
 
-[yargs]: https://github.com/yargs/yargs
-[commander]: https://github.com/rejeep/commander.el
+[ASDF]: https://asdf.common-lisp.dev/
+[Quicklisp]: https://www.quicklisp.org/beta/
 
-[DSL-Eask]: https://emacs-eask.github.io/DSL/
-[DSL-Cask]: https://cask.readthedocs.io/en/latest/guide/dsl.html
+[Roswell]: https://roswell.github.io/
+[Qlot]: https://github.com/fukamachi/qlot
 
-[Windows]: https://www.microsoft.com/en-us/windows?r=1
+[Make]: https://www.gnu.org/software/make/
diff --git a/docs/content/Getting-Started/Introduction/_index.zh-tw.md b/docs/content/Getting-Started/Introduction/_index.zh-tw.md
@@ -3,121 +3,54 @@ title: 🚪 介紹
 weight: 0
 ---
 
-Eask 被構建為用作 Elisp 包中的包開發工具。 但是現在，Eask 支持各種類型的 Emacs Lisp 任務。
-它可以通過三種主要方式使用：
+Qob 嘗試在這些事情上做得很好：
 
-1. Elisp 包的開發工具
-2. 配置的依賴管理
-3. 為所有其他目的運行 elisp 程序
+- 與 [ASDF][] 及 [Quicklisp][] 搭配使用。
+- 像 [Qlot][] 一樣支援專案本機，並支援全局範圍設施。
+- 可在所有現代作業系統上運作： [Linux][]、[macOS][]和[Windows][]。
 
-那麼，除上述內容外，Eask 與其他構建工具（如 [Cask][]、[makem.sh][] 和 [Eldev][] 之間的主要區別是什麼？
+我們的目標是讓 Qob 成為多合一的工具，讓使用者不再需要安裝
+[Roswell][] 和 [Qlot][] 之類的工具，這些工具只能達到特定的目標。
 
-好問題！ Eask 現在不僅僅是一個構建工具，它可以用於各種目的！ 但 Eask 的目標是：
+## ❓ 為什麼選擇 Qob？
 
-- **一致**足以跨所有系統進行沙盒
-- **通用**足以讓 Emacsers 經常使用命令（`byte-compile`、`checkdoc` 等）
-- **穩健**即使在出現用戶錯誤的情況下也足以提供有用的結果
-- **無依賴**，使該工具可以在任何平台上運行
+Qob 是一個 Common Lisp 專案管理工具，類似於 Maven 或 Leiningen。
+它的目標是控制 Common Lisp 系統的整個生命週期並使其自動化，
+包括相依性管理、打包、發行和測試。
 
-*附言 有關更多詳細信息，請參閱[為什麼使用 Eask？](https://emacs-eask.github.io/#-why-eask)。*
-
-## ❓ 為什麼選擇 Eask？
-
-`Eask` 與 Cask 具有相同的理念，請參閱他們的網站 [Why Cask?](https://cask.readthedocs.io/en/latest/guide/introduction.html#introduction-why-cask)
-以了解您為什麼應該這樣做, 使用 Eask（或 Cask）。
-
-[Cask][]、[makem.sh][] 或 [Eldev][] 等許多工具並不**“真正”**支持 Windows。 `Cask`
-已經放棄了對舊版 Windows 的支持，`makem.sh` 在 bash 上運行，`Eldev` 確實支持 Windows，
-但作者沒有在 Windows 上使用它（沒有完整的測試，請參閱他們的
-[CI 工作流程]（https //github.com/doublep/eldev/actions/workflows/test.yml））。
-`Eask` 旨在適配所有平台，包括 `Linux`、`macOS` 和 `Windows`。 它側重於跨平台能力和每個
-操作系統之間的一致性。 如果 Eask 可以在您的機器上運行，那麼它也可以在任何平台上運行。
-
-這是我們的建議； 如果您打算在特定於操作系統的軟件包上工作（從不使用其他平台），請使用其他工具。
-另一方面，Eask 旨在提供每個操作系統之間的最佳一致性。 或者，如果你想學習一個隨處可用的工具，
-Eask 是最好的選擇之一。
-
-## ⚖️ 比較
-
-該表是通過閱讀這些項目的文檔和源代碼編制的，但作者不是這些工具的專家。 歡迎指正。
-
-### 🔍 專案方面
-
-該表顯示了作者選擇的技術以及項目的構建方式。 此外，他們做出了哪些技術決策？ 放棄支持？ 項目佈局？ 等等。
-
-|                | Eask              | Cask                   | Eldev          | makem.sh               |
-|----------------|-------------------|------------------------|----------------|------------------------|
-| bin folder     | binary, bash, bat | bash, bat              | bash, bat, ps1 | bash                   |
-| Cross-Platform | ✅                | ❌, 不支援 [Windows][] | ✅             | ❌, 不支援 [Windows][] |
-| Emacs version  | 26.1+             | 24.5+                  | 24.4+          | 26.1+                  |
-| Size           | 9,000+ 行         | 3,000+ 行              | 8,000+ 行      | 1,200+ 行              |
-| Executable     | ✅                | ❌                     | ❌             | ❌                     |
-| Pure Elisp     | ❌, JavaScript    | ✅                     | ✅             | ✅                     |
-| CLI Parser     | [yargs][]         | [commander][]          | 內建           | 內建                   |
-
-{{< hint info >}}
-💡 **makem.sh** 也有很好的比較文檔，請訪問他們的[站點](https://github.com/alphapapa/makem.sh#comparisons)
-{{< /hint >}}
-
-### 🔍 功能方面
-
-這是每個工具之間的功能比較。 每種工具都有其優點； 選擇適合您的工具！
-
-如果這些功能沒有在下面列出，要么被遺忘，要么只是被認為太重要了，所以每個工具都有它； 因此我們不將它們添加到列表中。
-
-|                           | Eask                                    | Cask                   | Eldev        | makem.sh |
-|---------------------------|-----------------------------------------|------------------------|--------------|----------|
-| Elisp configuration       | ✅, [DSL][DSL-Eask] 是可選的            | ❌, 僅 [DSL][DSL-Cask] | ✅, 純 elisp | ❌       |
-| Handle `archives` failure | ✅, see [archives][emacs-eask/archives] | ❌                     | ❌           | ❌       |
-| `create` project, etc     | ✅                                      | ❌                     | ❌           | ❌       |
-| `link` local dependencies | ✅                                      | ✅                     | ✅           | ❌       |
-| `exec` program            | ✅                                      | ✅                     | ❌           | ❌       |
-| `eval` expressions        | ✅                                      | ✅                     | ✅           | ❌       |
-| `emacs` execution         | ✅                                      | ✅                     | ❌           | ❌       |
-| Built-in `linters`        | ✅                                      | ❌                     | ✅           | ❌       |
-| Built-in `tests`          | ✅                                      | ❌                     | ✅           | ❌       |
-| Run script                | ✅                                      | ❌                     | ❌           | ❌       |
-| Self-defined commands     | ✅                                      | ❌                     | ✅           | ❌       |
-| Subcommand                | ✅                                      | ❌                     | ❌           | ❌       |
+- Ruby 專案有 `gemspec` 檔案嗎？
+- Node.js 專案有 `package.json` 檔案嗎？
+- Clojure 專案有 `project.clj` 檔案嗎？
+- Common Lisp 專案有 `Qob` 檔案嗎？
 
 ## 📰 消息
 
-- `0.9.x` - Improve UX in general
-- `0.8.x` - Add `link` command
-- `0.7.x` - Fix `default-directory` isn't honored by **-g** option
-- `0.6.x` - You can now use `eask create` to create an Elisp project
-- `0.5.x` - Handle error for failed archive
-- `0.4.x` - Add color logger
-- `0.3.x` - Add verbosity level and timestamps
-- `0.2.x` - Done basic error handling with exit code at the end of executions
-- `0.1.39` - Use `spawn` instead `exec`; now messages will be printed immediately
-- `0.1.x` - Project bare-bones are pretty much complete!
+請參考[這](https://cl-qob.github.io/Getting-Started/Introduction/#-news).
 
 ## 📝 TODO 事項列表
 
-請參考[這](https://emacs-eask.github.io/Getting-Started/Introduction/#-todo-list).
+請參考[這](https://cl-qob.github.io/Getting-Started/Introduction/#-todo-list).
 
 ## 📂 基礎項目
 
-Eask 的設計深受以下項目的影響：
+Qob 的設計深受以下項目的影響：
 
-* [Cask][] - Emacs 的項目管理工具
-* [makem.sh][] -用於構建和測試 Emacs Lisp 包的類似 Makefile 的腳本
-* [epm](https://github.com/xuchunyang/epm) - Emacs 包管理器
-* [Eldev][] - Elisp 開發工具
+- [Roswell][] - Common Lisp 環境設定公用程式
+- [Qlot][] - Common Lisp 專案本機函式庫安裝程式
 
 
 <!-- Links -->
 
-[emacs-eask/archives]: https://github.com/emacs-eask/archives
-[Cask]: https://github.com/cask/cask
-[makem.sh]: https://github.com/alphapapa/makem.sh
-[Eldev]: https://github.com/doublep/eldev
+[Linux]: https://en.wikipedia.org/wiki/Linux
+[macOS]: https://en.wikipedia.org/wiki/MacOS
+[Windows]: https://en.wikipedia.org/wiki/Microsoft_Windows
+
+[SBCL]: https://www.sbcl.org/
 
-[yargs]: https://github.com/yargs/yargs
-[commander]: https://github.com/rejeep/commander.el
+[ASDF]: https://asdf.common-lisp.dev/
+[Quicklisp]: https://www.quicklisp.org/beta/
 
-[DSL-Eask]: https://emacs-eask.github.io/DSL/
-[DSL-Cask]: https://cask.readthedocs.io/en/latest/guide/dsl.html
+[Roswell]: https://roswell.github.io/
+[Qlot]: https://github.com/fukamachi/qlot
 
-[Windows]: https://www.microsoft.com/en-us/windows?r=1
+[Make]: https://www.gnu.org/software/make/