You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@groovy.apache.org by pa...@apache.org on 2020/10/11 20:34:17 UTC
[groovy] 01/01: better symmetry for html/pdf single page
documentation
This is an automated email from the ASF dual-hosted git repository.
paulk pushed a commit to branch asciidocAll
in repository https://gitbox.apache.org/repos/asf/groovy.git
commit ede7bffb8cee70b6f55a6437f728023c7055b030
Author: Paul King <pa...@asert.com.au>
AuthorDate: Mon Oct 12 06:34:06 2020 +1000
better symmetry for html/pdf single page documentation
---
.../groovy/org.apache.groovy-distribution.gradle | 6 +-
src/spec/doc/core-domain-specific-languages.adoc | 8 +-
.../doc/fragment_design-pattern-flyweight.adoc | 7 +-
src/spec/doc/index.adoc | 113 --------------------
subprojects/groovy-binary/build.gradle | 1 +
subprojects/groovy-binary/src/spec/doc/index.adoc | 114 +++++++++++++++++++++
.../src/spec/doc/groovy-console.adoc | 18 ++--
subprojects/groovy-jmx/src/spec/doc/jmx.adoc | 12 +--
.../src/spec/doc/fragment_swing-builder.adoc | 6 +-
9 files changed, 145 insertions(+), 140 deletions(-)
diff --git a/buildSrc/src/main/groovy/org.apache.groovy-distribution.gradle b/buildSrc/src/main/groovy/org.apache.groovy-distribution.gradle
index 6632d8d..e1de8a7 100644
--- a/buildSrc/src/main/groovy/org.apache.groovy-distribution.gradle
+++ b/buildSrc/src/main/groovy/org.apache.groovy-distribution.gradle
@@ -207,16 +207,14 @@ tasks.register("doc") {
tasks.register("asciidocAll", Copy) {
from configurations.allAsciidoc
+ from tasks.named('asciidoctor')
into layout.buildDirectory.dir("asciidocAll/html5")
}
tasks.named('asciidoctorPdf') {
baseDirFollowsSourceFile()
logDocuments = true
- sourceDir = rootProject.file('src/spec/doc')
- sources {
- include 'index.adoc'
- }
+ sourceDir = file('src/spec/doc')
outputDir = "$buildDir/asciidocAll/pdf"
}
diff --git a/src/spec/doc/core-domain-specific-languages.adoc b/src/spec/doc/core-domain-specific-languages.adoc
index 071c65e..63ac377 100644
--- a/src/spec/doc/core-domain-specific-languages.adoc
+++ b/src/spec/doc/core-domain-specific-languages.adoc
@@ -18,6 +18,9 @@
under the License.
//////////////////////////////////////////
+ifndef::reldir_root[]
+:reldir_root: .
+endif::[]
= Domain-Specific Languages
@@ -1079,8 +1082,7 @@ include::../../../subprojects/groovy-json/src/spec/doc/fragment_json-builder.ado
include::../../../subprojects/groovy-json/src/spec/doc/fragment_streaming-jason-builder.adoc[leveloffset=+3]
-:reldir: ../../../subprojects/groovy-swing/src/spec/doc
-include::{reldir}/fragment_swing-builder.adoc[leveloffset=+3]
+include::../../../subprojects/groovy-swing/src/spec/doc/fragment_swing-builder.adoc[leveloffset=+3]
include::../../../subprojects/groovy-ant/src/spec/doc/fragment_ant-builder.adoc[leveloffset=+3]
@@ -1599,7 +1601,7 @@ include::../../../subprojects/groovy-cli-picocli/src/spec/test/builder/CliBuilde
----
Gives this output:
-image:assets/img/usageMessageSpec.png[]
+image:{reldir_root}/assets/img/usageMessageSpec.png[]
*Property: parser*
diff --git a/src/spec/doc/fragment_design-pattern-flyweight.adoc b/src/spec/doc/fragment_design-pattern-flyweight.adoc
index b25f99f..e5558c3 100644
--- a/src/spec/doc/fragment_design-pattern-flyweight.adoc
+++ b/src/spec/doc/fragment_design-pattern-flyweight.adoc
@@ -18,6 +18,9 @@
under the License.
//////////////////////////////////////////
+ifndef::reldir_root[]
+:reldir_root: .
+endif::[]
= Flyweight Pattern
@@ -35,14 +38,14 @@ First we are going to model some complex aircraft (the first being a hoax compet
include::../test/DesignPatternsTest.groovy[tags=flyweight_boeing797,indent=0]
----
-image::assets/img/b797-hoax.jpg[]
+image::{reldir_root}/assets/img/b797-hoax.jpg[]
[source,groovy]
----
include::../test/DesignPatternsTest.groovy[tags=flyweight_airbus380,indent=0]
----
-image::assets/img/a380.jpg[]
+image::{reldir_root}/assets/img/a380.jpg[]
If we want to model our fleet, our first attempt might involve using many instances of these heavy-weight objects. It turns out though that only a few small pieces of state (our extrinsic state) change for each aircraft, so we will have singletons for the heavy-weight objects and capture the extrinsic state (bought date and asset number in the code below) separately.
diff --git a/src/spec/doc/index.adoc b/src/spec/doc/index.adoc
deleted file mode 100644
index dc3329c..0000000
--- a/src/spec/doc/index.adoc
+++ /dev/null
@@ -1,113 +0,0 @@
-//////////////////////////////////////////
-
- 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.
-
-//////////////////////////////////////////
-
-= Groovy Language Documentation
-:doctype: book
-
-include::core-introduction.adoc[]
-
-== Groovy Language Specification
-
-include::core-syntax.adoc[leveloffset=+2]
-
-include::core-operators.adoc[leveloffset=+2]
-
-include::core-program-structure.adoc[leveloffset=+2]
-
-include::core-object-orientation.adoc[leveloffset=+2]
-
-include::core-closures.adoc[leveloffset=+2]
-
-include::core-semantics.adoc[leveloffset=+2]
-
-== Tools
-
-include::tools-groovy.adoc[leveloffset=+2]
-
-include::tools-groovyc.adoc[leveloffset=+2]
-
-include::../../../subprojects/groovy-groovysh/src/spec/doc/groovysh.adoc[leveloffset=+2]
-
-:reldir: ../../../subprojects/groovy-console/src/spec/doc
-include::{reldir}/groovy-console.adoc[leveloffset=+2]
-
-include::../../../subprojects/groovy-groovydoc/src/spec/doc/groovydoc.adoc[leveloffset=+2]
-
-include::tools-ide.adoc[leveloffset=+2]
-
-== User Guides
-
-include::core-getting-started.adoc[leveloffset=+2]
-
-include::core-differences-java.adoc[leveloffset=+2]
-
-include::core-gdk.adoc[leveloffset=+2]
-
-include::core-metaprogramming.adoc[leveloffset=+2]
-
-include::grape.adoc[leveloffset=+2]
-
-include::core-testing-guide.adoc[leveloffset=+2]
-
-include::../../../subprojects/groovy-json/src/spec/doc/json-userguide.adoc[leveloffset=+2]
-
-include::../../../subprojects/groovy-sql/src/spec/doc/sql-userguide.adoc[leveloffset=+2]
-
-include::../../../subprojects/groovy-xml/src/spec/doc/xml-userguide.adoc[leveloffset=+2]
-
-include::../../../subprojects/groovy-yaml/src/spec/doc/yaml-userguide.adoc[leveloffset=+2]
-
-include::../../../subprojects/groovy-contracts/src/spec/doc/contracts-userguide.adoc[leveloffset=+2]
-
-=== Scripting Ant tasks
-
-Groovy integrates very well with http://ant.apache.org[Apache Ant] thanks to <<antbuilder,AntBuilder>>.
-
-include::../../../subprojects/groovy-ant/src/spec/doc/groovy-ant-task.adoc[leveloffset=+2]
-
-include::../../../subprojects/groovy-templates/src/spec/doc/template-engines.adoc[leveloffset=+2]
-
-include::../../../subprojects/groovy-servlet/src/spec/doc/servlet-userguide.adoc[leveloffset=+2]
-
-include::guide-integrating.adoc[leveloffset=+2]
-
-include::core-domain-specific-languages.adoc[leveloffset=+2]
-
-:reldir: ../../../subprojects/groovy-jmx/src/spec/doc
-include::{reldir}/jmx.adoc[leveloffset=+2]
-
-=== Creating Swing UIs
-
-Creating Swing UIs is made easy thanks to the use of <<swingbuilder,SwingBuilder>>.
-
-=== Security
-
-(TBD)
-
-
-include::design-patterns-in-groovy.adoc[leveloffset=+2]
-
-== Acknowledgements
-
-include::contributors.adoc[leveloffset=+2]
-
-include::license.adoc[leveloffset=+2]
-
diff --git a/subprojects/groovy-binary/build.gradle b/subprojects/groovy-binary/build.gradle
index 712c843..5005f80 100644
--- a/subprojects/groovy-binary/build.gradle
+++ b/subprojects/groovy-binary/build.gradle
@@ -21,6 +21,7 @@ import org.apache.tools.ant.filters.ReplaceTokens
plugins {
id 'org.apache.groovy-distribution'
id 'org.apache.groovy-published-library'
+ id 'org.apache.groovy-asciidoctor'
}
distribution {
diff --git a/subprojects/groovy-binary/src/spec/doc/index.adoc b/subprojects/groovy-binary/src/spec/doc/index.adoc
new file mode 100644
index 0000000..9586c2a
--- /dev/null
+++ b/subprojects/groovy-binary/src/spec/doc/index.adoc
@@ -0,0 +1,114 @@
+//////////////////////////////////////////
+
+ 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.
+
+//////////////////////////////////////////
+
+= Groovy Language Documentation
+:doctype: book
+
+:reldir_root: ../../../../../src/spec/doc
+include::{reldir_root}/core-introduction.adoc[]
+
+== Groovy Language Specification
+
+include::{reldir_root}/core-syntax.adoc[leveloffset=+2]
+
+include::{reldir_root}/core-operators.adoc[leveloffset=+2]
+
+include::{reldir_root}/core-program-structure.adoc[leveloffset=+2]
+
+include::{reldir_root}/core-object-orientation.adoc[leveloffset=+2]
+
+include::{reldir_root}/core-closures.adoc[leveloffset=+2]
+
+include::{reldir_root}/core-semantics.adoc[leveloffset=+2]
+
+== Tools
+
+include::{reldir_root}/tools-groovy.adoc[leveloffset=+2]
+
+include::{reldir_root}/tools-groovyc.adoc[leveloffset=+2]
+
+include::../../../../../subprojects/groovy-groovysh/src/spec/doc/groovysh.adoc[leveloffset=+2]
+
+:reldir_console: ../../../../../subprojects/groovy-console/src/spec/doc
+include::{reldir_console}/groovy-console.adoc[leveloffset=+2]
+
+include::../../../../../subprojects/groovy-groovydoc/src/spec/doc/groovydoc.adoc[leveloffset=+2]
+
+include::{reldir_root}/tools-ide.adoc[leveloffset=+2]
+
+== User Guides
+
+include::{reldir_root}/core-getting-started.adoc[leveloffset=+2]
+
+include::{reldir_root}/core-differences-java.adoc[leveloffset=+2]
+
+include::{reldir_root}/core-gdk.adoc[leveloffset=+2]
+
+include::{reldir_root}/core-metaprogramming.adoc[leveloffset=+2]
+
+include::{reldir_root}/grape.adoc[leveloffset=+2]
+
+include::{reldir_root}/core-testing-guide.adoc[leveloffset=+2]
+
+include::../../../../../subprojects/groovy-json/src/spec/doc/json-userguide.adoc[leveloffset=+2]
+
+include::../../../../../subprojects/groovy-sql/src/spec/doc/sql-userguide.adoc[leveloffset=+2]
+
+include::../../../../../subprojects/groovy-xml/src/spec/doc/xml-userguide.adoc[leveloffset=+2]
+
+include::../../../../../subprojects/groovy-yaml/src/spec/doc/yaml-userguide.adoc[leveloffset=+2]
+
+include::../../../../../subprojects/groovy-contracts/src/spec/doc/contracts-userguide.adoc[leveloffset=+2]
+
+=== Scripting Ant tasks
+
+Groovy integrates very well with http://ant.apache.org[Apache Ant] thanks to <<antbuilder,AntBuilder>>.
+
+include::../../../../../subprojects/groovy-ant/src/spec/doc/groovy-ant-task.adoc[leveloffset=+2]
+
+include::../../../../../subprojects/groovy-templates/src/spec/doc/template-engines.adoc[leveloffset=+2]
+
+include::../../../../../subprojects/groovy-servlet/src/spec/doc/servlet-userguide.adoc[leveloffset=+2]
+
+include::{reldir_root}/guide-integrating.adoc[leveloffset=+2]
+
+:reldir_swing: ../../../../../subprojects/groovy-swing/src/spec/doc
+include::{reldir_root}/core-domain-specific-languages.adoc[leveloffset=+2]
+
+:reldir_jmx: ../../../../../subprojects/groovy-jmx/src/spec/doc
+include::{reldir_jmx}/jmx.adoc[leveloffset=+2]
+
+=== Creating Swing UIs
+
+Creating Swing UIs is made easy thanks to the use of <<swingbuilder,SwingBuilder>>.
+
+=== Security
+
+(TBD)
+
+include::{reldir_root}/design-patterns-in-groovy.adoc[leveloffset=+2]
+
+== Acknowledgements
+
+include::{reldir_root}/contributors.adoc[leveloffset=+2]
+
+include::{reldir_root}/license.adoc[leveloffset=+2]
+
diff --git a/subprojects/groovy-console/src/spec/doc/groovy-console.adoc b/subprojects/groovy-console/src/spec/doc/groovy-console.adoc
index fb42012..5196662 100644
--- a/subprojects/groovy-console/src/spec/doc/groovy-console.adoc
+++ b/subprojects/groovy-console/src/spec/doc/groovy-console.adoc
@@ -18,8 +18,8 @@
under the License.
//////////////////////////////////////////
-ifndef::reldir[]
-:reldir: .
+ifndef::reldir_console[]
+:reldir_console: .
endif::[]
= groovyConsole, the Groovy swing console
@@ -33,7 +33,7 @@ This page documents the features of this user interface.
[[GroovyConsole-Basics]]
== Basics
-image:{reldir}/assets/img/GroovyConsole.png[image]
+image:{reldir_console}/assets/img/GroovyConsole.png[image]
. Groovy Console is launched via `groovyConsole` or
`groovyConsole.bat`, both located in `$GROOVY_HOME/bin`
@@ -120,7 +120,7 @@ an infinite loop? Interrupting script execution can be achieved by clicking
the `interrupt` button on the small dialog box that pops up when a script
is executing or through the `interrupt` icon in the tool bar.
-image:{reldir}/assets/img/gconsole-toolbar.png[Toolbar]
+image:{reldir_console}/assets/img/gconsole-toolbar.png[Toolbar]
However, this may not be sufficient to interrupt a script: clicking the button
will interrupt the execution thread, but if your code doesn't handle the interrupt
@@ -174,7 +174,7 @@ You can customize the way script output results are visualized. Let’s
see how we can customize this. For example, viewing a map result would
show something like this:
-image:{reldir}/assets/img/gconsole-sc-without-visu.png[image]
+image:{reldir_console}/assets/img/gconsole-sc-without-visu.png[image]
What you see here is the usual textual representation of a Map. But,
what if we enabled custom visualization of certain results? The Swing
@@ -211,7 +211,7 @@ own script results representations. In our case, we transform the Map
into a nice-looking Swing JTable. We’re now able to visualize maps
in a friendly and attractive fashion, as the screenshot below shows:
-image:{reldir}/assets/img/gconsole-sc-with-visu.png[image]
+image:{reldir_console}/assets/img/gconsole-sc-with-visu.png[image]
[[GroovyConsole-ASTbrowser]]
== Advanced debugging: AST browser
@@ -224,13 +224,13 @@ In the example below, we have annotated our class with the `@Immutable` annotati
and the Groovy compiler has generated a lot of boilerplate code for us.
We can see the code for the generated equals method in the `Source` tab.
-image:{reldir}/assets/img/astbrowser_source.png[AST Browser]
+image:{reldir_console}/assets/img/astbrowser_source.png[AST Browser]
We can even examine the JVM bytecode generated by the compiler.
In the image below we are looking at the bytecode for the Groovy
expression `LocalDate.parse('2020/02/10', 'yyyy/MM/dd')`.
-image:{reldir}/assets/img/astbrowser_bytecode.png[AST Browser]
+image:{reldir_console}/assets/img/astbrowser_bytecode.png[AST Browser]
[[GroovyConsole-CSTbrowser]]
== Advanced debugging: CST browser
@@ -238,5 +238,5 @@ image:{reldir}/assets/img/astbrowser_bytecode.png[AST Browser]
Groovy Console can visualize the CST (Concrete Syntax Tree) representing
the initial parsing of the script. This is mainly useful for parsing gurus.
-image:{reldir}/assets/img/cstbrowser.png[CST Browser]
+image:{reldir_console}/assets/img/cstbrowser.png[CST Browser]
diff --git a/subprojects/groovy-jmx/src/spec/doc/jmx.adoc b/subprojects/groovy-jmx/src/spec/doc/jmx.adoc
index e8f9aac..7bc5395 100644
--- a/subprojects/groovy-jmx/src/spec/doc/jmx.adoc
+++ b/subprojects/groovy-jmx/src/spec/doc/jmx.adoc
@@ -18,8 +18,8 @@
under the License.
//////////////////////////////////////////
-ifndef::reldir[]
-:reldir: .
+ifndef::reldir_jmx[]
+:reldir_jmx: .
endif::[]
= Working with JMX
@@ -204,7 +204,7 @@ Catalina:j2eeType=WebModule,name=//localhost/host-manager,J2EEApplication=none,J
The output will look like this:
-image:{reldir}/assets/img/catalina.png[]
+image:{reldir_jmx}/assets/img/catalina.png[]
Note: if you get errors running this script, see the **Troubleshooting** section below.
@@ -303,7 +303,7 @@ chart.draw(swing.canvas.graphics, swing.canvas.bounds)
Which looks like:
-image:{reldir}/assets/img/oc4jpie.png[]
+image:{reldir_jmx}/assets/img/oc4jpie.png[]
== WebLogic Example
@@ -414,7 +414,7 @@ Operations:
You can even attach to the process while it is running with https://docs.oracle.com/en/java/javase/14/management/using-jconsole.html[jconsole]. It will look something like:
-image:{reldir}/assets/img/jconsole.png[]
+image:{reldir_jmx}/assets/img/jconsole.png[]
We started the Groovy application with the `-Dcom.sun.management.jmxremote` JVM argument.
@@ -624,7 +624,7 @@ Remember, **JmxBuilder.export() returns an array of GroovyMBean[] objects** for
====== JConsole view of Exported Bean
-image:{reldir}/assets/img/jconsole-implicit-export.png[]
+image:{reldir_jmx}/assets/img/jconsole-implicit-export.png[]
==== JmxBuilder.bean() Syntax
diff --git a/subprojects/groovy-swing/src/spec/doc/fragment_swing-builder.adoc b/subprojects/groovy-swing/src/spec/doc/fragment_swing-builder.adoc
index ff7436a..4181671 100644
--- a/subprojects/groovy-swing/src/spec/doc/fragment_swing-builder.adoc
+++ b/subprojects/groovy-swing/src/spec/doc/fragment_swing-builder.adoc
@@ -18,8 +18,8 @@
under the License.
//////////////////////////////////////////
-ifndef::reldir[]
-:reldir: .
+ifndef::reldir_swing[]
+:reldir_swing: .
endif::[]
[[swingbuilder]]
@@ -38,7 +38,7 @@ include::../test/SwingBuilderTest.groovy[tags=simple_example,indent=0]
Here is what it will look like:
-image:{reldir}/assets/img/SwingBuilder001.png[]
+image:{reldir_swing}/assets/img/SwingBuilder001.png[]
This hierarchy of components would normally be created through a series of repetitive instantiations, setters, and finally attaching this child to its respective parent.
Using `SwingBuilder`, however, allows you to define this hierarchy in its native form, which makes the interface design understandable simply by reading the code.