用户手册编写说明

1 文档平台介绍

Gitbook 是用 Nodejs 编写的电子书编写平台，支持 Markdown 和 AsciiDoc 两种语法，可以输出为 HTML、PDF 和 eBOOk 等格式的电子书，与 git 结合可以很方便地进行文档的协作编辑。 协作者可以使用 git 管理提交修改，git 服务器则负责进行 merge 提交，并发布文档。

2 编写环境配置

现在的用户手册 Repo 在 code.ihep.a.cn 上, 需要有 code.ihep.ac.cn 的账号和权限才能下载， 没有访问权限的情况可 发邮件 申请添加。

2.1 Markdown 编辑器

下面列出了一些各平台上比较常用的 Markdown 编辑器。

2.1.1 全平台

  • VS Code: 微软开发的开源编辑器，安装 markdown 插件使用
  • Typora: Windows 平台上非常好用的编辑器
  • Sublime Text: 商业软件，可免费试用
  • Atom: Github 出品的编辑器，功能强大
  • Yu Writer: 漂亮好用的 Markdown 写作工具
  • Inkdrop: 商业软件， 支持丰富插件
  • 作业部落: 作业部落出的客户端
  • Laverna： 支持 Dropbox 同步, 具有加密功能

2.1.2 Windows

2.1.3 Linux

2.1.4 macOS

macOS 下的很多是收费软件。

  • Ulysses：收费软件，支持 macOS, iPhone, iPad
  • MWeb：收费软件
  • Bear：收费软件
  • Mou: 现已收费
  • MacDown：开源免费
  • Paper：有内购功能，免费版支持 markdown

2.2 git 使用环境

2.2.1 Windows

下面就简单介绍一下 VS Code + git for Windows 的配置

安装 Git for Windows。

git-step-1
git-step-2

选择使用 Visual Studio Code 作为 Git 的编辑器, 若要用 Typora 则不用管：

git-step-3

可以安装额外的 Unix 工具：

git-step-4

换行符的问题， 选择第一个：

git-step-5

打开 Git-Bash， 就可以运行 code file.md 用 VS Code 来打开 Markdown 文件了。

VS Code 要能预览 Markdown 文件， 要安装插件， 可以安装 Auto-Open Markdown Preview 来实现。

安装完 Git for Windows 和 Visual Studio Code 后， 在 VS Code 里进行设置，按 Ctrl + , 修改 git.path 为 安装路径，如 C:\Program Files\Git\bin\git.exe， 则为 "git.path": "C:\\Program Files\\Git\\bin\\git.exe" ：

vs-code-git

下面介绍一下 Typora + Git for Windows 的配置。

在 控制面版-> 系统-> 系统信息 -> 环境变量 中，修改 Path 变量，添加 Typora 安装路径

tyopra-step-1
tyopra-step-2
tyopra-step-3

之后，就可以在 git-bash 中 运行 touch file; Typora.exe file.md 打开已有文档了。在 ~/.bashrc 中 加入如下别名

alias ee="Typora.exe"

然后 source ~/.bashrc，就可以直接运行 ee file.md 编辑文档了。

2.2.2 Linux

默认情况下，都安装了 git。如果没有也很方便从仓库中进行安装：

#### Debian/Ubuntu
$ sudo apt install git
#### Fedora/CentOS
$ sudo yum install git
#### OpenSUSE
$ sudo zypper in git

2.2.3 macOS

若 macOS 开启了开发者模式，应该已经有 git 了。

2.3 ssh 环境配置

在 ~/.ssh/config 中设置文档服务器的别名，这一步很重要，没有这个文件则创建一个。

Host code
    Hostname code.ihep.ac.cn
    User git
    Port 22
    Identityfile ~/.ssh/id_rsa

此处的 ~/.ssh/id_rsa 为 个人的密钥，并且个人公钥 ~/.ssh/id_rsa.pub 已经添加到 Code 平台 的个人 SSH Keys (点击) 中，注意 ~/.ssh/config 权限要设为 600, ~/.ssh/id_rsa 设置为 400。

2.4 git 配置文件

git 在配置文件为 ~/.gitconfig， 没有这个文件则可以创建一个，可以在里面加入一些 alias，重要的是 name 和 email 这两项，将这两个变量改成自己的，没有这两项极可能会报错。 不设置 git alias 也没问题。

