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'
[main a84b2cf] document number encoding
1 file changed, 199 insertions(+)

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

$ git push origin main

接下来，我们返回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. 空行

    • 文件末尾没有空行。
    • 列表可以用空行分隔每个项目。