Apache OFBiz Documentation Guidelines

• 语言: 英语
• 格式: .pdf
• 来源: ofbizextra.org

摘要

文档提供了Apache OFBiz项目文档编写指南，包括配置、FAQ和 glossary的编写、图片的导入、代码的格式化以及遵循Apache许可协议的要求。文档强调了使用Asciidoc进行编写，并提供了具体的配置示例和代码高亮支持。

AI总结

### Apache OFBiz 文档指南总结

#### 1. 引言
- 该指南为 Apache OFBiz 项目提供风格和格式的通用指导，旨在统一文档编写规范。
- 提供了部分功能和格式选项的示例，供文档编写者参考。
- 主要参考资源包括 Asciidoc 官方指南、写作指南和快速参考文档。

#### 2. 通用规则
- **文档配置**：独立发布的文档（如开发手册、用户手册）需包含统一配置，确保输出格式一致。非独立文档可继承父文档的配置。
- **配置项**：
- 作者信息
- 图片目录定义
- PDF 渲染配置（如标题 Logo、代码高亮器）
- 全局配置（如文档类型、版本号、图标样式等）。
- **文件组织**：每个组件对应一个主文档，位于 `src/docs/asciidoc` 目录，并包含相关文件。

#### 3. 文本编写规范
- **FAQ 和 glossary**：
- 使用带 ID 的列表形式编写，支持内部链接。
- 每个术语表条目 ID 采用大写，空格替换为 `_`。
- **部分文件包含**：使用标签标记需要包含的内容，并通过指定标签包含文件。

#### 4. 图片导入
- **HTML 输出**：图片路径需指定 `images/` 文件夹，格式为 `image::图片路径[图片描述]`。
- **PDF 输出**：需在文档头配置图片路径，图片将自动调整大小。
- **内联图片**：使用 `image:` 宏，格式为 `image:图片路径[图片描述]`。

#### 5. 代码格式化
- 支持多种编程语言的代码高亮，包括 Java、Groovy、XML、CSS 和 JavaScript。
- 示例：
- Java 代码：

    public class Foo {
        public String bar;
        public String bar() {
            return bar;
        }
    }

- 带解释的代码：

    public class Foo {
        public String bar; ①
        public String bar() { return bar; ② }
    }

- ① 声明 bar 字段
- ② 返回 bar 值

#### 6. Apache 许可证头
- 每个 `.adoc` 文件需包含 Apache 许可证头，格式如下：

  /// Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements...

#### 7. 文件组织
- 文档结构：

  src/
    - docs/
      - asciidoc/
        - _include/
        - images/
        - {componentName}/

- 每个组件对应一个主文档，包含相关子文件。