From a40f3be16b18d8220f36ac2e25e2a79938f5453b Mon Sep 17 00:00:00 2001 From: icyleaf Date: Fri, 11 Sep 2015 11:50:26 +0800 Subject: [PATCH 1/3] Split doc file by i18n rule, add zh-CN docs --- docs/{ => en-US}/FAQ.md | 0 docs/{ => en-US}/Packages.md | 0 docs/zh-CN/FAQ.md | 95 +++++++++++++++++++++++++++++ docs/zh-CN/Packages.md | 80 +++++++++++++++++++++++++ docs/zh-CN/README.md | 112 +++++++++++++++++++++++++++++++++++ 5 files changed, 287 insertions(+) rename docs/{ => en-US}/FAQ.md (100%) rename docs/{ => en-US}/Packages.md (100%) create mode 100644 docs/zh-CN/FAQ.md create mode 100644 docs/zh-CN/Packages.md create mode 100644 docs/zh-CN/README.md diff --git a/docs/FAQ.md b/docs/en-US/FAQ.md similarity index 100% rename from docs/FAQ.md rename to docs/en-US/FAQ.md diff --git a/docs/Packages.md b/docs/en-US/Packages.md similarity index 100% rename from docs/Packages.md rename to docs/en-US/Packages.md diff --git a/docs/zh-CN/FAQ.md b/docs/zh-CN/FAQ.md new file mode 100644 index 0000000..a5e0ba6 --- /dev/null +++ b/docs/zh-CN/FAQ.md @@ -0,0 +1,95 @@ +
+ + + +
+ +
+ +# FAQ + +感谢您花一些时间来阅读 FAQ。如果没有从下面找到你想问的问题欢迎给我们提交新的问题(Issue)。 + + +## 什么是 Oh My Fish，我为什么会使用它？ + +Oh My Fish 是基于 [fishshell](https://fishshell.org) 封装的高级 _框架_。它可以帮你管理你的配置，主题和插件。 + + +## 使用 Oh My Fish 我需要注意什么？ + +_什么都不需要注意_。安装 Oh My Fish 并想平时使用 Fish Shell 一样。当你需要获取更多帮助仅需要执行 `omf help`。 + + +## 什么是 Oh My Fish 包（Packages）？ + +Oh My Fish 包是使用 fish 编写的一系列主题和插件用于扩展 Shell 的核心功能，比如初始化时执行自定义代码，添加自动补全等。 + + +## Oh My Fish 包大概包含哪些类型? + +目前粗略分类可以定义 3 中类型： + +1. 配置增强。比如 [`pkg-pyenv`](https://github.com/oh-my-fish/pkg-pyenv) checks whether `pyenv` exists in your system and runs `(pyenv init - | psub)` for you during startup. + +2. 主题. 查看我们的[主题目录](https://github.com/oh-my-fish). + +3. Traditional shell utilities. For example [`pkg-copy`](https://github.com/oh-my-fish/pkg-copy), a clipboard utility compatible across Linux and OSX. + + +## Oh My Fish 主要都干了什么? + ++ 自动加载 `$OMF_PATH/` 目录下已安装的插件和主题。 + ++ 自动加载你的配置。默认路径 `~/.config/omf`，除非你自定义了 `$OMF_CONFIG` 变量。 + ++ 自动加载 `$OMF_PATH` 和 `$OMF_CONFIG` 目录下面的所有的 `functions` + ++ 如果存在加载 `$OMF_CONFIG/init.fish`。 + + +## 如何升级之前已安装的 Oh My Fish? + +> :warning: 务必先备份你的 dotfiles 和其他自定义的数据。 + +``` +curl -L github.com/oh-my-fish/oh-my-fish/raw/master/bin/install | sh +``` + +现在你可以安全的移除 `$fish_path`. + +```fish +rm -rf "$fish_path" +``` + + +## 我使用 `fish_config` 修改了自己的 prompt，现在我无法恢复 Oh My Fish 主题的 prompt，我该怎么办？ + +`fish_config` 默认会使用 `~/.config/fish/functions/fish_prompt.fish` 设置 prompt，该文件在 Oh My Fish 主题启用后加载， +它拥有高优先级来覆盖 Oh My Fish 主题的 prompt，如果你要恢复主题的 prompt，最简单的方法就是删除该文件： + +``` +rm ~/.config/fish/functions/fish_prompt.fish +``` + + +## 如何把 fish 设置为我默认的 shell? + +添加 Fish 到 `/etc/shells`: + +```sh +echo "/usr/local/bin/fish" | sudo tee -a /etc/shells +``` + +切换并保存默认 shell: + +```sh +chsh -s /usr/local/bin/fish +``` + +切换之前的 shell: +> 一般来说是 `/bin/bash`、`/bin/tcsh` 或者 `/bin/zsh`. + +```sh +chsh -s /bin/bash +``` diff --git a/docs/zh-CN/Packages.md b/docs/zh-CN/Packages.md new file mode 100644 index 0000000..d0d7bfb --- /dev/null +++ b/docs/zh-CN/Packages.md @@ -0,0 +1,80 @@ +# 创建插件或主题 + +本教程通过创建一个简单的 `hello_world` 让我们一起来学习，插件名通常仅接受小写英文字母和连字符分割每个单词。 + +Oh My Fish 提供一个脚手架工具帮助生成插件或主题的模板结构。通过执行命令 `omf new` 生成： + +```fish +$ omf new pkg hello_world +``` + +> 使用 `omf new theme my_theme_name` 创建主题模板。 + +该操作会创建插件的目录并切换到该路径下面： + +``` +$ ls -l + README.md + hello_world.fish + completions/hello_world.fish +``` + +通常在 `README.md` 描述插件的工作原理，依据插件情况可以提供一些 [auto completion](http://fishshell.com/docs/current/commands.html#complete) + +`hello_world.fish` 定义一个简单的 function： + +```fish +function hello_world -d "Prints hello world" + echo "Hello World!" +end +``` + +在你的插件中，每个函数的声明定义必须存放在独立的文件中，这是 fish 自动加载机制强制的，旨在加载功能所需要的，避免无用函数的过渡加载。 + +请记住，fish 缺乏一个私有范围，所以如果你需要分离你的插件到函数，考虑私有函数增加前缀类似 `__hello_world.my_extra_function` 以避免类名冲突和全局命名控件的污染。 + + +# 事件 + +利用 fish 事件的优势，目前 Oh My Fish 定义了两个事件提供给开发者使用： + +## 初始化 + +如果你想在插件被加载时收到[通知](http://fishshell.com/docs/current/commands.html#emit)，你可以在 `hello_world.fish` 添加下面的代码： + +```fish +function init -a path --on-event init_hello_world + echo "hello_world initialized" +end +``` + +该事件可以用于修改环境变量、加载资源和自动加载函数等。如果你的插件没有输出任何的函数，你仍然可以使用该事件加载其他的函数。 + +## 卸载 + +Oh My Fish 通过 `omf remove ` 移除已安装的插件前会发送 `uninstall_` 事件。订阅者可以使用该事件清理自定义的资源等操作。 + +```fish +function uninstall --on-event uninstall_hello_world +end +``` + + +# 发布插件 + +Oh My Fish 在 `$OMF_PATH/db/` 目录注册已发布的插件或主题。 + +添加你的插件或主题到注册目录需要执行: + +```fish +# 插件： +omf submit pkg/hello_world .../hello_world.git + +# 主题： +omf submit theme/my_theme .../my_theme_name.git +``` + +此操作仅在本地会添加一个新的注册索引，最后你还需要[提交 PR][omf-pulls-link]并入官方的注册索引。 + + +[omf-pulls-link]: https://github.com/oh-my-fish/oh-my-fish/pulls diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md new file mode 100644 index 0000000..ab478e6 --- /dev/null +++ b/docs/zh-CN/README.md @@ -0,0 +1,112 @@ + + + +> The Fishshell Framework + +[![MIT License](https://img.shields.io/badge/license-MIT-007EC7.svg?style=flat-square)](/LICENSE.md) [![Fish Shell Version](https://img.shields.io/badge/fish-v2.2.0-007EC7.svg?style=flat-square)](http://fishshell.com) [![Travis Build Status](http://img.shields.io/travis/oh-my-fish/oh-my-fish.svg?style=flat-square)](https://travis-ci.org/oh-my-fish/oh-my-fish) [![Travis Build Status](https://img.shields.io/badge/gitter-join_chat-brightgreen.svg?style=flat-square)](https://gitter.im/oh-my-fish/oh-my-fish?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) + +Oh My Fish 提供核心基础设施的配置，允许每个人可以轻松安装插件或随心所欲更换 Shell 外观样式，它的速度敏捷和可扩展性让你**如鱼得水**。 + +

