diff --git a/fj-doc-guide/src/main/docs/asciidoc/chapters/03_1_doc_format_xml.adoc b/fj-doc-guide/src/main/docs/asciidoc/chapters/03_1_doc_format_xml.adoc new file mode 100644 index 000000000..fafe9cb0b --- /dev/null +++ b/fj-doc-guide/src/main/docs/asciidoc/chapters/03_1_doc_format_xml.adoc @@ -0,0 +1,51 @@ +[#doc-format-entry-point-xml] +=== XML Source Format + +When writing a sample Venus Document, it is possible to draw from some online resources : + +. https://www.fugerit.org/data/java/doc/xsd/doc-2-0.xsd[Venus DOC XML Schema Definition] - Current version of the Venus DOC XSD, the main source for writing valid Venus document meta model. +. https://venusdocs.fugerit.org/fj-doc-base/src/main/docs/doc_xsd_config_ref.html[Venus DOC XML Reference] - the informations contained in the previous XSD in HTML format for convenience. +. https://venusdocs.fugerit.org/docs/html/doc_meta_info.html[Venus DOC meta informations reference] - documentations for existing 'info' properties for 'metadata' section. +. https://docs.fugerit.org/fj-doc-playground/home/[Online Playground] - To test how the XML elements are rendered to documents by DocHandlers. + +Supported is provided by the base module dependency : + +[source,xml] +---- + + org.fugerit.java + fj-doc-base + ${fj-doc-version} + +---- + +Here is an example xml : + +[source,xml] +---- + + + + + + + + 10;10;10;30 + + Hello World + fugerit79 + en + + + Hello World! + + + +---- diff --git a/fj-doc-guide/src/main/docs/asciidoc/chapters/03_2_doc_format_json_yaml.adoc b/fj-doc-guide/src/main/docs/asciidoc/chapters/03_2_doc_format_json_yaml.adoc new file mode 100644 index 000000000..911b9609a --- /dev/null +++ b/fj-doc-guide/src/main/docs/asciidoc/chapters/03_2_doc_format_json_yaml.adoc @@ -0,0 +1,184 @@ +[#doc-format-entry-point-json-yaml] +=== JSON and YAML Source Format + +It is possible to use JSON or YAML as source. It is just needed to follow some conversion rules. + +The conversion rules from xml to json/yaml are : + +. xml meta information are translated as top level property (xmlns etc.) +. Every JSON/YAML object contains the information of a XML tag +. "_t" special property contains the tag name (for example "_t" : "metadata") +. "_v" special property contains the text content of an element +. "_e" special property contains a list of child elements +. any other xml attribute is mapped as a JSON/YAML property (for example "name" : "margins") + +NOTE: As it is possible to directly convert JSON and YAML, rules for YAML are the same as for JSON format. + +NOTE: All XML comments are ignored + +NOTE: For XML/JSON/YAML conversion a https://docs.fugerit.org/fj-doc-playground/home/[Online Playground] is available. + +Support for _JSON_ format needs the following dependency : + +[source,xml] +---- + + org.fugerit.java + fj-doc-base-json + ${fj-doc-version} + +---- + +Here is a simple JSON source document : + +[source,json] +---- +{ + "xmlns" : "http://javacoredoc.fugerit.org", + "xsi:schemaLocation" : "http://javacoredoc.fugerit.org https://www.fugerit.org/data/java/doc/xsd/doc-2-0.xsd", + "xmlns:xsi" : "http://www.w3.org/2001/XMLSchema-instance", + "_t" : "doc", + "_e" : [ { + "_t" : "metadata", + "_e" : [ { + "name" : "margins", + "_t" : "info", + "_v" : "10;10;10;30" + }, { + "name" : "doc-title", + "_t" : "info", + "_v" : "Hello World" + }, { + "name" : "doc-author", + "_t" : "info", + "_v" : "fugerit79" + }, { + "name" : "doc-language", + "_t" : "info", + "_v" : "en" + } ] + }, { + "_t" : "body", + "_e" : [ { + "_t" : "para", + "_v" : "Hello World!" + } ] + } ] +} +---- + +Support for _YAML_ format needs the following dependency : + +[source,xml] +---- + + org.fugerit.java + fj-doc-base-yaml + ${fj-doc-version} + +---- + +Here is the equivalent YAML : + +[source,yaml] +---- +--- +xmlns: "http://javacoredoc.fugerit.org" +xsi:schemaLocation: "http://javacoredoc.fugerit.org https://www.fugerit.org/data/java/doc/xsd/doc-2-1.xsd" +xmlns:xsi: "http://www.w3.org/2001/XMLSchema-instance" +_t: "doc" +_e: +- _t: "metadata" + _e: + - name: "margins" + _t: "info" + _v: "10;10;10;30" + - name: "doc-title" + _t: "info" + _v: "Basic example" + - name: "doc-subject" + _t: "info" + _v: "fj doc venus sample source xml" + - name: "doc-author" + _t: "info" + _v: "fugerit79" + - name: "doc-language" + _t: "info" + _v: "en" + - name: "default-font-name" + _t: "info" + _v: "TitilliumWeb" + - name: "excel-table-id" + _t: "info" + _v: "data-table=print" + - name: "csv-table-id" + _t: "info" + _v: "data-table" + - _t: "footer-ext" + _e: + - align: "right" + _t: "para" + _v: "${currentPage} / ${pageCount}" +- _t: "body" + _e: + - _t: "para" + _v: "My sample title" + - padding: "2" + columns: "3" + width: "100" + id: "data-table" + colwidths: "30;30;40" + _t: "table" + _e: + - _t: "row" + _e: + - border-color: "#000000" + border-width: "1" + align: "center" + _t: "cell" + _e: + - style: "bold" + _t: "para" + _v: "Name" + - align: "center" + _t: "cell" + _e: + - style: "bold" + _t: "para" + _v: "Surname" + - align: "center" + _t: "cell" + _e: + - style: "bold" + _t: "para" + _v: "Title" + - _t: "row" + _e: + - _t: "cell" + _e: + - _t: "para" + _v: "Luthien" + - _t: "cell" + _e: + - _t: "para" + _v: "Tinuviel" + - _t: "cell" + _e: + - _t: "para" + _v: "Queen" + - _t: "row" + _e: + - _t: "cell" + _e: + - _t: "para" + _v: "Thorin" + - _t: "cell" + _e: + - _t: "para" + _v: "Oakshield" + - _t: "cell" + _e: + - _t: "para" + _v: "King" + +---- \ No newline at end of file diff --git a/fj-doc-guide/src/main/docs/asciidoc/chapters/03_3_doc_format_kotlin.adoc b/fj-doc-guide/src/main/docs/asciidoc/chapters/03_3_doc_format_kotlin.adoc new file mode 100644 index 000000000..a02040020 --- /dev/null +++ b/fj-doc-guide/src/main/docs/asciidoc/chapters/03_3_doc_format_kotlin.adoc @@ -0,0 +1,58 @@ +[#doc-format-entry-point-kotlin] +=== Kotlin Source Format (Experimental) + + +Supported is provided by the base module dependency. + +[source,xml] +---- + + org.fugerit.java + fj-doc-ext-kotlin + ${fj-doc-ext-kotlin-version} + +---- + +NOTE: At the moment kotlin (KTS) support is still experimental. The link:https://github.com/fugerit-org/fj-doc-ext-kotlin[Kotlin extension] is maintained on a separate repository. + +Kotlin source is based on a custom DSL (Domain Specific Language). +The link:https://github.com/fugerit-org/fj-doc-ext-kotlin/blob/main/src/main/java/org/fugerit/java/doc/base/kotlin/dsl/dslDoc.kt[Fugerit Doc Kotlin DSL] is basically a mapping of the xsd. + +Here is a sample kotlin source document : + +[source,kts] +---- +import org.fugerit.java.doc.base.kotlin.dsl.dslDoc + +dslDoc { + val docTitle = attStr( data, "docTitle" ) + meta { + info( ( docTitle ) ).name( "doc-title" ) + info( ( "10;10;10;30" ) ).name( "margins" ) + info( ( "fj doc venus sample source Kotlin Template - kts" ) ).name( "doc-subject" ) + info( ( "fugerit79" ) ).name( "dock-author" ) + info( ( "en" ) ).name( "doc-language" ) + info( ( "TitilliumWeb" ) ).name( "default-font-name" ) + info( ( "data-table=print" ) ).name( "excel-table-id" ) + info( ( "data-table" ) ).name( "csv-table-id" ) + footerExt { + para( '$'+"{currentPage} / "+'$'+"{pageCount}" ).align( "right" ) + } + } + body { + h( docTitle ).headLevel( 1 ) + table { + row { + cell { para( "Name" ) }.align( "center" ) + cell { para( "Surname" ) }.align( "center" ) + cell { para( "Title" ) }.align( "center" ) + }.header( true ) + attListMap( data, "listPeople" ).forEach( { e -> row { + cell { para( attStr( e, "name" ) ) } + cell { para( attStr( e, "surname" ) ) } + cell { para( attStr( e, "title" ) ) } + } } ) + }.columns( 3 ).colwidths( "30;30;40" ).width( 100 ).id( "data-table" ).padding( 2 ) + } +} +---- diff --git a/fj-doc-guide/src/main/docs/asciidoc/index.adoc b/fj-doc-guide/src/main/docs/asciidoc/index.adoc index dace69791..fa16ea703 100644 --- a/fj-doc-guide/src/main/docs/asciidoc/index.adoc +++ b/fj-doc-guide/src/main/docs/asciidoc/index.adoc @@ -15,6 +15,9 @@ include::chapters/02_2_maven_plugin_init.adoc[] include::chapters/02_3_maven_plugin_verify.adoc[] include::chapters/03_doc_format.adoc[] +include::chapters/03_1_doc_format_xml.adoc[] +include::chapters/03_2_doc_format_json_yaml.adoc[] +include::chapters/03_3_doc_format_kotlin.adoc[] include::chapters/04_doc_freemarker.adoc[] include::chapters/04_1_doc_freemarker_config.adoc[]