# 关于编写 "描述主体结构预览说明" 的规范

1. 主体结构预览

    一般以 `tree` 命令进行获取目录结构进行展示所需要描述的预览内容。

2. 对主体结构中的内容单独说明
    
    并使用所用语言进行非侵入式独立描述，而不是在代码中填充说明与注释。
    
    在单行描述中，尽量不超过您认为最大的字符数量宽度，可以收缩内容的重要性。

    在此种说明文档中，尽量使用您所描述的对象支持的代码注释，而不是以白底黑字进行描述。

    对于规范的全部：主体结构 + 单独内容中进行简单(而不是简少)的说明。

一个简单的例子，例如: 有关项目源代码结构的预览说明

- 项目结构预览

    ```
    .
    ├── assets
    ├── debian
    ├── DOCS
    ├── patchs
    ├── src
    ├── tool
    └── translations

    10 directories, 9 files
    ```

- 来自 debian 目录的说明

    ```shell
    # 将此项目进行 debian 的标志，基于 debian 系列的发行版可对包含
    # 此种目录的开源项目进行构建 deb 软件包。

    # 1. 构建软件包(打包)
    # 执行 dpkg-buildpackage 命令以尝试构建此软件包
    dpkg-buildpackage
    # 如果构建将会在上级目录中产生一个 deb，而源代码目录不会有任何变化。
    
    # 如果出现以下内容可忽视，仅需要查看是否已成功构建软件包:
        # gpg: 已跳过 ""： 无效的用户ID 
        # gpg: ...: clear-sign failed: 无效的用户ID
        # dpkg-buildpackage: error: failed to sign .dsc file
    ```

- 来自 patchs 目录的说明

    ```shell
    # 一种用于可扩展的补丁，主要目的是为项目提供可选的应用方案，而不是直接堆砌到
    # 当前项目的分支中。您可以认为所有分支都是主线分支。
    # 例如:
        # 主线稳定分支: master
        # 主线开发分支: dev
        # 主线其它:    ...

    # 注意:
    #   当您认为您所提交的内容并不会为主线带来 bug fix 之类的内容，请使用补丁。
    #   当您所提交的内容会带来不可预知的问题的时候，或会改变目前主线的开发模式时，
    #   此种方式可确保您提交的方案可被任意时间被弃用，而不是由其它维护者耗费精力
    #   去试图移除您提交的内容，而不是等待由提交者进行新的维护。
    ```

- 来自其它的内容...可随时由任何人进行补充


- 一些在关此种预览描述的文档

    ```shell
    # 此种描述还将出现在 `src/README.md` 的描述中。
    # 当然，我预期会由其它维护者进行移动到 `DOCS` 之下。
    
    # 另外在 `patchs/zinface-community-cmake-build-system.patch` 补丁文件中，
    # 也随附过一个简要的文档内容，而它是记录了 `Spark` 为名的构建模式。
    
    # 在未应用此补丁时，将不会出现在任何地方。
    ```
    