[user]
    name = Bob
    email = bob@mail

[alias]
    a = add .
    br = branch
    ci = commit -m
    co = checkout
    df = diff
    dump = cat-file -p
    last = log -1 HEAD
    pl = pull
    ps = push
    st = status
    type = cat-file -t

3 文档编写流程

每人在自己的 个人分支 下面编写文档，将改动后的个人分支 commit 后 push 到服务器. 服务器会进行后续的工作。在此之前, 确认 你已经做好 2.3 ssh 环境配置 小节, 并能够访问 manual/manual_source, 初始登录 Code 平台等无权访问的情况, 请 发邮件 说明情况.

3.1 Clone 用户手册仓库

从 git 服务器上 clone 整个用户手册仓库:

### clone gitbook repo
$ cd ~/; git clone code:manual/manual_source;
$ mv manual_source book && cd book

3.2 新建个人分支

我们的编写都是在个人分支下进行的。比如我们要新建一个 bob 的个人分支:

### create own branch: bob
$ git branch bob && git checkout bob

如果 已经在别的地方做了修改 或 其他人修改了你负责的部分 并提交到了服务器，需要在本地先进行 pull：

$ git pull

3.3 编写文档

Markdown 使用方法可参考前面的 Markdown 语法. 使用适合的编辑器编写文档. 编写文档之前, 最好等拉取最新的修改, 然后进行编写.

3.4 提交发布

在编写好文档后，需要 commit 并 push 本地人个分支到服务端个人分支，服务端会自动将个人分支 merge 到 master 分支并构建发布更新后的手册。

### Make sure you are at your branch instead of master
$ cd ~/book
$ git branch
* bob
  master
$ git add . --all
$ git commit -am "commit message"
# push your branch bob to remote server
$ git push -u origin bob
...

push 之后服务器会自动进行后续流程。 可以写一个 hook, 让提交更方便。

$ cd ~/book/.git/hooks/
$ branch=$(git branch | awk '/\*/{print $2}')
$ cat << EOF >> post-commit
echo "committed local files, and now start to push local commit to remote branch $branch"
git push -u origin $branch
echo "finished pushing local commit to remote branch $branch and published the newer user manual "
EOF
$ chmod +x post-commit

之后就可以在 commit 之后自动进行 push 操作了, 如下所示：

auto_push

如果提交 commit 之后, 网页没有修改, 可能是 有冲突, 需要修改冲突后再提交.

3.5 撤销更改

如果在提交了更改后，发现有些更改是有问题的。可以下次更改回来，也可以撤销之前的提交。

### Usage:
$ git revert your-branch
### e.g.
$ git revert bob
...

4 文档编写规范

  1. 文档分为中英两部分，分别在 en、zh 两个目录下，文档结构相同，图片可通过相对路径复用。
  2. 每一小节标题为一号标题 (每一个 Markdown 文件有一个一号标题)。
    # 小节标题为一号标题
  3. 一级标题后是目录,需要加上如下内容：
    <!-- toc -->
  4. 每一小节分章节为二号标题，章节下面分的小标题为三号标题，以此类推。
    ## 小节分章节是是二号标题
### 章节再分为三号标题
#### 再有需要可以四号标题
  5. 章节标题加上数字序号, 如 2.1.1 这样.
  6. 一级标题和二级标题间除了 <!--toc--> 不能有其他内容.
  7. 正文用普通字体、黑色，警告字体颜色用 红色。
    警告用 <span style="color:red">红色</span>
或者用 <font color="red">红色</font>
  8. 强调内容用 *倾斜*-倾斜、**加黑**-加黑、***倾斜加黑*** - 倾斜加黑、~~划掉~~-划掉。
  9. 代码用代码块，由两行三个反引号上下夹起来。
  10. 有序列表 用来表示步骤等，无序列表 用来表示枚举等。
  11. 警告，通知等引用块、消息块。
    消息
> **[info] For 消息**
警告
> **[warning] For 警告**
危险警告
> **[danger] For 危险**
成功
> **[success] For 成功消息**
  12. 英语版本标题首字母大写(??)。
    # User Manual
## User Manual Part I

这里 是一个文档样例，可以右键点击另存为下载查看。

results matching ""

    No results matching ""