+ +# 安装 + +```fish +curl -L github.com/oh-my-fish/oh-my-fish/raw/master/bin/install | sh +omf help +``` + +或者 _下载脚本_ 后自己执行： + +```fish +curl -L github.com/oh-my-fish/oh-my-fish/raw/master/bin/install > install +chmod +x install +./install +``` + +# 快速入门 + +Oh My Fish 自带的辅助命令工具 `omf` 可以帮助你快速获取安装新插件和主题。 + +#### `omf update` + +更新自身和已安装的所有插件和默认主题。 + +#### `omf install` _`[|]`_ + +安装 _一个或多个_ 插件。 + +- 你可以通过输入指定的 URL 直接安装插件 `omf install URL` +- 当没有执行没有传入任何参数，将会从 [bundle](#dotfiles) 文件检索并安装本地尚未安装的插件和主题。 + +#### `omf list` + +显示本地已安装的插件列表。 + +#### `omf theme` _``_ + +应用一个主题。查看全部可用主题执行 `omf theme`. + +#### `omf remove` _``_ + +移除主题或插件。 + +> 插件如果注册(subscribed)过 `uninstall_` 事件将会在插件移除前触发，因此你可以自定义自身清理和扫尾的工作以保证插件干净移除。 +详见[卸载部分](Packages.md#uninstall)获取更多信息。 + +#### `omf new pkg | theme` _``_ + +创建新插件和主题的生成工具。 + +> 创建的模板会新创建并保存于 `$OMF_CONFIG/{pkg | themes}/` 文件夹下面。 + +#### `omf submit` _`pkg/`_ _`[]`_ + +添加一个新的插件。提交新主题请使用 `omf submit` _`themes/`_ _``_。 + +新插件或新主题需要托管于 Git 仓库，上面命令 url 需要输入 git 仓库的 url 地址。 +此命令仅仅是把 git 仓库地址保存与 Oh My Fish 的 db 数据库，同时还需要[提交 PR][omf-pulls-link]让组织把你的插件或主题归于框架。 + +#### `omf query` _``_ + +用于查看所有会话的变量。用于查看调试类似 _PATH_ 变量，比如 `$fish_function_path`，`$fish_complete_path` 等。 + +#### `omf destroy` + +卸载 Oh My Fish. + +# 高级用法 + +Oh My Fish 安装脚本会把自身启动代码加载到 fish 的配置文件 (`~/.config/fish/config.fish`). + +## 启动脚本 + +每次你新打开 Shell 都会从 _配置文件_ (默认：`~/.config/omf`) 加载 Oh My Fish 的启动脚本([`init.fish`](../init.fish)) 进行初始化： +自动加载插件，主题和你自定义的配置文件。更多信息请查看[FAQ](docs/FAQ.md#what-does-oh-my-fish-do-exactly). + +## Dotfiles + +`$OMF_CONFIG` 目录存储用户使用 Oh My Fish 的重要配置参数，这是最完美的方式把该目录的所有文件加入你的 dotfiles 或加入到版本控制。 +这里有两个重要的文件： + +- __`theme`__ - 当前主题 +- __`bundle`__ - 显示当前已安装的插件/主题列表 + +### 关于 bundle + +每次当有插件和主题被安装或移除都会更新 `bundle` 文件。你也可以手动编辑该文件并执行 `omf install` 保证变更状态。 +需要注意的是当有插件、主题被添加到 bundle 文件会自动被安装。但从 bundle 中移除掉它们却不会从用户安装路径移除物理文件。 + +## 创建插件 + +Oh My Fish 使用了友好的插件架构能够简化插件的开发，其中包括初始化、卸载事件和函数的自动加载。[查看相关文档](docs/Packages.md) 获取更多信息。 + +# 开源协议 + +Copyright (c) 2015 Bruno Ferreira Pinto. 详见 [开源协议文件](LICENSE). + +[fishshell]: http://fishshell.com + +[contributors]: https://github.com/oh-my-fish/oh-my-fish/graphs/contributors + +[omf-pulls-link]: https://github.com/oh-my-fish/oh-my-fish/pulls \ No newline at end of file From 639390b203ee3ca0a0b836c3365b5badcb6a03e4 Mon Sep 17 00:00:00 2001 From: icyleaf Date: Fri, 11 Sep 2015 20:23:05 +0800 Subject: [PATCH 2/3] Added switch language menu --- README.md | 5 +++++ docs/en-US/FAQ.md | 6 ++++++ docs/en-US/Packages.md | 13 +++++++++++++ docs/zh-CN/FAQ.md | 11 ++++++++--- docs/zh-CN/Packages.md | 15 ++++++++++++++- docs/zh-CN/README.md | 17 +++++++++++------ 6 files changed, 57 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index ebadc3e..ed30c36 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,11 @@ Oh My Fish provides core infrastructure to allow you to install packages which e

