From d72fe54346aa6963ae835f48681fa1ed917fb3fe Mon Sep 17 00:00:00 2001 From: Guillaume Grossetie Date: Mon, 22 Aug 2022 20:47:27 +0200 Subject: proofread documentation (PR #4336) --- docs/modules/ROOT/pages/features.adoc | 2 +- docs/modules/ROOT/pages/localization-support.adoc | 2 +- docs/modules/ROOT/pages/safe-modes.adoc | 2 +- docs/modules/ROOT/pages/whats-new.adoc | 4 ++-- docs/modules/api/pages/catalog-assets.adoc | 2 +- docs/modules/api/pages/convert-files.adoc | 2 +- docs/modules/api/pages/convert-strings.adoc | 6 +++--- docs/modules/api/pages/sourcemap.adoc | 2 +- docs/modules/convert/pages/templates.adoc | 2 +- docs/modules/extensions/pages/index.adoc | 2 +- docs/modules/html-backend/pages/custom-stylesheet.adoc | 4 ++-- docs/modules/install/pages/linux-packaging.adoc | 2 +- docs/modules/install/pages/windows.adoc | 8 ++++---- docs/modules/migrate/pages/asciidoc-py.adoc | 4 ++-- docs/modules/migrate/pages/ms-word.adoc | 10 +++++----- docs/modules/stem/pages/mathematical.adoc | 2 +- docs/modules/syntax-highlighting/pages/index.adoc | 2 +- docs/modules/syntax-highlighting/pages/pygments.adoc | 4 ++-- docs/modules/tooling/pages/index.adoc | 2 +- 19 files changed, 32 insertions(+), 32 deletions(-) (limited to 'docs') diff --git a/docs/modules/ROOT/pages/features.adoc b/docs/modules/ROOT/pages/features.adoc index dc481c2f..f2b9c143 100644 --- a/docs/modules/ROOT/pages/features.adoc +++ b/docs/modules/ROOT/pages/features.adoc @@ -93,7 +93,7 @@ Asciidoctor offers two interfaces for processing AsciiDoc content: a commandline The *CLI* is designed as a simple tool for non-programmers who want to convert AsciiDoc without having to write a program or for converting content in an automated environment such as CI. Many of the processing options are accessible from the CLI using option flags. When you're first starting out with Asciidoctor, you'll mostly likely interact with it via the CLI. -Although the CLI itself does not require any programming, it can still load extension code that auguments processing. +Although the CLI itself does not require any programming, it can still load extension code that augments processing. NOTE: If you're migrating from AsciiDoc.py, the `asciidoctor` CLI is a drop-in replacement for the `asciidoc` CLI. diff --git a/docs/modules/ROOT/pages/localization-support.adoc b/docs/modules/ROOT/pages/localization-support.adoc index 33445b71..1a4fcaae 100644 --- a/docs/modules/ROOT/pages/localization-support.adoc +++ b/docs/modules/ROOT/pages/localization-support.adoc @@ -149,7 +149,7 @@ Of course, you're probably hoping this has already been done for you. Indeed, it has! You can find an {url-lang-attributes}[AsciiDoc file^] in the Asciidoctor repository that provides translations of these attributes for most major languages. -Thus far, the built-in labels have been translated into the following languages: Arabic, Belarusian, Bulgarian, Catalan, Czech, Danish, Dutch, German, Spanish, Persian (Farsi), Finnish, French, Hungarian, Bahasa Indonesian, Italian, Japanese, Korean, Norweign Bokmål, Norwegian Nynorsk, Polish, Portuguese, Brazilian Portuguese, Romanian, Russian, Serbian Cyrillic, Serbian Latin, Swedish, Turkish, Ukrainian, Vietnamese, Simplified Chinese, and Traditional Chinese. +Thus far, the built-in labels have been translated into the following languages: Arabic, Belarusian, Bulgarian, Catalan, Czech, Danish, Dutch, German, Spanish, Persian (Farsi), Finnish, French, Hungarian, Bahasa Indonesian, Italian, Japanese, Korean, Norwegian Bokmål, Norwegian Nynorsk, Polish, Portuguese, Brazilian Portuguese, Romanian, Russian, Serbian Cyrillic, Serbian Latin, Swedish, Turkish, Ukrainian, Vietnamese, Simplified Chinese, and Traditional Chinese. The translations are defined using AsciiDoc attribute entries inside conditional preprocessor blocks, just as suggested above. To use this file to translate the built-in labels according the value of the `lang` attribute (just like the DocBook toolchain does), follow these steps: diff --git a/docs/modules/ROOT/pages/safe-modes.adoc b/docs/modules/ROOT/pages/safe-modes.adoc index 395ac728..045ba7fe 100644 --- a/docs/modules/ROOT/pages/safe-modes.adoc +++ b/docs/modules/ROOT/pages/safe-modes.adoc @@ -60,7 +60,7 @@ Additionally, it: * disables icons * disables include directives (`+include::[]+`) * 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` diff --git a/docs/modules/ROOT/pages/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc index 1cb9cd1d..cb663468 100644 --- a/docs/modules/ROOT/pages/whats-new.adoc +++ b/docs/modules/ROOT/pages/whats-new.adoc @@ -24,7 +24,7 @@ _**Release date:** 2022.01.05_ * Change `AbstractBlock#sections?` to return false when called on block that isn't a Section or Document (PR #3591) (*@Mogztter*) * Hide built-in marker on HTML summary element in Safari when using default stylesheet (#4162) * Hide outline around HTML summary when activated in Safari (#4162) -* Include primary video in value of playlist attribute when embeddding YouTube video (#4156) +* Include primary video in value of playlist attribute when embedding YouTube video (#4156) * Honor `stripes=none` on nested table (#4165) * Update default stylesheet to fix spacing around empty list item (#4184) * Honor `:header_only` option when parsing document with manpage doctype (#4192) @@ -508,7 +508,7 @@ _**Release date:** 2019.03.22_ == Improvements * Propagate document ID to DocBook output (#3011) -* Always store section numeral as string; compute roman numeral for part at assignment time (@vmj) +* Always store section numeral as string; compute Roman numeral for part at assignment time (@vmj) * Refactor code to use modern Hash syntax * Define `LIB_DIR` constant; rename *_PATH constants to *_DIR constants to be consistent with RubyGems terminology (#2764) * Only define `ROOT_DIR` if not already defined (for compatibility with Asciidoctor.js) diff --git a/docs/modules/api/pages/catalog-assets.adoc b/docs/modules/api/pages/catalog-assets.adoc index 6ba2d043..663c78fa 100644 --- a/docs/modules/api/pages/catalog-assets.adoc +++ b/docs/modules/api/pages/catalog-assets.adoc @@ -176,7 +176,7 @@ In the output, the image references will be shown as absolute paths. === :refs In addition to images and links, you can also access all targetable references (i.e., elements that have an ID). -First, let's add some referencable elements to our document. +First, let's add some referenceable elements to our document. [,asciidoc] ---- diff --git a/docs/modules/api/pages/convert-files.adoc b/docs/modules/api/pages/convert-files.adoc index 8eb3cb91..94dcfdb0 100644 --- a/docs/modules/api/pages/convert-files.adoc +++ b/docs/modules/api/pages/convert-files.adoc @@ -1,7 +1,7 @@ = Load and Convert Files Using the API :navtitle: Load and Convert Files -This page explains how to load and convert AsciiDoc-formatted files using the API. +This page explains how to load and convert AsciiDoc files using the API. == Load an AsciiDoc file diff --git a/docs/modules/api/pages/convert-strings.adoc b/docs/modules/api/pages/convert-strings.adoc index 25efb655..c4ef8d3c 100644 --- a/docs/modules/api/pages/convert-strings.adoc +++ b/docs/modules/api/pages/convert-strings.adoc @@ -1,12 +1,12 @@ = Load and Convert Strings Using the API :navtitle: Load and Convert Strings -This page explains how to load and convert AsciiDoc-formatted strings using the API. +This page explains how to load and convert AsciiDoc strings using the API. A string is the bare AsciiDoc content (often the contents of a file). == Load an AsciiDoc string -To parse an AsciiDoc-formatted string into a document object model, use: +To parse an AsciiDoc string into a document object model, use: [source,ruby] ---- @@ -32,7 +32,7 @@ However, if you're only interested in converting the AsciiDoc source when using == Convert an AsciiDoc string -To convert the AsciiDoc-formatted string directly to HTML, use: +To convert the AsciiDoc string directly to HTML, use: [source,ruby] ---- diff --git a/docs/modules/api/pages/sourcemap.adoc b/docs/modules/api/pages/sourcemap.adoc index c65d494c..ed32891f 100644 --- a/docs/modules/api/pages/sourcemap.adoc +++ b/docs/modules/api/pages/sourcemap.adoc @@ -151,4 +151,4 @@ The lineno of the paragraph in the source location is now one greater than befor .... If you're writing a custom converter, the source location is not available for inline elements. -However, you can access the source location of the parent element (e.g., `node.parent.source_location`), which should at leasat get you close to the location of the element. +However, you can access the source location of the parent element (e.g., `node.parent.source_location`), which should at least get you close to the location of the element. diff --git a/docs/modules/convert/pages/templates.adoc b/docs/modules/convert/pages/templates.adoc index 94ab128e..7e0c087f 100644 --- a/docs/modules/convert/pages/templates.adoc +++ b/docs/modules/convert/pages/templates.adoc @@ -341,7 +341,7 @@ Refer to the documentation for the template engine for details. If you find yourself putting a lot of logic in the template, you may want to extract that logic into custom helper functions. When using Haml or Slim, you can define these helper functions in the file [.path]_helper.rb_ located in the same folder as the templates. -These helper functions can simplify reoccuring elements that appear across multiple templates. +These helper functions can simplify reoccurring elements that appear across multiple templates. The helper file must define the Ruby module `Haml::Helpers` or `Slim::Helpers`, depending on which template engine your templates target. Every method defined in that module becomes a top-level function in the template. diff --git a/docs/modules/extensions/pages/index.adoc b/docs/modules/extensions/pages/index.adoc index 33b35755..5b45fbc0 100644 --- a/docs/modules/extensions/pages/index.adoc +++ b/docs/modules/extensions/pages/index.adoc @@ -6,7 +6,7 @@ Asciidoctor provides an extension API that offers a superset of extension points As a result, extensions in Asciidoctor are easy to write, powerful, and simple to distribute. Asciidoctor also allows extensions to be written using the full power of a programming language (whether it be Ruby, Java, Groovy or JavaScript). -You don't have to shave yaks to get the functionality you want, and you can distribute the extension using defacto-standard packaging mechanisms like RubyGems or JARs. +You don't have to shave yaks to get the functionality you want, and you can distribute the extension using de facto standard packaging mechanisms like RubyGems or JARs. == Available extension points diff --git a/docs/modules/html-backend/pages/custom-stylesheet.adoc b/docs/modules/html-backend/pages/custom-stylesheet.adoc index 6bb57137..37f6ea14 100644 --- a/docs/modules/html-backend/pages/custom-stylesheet.adoc +++ b/docs/modules/html-backend/pages/custom-stylesheet.adoc @@ -100,7 +100,7 @@ Let's look at those problem and ways to work through them. [#stylesdir-and-linkcss] == Styles directory and linkcss -Using `stylesdir` gets tricky when your linking to the stylesheet instead of embedding it. +Using `stylesdir` gets tricky when you're linking to the stylesheet instead of embedding it. That's because we're now dealing with two different paths. One is the path where the stylesheet is located on disk (either absolute or relative to the document). The other is the path the browser uses to access the stylesheet. @@ -196,5 +196,5 @@ For [.path]_c.adoc_, set `stylesdir` to: :stylesdir: ../my-styles ---- -If you're serving your documents from a webserver, you can solve this problem by providing an absolute path to the stylesheet. +If you're serving your documents from a web server, you can solve this problem by providing an absolute path to the stylesheet. You can also try to use the `copycss` per document to control where Asciidoctor looks for the stylesheet independent of where Asciidoctor copies it and the converter configured the HTML to reference it. diff --git a/docs/modules/install/pages/linux-packaging.adoc b/docs/modules/install/pages/linux-packaging.adoc index afea37ea..ff2fa416 100644 --- a/docs/modules/install/pages/linux-packaging.adoc +++ b/docs/modules/install/pages/linux-packaging.adoc @@ -17,7 +17,7 @@ Consult the package repository for your distribution to find out which version i * {url-arch}[Arch Linux (asciidoctor)^] * {url-debian}[Debian (asciidoctor)^] * {url-fedora}[Fedora (asciidoctor)^] -* {url-suse}[OpenSUSE (rubygem-asciidoctor)^] +* {url-suse}[openSUSE (rubygem-asciidoctor)^] * {url-ubuntu}[Ubuntu (asciidoctor)^] If you want to use a version of Asciidoctor that is newer than what is available via your package manager, see xref:ruby-packaging.adoc[]. diff --git a/docs/modules/install/pages/windows.adoc b/docs/modules/install/pages/windows.adoc index 99d29b1e..05fff633 100644 --- a/docs/modules/install/pages/windows.adoc +++ b/docs/modules/install/pages/windows.adoc @@ -1,15 +1,15 @@ = Install on Windows -To install Asciidoctor on Windows, you can use Chocolatey or Rubyinstaller. +To install Asciidoctor on Windows, you can use Chocolatey or RubyInstaller. == Chocolatey -When you already use https://chocolatey.org[chocolatey^] on your machine, you can use: +When you already use https://chocolatey.org[Chocolatey^] on your machine, you can use: C:\> choco install ruby Then follow the xref:ruby-packaging.adoc[gem installation instructions]. -== Rubyinstaller +== RubyInstaller -Or you use the https://rubyinstaller.org/downloads/[Rubyinstaller^], download the package for your Windows Version and after the installation, then follow the xref:ruby-packaging.adoc[gem installation instructions]. +Or you use the https://rubyinstaller.org/downloads/[RubyInstaller^], download the package for your Windows Version and after the installation, then follow the xref:ruby-packaging.adoc[gem installation instructions]. diff --git a/docs/modules/migrate/pages/asciidoc-py.adoc b/docs/modules/migrate/pages/asciidoc-py.adoc index a7a99906..26a1ffb2 100644 --- a/docs/modules/migrate/pages/asciidoc-py.adoc +++ b/docs/modules/migrate/pages/asciidoc-py.adoc @@ -62,7 +62,7 @@ There are similar attributes to control how additional resources are resolved. As the steward of the AsciiDoc language, Asciidoctor reworked some of the AsciiDoc syntax originally introduced by AsciiDoc.py in an effort to make it more consistent, easier to learn, and, in some cases, more concise. This section outlines those improvements to the modern AsciiDoc syntax and how it differs from the legacy AsciiDoc recognized by AsciiDoc.py. -*If a feature or attribute isn't mentioned in the following tables, than it works in Asciidoctor just like it worked in AsciiDoc.py.* +*If a feature or attribute isn't mentioned in the following tables, then it works in Asciidoctor just like it worked in AsciiDoc.py.* === Inline formatting @@ -306,7 +306,7 @@ If you can't migrate right now, you can activate compat mode by setting the `com $ asciidoctor -a compat-mode document.adoc -You can also enable compat mode implicitly by beginning the document with an setext-style (i.e., two-line) document title: +You can also enable compat mode implicitly by beginning the document with a setext-style (i.e., two-line) document title: [,asciidoc] ---- diff --git a/docs/modules/migrate/pages/ms-word.adoc b/docs/modules/migrate/pages/ms-word.adoc index 4f855ff9..b16d37a8 100644 --- a/docs/modules/migrate/pages/ms-word.adoc +++ b/docs/modules/migrate/pages/ms-word.adoc @@ -8,7 +8,7 @@ == Pandoc -{url-pandoc}[Pandoc^] is a swiss army knife for converting one markup format to another. +{url-pandoc}[Pandoc^] is a Swiss army knife for converting one markup format to another. It does an admirable job converting simple docx files to AsciiDoc. NOTE: Generally, we don't like to recommend pandoc because it doesn't create AsciiDoc the way we prefer. @@ -96,7 +96,7 @@ See <> to fix it. == Optimizing for Pandoc The basic usage documented above is fine for one-off imports. -If you have a lot to do, it's worth while cleaning the input document first, and automating the post-conversion tidy up. +If you have a lot to do, it's worthwhile cleaning the input document first, and automating the post-conversion tidy up. . Clean up the MS Word document: // Title pages are usually easier to recreate manually @@ -128,7 +128,7 @@ If you have a lot to do, it's worth while cleaning the input document first, and ** Optional: insert ids and cross references using AsciiDoc notation (You might find it easier doing it now rather than in the AsciiDoc document later.) // Not sure if it is significant, but pandoc seems to be designed against this spec, rather than the normal docx. -** Save as "`Strict Open-xml document (docx)``" +** Save as "`Strict Open XML document (docx)``" . Convert using pandoc as shown above. . Check that the output document looks OK, and that all images have been extracted. + @@ -180,7 +180,7 @@ It will get confused by abbreviations, but there is no way around that. $ perl -W -pe 's!^Figure (\d+)\s?(.*)![[fig-$1]]\n.$2\n!g' -i output.adoc -* Replace references to figures with asciidoc xref +* Replace references to figures with AsciiDoc xref $ perl -W -pe 's!Figure (\d+)!<>!g' -i output.adoc @@ -196,7 +196,7 @@ The source for the add-on can be found in {url-google-asciidoc-source}[its repos This method is only useful for very small files or if the other methods are not available. * It keeps the text, and _fixes_ fields like auto-numbered lists and cross references. -* It loses tables (converted to plain paragraphs), images, symbols, form fields, and textboxes. +* It loses tables (converted to plain paragraphs), images, symbols, form fields, and text boxes. In MS Word, use "Save as > Plain text", then when the File Conversion dialog appears, set: diff --git a/docs/modules/stem/pages/mathematical.adoc b/docs/modules/stem/pages/mathematical.adoc index 6b77a72a..c8087fc6 100644 --- a/docs/modules/stem/pages/mathematical.adoc +++ b/docs/modules/stem/pages/mathematical.adoc @@ -32,7 +32,7 @@ The extension can be used with the built-in converters as well as add-on convert The main drawback of Asciidoctor Mathematical when compared to MathJax is that you don't have a lot of control over the size and resolution of the images it generates. It also lacks the interactivity with the expression that MathJax provides. -So when your converting to HTML, MathJax is going to give you a better result. +So when you're converting to HTML, MathJax is going to give you a better result. Another drawback when compared to MathJax is that it requires installing an extra library, and that library can be difficult to install. Nonetheless, if you need it and you're up for the challenge, that's where we're headed next. diff --git a/docs/modules/syntax-highlighting/pages/index.adoc b/docs/modules/syntax-highlighting/pages/index.adoc index 2d730230..d27fd66f 100644 --- a/docs/modules/syntax-highlighting/pages/index.adoc +++ b/docs/modules/syntax-highlighting/pages/index.adoc @@ -46,7 +46,7 @@ There are benefits and drawbacks of each type. The benefit of a client-side syntax highlighter is that does not require installing any additional libraries. It also makes conversion faster and makes it produce smaller output since the syntax highlighting is deferred until page load. The main drawback is that callouts in the source block can be mangled by the syntax highlighter or confuse it. -The benefits of a build-time syntax highlighter is that you have more control over syntax highlighting and can enable additional features such as line numbers and line highlighting. +The benefits of a build-time syntax highlighter are that you have more control over syntax highlighting and can enable additional features such as line numbers and line highlighting. The main drawback is that it requires installing an extra library, it slows down conversion, and causes the output to be larger. You should try each syntax highlighter and find the one that works best for you. diff --git a/docs/modules/syntax-highlighting/pages/pygments.adoc b/docs/modules/syntax-highlighting/pages/pygments.adoc index 605a8df9..1d5fa99f 100644 --- a/docs/modules/syntax-highlighting/pages/pygments.adoc +++ b/docs/modules/syntax-highlighting/pages/pygments.adoc @@ -16,7 +16,7 @@ It comes bundled with the pygments.rb gem. IMPORTANT: You must have Python installed to use pygments.rb. -The version of Python required depends on which pygments.rb release you using: +The version of Python required depends on which pygments.rb release you're using: * pygments.rb 1.x requires Python 2. Check that you have a `python2` (Linux), `python` (macOS), or `py -2` (Windows) executable on your PATH. @@ -107,7 +107,7 @@ This command ensures that you are invoking the `pygmentize` command from the Pyg If you're using pygments.rb 1.x, you may need to adjust the timeout. This configuration step is not necessary if you're using pygments.rb 2.x with Python 3. -Since Pygments is an external program, the call to that command in pygments.rb 1.x is managed by a timeout to safe-guard against a hanging process. +Since Pygments is an external program, the call to that command in pygments.rb 1.x is managed by a timeout to safeguard against a hanging process. By default, this timeout is 8 seconds. If you discover that the call is failing to complete within this timeout period, you can increase the timeout (in seconds) by setting the `MENTOS_TIMEOUT` environment variable. diff --git a/docs/modules/tooling/pages/index.adoc b/docs/modules/tooling/pages/index.adoc index 2f5eac34..bf6d2d1f 100644 --- a/docs/modules/tooling/pages/index.adoc +++ b/docs/modules/tooling/pages/index.adoc @@ -26,7 +26,7 @@ When you browse to an AsciiDoc file in the repository view, you will see an HTML That preview is powered by Asciidoctor. The HTML that's rendered is the embedded output produced by the built-in HTML converter. That means it won't look like a standalone HTML document generated by Asciidoctor. -Rather, the HTML is styled to match the theme of the hosting service and sanitized so it does not impact the rendering of the page. +Rather, the HTML is styled to match the theme of the hosting service and sanitized, so it does not impact the rendering of the page. That means that certain features may not be available. Both services apply syntax highlighting to source blocks. -- cgit v1.2.3