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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 910479158955009faec89ab7797f5b30c5d97aff3433c276fb6bc34d0f1e10c2
-  data.tar.gz: e082c0a766caa8a2cd5f5f60f8063052f75ca398b2a6933afc06eb581c9c1e48
+  metadata.gz: 53e488dac87a1685e9450b031e44aea9ef5d265b92f974965e7b212df326b284
+  data.tar.gz: 27559c5adc5c7daf42eb2b958ed6d96be360d6ee4a25689e726f2c42dffca8b5
 SHA512:
-  metadata.gz: ce3c945787e12aef49a863250cbdab404e5a2c0ee7396c81c8a969829b724506c0c5cfec3bb42a407cac9bb017d03bb4d1979fd11d0539ee466339648f52f4a4
-  data.tar.gz: 4bf8d47eb9008153011617d1e3438b7c8bff86d1e70a0686dd8494f543fac7dc4f72c7cd75d4c8ae02b9a95ddea30f8ad665a4f23e7a208775e9e6f6fa5dd145
+  metadata.gz: 7b48ae24cdb081bedffb3702cd10821ac8739e52d372042dfeb851acb9d0b607d3e72afb6fd6e7cabc0be2a81647eaf50f46604ba3b0f44b5d30ea2db9616608
+  data.tar.gz: 53cd492e35f520d503d7643723a4289abe3f88ef8f9b00607d494e1e2e0240692e58da74af6f05d0f10e365070ac24fe0d195612b29b589f8579e585eccc6797

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Record of bug fixes, enhancements, and changes.
 
+## [1.0.0] – 22-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

@@ -80,7 +80,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,6 +15,9 @@ include Asciidoctor
 
 Asciidoctor::Extensions::register do
 
+  CALLOUT_SOURCE_BLOCK_ROLE = 'external-callout-block'
+  CALLOUT_ORDERED_LIST_ROLE = 'external-callout-list'
+
   LOCATION_TOKEN_RX = /@(\d+)|@\/([^\/]+?)\//
   LOCATION_TOKEN_ARRAY_RX = /^(@\d+|@\/[^\/]+?\/)((\s+@\d+)|(\s+@\/[^\/]+?\/))*$/
 
@@ -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

data/lib/version.rb

@@ -3,7 +3,7 @@
 module Asciidoctor
   module External
     module Callout
-      VERSION = "0.0.6-beta7"
+      VERSION = "1.0.0"
     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.0.0
 platform: ruby
 authors:
 - Ray Offiah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-06-11 00:00:00.000000000 Z
+date: 2022-06-16 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: