Sorry Jacques, I missed your previous message.
Those files are referenced in the documentation_guidelines.adoc file to show how to include/reference external files. The guidelines are still valid and IMO useful for new contributors starting to work on documentation with asciidoc.
What are the reasons to remove those files? Best regards, Michael Brohl ecomify GmbH - www.ecomify.de Am 11.07.20 um 17:04 schrieb Jacques Le Roux:
Reading https://www.vogella.com/tutorials/AsciiDoc/article.html I understand that this file were used to start the work or possibly show how to use AsciiDoc.I believe they are now useless and we should get rid of them with the resource dir. I'll do so in a week if nobody is against.Jacques Le 09/07/2020 à 10:00, Jacques Le Roux a écrit :Hi Michael,I just stumbled upon the article.adoc and source.java files. What are those files used for?Thanks Jacques Le 10/04/2018 à 23:24, mbr...@apache.org a écrit :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.adocofbiz/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.adocURL: 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.javaURL: 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 filePropchange: ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/source.java ------------------------------------------------------------------------------svn:eol-style = nativePropchange: ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/source.java ------------------------------------------------------------------------------svn:keywords = Date Rev Author URL IdPropchange: ofbiz/ofbiz-framework/trunk/docs/asciidoc/resource/source.java ------------------------------------------------------------------------------svn:mime-type = text/plain
smime.p7s
Description: S/MIME Cryptographic Signature
