docs/asciidoc/documentation_guidelines.adoc - ofbiz-framework - Git at Google

 ////
 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
 ----
	////
	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
	----