Apache OFBiz Documentation Guidelines Release 18.12

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

摘要

文档详细介绍了Apache OFBiz项目的文档编写规范，包括配置选项、文件命名规则、许可证头要求、图像导入方法以及键盘快捷键的使用。文档强调了统一风格和格式的重要性，并提供了具体的实施指南和示例。内容涵盖从基本配置到高级功能的各个方面，旨在确保文档的一致性和可读性。

AI总结

### Apache OFBiz 文档指南总结

#### 1. 介绍
- 本指南为 Apache OFBiz 项目提供风格规范和示例，旨在帮助编写一致且高质量的文档。
- 主要参考资源包括：
- [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/)

#### 2. 通用规则
- **文档配置**：
- 独立发布的手册（如开发者手册、用户手册）需包含通用配置，确保输出格式统一。
- 配置示例：

    :imagesdir: ./images
    :title-logo-image: image::OFBiz-Logo.svg[Apache OFBiz Logo, pdfwidth=4.25in, align=center]
    :source-highlighter: rouge

- 全局配置选项（如 `doctype`、`icons`、`sectnums` 等）在 `build.gradle` 文件中设置，供参考。
- **版权声明**：
- 每个 `.adoc` 文件必须包含 Apache 许可证头，格式如下：

    /// Licensed to the Apache Software Foundation...
    /// ```
- **文件命名**：
  - 文件名采用小写，后缀为 `.adoc`。
  - 模块化文件命名规则：
    - 主要文件：`componentName.adoc`（如 `humanres.adoc`）。
    - 子文件：`componentName-subject.adoc`（如 `hr-intro.adoc`）。
  - 命名需保持一致性，例如 `[shortname]-intro`、`[shortname]-faq` 等格式。

#### 3. 其他内容
- **FAQ 或术语表**：建议在文档中包含常见问题解答或术语表。
- **标签使用**：
  - 使用 `include::resource/article.adoc[tags=tagname]` 导入文件。
  - 文本中需添加 `# end::tagname[]` 标记。
- **图片导入**：
  - 使用 `image::` 导入图片，例如：

image::OFBiz-Logo.svg[Apache OFBiz Logo, pdfwidth=3.0in, align=left]

  - 图片路径需在文档头配置中指定。
- **键盘快捷键**：
  - 使用 `kbd` 宏定义快捷键，例如：

kbd:[Alt+F11] - Toggle Full Screen Mode in the Eclipse IDE

- **内联图标**：
  - 使用 `icon` 宏添加图标，例如：

icon:comment[] - 这是一个评论图标
icon:file[] - 这是一个文件图标

  - 需在文档头添加 `:icons: font` 指令以启用 Font Awesome 图标。

#### 4. 总结
- 本指南提供了 Apache OFBiz 文档编写的标准和示例，涵盖配置、命名、版权声明、内容组织及格式化等多个方面。
- 遵循指南可确保文档的一致性、可读性和专业性，便于维护和扩展。