asciidoctor-external-callout 0.0.6.pre.beta7 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 910479158955009faec89ab7797f5b30c5d97aff3433c276fb6bc34d0f1e10c2
-  data.tar.gz: e082c0a766caa8a2cd5f5f60f8063052f75ca398b2a6933afc06eb581c9c1e48
+  metadata.gz: 284ba079c9ce91935490ced1b9041717c3d733f1eb03cb428b75b3b85b5718e4
+  data.tar.gz: aca07340cfd7cf61f7afc90825c137e20934cb3905ab83a2be91e41ff589b2e1
 SHA512:
-  metadata.gz: ce3c945787e12aef49a863250cbdab404e5a2c0ee7396c81c8a969829b724506c0c5cfec3bb42a407cac9bb017d03bb4d1979fd11d0539ee466339648f52f4a4
-  data.tar.gz: 4bf8d47eb9008153011617d1e3438b7c8bff86d1e70a0686dd8494f543fac7dc4f72c7cd75d4c8ae02b9a95ddea30f8ad665a4f23e7a208775e9e6f6fa5dd145
+  metadata.gz: 6f6dd07c7042d9432d3e6f3de53fa67dc52248aa9a3cdc38f937c831edd66327081293c148601161eaf0a644cd7f7995ed0a9b1aeaa5df266f79d53e0565ff60
+  data.tar.gz: 854510529f76e96891b1ac7e482b984a0df273dbd97f8d84c37d85c940f86d6d5fd187aa79ff7e4c314913a10ab0b4439558dd31c9bbafcd76e2d5c6da8afa32

data/.gitignore

@@ -8,6 +8,8 @@
 /tmp/
 /.idea
 **/sample.html
+**/sample_global_search.html
+**/sample.pdf
 *.gem
 /Gemfile.lock
 /.asciidoctor

data/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 Record of bug fixes, enhancements, and changes.
 
+## [1.1.2] – 2022-07-07
+
+### Fixed
+- Code fix to stop the constants from reloading every time the extension is run. (Tidying up for execution inside the Asciidoc plugin)
+
+## [1.1.1] – 2022-06-23
+
+### Fixed
+- Fixed regular expression to correctly detect new flags.
+
+## [1.1.0] – 2022-06-23
+
+### Added
+- The text search now supports a global flag (`@/text/g`). The `g` flag will add the callout to all the lines that match the search criteria. Use wisely.
+- Added the `i` flag for case-insensitive searches: (`@/text/i`). Again, don't go mad.
+
+## [1.0.0] – 2022-06-16
+
+### Added
+- Added roles to the source block and the callout list so that CSS folk can pick them out to make style changes (For example, adjusting the gap between callout items in the source code block.)
+
 ## [0.0.6-beta6] – 2022-06-11
 
 ### Changed

data/README.md

@@ -62,6 +62,15 @@ Two types of location token are supported:
 If you have a large listing then it may be preferable to use the text search rather than counting all the lines. It may also be preferable to use a smaller listing, as a long listing might mean that your description is a bit too general. +
 Using the text search method means that the location of the callout will move with the line; handy if you're referencing a source file that might get the occasional tweak outside your control.
 
