Apache OFBiz Documentation Guidelines 22.01

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

摘要

The document provides guidelines for writing documentation for the Apache OFBiz project. It covers common configurations for standalone guides, FAQ and glossary creation, image importation, and code formatting using Asciidoc. Key configurations include setting the document type, version, and icon settings. The guidelines also include examples for Java, Groovy, XML, CSS, and JavaScript code formatting, as well as instructions for including images and maintaining a glossary.

AI总结

# Apache OFBiz 文档编写指南总结

## 1. 介绍
- 本指南作为 Apache OFBiz 项目文档的风格指南，提供了一些功能和格式选项的示例，旨在帮助编写一致且高质量的文档。
- 参考资料包括官方 Asciidoc 用户指南、Asciidoc 作者指南等。

## 2. 一般规则
### 2.1 文档配置
- 独立发布的文档（如开发手册、用户手册）应包含相同的配置，以确保输出格式一致。
- 配置包括：
- 图片目录定义
- PDF 渲染配置
- 使用 Rouge 作为代码高亮器
- 全局配置（如 `doctype`、`revnumber`）在 Gradle 构建文件中设置。

### 2.2 Apache 许可证头
- 每个 `.adoc` 文件必须包含 Apache 许可证头，放在 `/// license...///` 之间。

### 2.3 文件组织
- 每个应用有一个主文档文件，位于 `src/docs/asciidoc` 目录，包含其他文件（如 `src/docs/asciidoc/_include`）。
- 组件目录结构示例：

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

## 3. 如何编写 FAQ 或 Glossary
- 使用带标签的列表编写 FAQ 和 Glossary。
- FAQ 和 Glossary 项应有 ID，以便内部链接。
- 示例：

  [#faq_entry_1] FAQ 进入 1:: 这是示例 FAQ 的第 1 项。

## 4. 导入图片
- 使用 `image::` 宏导入图片。
- HTML 输出中可添加 alt 文本，图片位置需在文档头配置。
- 示例：

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

## 5. 代码格式化
- 使用 Asciidoc 和 Rouge 支持多种编程语言的代码高亮。
- 示例包括 Java、Groovy、XML、CSS 和 JavaScript 代码块。
- 支持带编号和带注释的代码块。

## 6. 总结
- Apache OFBiz 文档编写指南提供了详细的配置、格式和组织规范，确保文档的一致性和可读性。
- 关键点包括文档配置、许可证头、FAQ/Glossary 编写、图片导入和代码高亮等。