docs/reference-manual/native-image update ref links to rel paths; start sentences from a new line

Author: olyagpl

docs/reference-manual/native-image/Agent.md

@@ -18,22 +18,17 @@ Native Image supports a wide range of options to configure a native image build
 
 ## Embedding a Configuration File
 
-A recommended way to provide configuration is to embed a
-**native-image.properties** file into a project JAR file. The Native Image builder
-will automatically pick up all configuration options provided anywhere below the
-resource location `META-INF/native-image/` and use it to construct
-`native-image` command line arguments.
-
-To avoid a situation when constituent parts of a project are built
-with overlapping configurations, it is recommended to use "subdirectories" within
-`META-INF/native-image`. That way a JAR file built from multiple maven projects
-cannot suffer from overlapping `native-image` configurations. For example:
+A recommended way to provide configuration is to embed a **native-image.properties** file into a project JAR file.
+The Native Image builder will automatically pick up all configuration options provided anywhere below the resource location `META-INF/native-image/` and use it to construct `native-image` command line arguments.
+
+To avoid a situation when constituent parts of a project are built with overlapping configurations, it is recommended to use "subdirectories" within `META-INF/native-image`.
+That way a JAR file built from multiple maven projects cannot suffer from overlapping `native-image` configurations.
+For example:
 * _foo.jar_ has its configurations in `META-INF/native-image/foo_groupID/foo_artifactID`
 * _bar.jar_ has its configurations in `META-INF/native-image/bar_groupID/bar_artifactID`
 
-The JAR file that contains `foo` and `bar` will then contain both configurations
-without conflicting with one another. Therefore the recommended layout for
-storing native image configuration data in JAR files is the following:
+The JAR file that contains `foo` and `bar` will then contain both configurations without conflicting with one another.
+Therefore the recommended layout for storing native image configuration data in JAR files is the following:
 ```
 META-INF/
 └── native-image
@@ -42,12 +37,9 @@ META-INF/
             └── native-image.properties
 ```
 
-Note that the use of `${.}` in a _native-image.properties_ file expands to the
-resource location that contains that exact configuration file. This can be
-useful if the _native-image.properties_ file wants to refer to resources within
-its "subfolder", for example, `-H:SubstitutionResources=${.}/substitutions.json`.
-Always make sure to use the option variants that take resources, i.e., use
-`-H:ResourceConfigurationResources` instead of `-H:ResourceConfigurationFiles`.
+Note that the use of `${.}` in a _native-image.properties_ file expands to the resource location that contains that exact configuration file.
+This can be useful if the _native-image.properties_ file wants to refer to resources within its "subfolder", for example, `-H:SubstitutionResources=${.}/substitutions.json`.
+Always make sure to use the option variants that take resources, i.e., use `-H:ResourceConfigurationResources` instead of `-H:ResourceConfigurationFiles`.
 Other options that are known to work in this context are:
 * `-H:DynamicProxyConfigurationResources`
 * `-H:JNIConfigurationResources`
@@ -56,16 +48,14 @@ Other options that are known to work in this context are:
 * `-H:SubstitutionResources`
 * `-H:SerializationConfigurationResources`
 
-By having such a composable _native-image.properties_ file, building an image
-does not require any additional arguments specified on command line. It is
-sufficient to just run the following command:
+By having such a composable _native-image.properties_ file, building an image does not require any additional arguments specified on command line.
+It is sufficient to just run the following command:
 ```shell
 $JAVA_HOME/bin/native-image -jar target/<name>.jar
 ```
 
