[ofbiz-framework] branch trunk updated: Documented: OFBizDocumentationSystem migration to Asciidoc and Review (OFBIZ-11364)

[holivier]

This is an automated email from the ASF dual-hosted git repository.

holivier pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/ofbiz-framework.git


The following commit(s) were added to refs/heads/trunk by this push:
     new ac6964e  Documented: OFBizDocumentationSystem migration to Asciidoc and Review (OFBIZ-11364)
ac6964e is described below

commit ac6964e8eba64c8a84a5954e2e2fead0e434fbb0
Author: holivier <[hidden email]>
AuthorDate: Sat Nov 14 16:55:31 2020 +0100

    Documented: OFBizDocumentationSystem migration to Asciidoc and Review (OFBIZ-11364)
   
    Rewrite the document, add a part in documentation guidline.
    Add a include for OFBizDocumentationSystem document in user manual and developer-manual.
---
 .../_include/OFBizDocumentationSystem.adoc         | 89 ++++++++++++++++++++++
 docs/asciidoc/developer-manual.adoc                |  2 +
 docs/asciidoc/documentation_guidelines.adoc        | 40 +++++++++-
 docs/asciidoc/user-manual.adoc                     |  2 +
 4 files changed, 129 insertions(+), 4 deletions(-)

diff --git a/docs/asciidoc/_include/OFBizDocumentationSystem.adoc b/docs/asciidoc/_include/OFBizDocumentationSystem.adoc
new file mode 100644
index 0000000..652a6cf
--- /dev/null
+++ b/docs/asciidoc/_include/OFBizDocumentationSystem.adoc
@@ -0,0 +1,89 @@
+////
+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.
+////
+= The Apache OFBiz documentation system
+
+== Overview
+there are two supports for OFbiz documentation, the https://cwiki.apache.org/confluence/display/OFBENDUSER/OFBiz+End+User+Docs+Home[wiki]
+and some mains documents (in pdf and html format)
+
+* user-manual
+* developer-manual
+* documentation_guidelines
+* README
+
+=== Asciidoc
+The OFBiz documents are generated from a number of Asciidoc files. In general the files are stored on each component
+in the 'src/docs/asciidoc' directories. +
+The general main documents include all files from component.
+
+The manuals and guidelines documents are located in docs/asciidoc directories, and REAME.adoc is in root directory.
+
+Help link in the OFBiz user interface, are link to the user-manual generated by buildbot process from Apache OFBiz community.
+It’s possible to change a property in OFBiz to have link to your own generation.
+
+For details about asciidoc rules used in Apache OFBiz have a look to link:documentation_guidelines.html[Documentation Guidelines]
+
+==== Application components
+All main files of each component are included in user-manual.adoc
+
+==== Framework components
+All main files of each component are included in developer-manual.adoc except for webtools which is included in user-manual
+
+==== Plugins
+For the main files of the plugin components, there are two ways to read them.
+
+On the one hand, the plugin documentation generation process generates one document per plugin, so that you can see
+the list of documents in the link:../../pluginsdoc/html5[pluginsdoc directory] and thus read each of them;
+
+On the other hand, each plugin master file is included in the plugin chapter of the user manual or developer manual,
+depending on whether the plugin is "technical" or "functional".
+
+=== Wiki
+Wiki is the second way to contribute to the documentation.
+Detail on how to https://cwiki.apache.org/confluence/display/OFBENDUSER/Help+for+providing+help+content[Help for providing help content]
+is on the wiki icon:smile-o[]
+
+Most of wiki page has been or will be migrated to the asciidoc pages, but, as wiki is more easier to be update
+(update existing page or create new one) the two system will continue to exist and live.
+
+
+== Contributing a new help screen, a few steps.
+link:documentation_guidelines.html[Documentation Guidelines] is the first doc to read to be able to contribute to documentation
+and/or help.
+
+If you are looking for asciidoc files format examples, please look at the following files:
+
+. An example for a chapter of a component at: applications/humanres/src/docs/asccidoc/_include/hr-intro.adoc
+. An example of a help screen: applications/humanres/src/docs/asccidoc/_include/HELP-hr-main.adoc
+
+=== Screens
+If you would like to create a new help for a certain screen, you need to do the following:
+
+. Write documentation in a functional point of view and in a process perspective.
+. Each title (in all level) generate in html an anchor, so starting point of the help should be a title.
+. Take the anchor generated (something like _the_title , with only lowercase), for example by looking in the html file generated.
+. In the screen add a `<set field` for `helpAnchor` with anchor generated as value.
+
+== Internationalization of the help system
+Currently documentation is only in English (except for 3 or 4 files, not included).
+
+In near future, there will be a solution to be able to have documentation/help in multiple languages,
+a https://issues.apache.org/jira/browse/OFBIZ-12030[jira (OFBIZ-12030)] is open of that.
+
+The switching between locale will be completely automatic (depending on OFBiz user local)
diff --git a/docs/asciidoc/developer-manual.adoc b/docs/asciidoc/developer-manual.adoc
index a25d138..a770ed2 100644
--- a/docs/asciidoc/developer-manual.adoc
+++ b/docs/asciidoc/developer-manual.adoc
@@ -190,6 +190,8 @@ Continuing the example, the FindInvoices screen contains many details including
 two forms. One form is for entering invoice search fields and the other form
 displays search results.
 
+include::_include/OFBizDocumentationSystem.adoc[leveloffset=+2]
+
 == Web Framework
 
 include::../../framework/webapp/src/docs/asciidoc/webapp.adoc[leveloffset=+1]
diff --git a/docs/asciidoc/documentation_guidelines.adoc b/docs/asciidoc/documentation_guidelines.adoc
index 88bcb6a..cc4ce09 100644
--- a/docs/asciidoc/documentation_guidelines.adoc
+++ b/docs/asciidoc/documentation_guidelines.adoc
@@ -51,7 +51,7 @@ how we are organised.
 
 === Document configuration
 
-Documents that will be published as standalone guides (e.g. developer manual, user manual) should contain common 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]
@@ -123,6 +123,34 @@ 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.
@@ -137,7 +165,6 @@ so the naming format will be ([shortname]-intro, [shortname]-glossary, [shortnam
 [shortname]-security etc.)
 
 .For Human Resources this will be as follows:
-[example]
 ====
     humanres.adoc
         |- hr-intro.adoc
@@ -481,10 +508,15 @@ SELECT * FROM FOO;
 == 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.
+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[]
diff --git a/docs/asciidoc/user-manual.adoc b/docs/asciidoc/user-manual.adoc
index bc7481a..3ddf0f4 100644
--- a/docs/asciidoc/user-manual.adoc
+++ b/docs/asciidoc/user-manual.adoc
@@ -136,6 +136,8 @@ to the core applications in design and structure, but are not shipped with
 OFBiz by default. Thus to install a plugin a user must add it to the framework
 first.
 
+include::_include/OFBizDocumentationSystem.adoc[leveloffset=+2]
+
 include::../../README.adoc[tags=quickstart]
 
 include::../../applications/commonext/src/docs/asciidoc/ofbiz-setup.adoc[leveloffset=+1]