WIP: Add contributing in appendix

source/appendix/contributing/building.rst

@@ -0,0 +1,24 @@
+编译文档
+=========
+
+在下载项目源码后，需要安装 Sphinx 生成HTML，若需要生成PDF还需要安装TeXLive 2017。
+
+安装TeXLive 2017
+------------------
+
+TeXLive 是由国际 TeX 用户组（TeX Users Group，TUG）整理和发布的 TeX 软件发行套装，包含与TeX系统相关的各种程序、编辑与查看工具、常用宏包及文档、常用字体及多国语言支持。
+
+参考 https://blog.seisman.info/texlive-install/ 安装TeXLive 2017 并更新所有宏包至最新版本。
+
+编译文档
+--------
+
+::
+
+    $ cd SAC_Docs_zh/
+    $ make html
+    $ firefox build/html/index.html
+    $ make latexpdf
+    $ evince build/latex/SAC_Docs.pdf
+
+若编译时出现错误，请到项目主页处提交Issue。

source/appendix/contributing/documentation-layout.rst

@@ -0,0 +1,44 @@
+文档结构
+=========
+
+文档源码中核心文档及目录的结构::
+
+    .
+    |-- SAC_Docs.tex        # 主文档
+    |-- SAC_macros.tex      # LaTeX导言区
+    |-- cover.tex           # 封面页
+    |-- frontmatterIII.tex  # 废话页
+    |-- version.tex         # 版本说明
+    |-- contributor.tex     # 维护者列表
+    |
+    |-- figures             # 文档内的插图
+    |-- scripts             # 用于绘制插图的脚本
+    |
+    |-- introduction        # 简介
+    |-- basic               # SAC基础
+    |-- fileformat          # 文件格式
+    |-- data-process        # 数据处理
+    |-- graphics            # 绘图
+    |-- macros              # SAC宏语言
+    |-- call-in-script      # 脚本中调用
+    |-- libs                # 函数库的使用
+    |-- sacio               # SAC I/O
+    |-- tools               # 相关工具
+    |-- tricks-and-traps    # 技巧与陷阱
+    |-- appendix            # 附录
+    |
+    |-- commands            # 基础命令
+    |-- sss                 # SSS子程序
+    `-- spe                 # SPE子程序
+
+
+文档的结构还是比较清晰的，主文件是 ``SAC_Docs.tex`` ，每个目录基本对应一章，每个目录内的文件一般对应一节内容。
+
+除此之外，源码里还有一些其他文件：
+
+1. ``README.md`` 项目的说明文档
+2. ``Makefile`` 项目构建文件
+3. ``.gitignore`` 包含git忽略的文件列表
+4. ``.travis.yml`` travis服务的配置文件
+5. ``.texlive-minimal-installer.sh`` 为项目安装一个最小版本的TeXLive，用于travis服务中
+6. ``travis-deploy.sh`` 用于travis服务中，在生成PDF后，自动推送到项目主页的pdf分支中

source/appendix/contributing/general-guidelines.rst

@@ -0,0 +1,35 @@
+项目维护简介
+============
+
+项目简介
+---------
+
+本项目源码语言是 reStructuredText，使用 `Sphinx <https://sphinx-doc.org/>`__ 生成HTML网页，
+并借助 `<TeXLive 2017 <https://www.tug.org/texlive/>`__ 编译生成PDF。
+文档中的图片大多用 SAC 和 GMT6 绘制而成，若需要重新生成图片，则需要安装SAC、GMT6。
+
+要维护的内容
+------------
+
+本手册需要维护的部分可以分为如下几类（按由简到繁、由易到难排序）：
+
+- 错别字
+- 个别行或页面的排版问题
+- 需要解释清楚或易引起歧义的部分
+- 部分未翻译的命令，以及个别命令中未翻译的部分
+- 某些命令在不同SAC版本间的语法不兼容
+- 随着SAC新版本的发布，更新手册中相应的内容
+- 补充命令示例以及脚本示例
+- 补充其他尚未包含在手册中的与SAC相关的知识点
+- 文档结构的调整
+- 项目源码的优化
+
+对维护者的要求
+--------------
+
+一个合格的维护者应满足如下条件：
+
+- SAC 用户，对维护手册有足够的热情
+- 使用 Linux 或 macOS 操作系统
+- 拥有 GitHub 账户
+- 了解 Git 的基础知识

source/appendix/contributing/index.rst

@@ -0,0 +1,14 @@
+贡献指南
+========
+
+欢迎 SAC 中文用户参与到 SAC参考手册的维护与更新中。
+
+
+.. toctree::
+    :maxdepth: 2
+
+    general-guidelines
+    documentation-layout
+    tools
+    building
+    workflow

source/appendix/contributing/tools.rst

@@ -0,0 +1,46 @@
+GitHub, Git, LaTeX学习资源
+==========================
+
+维护本项目，必须学会使用GitHub和Git，对LaTeX不做要求。
+
+GitHub
+-------
+
+参考文档：https://www.worldhello.net/gotgithub/02-join-github/010-account-setup.html
+
+1. 注册GitHub账户
+2. 向GitHub账户中添加当前机器的SSH秘钥，以使得当前机器拥有GitHub账户的读写权限
+
+Git
+----
+
+Git是现在非常流行的版本控制软件，Linux下直接用系统自带的包管理器即可安装`git`。同时也可以安装`gitk`或者其他git的GUI软件，以方便查看git提交历史。
+
+安装完git之后需要配置全局变量::
+
+    $ git config --global user.name "Your Name"
+    $ git config --global user.email "[email protected]"
+
+参考资料：
+
+- [git简明指南](https://rogerdudler.github.io/git-guide/index.zh.html)
+- [GotGitHub](https://www.worldhello.net/gotgithub/index.html)
+- [廖雪峰的Git教程](https://www.liaoxuefeng.com/wiki/0013739516305929606dd18361248578c67b8067c8c017b000)
+- [Pro Git](https://git-scm.com/book/zh/v2)
+
+git的功能很多，维护本项目所需要的命令基本上只有::
+
+    $ git add 
+    $ git commit
+    $ git checkout -b 
+    $ git rebase 
+    $ git pull
+    $ git push
+
+LaTeX
+-------
+
+学习资源：
+
+1. https://dralpha.altervista.org/zh/tech/lnotes2.pdf
+2. https://github.com/louisstuart96/lshort-new-zh-cn

source/appendix/contributing/workflow.rst

@@ -0,0 +1,83 @@
+维护流程
+=========
+
+准备工作
+--------
+
+1. 在项目主页，点击右上角的Fork按钮，将该项目复制到你的GitHub账户下。
+   以下假定你的GitHub账户名为 ``USER``
+
+2. Clone源码到当前机器::
+
+       $ git clone [email protected]:USER/SAC_Docs_zh.git
+       $ cd SAC_Docs_zh/
+
+3. 将项目的官方repo添加为远程repo，并命名为 upstream，这样方便以后与官方repo同步进度::
+
+       $ git remote add upstream https://github.com/seisman/SAC_Docs_zh.git
+
+正式维护该项目
+--------------
+
+1. 从官方repo中拉取源码的最新版本，并合并到本地master分支，
+   以保证本地的master分支与官方master分支同步
+
+       # 切换到本地的master分支
+       $ git checkout master
+       # 获取upstream/master分支并合并到本地master分支
+       $ git pull upstream master
+
+2. 新建单独的分支，在分支中修改文档并提交。假定分支名为 ``mydev``\ ::
+
+       $ git checkout -b mydev
+
+3. 对文档做修改，并提交commit，此过程可以循环多次::
+
+       $ git status
+       $ git add --all
+       $ git status
+       $ git commit -m "此处填写本次提交的注释信息"
+
+4. 分支开发的过程中，可能upstream的官方master分支已经更新，可以经常与主干保持同步::
+
+       # 本地切换到master分支，并合并upstream的master分支的更新
+       $ git checkout master
+       $ git pull upstream master
+       # 切换到开发分支，并使得当前分支基于最新的master分支
+       $ git checkout mydev
+       $ git rebase master
+
+5. 分支开发的过程中，可能会有很多次commit，某些commit可能不那么重要，
+   可以将多个commit压缩成一个或若干个commit，这样不仅清晰，也容易管理::
+
+   $ git rebase -i master
+
+
+6. 将分支推送到远程仓库::
+
+       # 将mydev分支推送到USER的repo下
+       $ git push origin mydev
+
+7. 进入 https://github.com/USER/SAC_Docs_zh ，点击Pull Request即可提交PR
+8. seisman在收到PR后，会对代码进行审核、评论以及修改，并决定是否结束该PR
+9. 若PR已被接受，则可以删除本地和GitHub上的mydev分支::
+
+       # 切换回本地master分支
+       $ git checkout master
+       # 删除本地mydev分支
+       $ git branch -D mydev
+       # 合并upstream/master分支到本地master
+       $ git pull upstream master 
+       # 删除GitHub上的远程分支，也可以在GitHub上点击按钮删除分支
+       $ git push origin :mydev
+
+对维护的若干说明
+----------------
+
+为了简化维护流程，避免重复或不必要的劳动，请遵循如下原则。
+
+若只是对文档做简单的微调，比如修改简单的bug或typo，整理部分语句等，可以直接修改并提交PR。若需要对文档做大量修改，比如新增章节、调整文档结构等，请先到项目主页中提交Issue，由众多维护者一起讨论是否有必要做修改。
+
+若暂时不打算解决某Issue，则该Issue会有标签`Pull Request Welcomed`，维护者可以随意认领具有`Pull Request Welcomed`标签的Issue，若某Issue已经被认领，则设置标签为`In Progress`。
+
+对于已经熟练使用Git的维护者，我会将其加为合作者，即其可以将提交push到seisman的repo中，这样流程更加简单。

source/index.rst

@@ -78,4 +78,5 @@ SAC参考手册
    appendix/resp/index
    appendix/data-fetch/index
    appendix/naming-convections
+   appendix/contributing/index
    appendix/changelog