Apache OFBiz Documentation Guidelines

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

摘要

文档详细介绍了Apache OFBiz项目的AsciiDoc文档编写指南，包括文档配置、许可证要求、文件组织结构以及常见格式（如代码高亮、XML、SQL、HTML、JavaScript等）的示例。文档强调了AsciiDoc的使用规范，如如何引用外部文件、导入图片，以及如何确保文档输出的一致性。

AI总结

《Apache OFBiz Documentation Guidelines》提供了编写和组织文档的规范，主要内容包括：

### 1. **通用规则**
- **独立文档配置**：独立发布的文档（如开发手册、用户手册）需包含公共配置，确保输出格式一致。非独立文档可继承父文档的配置。
- **Gradle构建文件配置**：文档全局配置由Gradle构建文件设置，包括文档类型、版本号、图标样式等。

### 2. **Apache License Header**
- 每个`.adoc`文件必须包含Apache许可证头，放置在`//// license… ////`注释之间，以确保文档符合Apache 2.0许可协议。

### 3. **文件组织**
- 文档按组件组织，每个组件对应一个主文件，位于`src/docs/asciidoc`目录下，并包含位于`src/docs/asciidoc/_include`中的其他文件。

### 4. **包含文件**
- 使用标签标记需要包含的内容，例如：

  include::resource/article.adoc[tags=tagname]

### 5. **图片导入**
- 图片可通过`image::`语法导入，支持HTML和PDF输出。图片路径需在文档头配置中指定。
- 内联图片使用`image:`语法。

### 6. **代码格式**
- 支持多种语言的代码高亮（如Java、Groovy、XML、JSON、SQL、HTML等），并提供代码块格式化和编号功能。

### 7. **其他资源**
- 推荐参考：
- [Asciidoc官方用户指南](http://asciidoc.org/userguide.html)
- [Asciidoc作者指南](https://asciidoctor.org/docs/asciidoc-writers-guide/)
- [Asciidoc快速参考](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/)
- [Asciidoc推荐实践](https://asciidoctor.org/docs/asciidoc-recommended-practices/)

### 8. **文档编写团队**
- 如有兴趣参与文档编写，请参考[Apache OFBiz文档团队](https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Documentation+Team)了解更多组织信息和贡献方式。