diff --git a/docs/content/Getting-Started/Basic-Usage/images/scopes.png b/docs/content/Getting-Started/Basic-Usage/images/scopes.png deleted file mode 100644 index 5ae9584..0000000 Binary files a/docs/content/Getting-Started/Basic-Usage/images/scopes.png and /dev/null differ diff --git a/docs/content/Getting-Started/Introduction/_index.en.md b/docs/content/Getting-Started/Introduction/_index.en.md index 744b916..4ca34b1 100644 --- 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 -[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 index 41066b2..daafedc 100644 --- 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 專案本機函式庫安裝程式 -[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/