svn commit: r1828857 - in /ofbiz/ofbiz-framework/trunk/docs/asciidoc: documentation_guidelines.adoc resource/ resource/article.adoc resource/source.java

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

svn commit: r1828857 - in /ofbiz/ofbiz-framework/trunk/docs/asciidoc: documentation_guidelines.adoc resource/ resource/article.adoc resource/source.java

mbrohl
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