Proofread documentation
MODIFY
docs/modules/ROOT/pages/cli.adoc
docs/modules/ROOT/pages/cli.adoc
There are two basic ways to make AsciidoctorJ available as a command line tool.
* Manual installation using the binary distribution.
-* Automatic installation using a package manager like {url-sdkman}[SDKMAN^] or {url-chocolatey}[Chocolately^].
+* Automatic installation using a package manager like {url-sdkman}[SDKMAN^] or {url-chocolatey}[Chocolatey^].
== Manual distribution installation
@@ -29,7 +29,7 @@ Linux: asciidoctorj-{artifact-version}/bin/asciidoctorj
Windows: asciidoctorj-{artifact-version}\bin\asciidoctorj.bat
----
-Next, say you want to convert an ASCIIDOC (.adoc) file to a pdf.
+Next, say you want to convert an AsciiDoc (.adoc) file to a pdf.
[source]
[subs="specialcharacters,attributes,callouts"]

MODIFY
docs/modules/ROOT/pages/conversion-examples.adoc
docs/modules/ROOT/pages/conversion-examples.adoc
= Examples
Here you will find simple but complete examples of how to convert documents using the different configuration options available.
-The examples cover the main scenarios, but you can mix and match usage of instances, builders and maps freely to suite yous needs.
+The examples cover the main scenarios, but you can mix and match usage of instances, builders and maps freely to suite yours needs.
== Setting attributes and options as instances

MODIFY
docs/modules/ROOT/pages/read-document-tree.adoc
docs/modules/ROOT/pages/read-document-tree.adoc
= Read the Document Tree
Instead of converting an AsciiDoc document, you may want to parse the document to read information it contains or navigate the document's structure.
-AsciidoctorJ let's you do this!
+AsciidoctorJ lets you do this!
AsciidoctorJ provides a model of the abstract syntax tree of the document.
These objects are directly linked to the internal representation.

MODIFY
docs/modules/ROOT/pages/ruby-runtime.adoc
docs/modules/ROOT/pages/ruby-runtime.adoc
@@ -5,7 +5,7 @@ Even though AsciidoctorJ tries to hide as much as possible there are some points
Every Asciidoctor instance uses and initializes its own Ruby runtime.
As booting a Ruby runtime takes a considerable amount of time it is wise to either use a single instance or pool multiple instances in case your program wants to render multiple documents instead of creating one Asciidoctor instance per conversion.
-Asciidoctor itself is threadsafe, so from this point of view there is no issue in starting only one instance.
+Asciidoctor itself is thread-safe, so from this point of view there is no issue in starting only one instance.
The JRuby runtime can be configured in numerous ways to change the behavior as well as the performance.
As the performance requirements vary between a program that only render a single document and quit and server application that run for a long time you should consider modifying these options for your own use case.

MODIFY
docs/modules/ROOT/partials/safe-modes.adoc
docs/modules/ROOT/partials/safe-modes.adoc
@@ -30,7 +30,7 @@ Additionally, it:
* disables icons
* disables the `include` directive
* data can not be retrieved from URIs
-* prevents access to stylesheets and JavaScripts
+* prevents access to stylesheets and JavaScript files
* sets the backend to `html5`
* disables `docinfo` files
* disables `data-uri`

MODIFY
docs/modules/extensions/pages/ast-introduction.adoc
docs/modules/extensions/pages/ast-introduction.adoc
@@ -78,4 +78,4 @@ Phrase nodes are usually created by inline macro extensions that process macros
Nodes are in general only created from within extensions.
Therefore the abstract base class of all extensions, `org.asciidoctor.extension.Processor`, has factory methods for every node type.
-Now that you have learned about the AST structure you can go into the details of writting the extensions.
+Now that you have learned about the AST structure you can go into the details of writing the extensions.

MODIFY
docs/modules/extensions/pages/block-macro-processor.adoc
docs/modules/extensions/pages/block-macro-processor.adoc
@@ -46,10 +46,10 @@ include::example$gist-macro.adoc[]
== Attributes and Positional attributes
-As a next step for the gist macro we might want to add support for Gitlab Snippets, which are a similar system to Github Gists.
-The property whether we want to embed a Github Gist or a Gitlab Snippet can be passed as the first attribute to the macro.
+As a next step for the gist macro we might want to add support for GitLab Snippets, which are a similar system to Github Gists.
+The property whether we want to embed a Github Gist or a GitLab Snippet can be passed as the first attribute to the macro.
-Gitlab Snippets can also be part of a project.
+GitLab Snippets can also be part of a project.
This project could be accepted as a second attribute.
That way Gists or Snippets could be embedded with our macro with these AsciiDoc block macros:
@@ -62,11 +62,11 @@ include::example$gist-macro-attributes.adoc[]
The first macro shows our original notation for how to embed a Github Gist.
-The second macro shows how to embed a Snippet from Gitlab that is not associated with a project.
+The second macro shows how to embed a Snippet from GitLab that is not associated with a project.
-The third macro shows how to embed a Snippet from Gitlab that is associated with the project `gitlab-org/gitlab-foss`.
+The third macro shows how to embed a Snippet from GitLab that is associated with the project `gitlab-org/gitlab-foss`.
-The last macro shows how to embed a Snippet from Gitlab that is associated with the project `gitlab-org/gitlab-foss` by not using a positional attribute, but instead naming it explicitly.
+The last macro shows how to embed a Snippet from GitLab that is associated with the project `gitlab-org/gitlab-foss` by not using a positional attribute, but instead naming it explicitly.
This can be achieved by the following extension:

MODIFY
docs/modules/extensions/pages/conversion-process-overview.adoc
docs/modules/extensions/pages/conversion-process-overview.adoc
@@ -6,7 +6,7 @@ As any language processing tool, the process can be roughly split into three ste
. Parsing: the raw sources content is read and analyzed to generate the internal representation, the AST (_abstract syntax tree_).
. Processing: the AST is processed. For example to detect possible errors, add automatically generated content (toc), etc.
. Output generation: once the final AST is set, it's again processed to generate the desired output.
-For example, a sub-section of the AST representing a title with a paragraph will be converted into its correspondent HTML or PDF output.
+For example, a subsection of the AST representing a title with a paragraph will be converted into its correspondent HTML or PDF output.
NOTE: Some liberty is taken to make the process easier to understand.
In reality, Asciidoctor has implementation details that divert from the 3 steps above.
@@ -16,7 +16,7 @@ The different extension types are called in different steps of the conversion pr
. Preprocessors are called when the parser requires the AsciiDoc source to parse.
. IncludeProcessors are called whenever an `include::` directive is found while reading the AsciiDoc source.
. BlockMacroProcessors and BlockProcessors are called while parsing in the order that they appear in the source document.
-. TreeProcessors are called after the document has been completely parsed into the Document tree right before processing.
+. Treeprocessors are called after the document has been completely parsed into the Document tree right before processing.
. InlineMacroProcessors are called during output generation in the order that they appear in the document.
. DocinfoProcessors are called at the beginning of output generation if they add content to the header.
And they are called at the end of output generation if they add content to the footer.

MODIFY
docs/modules/extensions/pages/extensions-introduction.adoc
docs/modules/extensions/pages/extensions-introduction.adoc
@@ -12,12 +12,12 @@ If you are migrating existing extensions to a newer version, please see the guid
====
Writing an extension is as simple as creating a Java class and sub-classing from one of the extension points.
-However, to explore the full potential it us recommended to:
+However, to explore the full potential it's recommended to:
. Have a brief understanding of the AsciidoctorJ conversion process and internal representation of the document.
In short, extensions allow you to tap into the conversion process to make modifications to enhance the generated content.
. Write an extension class.
-This is as simple as creating a sub-class from one of the extension points listed below.
+This is as simple as creating a subclass from one of the extension points listed below.
. Register your class to make AsciidoctorJ converter aware of it.
There several options depending on the use case.