+@/_text_/g
+: Works the same as the standard text search; the `g` flag means that callouts willl be added to _all_ the lines that match the search string, instead of just the first one.
+
+@/_text_/i
+: This is a case-insensitive search.
+
+@/_text_/gi
+: And of course, you can combine the two, though I'm not sure why you'd want to.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -80,7 +89,46 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+To use the extension, you need to register it before calling one of the Asciidoc `convert` functions to render the output.
+
+```ruby
+require 'asciidoctor-external-callout'
+require 'asciidoctor'
+
+Asciidoctor.convert_file File.join(File.dirname(__FILE__), 'sample.adoc'), safe: :unsafe, backend: :html5
+```
+
+## Use with the [IntelliJ Asciidoc Plugin](https://plugins.jetbrains.com/plugin/7391-asciidoc)
+
+If you're not using the excellent Asciidoc plugin then you're really missing out. 
+One if it's lesser known features is that it supports Asciidoc extensions written in Ruby:
+
+1. Create a new folder structure in the root of your IntelliJ project called `.asciidoctor/lib`.
+2. Copy the file `asciidoctor-external-calllout.rb` from this distribution to `.asciidoctor/lib`.
+
+Now, when you preview an Asciidoc file with the plugin enabled, external callouts will now show up in the preview.
+
+## Formatting
+
+By default, the callout extension will put a single space between callouts that occur on the same line. If you want to adjust this, then you need to create a style that puts a horizontal margin between the callouts:
+
+```css
+div.external-callout-block i.conum {
+    margin-left: 10px;
+    margin-right: 10px;
+}
+```
+The callout attaches a class called `external-callout-block` to each source listing it processes. You can use this to differentiate between standard callouts, and callouts written by the extension.
+
+The extension also adds a class called `external-callout-list` to the list of definitions at the bottom of the source block. (There's probably no need to adjust the styling for this.)
+
+Then to convert a document with a stylesheet, use something like this:
+
+```ruby
+Asciidoctor.convert_file File.join(File.dirname(__FILE__), 'sample.adoc'), 
+                         safe: :unsafe, backend: :html5,
+                         attributes: {'stylesheet' => './callout.css'}
+```
 
 ## Development
 

data/asciidoctor-external-callout.gemspec

@@ -9,7 +9,8 @@ Gem::Specification.new do |spec|
   spec.email         = ["clogs-wrench-0z@icloud.com"]
 
   spec.summary       = "Asciidoc extension for adding callouts without marking up the source listing block."
-  # spec.description   = "TODO: Write a longer description or delete this line."
+  spec.description   = "If you can't add callout markers to your source listing" \
+ "(if you need to keep a shell script runnable for example), then use this."
   spec.homepage      = "https://github.com/RayOffiah/asciidoctor-external-callout-ruby"
   spec.license       = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")

data/lib/asciidoctor-external-callout.rb

@@ -15,8 +15,11 @@ include Asciidoctor
 
 Asciidoctor::Extensions::register do
 
-  LOCATION_TOKEN_RX = /@(\d+)|@\/([^\/]+?)\//
-  LOCATION_TOKEN_ARRAY_RX = /^(@\d+|@\/[^\/]+?\/)((\s+@\d+)|(\s+@\/[^\/]+?\/))*$/
+  CALLOUT_SOURCE_BLOCK_ROLE ||= 'external-callout-block'
+  CALLOUT_ORDERED_LIST_ROLE ||= 'external-callout-list'
+
+  LOCATION_TOKEN_RX ||= /@(\d+)|(@\/[^\/]+?\/(?:i|g|gi|ig){0,2})/
+  LOCATION_TOKEN_ARRAY_RX ||= /^(@\d+|@\/[^\/]+?\/(i|g|gi|ig){0,2})((\s+@\d+)|(\s+@\/[^\/]+?\/(i|g|gi|ig){0,2}))*$/
 
   tree_processor do
 
@@ -37,6 +40,9 @@ Asciidoctor::Extensions::register do
 
             list.context = :colist
 
+            owner_block.add_role(CALLOUT_SOURCE_BLOCK_ROLE) unless owner_block.has_role?(CALLOUT_SOURCE_BLOCK_ROLE)
+            list.add_role(CALLOUT_ORDERED_LIST_ROLE) unless list.has_role?(CALLOUT_ORDERED_LIST_ROLE)
+
           end
 
         end
@@ -140,23 +146,27 @@ Asciidoctor::Extensions::register do
 
           if location.is_numeric?
 
-            number = location.to_i
+            line_number = location.to_i
 
-            if number <= owner_block.lines.length
-              line_numbers << (number - 1)
+            if line_number.between?(1, owner_block.lines.length)
+              line_numbers << (line_number - 1)  # Because the line number is now an array index, so -1
             else
-              warn "Out of range ==> #{number}"
+              warn "Line number out of range ==> #{line_number}"
             end
 
           else
 
             # Must be a string matcher then
 
-            number = find_matching_lines(location, owner_block)
+            # Is this a global search?
+            global_search = !!location.match(/\/([^\/]+?)\/.*g.*/)
+            case_insensitive = !!location.match(/\/([^\/]+?)\/.*i.*/)
+            search_string = location[/\/([^\/]+?)\//, 1]
+            found_line_numbers = find_matching_lines(search_string, global_search, case_insensitive, owner_block)
 
-            if number != nil
+            if !found_line_numbers.empty?
 
-              line_numbers << number
+              line_numbers = line_numbers.merge(found_line_numbers)
 
             else
               warn "Search term not found ==> #{location}"
@@ -179,9 +189,28 @@ Asciidoctor::Extensions::register do
 
     end
 
-    def find_matching_lines(search_string, owner_block)
+    def find_matching_lines(search_string, global_search, case_insensitive, owner_block)
+
+      if case_insensitive
+        string_to_match = Regexp.new(search_string, Regexp::IGNORECASE)
+      else
+        string_to_match = Regexp.new(search_string)
+      end
+      found_lines = Set.new
+
+      owner_block.lines.each_with_index do |line, index|
+
+        if line.match(string_to_match) != nil
+
+          found_lines << index
+
+          return found_lines unless global_search
+
+        end
+
+      end
 
-      owner_block.lines.index { |x| x.match(%r[#{search_string}]) }
+      found_lines
 
     end
 

data/lib/version.rb

@@ -3,7 +3,7 @@
 module Asciidoctor
   module External
     module Callout
-      VERSION = "0.0.6-beta7"
+      VERSION = "1.1.2"
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-external-callout
 version: !ruby/object:Gem::Version
-  version: 0.0.6.pre.beta7
+  version: 1.1.2
 platform: ruby
 authors:
 - Ray Offiah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-06-11 00:00:00.000000000 Z
+date: 2022-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -24,7 +24,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-description:
+description: If you can't add callout markers to your source listing(if you need to
+  keep a shell script runnable for example), then use this.
 email:
 - clogs-wrench-0z@icloud.com
 executables: []
@@ -61,9 +62,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.2.3
 signing_key: