5. 为本文档提供帮助

文档位于自己的源树中。我们将从分叉和克隆CouchDB文档GitHub镜像开始。这将允许我们通过pull请求将贡献发送到CouchDB。

如果你还没有一个GitHub帐户,现在是一个很好的时机,他们是免费的。如果你不想使用GitHub,我们下次会介绍一些其他的回馈方式。

去https://github.com/apache/couchdb-documentation然后单击右上角的“fork”按钮。这将在GitHub帐户中创建一个CouchDB分支。如果你的账户是 username ,你的叉子住在https://github.com/username/couchdb-documentation。在标题中,它告诉我我的“GitHub克隆URL”。我们需要复制并启动终端:

$ git clone https://github.com/username/couchdb-documentation.git
$ cd couchdb-documentation
$ subl .

我正在我最喜欢的编辑器中打开整个CouchDB文档源代码树。它给出了常见的目录列表:

ebin/
ext/
.git/
.gitignore
images/
LICENSE
make.bat
Makefile
NOTICE
rebar.config
src/
static/
templates/
themes/
.travis.yml

文档源位于 src ,您可以安全地忽略所有其他文件和目录。

首先,我们应该确定在文档中要在哪里记录这些内容。我们可以看穿http://docs.couchdb.org/en/latest/寻找灵感。这个 JSON Structure Reference 看起来是写这篇文章的好地方。

当前的状态主要包括描述JSON结构的表(毕竟,这是本章的标题),但是一些关于数字表示的文章并没有什么坏处。为了将来的参考,由于线程中的主题包括视图和视图中的不同编码(与存储引擎相反),我们应该记住在视图文档中也做一个注释,但是我们将留待以后讨论。

让我们尝试查找生成该文件的源文件http://docs.couchdb.org/en/latest/json-structure.html--我们很幸运,在 share/doc/src 我们找到文件了 json-structure.rst . 这看起来很有希望。 .rst 表示重组文本(请参见http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html对于标记引用),这是一种ASCII格式,用于编写文档,在本例中是文档。让我们看看打开它。

我们看到一些附加格式的ASCII表,看起来都像最终的HTML。到目前为止很容易。现在,让我们把这件事再加上一点。我们可以担心以后会安排得更好。

我们从增加一个新的标题开始:

Number Handling
===============

现在我们将粘贴到该线程的其余主电子邮件中。它主要是文本,但包含一些代码列表。让我们把它们标记起来。我们转过来:

ejson:encode(ejson:decode(<<"1.1">>)).
<<"1.1000000000000000888">>

进入:

.. code-block:: erlang

    ejson:encode(ejson:decode(<<"1.1">>)).
    <<"1.1000000000000000888">>

我们将跟随其他代码示例。我们转身:

Spidermonkey

$ js -h 2>&1 | head -n 1
JavaScript-C 1.8.5 2011-03-31
$ js
js> JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
"1.0123456789012346"
js> var f = JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
js> JSON.stringify(JSON.parse(f))
"1.0123456789012346"

进入::

Spidermonkey::

    $ js -h 2>&1 | head -n 1
    JavaScript-C 1.8.5 2011-03-31
    $ js
    js> JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
    "1.0123456789012346"
    js> var f = JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
    js> JSON.stringify(JSON.parse(f))
    "1.0123456789012346"

然后跟着其他的。

我稍微清理了一下文本,但使其听起来更像是文档条目,而不是邮件列表上的帖子。

下一步是验证是否所有标记都正确。我把这个留到以后再说。现在,我们将把更改贡献回CouchDB。

首先,我们提交更改:

$ > git commit -am 'document number encoding'
[master a84b2cf] document number encoding
1 file changed, 199 insertions(+)

然后我们把承诺推到CouchDB fork::

$ git push origin master

接下来,我们返回GitHub页面https://github.com/username/couchdb-documentation然后单击“拉请求”按钮。用有用的信息填写描述,然后点击“发送请求”按钮。

我们完了!

5.1. 本文档的样式指南

对文档进行更改时,应确保遵循样式。浏览一些文件,你会发现它的风格很简单。如果您不知道您的格式是否符合样式,请自问以下问题:

Is it needed for correct syntax?

如果答案是 No. 那可能不是。

这些指导方针力求简单,没有矛盾和例外。最好的风格是遵循的风格,因为它似乎是一种自然而然的方式。

5.1.1. 指导方针

指导方针是按优先级降序排列的。

  1. 句法

    • 正确的语法总是比风格更重要。这包括配置文件、HTML响应等。

  2. 编码

    • 所有文件都是 UTF-8 .

  3. 行尾

    • 所有行以结尾 \n .

    • 没有尾随空格。

  4. 线条长度

    • 最大线长度为 80 字符。

  5. 链接

    • 所有内部链接都是相对的。

  6. 缩进

    • 4 空间。

  7. 标题

    • 文件中最高级别的标题已结束并用下划线 = .

    • 较低级别的标题用以下字符按降序加下划线:

      = - ^ *  + # ` : . " ~ _
      
    • 上方和下划线与标题长度匹配。

  8. 空行

    • 文件末尾没有空行。

    • 列表可以用空行分隔每个项目。