Apache OFBiz Documentation Guidelines Release 18.12

# Apache OFBiz Documentation Guidelines (Release 18.12) ## Document Configuration - **Common Configuration**: Documents published as standalone guides must include common configuration to ensure consistent output. This is not required for documents embedded in parent documents, as they inherit configurations. - **Global Configurations**: - `imagesdir`: Specifies the image directory (e.g., `./images`). - `title-logo-image`: Defines the title logo image for PDF rendering (e.g., `image::OFBiz-Logo.svg`). - `source-highlighter`: Uses Rouge for code syntax highlighting. - **Gradle Build File Settings**: - `doctype`: Set to `book`. - `icons`: Set to `font`. - `sectnums`: Enabled for section numbering. - `toc`: Enabled for table of contents with `toclevels` set to `5`. ## Document Structure and Styling - **Headings and Tags**: Use heading counters and tags to organize content. For example: ```adoc # end::tagname[] 12include::resource/article.adoc[tags=tagname] ``` - **Examples**: Use `example` blocks for code and configuration examples. ## Image Import - **Image Syntax**: - For HTML: `image::OFBiz-Logo.svg[Apache OFBiz Logo]`. - For inline images: `image:OFBiz-Logo.svg[Apache OFBiz Logo, width=40%]`. - **Image Placement**: Images are placed in the `images` directory, as defined in the document header. ## Code Formatting - **Syntax Highlighting**: Supports syntax highlighting for Java, Groovy, XML, CSS, JavaScript, JSON, SQL, and HTML. - **Code Blocks**: - Use `source` blocks with language specification (e.g., `[source,java]`). - Numbered code blocks for better readability. - Inline comments and annotations for code explanation. ## Additional Content - **XML, CSS, JavaScript, and JSON**: Include examples of XML documents, CSS styles, JavaScript functions, and JSON objects. - **SQL and HTML**: Provide examples of SQL queries and HTML structures. This document provides a comprehensive guide for formatting and structuring documentation for the Apache OFBiz project, ensuring consistency and clarity.