RealICQClient/Includes/CnVCL/Doc/Templates/文本文档标准格式.txt

**********************************************************************
                     CnPack For Delphi/C++Builder
                     中国人自己的免费第三方开发包
                 (C)Copyright 2001-2016 CnPack 开发组
**********************************************************************

                          文本文档标准格式规范
                            Revision 1.0.0.2
                       =========================
                        作者：周劲羽 2003.03.02


本文档为一份 CnPack 标准格式文本文档的例子，CnPack 所有正式发布的文本
格式文件都要求遵守该文档的规定。

文档包含了以下一些内容：

  * 文档头标准格式。
  * 文本的换行、空格、缩进格式。
  * 文档目录结构和项目列表格式规范。
  * 其它的格式规定。

要获得该文档的最新版本及相关内容，请访问 CnPack 开发网站：

http://www.cnpack.org

======================================================================
1. 文档说明
======================================================================

该文档所规定的内容属于 CnPack 开发包标准规范的一部分，目的在于使所有发
布的文本格式文件具有一致的外观，同时也体现了开发包的严谨性。

对文本文件而言，虽然无法设置字体、字号、对齐等格式，但通过使用 '*'、
'='、'-'、'|' 等符号以及合理地布局，同样可以获得较好的外观。

下面的内容将对文本格式做一般性的规定，总的原则是尽量使文档美观且具有较
强的可读性。


======================================================================
2. 文档头标准格式
======================================================================

所有正式发布的 CnPack 文本格式文档，都使用统一的文件头，用以标识该文档
所从属的项目名称和版权信息。本文档头部用 '*' 号围起来的那部分即当前的
标准文档头，编写时可直接从本文档中拷贝使用。

版权信息头后，是文件名称、版本、作者、日期等说明，居中放置。


======================================================================
3. 文本的换行、空格、缩进格式
======================================================================

3.1 文本换行
------------
文本内容要求使用硬回车进行换行，原则上每行宽度不应超过 70 个字符，这也
是默认设置下用“记事本”打开文本文件时可以显示的最大宽度。

段落首行可以缩进，也可不缩进，但同一文档中应该统一。如果不缩进，段与段
之间应插入空行分隔。

如果文本中引用较长的超链接，最好将地址放在单独一行中，如果一行显示不
下，可不必换行。

节与节之间应该留有空行。

3.2 使用空格
------------
在以下地方应该使用空格：

  * 汉字中间的英文单词两边应各空一格，如 Sample 例子。
  * 文本中插入单独的字符时，应使用单引号并在两边各空一格，如 '*' 字符。
  * 文本中引用数字，也应在两边各空一格，如数字 65535 的使用。
  * 小节号、项目列表符后应该留一空格。
  * 当单词、符号、数字位于段首、段尾、行首或接标点符号时，邻近的那一端
    的空格应省略。

3.3 缩进格式
------------
当文本中使用编号列表，或某一段文字整块从属于某一内容时，可使用缩进。
比如，列举例子代码：

  var
    i: Integer;
  begin
    for i := 0 to 100 do
      ...
  end;


======================================================================
4. 文档的目录层次结构
======================================================================

文档中使用半角数字来表现目录层次结构，最高一级使用 1, 2, 3 等，次级为
2.1, 2.2, 2.3 等，再次为 3.1.1, 3.1.2 等，依次类推。主节号后可跟一附点
'.'，小节号应后加一空格再接标题内容。

根据文档中目录层次级数，可使用以下的框架来显示，这一原则可灵活使用：

======================================================================
1. 第一部分
======================================================================

...

----------------------------------------------------------------------
1.1 第一节
----------------------------------------------------------------------

...

1.1.1 第一小节
--------------

======================================================================
5. 使用项目列表
======================================================================

需要使用项目列表的地方，应缩进两个字符，同一条目换行后，新行应与上一行
正文部分对齐。

一般使用 '*' 作为列表标识符，在项目列表中嵌套项目列表时，子列表可使用
'-' 作为列表符，同时应注意缩进，如：

  * 这是一个项目列表的例子，在该列表条目中嵌套了另一个子项目列表，此时
    子列表应缩进。
    - 这是一个子列表。
    - 子列表使用 '-' 来标识。
    - 子列表要求缩进。
  * 第二个条目
  * 第三个条目


======================================================================
6. 其它说明
======================================================================

另外，文本文档中请不要使用全角字符的空格。

该文档规范的制定并非限制程序员的自由，而是以保障开发包整体质量为目的，
大家习惯了自然会发现它的好处。文档中未涉及的内容，以整洁、协调为标准。

开发包最终发布的所有正式文档都将有专人进行格式整理，如果成员在编写文档
时注意一下格式，会大大减轻文档维护人员的负担。

如果您对该文档有什么建议或不同意见，请与 CnPack 项目管理员联系：

mailto:master@cnpack.org
http://www.cnpack.org