+

+ English • + 简体中文 +

+ # Install ```fish diff --git a/docs/en-US/FAQ.md b/docs/en-US/FAQ.md index 056adf9..15ddfe9 100644 --- a/docs/en-US/FAQ.md +++ b/docs/en-US/FAQ.md @@ -6,6 +6,12 @@
+

+ English • + 简体中文 +

+ + # FAQ Thanks for taking the time to read this FAQ. Feel free to create a new issue if your question is not answered here. diff --git a/docs/en-US/Packages.md b/docs/en-US/Packages.md index 4cea7e4..ee3ef95 100644 --- a/docs/en-US/Packages.md +++ b/docs/en-US/Packages.md @@ -1,3 +1,16 @@ + + +
+ +

+ English • + 简体中文 +

+ # Creating To learn package creation let's create a new package that will provide a `hello_world` command for your shell. Package names may only contain lowercase letters and hyphens to separate words. diff --git a/docs/zh-CN/FAQ.md b/docs/zh-CN/FAQ.md index a5e0ba6..0cc513d 100644 --- a/docs/zh-CN/FAQ.md +++ b/docs/zh-CN/FAQ.md @@ -6,6 +6,11 @@
+

+ English • + 简体中文 +

+ # FAQ 感谢您花一些时间来阅读 FAQ。如果没有从下面找到你想问的问题欢迎给我们提交新的问题(Issue)。 @@ -30,11 +35,11 @@ Oh My Fish 包是使用 fish 编写的一系列主题和插件用于扩展 Shell 目前粗略分类可以定义 3 中类型： -1. 配置增强。比如 [`pkg-pyenv`](https://github.com/oh-my-fish/pkg-pyenv) checks whether `pyenv` exists in your system and runs `(pyenv init - | psub)` for you during startup. +1. 配置增强。比如 [`pkg-pyenv`](https://github.com/oh-my-fish/pkg-pyenv) 检测 `pyenv` 是否安装并运行 `(pyenv init - | psub)`。 2. 主题. 查看我们的[主题目录](https://github.com/oh-my-fish). -3. Traditional shell utilities. For example [`pkg-copy`](https://github.com/oh-my-fish/pkg-copy), a clipboard utility compatible across Linux and OSX. +3. 系统增强。比如 [`pkg-copy`](https://github.com/oh-my-fish/pkg-copy)，可同时支持 Linux 和 Mac OS X 的剪切工具。 ## Oh My Fish 主要都干了什么? @@ -92,4 +97,4 @@ chsh -s /usr/local/bin/fish ```sh chsh -s /bin/bash -``` +``` \ No newline at end of file diff --git a/docs/zh-CN/Packages.md b/docs/zh-CN/Packages.md index d0d7bfb..dc15c0a 100644 --- a/docs/zh-CN/Packages.md +++ b/docs/zh-CN/Packages.md @@ -1,3 +1,16 @@ + + +
+ +