MODIFY
docs/modules/extensions/pages/treeprocessor.adoc
docs/modules/extensions/pages/treeprocessor.adoc
A Treeprocessor gets the whole AST and may do whatever it likes with the document tree.
Examples for Treeprocessors could insert blocks, add roles to nodes with a certain content, etc.
-Treeprocessors are called by Asciidoctor at the end of the loading process after Preprocessors, Block processors, Macro processors and Include processors but before Postprocessors that are called after the conversion process.
+Treeprocessors are called by Asciidoctor at the end of the loading process after Preprocessors, BlockProcessors, MacroProcessors and IncludeProcessors but before Postprocessors that are called after the conversion process.
Our example Treeprocessor will recognize paragraphs that contain terminal scripts like below, make listing blocks from them and add the role `terminal`.
The custom role will allows us to customize the style.
@@ -21,7 +21,7 @@ The result when rendering this document with our Treeprocessor should be the sam
include::example$treeprocessorresult.adoc[]
....
-Note that a Blockprocessor would not work for this task, as a Blockprocessor requires a block name for which it is called.
+Note that a BlockProcessor would not work for this task, as a BlockProcessor requires a block name for which it is called.
However, in this case the only way to identify this type of blocks is the beginning of the first line.
The Treeprocessor could look like this:

MODIFY
docs/modules/project/pages/project-layout.adoc
docs/modules/project/pages/project-layout.adoc
= Project Layout
-The project is structured as a multi-module {url-gradle}[Gradle] build.
+The project is structured as a multimodule {url-gradle}[Gradle] build.
The root folder is the root project and there are several subproject folders, each prefixed with _asciidoctorj-_.
Each subproject produces a primary artifact (e.g., jar or zip) and its supporting artifacts (e.g., javadoc, sources, etc).
@@ -32,7 +32,7 @@ asciidoctorj-test-support::
Contains some common test classes that are used by multiple other subprojects and the Arquillian extension.
asciidoctorj-wildfly-integration-test::
- Wildfly integration tests.
+ WildFly integration tests.
asciidoctorj-springboot-integration-test::
Spring Boot example app and integration tests.

MODIFY
docs/modules/syntax-highlighting/pages/static-during-conversion.adoc
docs/modules/syntax-highlighting/pages/static-during-conversion.adoc
= Static Syntax Highlighting During Conversion
The examples we looked at until now did the actual syntax highlighting in the browser.
-But there are also cases where it is desirable to highlight the source during conversion, either because the syntax highlighter is implemented in Java, or syntax highlighting should also work when Javascript is not enabled at the client.
+But there are also cases where it is desirable to highlight the source during conversion, either because the syntax highlighter is implemented in Java, or syntax highlighting should also work when JavaScript is not enabled at the client.
The following example uses {url-prismjs}[prism.js] to show how to achieve this:
When a `SyntaxHighlighterAdapter` also implements the interface `org.asciidoctor.syntaxhighlighter.Highlighter` it will be called to convert the raw source text to HTML.
-The example uses {url-prismjs}[prism.js] which is also a Javascript library.
-But now we will call this library during document conversion and only add the css part in the resulting HTML, so that the highlighted source will appear correctly even if Javascript is disabled on the client.
+The example uses {url-prismjs}[prism.js] which is also a JavaScript library.
+But now we will call this library during document conversion and only add the css part in the resulting HTML, so that the highlighted source will appear correctly even if JavaScript is disabled on the client.
[source,java]
----
include::example$org/asciidoctor/integrationguide/syntaxhighlighter/PrismJsHighlighter.java[tags=include]
----
<1> A syntax highlighter that wants to statically convert the source text has to implement the interface `org.asciidoctor.syntaxhighlighter.Highlighter`.
-<2> We use the Nashorn Javascript engine to run prism.js.
+<2> We use the Nashorn JavaScript engine to run prism.js.
<3> When rendering to a file and the attributes `:linkcss` and `:copycss` are set the css file of prism.js should be written to disk.
Otherwise we include the content in a `<style/>` element.
<4> `highlight()` is the only method required by the `Highlighter` interface.

Proofread documentation