-To debug which configuration data gets applied for the image building, use `native-image --verbose`. This will show from where `native-image` picks up the
-configurations to construct the final composite configuration command line
-options for the native image builder.
+To debug which configuration data gets applied for the image building, use `native-image --verbose`.
+This will show from where `native-image` picks up the configurations to construct the final composite configuration command line options for the native image builder.
 ```shell
 native-image --verbose -jar build/basic-app-0.1-all.jar
 Apply jar:file://~/build/basic-app-0.1-all.jar!/META-INF/native-image/io.netty/common/native-image.properties
@@ -89,44 +79,38 @@ supported.
 
 **Args**
 
-Use this property if your project requires custom `native-image` command line options to build correctly. For example, the `native-image-configure-examples/configure-at-runtime-example` has `Args = --initialize-at-build-time=com.fasterxml.jackson.annotation.JsonProperty$Access`  in its `native-image.properties` file to ensure the class `com.fasterxml.jackson.annotation.JsonProperty$Access` gets initialized at image build time.
+Use this property if your project requires custom `native-image` command line options to build correctly.
+For example, the `native-image-configure-examples/configure-at-runtime-example` has `Args = --initialize-at-build-time=com.fasterxml.jackson.annotation.JsonProperty$Access` in its `native-image.properties` file to ensure the class `com.fasterxml.jackson.annotation.JsonProperty$Access` gets initialized at image build time.
 
 **JavaArgs**
 
-Sometimes it can be necessary to provide custom options to the JVM that runs the
-native image builder. The `JavaArgs` property can be used in this case.
+Sometimes it can be necessary to provide custom options to the JVM that runs the native image builder.
+The `JavaArgs` property can be used in this case.
 
 **ImageName**
 
-This property can be used to specify a user-defined name for the image. If
-`ImageName` is not used, a name gets automatically chosen:
+This property can be used to specify a user-defined name for the image.
+If `ImageName` is not used, a name gets automatically chosen:
 * `native-image -jar <name.jar>` has a default image name `<name>`
 * `native-image -cp ... fully.qualified.MainClass` has a default image name `fully.qualified.mainclass`
 
-Note that using `ImageName` does not prevent the user to override the name later via command line. For example, if `foo.bar` contains `ImageName=foo_app`:
+Note that using `ImageName` does not prevent the user to override the name later via command line.
+For example, if `foo.bar` contains `ImageName=foo_app`:
 * `native-image -jar foo.bar` generates the image `foo_app` but
 * `native-image -jar foo.bar application` generates the image `application`
 
 ### Order of Arguments Evaluation
-The arguments passed to `native-image` are evaluated left-to-right. This also
-extends to arguments that get passed indirectly via `META-INF/native-image`
-based native image configuration. Suppose you have a JAR file that contains
-_native-image.properties_ with `Args = -H:Optimize=0`. Then by using the
-`-H:Optimize=2` option after `-cp <jar-file>` you can override the setting that
-comes from the JAR file.
+The arguments passed to `native-image` are evaluated left-to-right.
+This also extends to arguments that get passed indirectly via `META-INF/native-image` based native image configuration.
+Suppose you have a JAR file that contains _native-image.properties_ with `Args = -H:Optimize=0`.
+Then by using the `-H:Optimize=2` option after `-cp <jar-file>` you can override the setting that comes from the JAR file.
 
 ### Specifying Default Options for Native Image
-If there is a need to pass some options for every image build unconditionally, for
-example, to always generate an image in verbose mode (`--verbose`), you can
-make use of the `NATIVE_IMAGE_CONFIG_FILE` environment variable.
-If it is set to a Java properties file, the Native Image builder will use the
-default setting defined in there on each invocation. Write a
-configuration file and export
-`NATIVE_IMAGE_CONFIG_FILE=$HOME/.native-image/default.properties` in
-`~/.bash_profile`. Every time `native-image` gets used, it will implicitly use
-the arguments specified as `NativeImageArgs`, plus the arguments specified on the
-command line. Here is an example of a configuration file, saved as
-`~/.native-image/default.properties`:
+If there is a need to pass some options for every image build unconditionally, for example, to always generate an image in verbose mode (`--verbose`), you can make use of the `NATIVE_IMAGE_CONFIG_FILE` environment variable.
+If it is set to a Java properties file, the Native Image builder will use the default setting defined in there on each invocation.
+Write a configuration file and export `NATIVE_IMAGE_CONFIG_FILE=$HOME/.native-image/default.properties` in `~/.bash_profile`.
+Every time `native-image` gets used, it will implicitly use the arguments specified as `NativeImageArgs`, plus the arguments specified on the command line.
+Here is an example of a configuration file, saved as `~/.native-image/default.properties`:
 
 ```
 NativeImageArgs = --configurations-path /home/user/custom-image-configs \
@@ -146,9 +130,9 @@ export NATIVE_IMAGE_USER_HOME= $HOME/.local/share/native-image
 The native image build runs on the Java HotSpot VM and uses the memory management of the underlying platform.
 The usual Java HotSpot command-line options for garbage collection apply to the native image builder.
 
