README.adoc in asciidoctor-reducer-1.0.0.alpha.6 vs README.adoc in asciidoctor-reducer-1.0.0.alpha.7

- old
+ new

@@ -1,8 +1,8 @@ = {project-name} Dan Allen <https://github.com/mojavelinux[@mojavelinux]> -v1.0.0.alpha.6, 2022-02-10 +v1.0.0.alpha.7, 2022-02-14 :idprefix: :idseparator: - ifndef::env-github[:icons: font] ifdef::env-github[] :caution-caption: :fire: @@ -20,14 +20,14 @@ The tool also applies preprocessor conditionals (unless the option to preserve them is specified), leaving behind only the enabled lines. If the document does not contain any preprocessor directives, the tool returns the original source. == Prerequisites -{project-name} is a Ruby program that you install using Ruby packaging. +{project-name} is a Ruby application that you install using Ruby packaging. To install and run {project-name}, you need Ruby 2.5 or better. -Run the following command to check whether you have Ruby installed and to check which version: +Run the following command to check which version of Ruby you have installed, if any: $ ruby -v If Ruby is not installed, you can install it using {url-rvm}[RVM] (or, if you prefer, the package manager for your system). We generally recommend using RVM as it allows you to install gems without requiring elevated privileges or messing with system libraries. @@ -39,12 +39,14 @@ You can install the latest version of the gem using the following command: $ gem install asciidoctor-reducer --pre Installing this gem makes the `asciidoctor-reducer` command available on your $PATH. -You can also require the gem into the Ruby runtime to use it as an Asciidoctor extension. +You can also require the gem into the Ruby runtime to use it as a library or Asciidoctor extension. +=== Project-scoped + If you prefer to manage the application as a project-scoped dependency, you can declare the gem in the project's [.path]_Gemfile_: .Gemfile [,ruby] ---- @@ -59,11 +61,11 @@ Installing the gem this way makes the `bundle exec asciidoctor-reducer` command available on your $PATH. == Usage -=== As command +=== Command You can run this tool using the provided command (i.e., CLI), named `asciidoctor-reducer`. To learn how to use the command, and to verify it's available, run the command with the `-h` option: $ asciidoctor-reducer -h @@ -73,11 +75,11 @@ .... asciidoctor-reducer [OPTION]... FILE .... The argument `FILE` is the AsciiDoc file you want to reduce. -The options, represented by `[OPTION]...`, are optional, as the name suggestions. +The options, represented by `+[OPTION]...+`, are optional, as the name suggestions. Thus, to use the command, pass the AsciiDoc file as the sole argument: $ asciidoctor-reducer input.adoc @@ -89,45 +91,93 @@ The command can also read the input document from stdin instead of a file. To use the command in this way, pass `-` as the first argument: $ cat input.adoc | asciidoctor-reducer - -To write the output to a file instead of stdout, also specify an output file using the `-o` option: +To write the output to a file in this case, specify an output file using the `-o` option: $ cat input.adoc | asciidoctor-reducer -o output.adoc - -Note that top-level include files in the input AsciiDoc document are resolved relative to current working directory. +=== API -=== As extension +You can also use this tool from a Ruby application using the provided API. +To begin, require the API for this library. -You can use this tool as an Asciidoctor extension when using the Asciidoctor API. -To do so, require it before calling the `Asciidoctor.load` method. - [,ruby] ---- -require 'asciidoctor/reducer' +require 'asciidoctor/reducer/api' ---- -Next, load a parent document that contains includes. +Next, reduce a parent document that contains includes. +This works without having to specify the safe mode since the default safe mode when using the API is `:safe`. [,ruby] ---- -doc = Asciidoctor.load_file 'sample.adoc', safe: :safe +doc = Asciidoctor::Reducer.reduce_file 'sample.adoc' ---- Finally, you can retrieve the reduced source from the returned document. [,ruby] ---- puts doc.source ---- -You can write this source to a file to save the reduced document. +The benefit of this approach is that you can access the reduced source and the parsed document that corresponds to it. +If you don't need the parsed document, you can retrieve the reduced source directly by passing the `String` type to the `:to` option: + +[,ruby] +---- +puts Asciidoctor::Reducer.reduce_file 'sample.adoc', to: String +---- + +You can write the reduced source directly to a file by passing a file path to the `:to` option: + +[,ruby] +---- +Asciidoctor::Reducer.reduce_file 'sample.adoc', to: 'sample-reduced.adoc' +---- + +== Extension + +Instead of using the API for this library, you can use the load API provided by Asciidoctor. +If you want to register the extension globally, require the library as follows: + +[,ruby] +---- +require 'asciidoctor/reducer' +---- + +When you use the Asciidoctor load API, the document will automatically be reduced. + +[,ruby] +---- +puts (Asciidoctor.load_file 'sample.adoc', safe: :safe).source +---- + +If you want to keep the extension scoped to the call, require the library as follows: + +[,ruby] +---- +require 'asciidoctor/reducer/extensions' +---- + +Next, use the extensions API to prepare an extension registry and pass it to the Asciidoctor load API: + +[,ruby] +---- +puts (Asciidoctor.load_file 'sample.adoc', safe: :safe, extension_registry: Asciidoctor::Reducer.prepare_registry).source +---- + +Working with the extension directly is intended for low-level operations. +Most of the time, you should use the API provided by this library. + == How it Works {project-name} uses a collection of Asciidoctor extensions to rebuild the AsciiDoc source as a single document. +Top-level include files in the input AsciiDoc document are resolved relative to current working directory. It starts by using a preprocessor extension to enhance the PreprocessorReader class to be notified each time an include is entered (pushed) or exited (popped). When an include directive is encountered, the enhanced reader stores the resolved lines and location of the include directive, thus keeping track of where those lines should be inserted in the original source. This information is stored as a stack, where each successive entry contains lines to be inserted into a parent entry. The enhanced reader also stores the location of preprocessor conditionals and whether the lines they enclose should be kept or dropped. @@ -189,10 +239,10 @@ $ bundle exec rspec To run all tests in a single spec, point RSpec at the spec file: - $ bundle exec rspec spec/asciidoctor_reducer_spec.rb + $ bundle exec rspec spec/reducer_spec.rb ==== Run specific tests If you only want to run a single test, or a group of tests, you can do so by tagging the test cases, then filtering the test run using that tag.