Author: mbrohl
Date: Tue Apr 10 21:24:31 2018
New Revision: 1828857
URL: http://svn.apache.org/viewvc?rev=1828857&view=rev
Log:
Improved: added the first draft of the documentation guidelines.
Added:
ofbiz/ofbiz-framework/trunk/docs/asciidoc/documentation_guidelines.adoc
ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/
ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/article.adoc
ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/source.java (with
props)
Added: ofbiz/ofbiz-framework/trunk/docs/asciidoc/documentation_guidelines.adoc
URL:
http://svn.apache.org/viewvc/ofbiz/ofbiz-framework/trunk/docs/asciidoc/documentation_guidelines.adoc?rev=1828857&view=auto
==============================================================================
--- ofbiz/ofbiz-framework/trunk/docs/asciidoc/documentation_guidelines.adoc
(added)
+++ ofbiz/ofbiz-framework/trunk/docs/asciidoc/documentation_guidelines.adoc Tue
Apr 10 21:24:31 2018
@@ -0,0 +1,627 @@
+////
+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
+Release 17.12
+:imagesdir: ./images
+ifdef::backend-pdf[]
+:title-logo-image: image::OFBiz-Logo.svg[Apache OFBiz Logo, pdfwidth=4.25in,
align=center]
+:source-highlighter: rouge
+endif::[]
+
+== Intro
+
+This guideline serves as a general styleguide and collection of examples of
how we are documenting the project.
+This intentionally is not a complete user manual but lists the subset of
functionality and formatting options we
+want 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 want to help with the documentation of the project, see 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 who will be published standalone (e.g. developer manual, user
manual) should contain a common configuration
+so that the output ist generated in the same way for all documents.
+
+[NOTE]
+This is not necessary for documents which will only be included in parent
documents. These documents will inherit the
+configuration from the parent.
+
+This ist the proposed configuration:
+
+----
+The Apache OFBiz Project // <1>
+Release 17.12 // <2>
+:imagesdir: ./images // <3>
+ifdef::backend-pdf[] // <4>
+:title-logo-image: image::OFBiz-Logo.svg[Apache OFBiz Logo, pdfwidth=4.25in,
align=center] // <5>
+:source-highlighter: rouge // <6>
+endif::[] // <7>
+----
+<1> author
+<2> target release, indicates for which release this documentation is valid
+<3> global definition of the image directory
+<4> begin block of configurations only for pdf rendering
+<5> define the title logo image
+<6> use the Rouge source code highlighter
+<7> 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>
+'experimental': '', // <2>
+'icons': 'font', // <3>
+'sectnums': '', // <4>
+'chapter-label': '', // <5>
+'toc': '', // <6>
+'toclevels': '5' // <7>
+----
+<1> doctype book
+<2> allow experimental features like keyboard shortcuts
+<3> make font awesome icons available
+<4> number chapters and sections automatically
+<5> do not prefix the chapters
+<6> insert a table of contents
+<7> 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 name conventions
+
+We will be implementing a consistent naming standard for the documentation
content files.
+Filenames will be in lower case and extension will be `.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:
+[example]
+====
+ 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 lines.
+* 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.
+====
+
+
+== 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.
+To use ---- in your listing use the [listing] style before that.
+The following example imports a file formatted as Java source code.
+
+[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 files partially.
+For this mark the part of the file to be included with a tag like 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 hence 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 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.
+
+=== 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 marco.
+----
+icon:comment[] This is a comment icon
+icon:file[] And a file icon
+icon:battery-full[] And a battery icon
+----
+
+.The output looks like the following
+[example]
+icon:comment[] This is a comment icon +
+icon:file[] And a file icon +
+icon:battery-full[] And a battery icon
+
+== 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.
+
+
+== Asciidoc FAQ
+
+=== How to reset Heading Counter in Asciidoc
+
+You can deactivate the counter for a section:
+----
+:sectnums!:
+
+== Preface
+
+:sectnums:
+
+== First Chapter
+----
+
+
Added: ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/article.adoc
URL:
http://svn.apache.org/viewvc/ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/article.adoc?rev=1828857&view=auto
==============================================================================
--- ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/article.adoc (added)
+++ ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/article.adoc Tue Apr 10
21:24:31 2018
@@ -0,0 +1,4 @@
+# tag::tagname[]
+This should be included!
+# end::tagname[]
+This text will not be included!
\ No newline at end of file
Added: ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/source.java
URL:
http://svn.apache.org/viewvc/ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/source.java?rev=1828857&view=auto
==============================================================================
--- ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/source.java (added)
+++ ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/source.java Tue Apr 10
21:24:31 2018
@@ -0,0 +1 @@
+System.out.println("Hello");
\ No newline at end of file
Propchange: ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/source.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/source.java
------------------------------------------------------------------------------
svn:keywords = Date Rev Author URL Id
Propchange: ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/source.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
