2.1. 文档制作简介

该手册采用 reStructuredText 标记语言( Markup Language )撰写, 使用 Sphinx 进行发布.

2.1.1. 标记语言简介

你可能觉得标记语言是个新名词, 然而你大错特错, 如果我说 HTMLLatex 也是标记语言, 前者用于创建网页, 后者用于排版文档书籍, 你可能就知道一点了.

简而言之, 标记语言就是特定的标记符号集合, 每个特定标记符可以实现特定的功能(自己总结的), 如倾斜、加粗、连接、引用等等, 如在reStructureText或者Markdown中, 使用星号括住文本, 可将文本渲染成斜体或粗体, 即 *我变斜了* 被渲染成 我变斜了, **我变粗了** 被渲染成 我变粗了 .

2.1.1.1. Markdown标记语言

Markdown设计哲学是易读(easy-to-read)易写(easy-to-write), 是一种轻量级标记语言, 之所以称为轻量级是因为其标记符号集合较小, 容易记住和使用. Markdown标记语言, 如今被越来越多的写作爱好者和撰稿者广泛使用, 也被大多数现代网站所采用, 如 GitHubStackOverflow简书CSDN有道云笔记Gitblog 等等. 此外, 很多开源项目的自述文件 README.md 就是采用Markdown语言编写的.

Markdown的语法手册可以参见:

由于Markdown的语法简单, 使得其共功能有限, 因而有了基于Markdown的各种语法扩展, 这里就不再细说, 有兴趣地话自行了解.

2.1.1.2. reStructuredText标记语言

reStructuredText 是比Markdown功能更为强大但语法也更为复杂的一种标记语言. 配合Sphinx使用, 可以撰写渲染排版出优美的文档, 且输出格式丰富. 两者的介绍分别见: reStructuredText简明教程Sphinx简明教程 .

2.1.1.3. 标记语言的优点

标记语言的撰写很简单, 不需要很高大上的IDE, 只需要一个能够编辑文字的文本编辑器即可, 完全可以只用Windows系统的“记事本”或者Linux上的“vi”来完成撰写. 这样的类似代码的语言, 很容易使用诸如Git这样的版本控制系统进行管理!可以总结出以下优点:

  • 专注于文本内容而不是排版样式

  • 兼容所有文本编辑器与字处理软件

  • 渲染导出格式丰富, 如HTML、PDF, 借助一些工具还可以导出Latex、epub等文件

  • 可以使用Git等版本控制系统管理文章版本

  • 可读、直观、易学

2.1.2. 使用标记语言需要会什么?

  • 哈哈, 首先得知道写什么

  • 嘿嘿, 你得会打字

  • 正经的, 你必须学习一门标记语言的语法(如Markdown、reStructureText)

  • 工具1:你需要一个文本编辑器(notepad、vi、Sublime Text

  • 工具2:你需要一个该标记语言的解释渲染器(太多了, 不同平台不一样, 如Sphinx)

让我们开始吧!!!