Update documentation

Author: fmbenhassine

spring-shell-docs/modules/ROOT/pages/appendices/techintro/index.adoc

@@ -1,6 +1,6 @@
 [appendix]
 [#appendix-tech-intro]
-= Techical Introduction
+= Technical Introduction
 :page-section-summary-toc: 1
 
 This appendix contains information for developers and others who would like to know more about how Spring Shell

spring-shell-docs/modules/ROOT/pages/appendices/tui/catalog.adoc

@@ -4,10 +4,10 @@
 
 ifndef::snippets[:snippets: ../../../../../src/test/java/org/springframework/shell/docs]
 
-Catalog application is showing various ways how Terminal UI Framework can be used.
-In this section we discuss how this application works. It can be considered to be
+Catalog application shows various ways how the Terminal UI Framework can be used.
+In this section, we discuss how this application works. It can be considered as
 a reference application as it's using most of the features available and tries
-to follow best practices.
+to follow the best practices.
 
 [[create-scenario]]
 == Create Scenario

spring-shell-docs/modules/ROOT/pages/appendices/tui/index.adoc

@@ -5,9 +5,9 @@
 
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
-This is a technical introduction to _UI Framework_.
+This is a technical introduction to the _UI Framework_.
 
-_UI Framework_ is a toolkit to build rich console apps.
+The _UI Framework_ is a toolkit to build rich console apps.
 
 
 

spring-shell-docs/modules/ROOT/pages/appendices/tui/viewdev.adoc

@@ -2,7 +2,7 @@
 = View Development
 :page-section-summary-toc: 1
 
-While a _view_ just need to implement `View` it's usually convenient to just
+While a _view_ just needs to implement `View`, it's usually convenient to just
 use `BoxView` as a parent.
 
 [[register-bindings]]

spring-shell-docs/modules/ROOT/pages/basics/reading.adoc

@@ -5,13 +5,13 @@
 Throughout this documentation, we make references to configuring something by using
 annotations or programmatic examples.
 
-NOTE: There are two annotation models, xref:commands/registration/annotation.adoc[annotations]
-referred to new annotation model, xref:commands/registration/legacyannotation.adoc[legacy annotations]
-referred to old legacy annotation model.
+NOTE: There are two annotation models: the xref:commands/registration/annotation.adoc[annotations] model
+referred to as the new annotation model, and the xref:commands/registration/legacyannotation.adoc[legacy annotations]
+model referred to as the old legacy annotation model.
 
-Old legacy annotation model mostly relates to use of `@ShellMethod` and `@ShellOption` and
-new annotation model relates to use of `@Command`.
+The old legacy annotation model mostly relates to the use of `@ShellMethod` and `@ShellOption` and
+the new annotation model relates to the use of `@Command`.
 
 The programmatic model is how things are actually registered, even if you use annotations.
 
-NOTE: The documentation structure is getting revised to clarify how to provide configurations in separate ways. Thank you for understanding while that work is still in progress. 
+NOTE: The documentation structure is getting revised to clarify how to provide configurations in separate ways.

spring-shell-docs/modules/ROOT/pages/building.adoc

@@ -25,17 +25,17 @@ traditionally been relatively complex process while it may look like
 there's not that much happening as it's all just text.
 
 Remember all those old manual typewriters or matrix printers?
-A character is printed where a cursor is which then need to be moved
+A character is printed then a cursor needs to be moved
 if printing in a different position. In a nutshell that's how current
 terminal emulators work.
 
-To access and understand existing terminal emulator environment better
+To access and understand existing terminal emulators environment better,
 JLine can use native code via its own shared libraries. JLine detects
 which providers are present and then makes a choice which one to use.
 Traditionally there's been 3 providers, `jansi`, `jni` and `jna` which
 should all provide same functionalities.
 
-Our starters can be used to spesifically pick some of these JLine
+Our starters can be used to specifically pick some of these JLine
 providers.
 
 == FFM
@@ -127,7 +127,7 @@ When gradle build is run with `./gradlew nativeCompile` you should get binary
 under `build/native/nativeCompile` directory.
 
 For `maven` use `spring-boot-starter-parent` as parent and you'll get `native`
-profile which can be used to do a compilation. You need to configure metadata repository
+profile which can be used to do a native compilation. You need to configure metadata repository:
 
 [source, xml, subs=attributes+]
 ----

spring-shell-docs/modules/ROOT/pages/commands/alias.adoc

@@ -8,10 +8,9 @@ cases where you want to create a shorter version of a command or going
 through a complete command rename while keeping old one temporarily in
 place.
 
-Format for _alias_ is slighly different than a _command_. When _command_
+The format of _alias_ is slightly different from a _command_. When _command_
 is defined as an array it's concatenated together into a single command.
-When _alias_ is defined as an array it's used to create a separate
-aliases.
+When _alias_ is defined as an array it's used to create separate aliases.
 
 Aliases with a plain `CommandRegistration` is simple and clear as you
 get exactly what you define as there's no "magic" in it.

spring-shell-docs/modules/ROOT/pages/commands/builtin/clear.adoc

@@ -2,5 +2,5 @@
 = Clear
 :page-section-summary-toc: 1
 
-The `clear` command does what you would expect and clears the screen, resetting the prompt
+The `clear` command clears the screen, resetting the prompt
 in the top left corner.

spring-shell-docs/modules/ROOT/pages/commands/builtin/completion.adoc

@@ -2,8 +2,8 @@
 = Completion
 :page-section-summary-toc: 1
 
-The `completion` command set lets you create script files that can be used
-with am OS shell implementations to provide completion. This is very useful when
+The `completion` command lets you create script files that can be used
+with an OS shell implementation to provide completion. This is very useful when
 working with non-interactive mode.
 
-Currently, the only implementation is for bash, which works with `bash` sub-command.
+Currently, the only implementation is for bash, which works with the `bash` sub-command.

spring-shell-docs/modules/ROOT/pages/commands/builtin/help.adoc

@@ -2,9 +2,7 @@
 = Help
 
 Running a shell application often implies that the user is in a graphically limited
-environment. Also, while we are nearly always connected in the era of mobile phones,
-accessing a web browser or any other rich UI application (such as a PDF viewer) may not always
-be possible. This is why it is important that the shell commands are correctly self-documented, and this is where the `help`
+environment. This is why it is important that the shell commands are correctly self-documented, and this is where the `help`
 command comes in.
 
 Typing `help` + `ENTER` lists all the commands known to the shell (including xref:commands/availability.adoc[unavailable] commands)

spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/annotation.adoc

@@ -6,13 +6,13 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 `@ShellComponent` classes can have `@ExceptionResolver` methods to handle exceptions from component
 methods. These are meant for annotated methods.
 
-The exception may match against a top-level exception being propagated (e.g. a direct IOException
-being thrown) or against a nested cause within a wrapper exception (e.g. an IOException wrapped
-inside an IllegalStateException). This can match at arbitrary cause levels.
+The exception may match against a top-level exception being propagated (e.g. a direct `IOException`
+being thrown) or against a nested cause within a wrapper exception (e.g. an `IOException` wrapped
+inside an `IllegalStateException`). This can match at arbitrary cause levels.
 
 For matching exception types, preferably declare the target exception as a method argument, as
 the preceding example(s) shows. When multiple exception methods match, a root exception match is
-generally preferred to a cause exception match. More specifically, the ExceptionDepthComparator
+generally preferred to a cause exception match. More specifically, the `ExceptionDepthComparator`
 is used to sort exceptions based on their depth from the thrown exception type.
 
 Alternatively, the annotation declaration may narrow the exception types to match, as the
@@ -38,7 +38,7 @@ include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-exitc
 
 `@ExceptionResolver` with `void` return type is automatically handled as handled exception.
 You can then also define `@ExitCode` and use `Terminal` if you need to write something
-into console.
+into the console:
 
 [source, java, indent=0]
 ----

spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/index.adoc

@@ -4,15 +4,15 @@
 
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
-Exceptions happen from a user code wether it is intentional or not. This section describes
-how `spring-shell` handles exceptions and gives instructions and best practices how to
+Exceptions happen from a user code whether it is intentional or not. This section describes
+how Spring Shell handles exceptions and gives instructions and best practices on how to
 work with it.
 
-Many command line applications when applicable return an _exit code_ which running environment
-can use to differentiate if command has been executed successfully or not. In a `spring-shell`
-this mostly relates when a command is run on a non-interactive mode meaning one command
-is always executed once with an instance of a `spring-shell`. Take a note that _exit code_
-always relates to non-interactive shell.
+Many command line applications return an _exit code_ which can be used by the
+running environment to differentiate if command has been executed successfully or not.
+In Spring Shell, this mostly relates to when a command is run in a non-interactive mode,
+meaning one command is always executed once with an instance of a `spring-shell`. Take a note
+that _exit code_ always relates to non-interactive shell.
 
 
 

spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/mappings.adoc

@@ -5,15 +5,15 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Default behaviour of an exit codes is as:
 
-- Errors from a command option parsing will result code of `2`
-- Any generic error will result result code of `1`
-- Obviously in any other case result code is `0`
+- Errors from a command option parsing will result to a code of `2`
+- Any generic error will result to a code of `1`
+- Obviously in any other case will result to a code of `0`
 
 Every `CommandRegistration` can define its own mappings between _Exception_ and _exit code_.
-Essentially we're bound to functionality in `Spring Boot` regarding _exit code_ and simply
+Spring shell uses a similar approach to `Spring Boot` regarding _exit code_ and simply
 integrate into that.
 
-Assuming there is an exception show below which would be thrown from a command:
+Assuming there is an exception shown below which would be thrown from a command:
 
 [source, java, indent=0]
 ----

spring-shell-docs/modules/ROOT/pages/commands/exceptionhandling/resolving.adoc

@@ -5,23 +5,23 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Unhandled exceptions will bubble up into shell's `ResultHandlerService` and then eventually
 handled by some instance of `ResultHandler`. Chain of `ExceptionResolver` implementations
-can be used to resolve exceptions and gives you flexibility to return message to get written
-into console together with exit code which are wrapped within `CommandHandlingResult`.
+can be used to resolve exceptions and gives you the flexibility to return a message to get
+written into the console together with exit code which are wrapped within `CommandHandlingResult`.
 `CommandHandlingResult` may contain a _message_ and/or _exit code_.
 
 [source, java, indent=0]
 ----
 include::{snippets}/ErrorHandlingSnippets.java[tag=my-exception-resolver-class]
 ----
 
-`CommandExceptionResolver` implementations can be defined globally as bean.
+`CommandExceptionResolver` implementations can be defined globally as beans:
 
 [source, java, indent=0]
 ----
 include::{snippets}/ErrorHandlingSnippets.java[tag=my-exception-resolver-class-as-bean]
 ----
 
-or defined per `CommandRegistration` if it's applicable only for a particular command itself.
+or defined per `CommandRegistration` if it's applicable only to a particular command:
 
 [source, java, indent=0]
 ----
@@ -31,18 +31,18 @@ include::{snippets}/ErrorHandlingSnippets.java[tag=example1]
 NOTE: Resolvers defined with a command are handled before global resolvers.
 
 
-Use you own exception types which can also be an instance of boot's `ExitCodeGenerator` if
-you want to define exit code there.
+You can use your own exception types which can also be instances of Spring Boot's `ExitCodeGenerator`
+if you want to define exit code there:
 
 [source, java, indent=0]
 ----
 include::{snippets}/ErrorHandlingSnippets.java[tag=my-exception-class]
 ----
 
-Some build in `CommandExceptionResolver` beans are registered to handle common
+Some built-in `CommandExceptionResolver` beans are registered to handle common
 exceptions thrown from command parsing. These are registered with _order_
-presedence defined in `CommandExceptionResolver.DEFAULT_PRECEDENCE`.
+precedence defined in `CommandExceptionResolver.DEFAULT_PRECEDENCE`.
 As these beans are used in a given order, `@Order` annotation or `Ordered`
-interface from can be used just like in any other spring app. This
+interface can be used just like in any other Spring app. This
 is generally useful if you need to control your own beans to get used
-either before or after a defaults.
+either before or after default ones.

spring-shell-docs/modules/ROOT/pages/commands/helpoptions.adoc

@@ -5,22 +5,22 @@ ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 _Spring Shell_ has a build-in `help` command but not all favour getting command help
 from it as you always need to call it with arguments for target command. It's
-common in many cli frameworks for every command having options _--help_ and _-h_
+common in many CLI frameworks for every command having options _--help_ and _-h_
 to print out command help.
 
 Default functionality is that every command will get modified to have options
 _--help_ and _-h_, which if present in a given command will automatically
-short circuit command execution into a existing `help` command regardless
-what other command-line options is typed.
+short circuit command execution into an existing `help` command regardless
+what other command-line options are typed.
 
-Below example shows its default settings.
+The following example shows its default settings:
 
 [source, java, indent=0]
 ----
 include::{snippets}/CommandRegistrationHelpOptionsSnippets.java[tag=defaults]
 ----
 
-It is possible to change default behaviour via configuration options.
+It is possible to change default behaviour via configuration options:
 
 [source, yaml]
 ----
@@ -33,6 +33,6 @@ spring:
       command: help
 ----
 
-NOTE: Commands defined programmationally or via annotations will automatically add
-help options. With annotation model you can only turn things off globally, programmatic
-model gives option to modify settings per command.
+NOTE: Commands defined programmatically or via annotations will automatically add
+help options. With the annotation model you can only turn things off globally, while
+with the programmatic model you can modify settings per command.

spring-shell-docs/modules/ROOT/pages/commands/hidden.adoc

@@ -4,18 +4,18 @@
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 It is possible to _hide_ a command which is convenient in cases where it is not yet ready for
-prime time, is meant for debugging purposes or you have any other reason you dont want to
-advertise its presense.
+prime time, or is meant for debugging purposes or you have any other reason you don't want to
+advertise its presence.
 
-Hidden command can be executed if you know it and its options. It is effectively removed
+A hidden command can be executed if you know it and its options. It is effectively removed
 from:
 
 * Help listing
 * Help page for command return "unknown command"
 * Command completion in interactive mode
 * Bash completion
 
-Below is an example how to define command as _hidden_. It shows available builder methods
+Below is an example of how to define _hidden_ command. It shows available builder methods
 to define _hidden_ state.
 
 [source, java, indent=0]

spring-shell-docs/modules/ROOT/pages/commands/index.adoc

@@ -5,7 +5,7 @@
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 In this section, we go through an actual command registration and leave command options
-and execution for later in a documentation. You can find more detailed info in
+and execution for a later section in the documentation. You can find more details in
 xref:appendices/techintro/registration.adoc[Command Registration].
 
 

spring-shell-docs/modules/ROOT/pages/commands/interactionmode.adoc

@@ -5,9 +5,9 @@
 ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs]
 
 Command registration can define `InteractionMode` which is used to hide commands
-depending which mode shell is executing. More about that in xref:execution.adoc#using-shell-execution-interactionmode[Interaction Mode].
+depending on which mode the shell is executing in. More about that in xref:execution.adoc#using-shell-execution-interactionmode[Interaction Mode].
 
-You can define it with `CommandRegisration`.
+You can define the interaction mode with `CommandRegisration`:
 
 [source, java, indent=0]
 ----

spring-shell-docs/modules/ROOT/pages/commands/registration/index.adoc

@@ -4,14 +4,13 @@
 
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
-There are two different ways to define a command: through an annotation model and
-through a programmatic model. In the annotation model, you define your methods
-in a class and annotate the class and the methods with specific annotations.
-In the programmatic model, you use a more low level approach, defining command
-registrations (either as beans or by dynamically registering with a command catalog).
+There are two different ways to define a command. through an annotation model and through a programmatic model:
 
-Starting from _3.1.x_ a better support for defining commands using
-xref:commands/registration/annotation.adoc[annotations] were added. Firstly because eventually standard
+- In the annotation model, you define your methods in a class and annotate the class and the methods with specific annotations.
+- In the programmatic model, you use a more low level approach, defining command registrations (either as beans or by dynamically registering with a command catalog).
+
+Starting from version _3.1.x_, a better support for defining commands using
+xref:commands/registration/annotation.adoc[annotations] was added. Firstly because eventually standard
 package providing xref:commands/registration/legacyannotation.adoc[legacy annotations] will get deprecated
 and removed. Secondly so that we're able to provide same set of features than using underlying
 `CommandRegistration`. Creating a new annotation model allows us to rethink and modernise that

spring-shell-docs/modules/ROOT/pages/commands/registration/programmatic.adoc

@@ -19,7 +19,7 @@ a new builder so you don't need to worry about its internal state.
 IMPORTANT: Commands registered programmatically automatically
 add _help options_ mentioned in xref:commands/helpoptions.adoc[Help Options].
 
-If bean of this supplier type is defined then auto-configuration
+If a bean of this supplier type is defined then auto-configuration
 will back off giving you an option to redefine default functionality.
 
 [source, java, indent=0]
@@ -28,7 +28,7 @@ include::{snippets}/CommandRegistrationBeanSnippets.java[tag=fromsupplier]
 ----
 
 `CommandRegistrationCustomizer` beans can be defined if you want to centrally
-modify builder instance given you by supplier mentioned above.
+modify builder instance given to you by a supplier as mentioned below:
 
 [source, java, indent=0]
 ----

spring-shell-docs/modules/ROOT/pages/completion.adoc

@@ -18,8 +18,8 @@ methods which takes `CompletionContext` and returns a list of
 `CompletionProposal` instances. `CompletionContext` gives you various
 information about a current context like command registration and option.
 
-NOTE: Generic resolvers can be registered as a beans if those are useful
-for all commands and scenarious. For example existing completion
+NOTE: Generic resolvers can be registered as beans if those are useful
+for all commands and scenarios. For example existing completion
 implementation `RegistrationOptionsCompletionResolver` handles completions
 for a option names.