-During the native image build, the representation of a whole program is created to
-figure out which classes and methods will be used at run time. It is a
-computationally intensive process. The default values for memory usage at image build time are:
+During the native image build, the representation of a whole program is created to figure out which classes and methods will be used at run time.
+It is a computationally intensive process.
+The default values for memory usage at image build time are:
 ```
 -Xss10M \
 -Xms1G \
@@ -164,21 +148,16 @@ Check other related options to the native image builder from the `native-image -
 
 ## Runtime vs Build-Time Initialization
 
-Building your application into a native image allows you to decide which parts
-of your application should be run at image build time and which parts have to
-run at image run time.
+Building your application into a native image allows you to decide which parts of your application should be run at image build time and which parts have to run at image run time.
 
-All class-initialization code (static initializers and static
-field initialization) of the application you build an image for is executed
-at image run time by default. Sometimes it is beneficial to allow class
-initialization code to get executed at image build time for faster startup (e.g.,
-if some static fields get initialized to run-time independent data). This can be
-controlled with the following `native-image` options:
+All class-initialization code (static initializers and static field initialization) of the application you build an image for is executed at image run time by default.
+Sometimes it is beneficial to allow class initialization code to get executed at image build time for faster startup (e.g., if some static fields get initialized to run-time independent data).
+This can be controlled with the following `native-image` options:
 
 * `--initialize-at-build-time=<comma-separated list of packages and classes>`
 * `--initialize-at-run-time=<comma-separated list of packages and classes>`
 