+ English • + 简体中文 +

+ # 创建插件或主题 本教程通过创建一个简单的 `hello_world` 让我们一起来学习，插件名通常仅接受小写英文字母和连字符分割每个单词。 @@ -77,4 +90,4 @@ omf submit theme/my_theme .../my_theme_name.git 此操作仅在本地会添加一个新的注册索引，最后你还需要[提交 PR][omf-pulls-link]并入官方的注册索引。 -[omf-pulls-link]: https://github.com/oh-my-fish/oh-my-fish/pulls +[omf-pulls-link]: https://github.com/oh-my-fish/oh-my-fish/pulls \ No newline at end of file diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md index ab478e6..4ce30ad 100644 --- a/docs/zh-CN/README.md +++ b/docs/zh-CN/README.md @@ -1,14 +1,19 @@ - + > The Fishshell Framework -[![MIT License](https://img.shields.io/badge/license-MIT-007EC7.svg?style=flat-square)](/LICENSE.md) [![Fish Shell Version](https://img.shields.io/badge/fish-v2.2.0-007EC7.svg?style=flat-square)](http://fishshell.com) [![Travis Build Status](http://img.shields.io/travis/oh-my-fish/oh-my-fish.svg?style=flat-square)](https://travis-ci.org/oh-my-fish/oh-my-fish) [![Travis Build Status](https://img.shields.io/badge/gitter-join_chat-brightgreen.svg?style=flat-square)](https://gitter.im/oh-my-fish/oh-my-fish?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) +[![MIT License](https://img.shields.io/badge/license-MIT-007EC7.svg?style=flat-square)](../../LICENSE.md) [![Fish Shell Version](https://img.shields.io/badge/fish-v2.2.0-007EC7.svg?style=flat-square)](http://fishshell.com) [![Travis Build Status](http://img.shields.io/travis/oh-my-fish/oh-my-fish.svg?style=flat-square)](https://travis-ci.org/oh-my-fish/oh-my-fish) [![Travis Build Status](https://img.shields.io/badge/gitter-join_chat-brightgreen.svg?style=flat-square)](https://gitter.im/oh-my-fish/oh-my-fish?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) Oh My Fish 提供核心基础设施的配置，允许每个人可以轻松安装插件或随心所欲更换 Shell 外观样式，它的速度敏捷和可扩展性让你**如鱼得水**。

