Split doc file by i18n rule, add zh-CN docs

pull/64/merge
icyleaf 9 years ago committed by Bruno Pinto
parent 658c8ad50f
commit a40f3be16b

@ -0,0 +1,95 @@
<div align="center">
<a href="http://github.com/oh-my-fish/oh-my-fish">
<img width=120px src="https://cloud.githubusercontent.com/assets/8317250/8510172/f006f0a4-230f-11e5-98b6-5c2e3c87088f.png">
</a>
</div>
<br>
# 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
```

@ -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 <pkg>` 移除已安装的插件前会发送 `uninstall_<pkg>` 事件。订阅者可以使用该事件清理自定义的资源等操作。
```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

@ -0,0 +1,112 @@
<img src="docs/logo.png" align="left" width="192px" height="192px"/>
<img src="" align="left" width="0" height="192px" hspace="10"/>
> The <a href="http://fishshell.com">Fishshell</a> 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 外观样式,它的速度敏捷和可扩展性让你**如鱼得水**。
<br><br>
# 安装
```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` _`[<name>|<url>]`_
安装 _一个或多个_ 插件。
- 你可以通过输入指定的 URL 直接安装插件 `omf install URL`
- 当没有执行没有传入任何参数,将会从 [bundle](#dotfiles) 文件检索并安装本地尚未安装的插件和主题。
#### `omf list`
显示本地已安装的插件列表。
#### `omf theme` _`<theme>`_
应用一个主题。查看全部可用主题执行 `omf theme`.
#### `omf remove` _`<name>`_
移除主题或插件。
> 插件如果注册(subscribed)过 `uninstall_<pkg>` 事件将会在插件移除前触发,因此你可以自定义自身清理和扫尾的工作以保证插件干净移除。
详见[卸载部分](Packages.md#uninstall)获取更多信息。
#### `omf new pkg | theme` _`<name>`_
创建新插件和主题的生成工具。
> 创建的模板会新创建并保存于 `$OMF_CONFIG/{pkg | themes}/` 文件夹下面。
#### `omf submit` _`pkg/<name>`_ _`[<url>]`_
添加一个新的插件。提交新主题请使用 `omf submit` _`themes/<name>`_ _`<url>`_
新插件或新主题需要托管于 Git 仓库,上面命令 url 需要输入 git 仓库的 url 地址。
此命令仅仅是把 git 仓库地址保存与 Oh My Fish 的 db 数据库,同时还需要[提交 PR][omf-pulls-link]让组织把你的插件或主题归于框架。
#### `omf query` _`<variable name>`_
用于查看所有会话的变量。用于查看调试类似 _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
Loading…
Cancel
Save