-In addition to that, arbitrary computations are allowed at build time that can be put into `ImageSingletons` that are
-accessible at image run time. For more information please have a look at [Native Image configuration examples](https://github.com/graalvm/graalvm-demos/tree/master/native-image-configure-examples).
+In addition to that, arbitrary computations are allowed at build time that can be put into `ImageSingletons` that are accessible at image run time.
+For more information please have a look at [Native Image configuration examples](https://github.com/graalvm/graalvm-demos/tree/master/native-image-configure-examples).
 
 For more information, continue reading to the [Class Initialization in Native Image](ClassInitialization.md) guide.

docs/reference-manual/native-image/BuildConfiguration.md

@@ -6,7 +6,7 @@ permalink: /reference-manual/native-image/C-API/
 ---
 #  Native Image C API
 
-Native Image provides an API for the C language for initializing isolates and attaching threads for use with the entry point feature that is demonstrated [here](README.md#images-and-entry-points).
+Native Image provides an API for the C language for initializing isolates and attaching threads for use with the entry point feature that is demonstrated [here](README.md/#images-and-entry-points).
 The C API is available when Native Image is built as a shared library and its declarations are included in the header file that is generated during the build.
 
 ```c
@@ -79,6 +79,4 @@ int graal_detach_thread(graal_isolatethread_t* thread);
  */
 int graal_tear_down_isolate(graal_isolatethread_t* thread);
 ```
-In addition to the C level API, there is also a way to initialize an isolate
-from Java and thus use Java and Native Image to
-[implement native methods in Java](ImplementingNativeMethodsInJavaWithSVM.md).
+In addition to the C level API, there is also a way to initialize an isolate from Java and thus use Java and Native Image to [implement native methods in Java](ImplementingNativeMethodsInJavaWithSVM.md).

docs/reference-manual/native-image/C-API.md

@@ -19,7 +19,9 @@ Access to the static fields that were initialized at build time is transparent t
 Specifying class initialization policies can be complicated due to the following constraints that come from class initialization semantics:
 
 * When a class is initialized, all super classes and super interfaces with default methods must also be initialized.
-Interfaces without default methods, however, are not initialized. To describe this, a short-term "relevant supertype" is used furhter, and a relevant subtype for subtypes of classes and interfaces with default methods.
+Interfaces without default methods, however, are not initialized.
+To describe this, a short-term "relevant supertype" is used furhter, and a relevant subtype for subtypes of classes and interfaces with default methods.
+
 * Relevant supertypes of types initialized at build time must also be initialized at build time.
 * Relevant subtypes of types initialized at run time must also be initialized at run time.
 * No instances classes that are initialized at run time must be present in the image.
@@ -31,7 +33,8 @@ To enjoy the complete out-of-the-box experience of Native Image and still get th
 * [Explicitly Specifying Class Initialization](#explicitly-specifying-class-initialization)
 
 To track which classes were initialized and why, one can use the flag `-H:+PrintClassInitialization`.
-This flag greatly helps to configure the image build to work as intended. The goal is to have as many classes as possible initialized at build time, yet keep the correct semantics of the program.
+This flag greatly helps to configure the image build to work as intended.
+The goal is to have as many classes as possible initialized at build time, yet keep the correct semantics of the program.
 
 ## Build-Time Initialization of Native Image Runtime
 

docs/reference-manual/native-image/ClassInitialization.md

@@ -12,11 +12,12 @@ Dynamic proxy classes are generated from a list of interfaces.
 Native Image does not provide machinery for generating and interpreting bytecodes at run time.
 Therefore all dynamic proxy classes need to be generated at native image build time.
 
-See also the [guide on assisted configuration of Java resources and other dynamic features](BuildConfiguration.md#assisted-configuration-of-native-image-builds).
+See also the [guide on assisted configuration of Java resources and other dynamic features](BuildConfiguration.md/#assisted-configuration-of-native-image-builds).
 
 ## Automatic Detection
 
-Native Image employs a simple static analysis that detects calls to `java.lang.reflect.Proxy.newProxyInstance(ClassLoader, Class<?>[], InvocationHandler)` and `java.lang.reflect.Proxy.getProxyClass(ClassLoader, Class<?>[])`, then tries to determine the list of interfaces that define dynamic proxies automatically. Given the list of interfaces, Native Image generates proxy classes at image build time and adds them to the native image heap.
+Native Image employs a simple static analysis that detects calls to `java.lang.reflect.Proxy.newProxyInstance(ClassLoader, Class<?>[], InvocationHandler)` and `java.lang.reflect.Proxy.getProxyClass(ClassLoader, Class<?>[])`, then tries to determine the list of interfaces that define dynamic proxies automatically.
+Given the list of interfaces, Native Image generates proxy classes at image build time and adds them to the native image heap.
 In addition to generating the dynamic proxy class, the constructor of the generated class that takes a `java.lang.reflect.InvocationHandler` argument, i.e., the one reflectively invoked by `java.lang.reflect.Proxy.newProxyInstance(ClassLoader, Class<?>[], InvocationHandler)`, is registered for reflection so that dynamic proxy instances can be allocated at run time.
 
 The analysis is limited to situations where the list of interfaces comes from a constant array or an array that is allocated in the same method.

docs/reference-manual/native-image/DynamicProxy.md

@@ -6,8 +6,7 @@ permalink: /reference-manual/native-image/HostedvsRuntimeOptions/
 ---
 # Native Image Hosted and Runtime Options
 
-Along with all the options listed in the [Options](Options.md)
-guide,  Native Image also distinguishes hosted and runtime options.
+Along with all the options listed in the [Options](Options.md) guide, Native Image also distinguishes hosted and runtime options.
 
 * Hosted options: configure a native image build, i.e., influence what is put into the image and how the image is built.
 These are set using the prefix `-H:` on the command line.
@@ -19,15 +18,11 @@ For developer documentation on how to define and use options, read the documenta
 ## List of Useful Options
 
 ### Graph Dumping
-Native Image re-used the GraalVM options for graph dumping, logging, counters,
-and everything else in the GraalVM debug environment. These GraalVM options can
-be used both as hosted options (if you want to dump graphs of the native image
-builder), and as runtime options (if you want to dump graphs during dynamic
+Native Image re-used the GraalVM options for graph dumping, logging, counters, and everything else in the GraalVM debug environment.
+These GraalVM options can be used both as hosted options (if you want to dump graphs of the native image builder), and as runtime options (if you want to dump graphs during dynamic
 compilation at runtime).
 
-The GraalVM compiler options that work as expected include `Dump`, `DumpOnError`, `Log`,
-`MethodFilter`, and the options to specify file names and ports for the dump
-handlers.
+The GraalVM compiler options that work as expected include `Dump`, `DumpOnError`, `Log`, `MethodFilter`, and the options to specify file names and ports for the dump handlers.
 
 For example:
 * To dump the compiler graphs of the native image builder: `-H:Dump= -H:MethodFilter=ClassName.MethodName`.