+

+ English • + 简体中文 +

+ # 安装 ```fish @@ -81,8 +86,8 @@ Oh My Fish 安装脚本会把自身启动代码加载到 fish 的配置文件 (` ## 启动脚本 -每次你新打开 Shell 都会从 _配置文件_ (默认：`~/.config/omf`) 加载 Oh My Fish 的启动脚本([`init.fish`](../init.fish)) 进行初始化： -自动加载插件，主题和你自定义的配置文件。更多信息请查看[FAQ](docs/FAQ.md#what-does-oh-my-fish-do-exactly). +每次你新打开 Shell 都会从 _配置文件_ (默认：`~/.config/omf`) 加载 Oh My Fish 的启动脚本([`init.fish`](../../init.fish)) 进行初始化： +自动加载插件，主题和你自定义的配置文件。更多信息请查看[FAQ](FAQ.md#oh-my-fish-包大概包含哪些类型). ## Dotfiles @@ -99,11 +104,11 @@ Oh My Fish 安装脚本会把自身启动代码加载到 fish 的配置文件 (` ## 创建插件 -Oh My Fish 使用了友好的插件架构能够简化插件的开发，其中包括初始化、卸载事件和函数的自动加载。[查看相关文档](docs/Packages.md) 获取更多信息。 +Oh My Fish 使用了友好的插件架构能够简化插件的开发，其中包括初始化、卸载事件和函数的自动加载。[查看相关文档](Packages.md) 获取更多信息。 # 开源协议 -Copyright (c) 2015 Bruno Ferreira Pinto. 详见 [开源协议文件](LICENSE). +Copyright (c) 2015 Bruno Ferreira Pinto. 详见 [开源协议文件](../../LICENSE). [fishshell]: http://fishshell.com From 3069368dc5dd9e99f641ee488dffc76fb121daa0 Mon Sep 17 00:00:00 2001 From: Bruno Pinto Date: Tue, 29 Sep 2015 18:50:54 +0100 Subject: [PATCH 3/3] Remove license from README --- docs/zh-CN/README.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md index 4ce30ad..db46b2e 100644 --- a/docs/zh-CN/README.md +++ b/docs/zh-CN/README.md @@ -106,12 +106,8 @@ Oh My Fish 安装脚本会把自身启动代码加载到 fish 的配置文件 (` Oh My Fish 使用了友好的插件架构能够简化插件的开发，其中包括初始化、卸载事件和函数的自动加载。[查看相关文档](Packages.md) 获取更多信息。 -# 开源协议 - -Copyright (c) 2015 Bruno Ferreira Pinto. 详见 [开源协议文件](../../LICENSE). - [fishshell]: http://fishshell.com [contributors]: https://github.com/oh-my-fish/oh-my-fish/graphs/contributors -[omf-pulls-link]: https://github.com/oh-my-fish/oh-my-fish/pulls \ No newline at end of file +[omf-pulls-link]: https://github.com/oh-my-fish/oh-my-fish/pulls