|
|
@@ -0,0 +1,228 @@
|
|
|
+= 使用 Atom 编辑维基
|
|
|
+:author: mitm (翻译 jmecn)
|
|
|
+:revnumber:
|
|
|
+:revdate: 2018-01-16 13:44
|
|
|
+:relfileprefix: ../../
|
|
|
+:imagesdir: ../..
|
|
|
+:experimental:
|
|
|
+ifdef::env-github,env-browser[:outfilesuffix: .adoc]
|
|
|
+
|
|
|
+
|
|
|
+现在为Wiki贡献内容可比以前容易多了。Atom 编辑器为你提供了一个简单易用的跨平台工作环境，包
|
|
|
+括代码自动补全、语法高亮、即时预览、自动集成 Github 客户端等功能。它唯一没干的事情就是帮你
|
|
|
+写文档了。
|
|
|
+
|
|
|
+== 下载源文件
|
|
|
+
|
|
|
+.前置需求：
|
|
|
+. 拥有一个 link:https://github.com/[GitHub 账号]。
|
|
|
+. 成为 link:https://github.com/jMonkeyEngine/wiki/[jMonkeyEngine/wiki] 项目的成员。
|
|
|
+
|
|
|
+如果你不是该项目的成员，可以先把它复刻(fork)到你自己的 Github 仓库。在自己的分支中编辑后，
|
|
|
+再向 jMonkeyEngine/wiki 项目发起合并请求("`Pull Request`")，通过这种方式来贡献内容。
|
|
|
+
|
|
|
+把 wiki 仓库复刻(fork)到你自己的Github账号：
|
|
|
+
|
|
|
+. 打开 link:https://github.com/jMonkeyEngine/wiki[https://github.com/jMonkeyEngine/wiki] 页面。
|
|
|
+. 在页面顶部的菜单中，点击 icon:code-fork[]*Fork* 按钮。
|
|
|
+
|
|
|
+== 安装 Atom 编辑器
|
|
|
+
|
|
|
+. 下载和安装 Atom 编辑器 - https://atom.io/
|
|
|
+. 安装完成后，你可以点击 btn:[Theme Picker] 按钮打开 `Choose A Theme` 面板，然后根据个人喜好来定义编辑器的样式。
|
|
|
+. 当你完成个性化设置后，需要安装几个插件包(Package)，使Atom其能够兼容AsciiDoctor。安装插件包很简单。
|
|
|
+.. 打开 `Install A Package` 面板，点击 btn:[Open Installer] 按钮，或者在编辑器顶部的菜单中选择 `menu:Packages[Settings View>Install Package/Themes]`。
|
|
|
+.. 在搜索框中输入 "`asciidoc`" 然后点击 btn:[Packages] 按钮。
|
|
|
++
|
|
|
+.安装下列插件：
|
|
|
+*** *language-asciidoc* +
|
|
|
+*** *asciidoc-preview* +
|
|
|
+*** *autocomplete-asciidoc*
|
|
|
++
|
|
|
+TIP: 你可以安装 `*git-plus*` 插件来添加更多 Github 控件。
|
|
|
+
|
|
|
+. 编辑 Wiki 需要先把 wiki 仓库 clone 到本地。
|
|
|
+.. 打开 `命令面板` (kbd:[ctrl]+kbd:[shift] +kbd:[P] 或 `menu:Packages[Command Palette>Toggle]`)，在搜索框中输入 "`git`" 。
|
|
|
+.. 点击 btn:[GitHub: Clone]。
|
|
|
+.. 将 wiki 仓库的 +++<abbr title="Uniform Resource Locator">URL</abbr>+++ 粘贴到 `Clone from` 文本框中。
|
|
|
++
|
|
|
+--
|
|
|
+[source]
|
|
|
+----
|
|
|
+https://github.com/jMonkeyEngine/wiki.git
|
|
|
+----
|
|
|
+`To directory` 的内容会在你填写 `Clone from` 时自动更新。
|
|
|
+
|
|
|
+IMPORTANT: 如果你不是官方wiki的项目成员，请使用你复刻(fork)的 wiki 仓库 +++<abbr title="Uniform Resource Locator">URL</abbr>+++ 。
|
|
|
+--
|
|
|
+
|
|
|
+.. 填好后，点击 btn:[Clone] 按钮。
|
|
|
++
|
|
|
+克隆 wiki 源文件到你的电脑将花费一些时间。克隆完毕后，Atom 左侧将会打开一个新的 `Project`
|
|
|
+面板，同时在右侧打开 `Git` 和 `Github Preview` 面板。如果没有打开，你可以通过
|
|
|
+kbd:[ctrl]+kbd:[shift]+kbd:[9] 打开 `Git` 面板，通过 kbd:[ctrl]+kbd:[shift]+kbd:[8]
|
|
|
+打开 `Github Preview` 面板。或者，你也可以通过菜单 `menu:Packages[GitHub]` 打开这些面
|
|
|
+板。现在你可以在 Atom 界面的右下角，即 `状态栏`, 发现一些 Github 控件。
|
|
|
+
|
|
|
+. 在你提交任何对wiki的改动之前，必须先配置 git 的 "`user.email`" 和 "`user.name`" 变
|
|
|
+量。你可以使用 Git Bash 来配置，或者根据下面的指令来手动配置。
|
|
|
+
|
|
|
+* Git Bash: link:https://help.github.com/articles/setting-your-commit-email-address-in-git/[Setting your commit email address in Git]
|
|
|
+* 手动配置: link:https://help.github.com/articles/setting-your-commit-email-address-on-github/[Set your commit email address on GitHub]
|
|
|
+.. 打开你的 `.gitconfig` 文件 (位于 USER_HOME 目录中，如 `C:\Users\jmecn`) 并添加：
|
|
|
++
|
|
|
+[source]
|
|
|
+----
|
|
|
+[user]
|
|
|
+ name = 你的用户名
|
|
|
+ email = 你的邮件地址
|
|
|
+----
|
|
|
+.. 为了维护个人隐私，你可以在自己的 Github 账户中将邮箱设置为 `Keep my email address private`，
|
|
|
+并使用 `users.noreply.github.com` 邮件地址。
|
|
|
+
|
|
|
+. 最后，你需要在 Atom 中登录 Github 。打开 `Github Preview` 面板，点击 `Login` 按钮。
|
|
|
+Atom 会让你从官方页面登录 Github，并获得一个授权口令(Token)，在 `Github Preview` 面板
|
|
|
+中输入 Token 即可。
|
|
|
+
|
|
|
+
|
|
|
+所有维基文档都保存在 `asciidoc` 目录中，图片都保存在 `images` 目录中，多媒体资源都保存
|
|
|
+在 `resources` 目录中。你可以在这些目录下创建自己的目录，用来保存自己的新文档。
|
|
|
+
|
|
|
+当你编辑 Wiki 页面时，`Git` 面板会显示未保存的变更。当你对文档编辑完毕后，需要保存这些改
|
|
|
+动，并在 `Commit message` 中输入提交信息，然后推送(Push)这些改动。
|
|
|
+
|
|
|
+你可以通过快捷键 kbd:[ctrl]+kbd:[shift]+kbd:[A] 或者通过菜单 menu:Packages[AsciiDoc Preview>Toggle Preview] 来预览文档内容。
|
|
|
+
|
|
|
+
|
|
|
+== 更新本地wiki文件
|
|
|
+
|
|
|
+
|
|
|
+在提交任何改动之前，最好先更新你的本地 wiki 克隆。
|
|
|
+
|
|
|
+CAUTION: wiki 是一个开源项目，如果多人同时修改一个文档，有可能产生冲突。
|
|
|
+
|
|
|
+.项目成员
|
|
|
+在提交/推送改动之前，请使用 Atom Editor 来执行 "Pull" 命令，更新本地 wiki 克隆。
|
|
|
+
|
|
|
+作为 wiki 项目成员，你可以使用 Atom 来执行 Git 命令。
|
|
|
+
|
|
|
+.非项目成员
|
|
|
+在提交/推送改动之前，请使用 Github 的 "Pull Request" 功能把 wiki 官方仓库的内容更新到你的个人 wiki 仓库。
|
|
|
+
|
|
|
+. 登录 Github，进入你的个人 wiki 仓库页面。
|
|
|
+. 点击页面上方的 btn:[New Pull Request] 按钮。
|
|
|
++
|
|
|
+NOTE: 官方wiki仓库位于左侧，你的个人wiki仓库位于右侧。
|
|
|
+
|
|
|
+. 点击左侧的 btn:[base fork] 按钮，在下拉框中选择你的复刻(fork)的wiki仓库。
|
|
|
+. 点击 "`compare across forks`" 超链接。
|
|
|
+. 点击右侧的 btn:[head Fork] 按钮，在下拉框中选择官方wiki仓库(jMonkeyEngine/wiki)。
|
|
|
+. 如果两个仓库中的内容并不完全相同，将会出现一个绿色的 btn:[Create pull request] 按钮。点击这个按钮来更新你的wiki仓库。
|
|
|
+. 使用 Atom 来执行 Pull 命令，更新你的本地 wiki 文件。
|
|
|
+
|
|
|
+[IMPORTANT]
|
|
|
+====
|
|
|
+作为非项目成员，当你需要从官方wiki仓库更新内容到你的个人wiki仓库时，使用 Github 在线
|
|
|
+更新；当你需要从个人wiki仓库更新本地文件时，使用 Atom 执行 Pull 命令。
|
|
|
+====
|
|
|
+
|
|
|
+== 推送改动
|
|
|
+
|
|
|
+.项目成员
|
|
|
+作为wiki项目成员，你可以使用 Atom 来执行 Push 命令。
|
|
|
+
|
|
|
+.非项目成员
|
|
|
+先把本地改动推送到你的个人wiki仓库，再向官方wiki仓库发起合并请求：
|
|
|
+
|
|
|
+. 登录 Github，进入你的个人 wiki 仓库页面。
|
|
|
+. 点击页面上方的 btn:[New Pull Request] 按钮。
|
|
|
+. 注意：jMonkeyEngine/wiki 仓库位于左侧，你的个人wiki仓库位于页面右侧。
|
|
|
+. 点击绿色的 btn:[Create pull request] 按钮，输入一个简洁、有意义的标题，并在
|
|
|
+`commit` 框填写提交请求的理由和改动的内容，然后再次点击 btn:[Create pull request] 按钮。
|
|
|
+
|
|
|
+[IMPORTANT]
|
|
|
+====
|
|
|
+作为非项目成员，当改动发生在官方wiki仓库和你的个人wiki仓库之间时，使用 Github 在线
|
|
|
+提交PR。当改动发生在本地wiki文件和你的个人wiki仓库之间时，通过 Atom 推送改动。
|
|
|
+====
|
|
|
+
|
|
|
+== Wiki 模板
|
|
|
+
|
|
|
+为了让事情变得更简单一点，你可以创建 wiki 模板，用来生成自己的 wiki 页面。首先你需要安
|
|
|
+装 `*file-templates*` 插件。选择菜单 `menu:File[Settings>Install]` 打开安装界面，
|
|
|
+搜索 "`template`" 即可找到这个插件。
|
|
|
+
|
|
|
+. 安装完毕后，在 `命令面板` (kbd:[ctrl]+kbd:[shift] +kbd:[P] 或 `menu:Packages[Command Palette>Toggle]`) 中输入 "`file`" 。
|
|
|
+. 点击 btn:[File Templates: New Template] 按钮。
|
|
|
+. 在 `Template Name` 栏中，输入 `Jme3 Wiki Template`，然后点击 btn:[Create] 按钮。
|
|
|
+. 在 `命令面板` 中输入 "`file`" 并点击 btn:[File Templates: Update Template] 按钮。
|
|
|
+. 如果这是你的第一个文件模板，它会自动打开。如果不是，选择你刚才创建的 `Jme3 Wiki Template` 并点击 btn:[Edit Template] 按钮。
|
|
|
+. 复制下面的文本并粘贴到模板的页头位置。
|
|
|
++
|
|
|
+[source,subs="+macros"]
|
|
|
+----
|
|
|
+= 请输入文档标题
|
|
|
+:author: @author@
|
|
|
+:revnumber:
|
|
|
+:revdate: @timestamp@
|
|
|
+:relfileprefix: 请输入 asciidoc 目录的路径 ../../
|
|
|
+:imagesdir: 请输入 images 目录的路径 ../..
|
|
|
+:experimental:
|
|
|
+ifdef++::++env-github,env-browser[:outfilesuffix: .adoc]
|
|
|
+----
|
|
|
+. 完成后，关闭模板文档。然后会弹出对话框询问是否保存，点击 btn:[Yes] 按钮。
|
|
|
+
|
|
|
+现在你可以使用自己的文档模板来创建 wiki 文档了。打开 `命令面板` 并搜索 "`file`"，然后选
|
|
|
+择 btn:[File Templates: New File]。
|
|
|
+
|
|
|
+[TIP]
|
|
|
+====
|
|
|
+如果想要编辑模板，可通过 `命令面板` (kbd:[ctrl]+kbd:[shift] +kbd:[P]) 输入 "`file`" 然后选择 +
|
|
|
+`menu:File Templates: Update Template[Jme3 Wiki Page>Edit Template]`
|
|
|
+
|
|
|
+编辑后保存即可。
|
|
|
+====
|
|
|
+
|
|
|
+更多请查阅:
|
|
|
+
|
|
|
+<<zh-Hans-CN/wiki/wiki_header#,Wiki页头分析>>
|
|
|
+
|
|
|
+
|
|
|
+== Atom 代码片段
|
|
|
+
|
|
|
+
|
|
|
+[quote, Atom Flight Manual: Snippets]
|
|
|
+Snippets are an incredibly powerful way to quickly generate commonly needed code syntax from a shortcut.
|
|
|
+
|
|
|
+使用 Atom 作为 wiki 编辑器的好处之一，来源于 Atom 的代码片段(link:http://flight-manual.atom.io/using-atom/sections/snippets/[Snippets])功能。
|
|
|
+你可以在 `命令面板` (kbd:[ctrl]+kbd:[shift] +kbd:[P] or `menu:Packages[Command Palette>Toggle]`)
|
|
|
+中搜索 "`snippets`" ，然后点击 btn:[Snippets: Available] 按钮查看当前文档可用的代码片段清单。
|
|
|
+
|
|
|
+AsciiDoc 插件为 Atom 增加了强大的功能，但它依然不能满足全部 AsciiDoctor 语法。你可以通
|
|
|
+过自定义代码片段(snippets)来强化 Atom 的功能，下面我将为你展示第一个代码片段。只需要把下
|
|
|
+面的内容复制粘贴到你的 "`snippets.cson`" 文件中保存即可。你可以通过菜单
|
|
|
+ menu:File[Snippets] 打开这个文件。
|
|
|
+
|
|
|
+[source]
|
|
|
+----
|
|
|
+'.source.asciidoc':
|
|
|
+ '内部文件引用连接':
|
|
|
+ 'prefix': 'xref'
|
|
|
+ 'body': '<<${1:path/to/wiki/page}#,${2:自定义标签}>>'
|
|
|
+----
|
|
|
+
|
|
|
+然后，在文档中输入 kbd:[xref] 并点击 kbd:[Tab] 键，即可插入一条内部文件引用连接。完成后，你可以使用 kbd:[Tab] 键来切换参数。
|
|
|
+
|
|
|
+你可以通过提交新的代码片段来帮助 jMonkeyEngine 社区。使用你的编辑器来修改 <<wiki/atom_snippets#,Atom Snippets>> 文档即可。
|
|
|
+在做出任何改动之前，请先在 link:https://hub.jmonkeyengine.org/[jMonkeyEngine 官方论坛]
|
|
|
+的 "`Documentation`" 话题下发帖讨论，这样其他人才能了解可能的改动，并对你的代码片段进行测试。
|
|
|
+
|
|
|
+'''
|
|
|
+下一步，
|
|
|
+
|
|
|
+* 阅读 Wiki link:https://github.com/jMonkeyEngine/wiki[README] 页面.
|
|
|
+* 添加 link:http://asciidoctor.org/docs/user-manual/#introduction-to-asciidoctor[Introduction to Asciidoctor] 到你的收藏夹，你会经常查看它的。
|
|
|
+* 添加 link:https://atom.io/docs[Atom Docs] 到你的收藏夹。
|
|
|
+* 添加 link:http://flight-manual.atom.io/[Atom Flight Manual] 到你的收藏夹。
|
|
|
+* 添加 link:http://rogerdudler.github.io/git-guide/[git - the simple guide] 到你的收藏夹。
|
|
|
+* 开始为 Wiki 贡献内容。
|
yan