////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////
= Apache OFBiz Documentation Guidelines
The Apache OFBiz Project
:imagesdir: ./images
ifdef::backend-pdf[]
:title-logo-image: image::OFBiz-Logo.svg[Apache OFBiz Logo, pdfwidth=4.25in, align=center]
:source-highlighter: rouge
endif::[]

image:https://img.shields.io/badge/License-Apache%202.0-blue.svg[link="http://www.apache.org/licenses/LICENSE-2.0"]

== Intro

These guidelines serve as a general style guide and collection of examples of how we are documenting the project.
This is intentionally not a complete user manual, but lists the subset of functionality and formatting options we
would like to use.

For further reference and more examples see

* Official Asciidoc User Guide
footnote:[http://asciidoc.org/userguide.html]
* Asciidoc Writers Guide
footnote:[https://asciidoctor.org/docs/asciidoc-writers-guide/].
* Asciidoc Quick Reference
footnote:[https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/]
* Asciidoc Recommended Practices
footnote:[https://asciidoctor.org/docs/asciidoc-recommended-practices/]

If you would like to help out with the documentation of the project, please see the following wiki page
footnote:[https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Documentation+Team] for further information and
how we are organised.

== General rules

=== Document configuration

Documents that will be published as standalone guides (e.g. link:developer-manual.adoc[developer manual], link:user-manual.adoc[user manual]) should contain common configuration
so that the output will be generated in exactly the same way for all documents.

[NOTE]
This is not necessary for documents that will only be included as part of parent documents. In this case the documents will inherit the
configuration from the parent.

Please see below for details of the proposed configuration:

----
The Apache OFBiz Project // <1>
:imagesdir: ./images // <2>
ifdef::backend-pdf[] // <3>
:title-logo-image: image::OFBiz-Logo.svg[Apache OFBiz Logo, pdfwidth=4.25in, align=center] // <4>
:source-highlighter: rouge // <5>
endif::[] // <6>
----
<1> author
<2> global definition of the image directory
<3> begin block of configurations only for pdf rendering
<4> define the title logo image
<5> use the Rouge source code highlighter
<6> end block of configurations only for PDF rendering

The following configuration options are set globally in the Gradle build file.
They are not configured in the document itself and are listed for reference only:

.build.gradle
----
'doctype': 'book', // <1>
'revnumber': 'Trunk', // <2>
'experimental': '', // <3>
'icons': 'font', // <4>
'sectnums': '', // <5>
'chapter-label': '', // <6>
'toc': '', // <7>
'toclevels': '5' // <8>
----
<1> doctype book
<2> target release, indicates the release for which the documentation is valid
<3> allow experimental features like keyboard shortcuts
<4> make font awesome icons available
<5> number chapters and sections automatically
<6> do not prefix the chapters
<7> insert a table of contents
<8> max levels to show in the table of contents

=== Apache License Header

Each .adoc file must contain the Apache license header (put between "//// license... ////"). You can just copy the
following block:
----
////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////
----

=== file organization
There are one main file per application (located in the 'src/docs/asciidoc' directory), which include some other files
located in 'src/docs/asciidoc/_include'.

.For each component, there are these directories:
====
    src
      |- docs
          |- asciidoc
              |- _include
              |- images
                  |- ${componentName}
====

So, for include file use

  include::_include/xxxxxxx

and for image, it's necessary to add on top of main file

  :imagesdir: ./images/${compnentName}

and so include them with

  image::/xxxxxxx

During generating process images are copied on the root asciidoc/images directory

=== File name conventions

We will be implementing a consistent naming convention for the documentation content files.
Filenames should be in lower case with the extension `.adoc`.

Each guide will be named after the component / module name (e.g. humanres.adoc, accounting.adoc, manufacturing.adoc,
party.adoc etc).
Lower level files that are in the include directory will include a prefix/shortname indicating the component name,
separated by dashes (e.g `hr-intro.adoc`, `hr-glossary.adoc`, etc.)
Similar pages will have consistent naming. We will have several intro, glossary, FAQ, settings, security pages,
so the naming format will be ([shortname]-intro, [shortname]-glossary, [shortname]-faq, [shortname]-settings,
[shortname]-security etc.)

.For Human Resources this will be as follows:
====
    humanres.adoc
        |- hr-intro.adoc
        |- hr-employee-evaluations.adoc
        |- hr-glossary.adoc
        |- hr-employee-positions.adoc
        |- hr-employees.adoc
        |- hr-employments.adoc
        |- hr-performance-review.adoc
        |- hr-positions.adoc
        |- hr-qualifications.adoc
        |- hr-recruitment.adoc
        |- hr-skills.adoc
        |- hr-resumes.adoc
        |- hr-training.adoc
        |- hr-leave.adoc
        |- hr-security.adoc
        |- hr-global-settings.adoc
====


=== General formatting

* It is recommended to write one sentence per line and/or manually break the line after approximately 80 to 120 characters.
* Section titles will use asymmetric atx style +
  (e.g. `== This is an example of an Asymmetric Section Title`)
* When including another file using the `include` directive, please ensure that there is a blank line between each
  include line.


== Text formatting

=== Quoted Text

Words and phrases can be formatted by enclosing inline text with quote characters:

.Emphasized text

Word phrases enclosed in 'single quote characters' (acute accents) or _underline characters_ are emphasized.

.Strong text
Word phrases *enclosed in asterisk characters* are rendered in a strong font (usually bold).

.Monospaced text
Word phrases +enclosed in plus characters+ are rendered in a monospaced font.
Word phrases `enclosed in backtick characters` (grave accents) are also rendered in a monospaced font but in this case
the enclosed text is rendered literally and is not subject to further expansion (see inline literal passthrough).

.‘Single quoted text’
Phrases enclosed with a `single grave accent to the left and a single acute accent to the right' are rendered in single
quotation marks.

.“Double quoted text”
Phrases enclosed with ``two grave accents to the left and two acute accents to the right'' are rendered in quotation marks.

.Unquoted text
Placing #hashes around text# does nothing, it is a mechanism to allow inline attributes to be applied to otherwise unformatted text.


=== Paragraphs

You can indicate special information with an eye catching symbol. Please don't overuse this (less is more).

----
[TIP]
This is a tip or idea.
----

[TIP]
This is a tip or idea.

You can also have multiple lines and empty lines inside the paragraph using a whitespace and a plus sign:

----
[TIP]
This is a tip or idea. +
This is another idea. +
 +
More ideas...
----

[TIP]
This is a tip or idea. +
This is another idea. +
 +
More ideas...

----
[NOTE]
This is an information note.
----

[NOTE]
This is an information note.

----
[IMPORTANT]
This indicates important information.
----

[IMPORTANT]
This indicates important information.

----
[WARNING]
This is a warning or something to pay attention to.
----

[WARNING]
This is a warning or something to pay attention to.

----
[CAUTION]
This is something you should treat with caution.
----

[CAUTION]
This is something you should treat with caution.

----
[normal]
This is a Normal paragraph.
----

[normal]
This is a Normal paragraph.

----
[literal]
This is a Literal paragraph.
----

[literal]
This is a Literal paragraph.

----
[quote]
This is a Quote paragraph.
----

[quote]
This is a Quote paragraph.

----
[listing]
This is a Listing paragraph.
----

[listing]
This is a Listing paragraph.

----
[abstract]
This is an Abstract paragraph.
----

[abstract]
This is an Abstract paragraph.

----
[comment]
This is a Comment paragraph. It does not show up in the rendered text ;-)
----

[comment]
This is a Comment paragraph. It does not show up in the rendered text ;-)

----
[example]
This is a Example paragraph.
----

[example]
This is a Example paragraph.

----
[sidebar]
This is a Sidebar paragraph.
----
[sidebar]
This is a Sidebar paragraph.

----
[source]
This is a Source paragraph. See Code formatting for further examples.
----

[source]
This is a Source paragraph. See Code formatting for further examples.

.This indicates a simple description headline
This is the text for the simple description headline

.This indicates an example inside a block
====
Just a simple block example.
====

=== Keyboard shortcuts

You can also define keyboard shortcuts with the `kbd` macro.

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

The result is the following:

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

The result will be different depending on the rendering (PDF, HTML).

=== Using inline icons

You can also add the `:icons: font` directive to the top of your document, which allows you to use the icons
from http://fortawesome.github.io/Font-Awesome/icons/ directory via a macro using any of the following icon sets:

* fa - https://fontawesome.com/v4.7.0/icons (default)
* fas - https://fontawesome.com/icons?d=gallery&s=solid[Font Awesome - Solid]
* fab - https://fontawesome.com/icons?d=gallery&s=brands[Font Awesome - Brands]
* far - https://fontawesome.com/icons?d=gallery&s=regular[Font Awesome - Regular]
* fi - http://zurb.com/playground/foundation-icon-fonts-3[Foundation Icons]
* pf - https://paymentfont.com/[Payment font]

The fa icon set is deprecated. Please use one of the other three FontAwesome icon sets. +
when icon is not available in fa icon set but in an other, it's possible to give the correct set.

The generate Document process generate a INFOS message, if icon is available in an other set and it is not given.
----
icon:comment[set=far] This is a comment icon
icon:file[set=far] And a file icon
icon:battery-full[set=fas] And a battery icon
----

.The output looks like the following
[example]
icon:comment[set=far] This is a comment icon +
icon:file[set=far] And a file icon +
icon:battery-full[set=fas] And a battery icon


== Code formatting

Asciidoc and the used highlighter provide support for code syntax highlighting of several programming languages
and formats. The following are examples for code which is widely used within OFBiz.

.Java source code formatting
 [source,java]
 ----
 public class Foo {
   public String bar;
   public String bar() {
    return bar;
   }
 }
 ----

Renders to

[source,java]
----
public class Foo {
  public String bar;

  public String bar() {
    return bar;
  }
}
----

.Java source code formatting (numbered)
[source,java,numbered]
----
public class Foo {
  public String bar;

  public String bar() {
    return bar;
  }
}
----

.Java source code formatting (with explanation callouts)
[source,java]
----
public class Foo {
  public String bar; # <1>

  public String bar() {
    return bar; # <2>
  }
}
----
<1> Declares the `bar` field
<2> Returns the `bar` value


.Groovy
[source,groovy]
----
selected = UtilHttp.parseMultiFormData(parameters)
selected.each { row ->
    payment = from("Payment").where("paymentId", row.paymentId).queryOne()
    if (payment) {
        payments.add(payment)
    }
}
context.payments = payments
----


.XML document
[source,xml]
----
<author id="1">
  <personname>
    <firstname>Lazarus</firstname>
    <surname>het Draeke</surname>
  </personname>
</author>
----

.Cascading Stylesheet (CSS)
[source,css]
----
body {
    background: transparent url(/images/ofbiz_logo.png) no-repeat scroll left top;
    color: #000;
    font-family: Verdana, Arial, Helvetica, sans-serif;
    font-size: .75em;
    line-height: 1.5em;
    padding: 50px 0 0;
    bgcolor: #ffffcc;
}
----

.Javascript
[source,javascript]
----
function msg(){
    alert("Hello OFBiz");
}
----

.JSON
[source,json]
----
{
    "id": 1,
    "name": "A green door",
    "price": 12.50,
    "tags": ["home", "green"]
}
----

.Properties files
[source,properties]
----
foo = bar
----

.SQL
[source,sql]
----
SELECT * FROM FOO;
----

.HTML
[source,html]
----
<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html>
   <head>
      <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   </head>
   <body style="background-color: rgb(255, 255, 255);">
      <h1>Headline</h1>
  </body>
</html>
----


== Importing files or file includes

You can import files via the include macro.
This also works for source code includes. +
It's possible to use [listing] ---- before include to have the correct style. +
The following example imports a file formatted as Java source code.

  [source,java]
  ----
  include::resource/source.java[]
  ----

[source,java]
----
include::resource/source.java[]
----

=== Using leveloffset

Via the `leveloffset` attribute you can change the section offset, for example a `=` section will become `==` if you
add the following statement `:leveloffset: 1`.
Use `:leveloffset: 0` to reset the offset.

=== Importing files partially

It is also possible to include partial files.
For this, please mark the part of the file to be included with a tag similar to the following:

.article.adoc
----
# tag::tagname[]
This should be included!
# end::tagname[]
This text will not be included!
----

and include the file with the tagname in the brackets like this:

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

The result would be

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

=== Importing images

You can import images with
----
image::
----

For the HTML output you can add the alt text within the brackets [].
If the image is located in the images folder then the import would look like this:

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

Result:

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

Please notice that the images folder is specified in the document header configuration
and is therefore not provided here again.

The import of an image with `image::` will add the image in a new line.
If you want to add an image to be inline then use the macro `image:`

  This is just a text image:OFBiz-Logo.svg[Apache OFBiz Logo, width=40%] to show inline images.

Result:

This is just a text image:OFBiz-Logo.svg[Apache OFBiz Logo, width=40%] to show inline images.


== How to write a...

=== FAQ or Glossary

FAQ's and glossaries should be written as a labeled list.
For hyperlinking, they should also have an ID which can be linked within a list.

For example
----
<<faq_entry_1,FAQ entry 1>>
<<faq_entry_2,FAQ entry 2>>

[#faq_entry_1]
FAQ entry 1::
This is entry #1 in our example FAQ.

[#faq_entry_2]
FAQ entry 2::
This is entry #2 in our example FAQ.
----

Renders to

<<faq_entry_1,FAQ entry 1>> +
<<faq_entry_2,FAQ entry 2>>

[#faq_entry_1]
FAQ entry 1::
This is entry #1 in our example FAQ.

[#faq_entry_2]
FAQ entry 2::
This is entry #2 in our example FAQ.

==== Glossary

There is one Glossary per Component and a General Glossary in user-manual.

For glossary entries ID should be in Uppercase with space replace by "_"


== Asciidoc FAQ

=== How to reset Heading Counter in Asciidoc

You can deactivate the counter for a section:
----
:sectnums!:

== Preface

:sectnums:

== First Chapter
----