Merge pull request #2 from RayOffiah/add-roles-to-source-listing-and-callout-list

Add roles to source listing and callout list

Author: RayOffiah

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

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
 

asciidoctor-external-callout.gemspec

@@ -9,7 +9,8 @@ Gem::Specification.new do |spec|
   spec.email         = ["[email protected]"]
 
   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")

lib/asciidoctor-external-callout.rb

@@ -15,6 +15,9 @@
 
 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 @@
 
             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

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

test/asciidoctor-default.css

@@ -12,16 +12,22 @@ def teardown
   end
 
   def test_basic_conversion
-    document = Asciidoctor.convert_file File.join(File.dirname(__FILE__), 'sample.adoc'), safe: :unsafe, backend: :html5
+    document = Asciidoctor.convert_file File.join(File.dirname(__FILE__), 'sample.adoc'),
+                                        safe: :unsafe, backend: :html5,
+                                        attributes: {'stylesheet' => './callout.css'}
     assert document.instance_of? Document
     assert_equal 5, document.blocks.length
     assert_equal document.blocks[1].context, :paragraph
     assert_equal 4, document.blocks[4].items.length
     assert_equal 'The `use_dsl` line', document.blocks[4].items[0].instance_variable_get(:@text)
+    assert_equal true, document.blocks[4].has_role?('external-callout-list')
   end
 
   def test_callout_marker
-    document = Asciidoctor.convert_file File.join(File.dirname(__FILE__), 'sample.adoc'), safe: :unsafe, backend: :html5
+    document = Asciidoctor.convert_file File.join(File.dirname(__FILE__), 'sample.adoc'),
+                                        safe: :unsafe, backend: :html5,
+                                        attributes: {'stylesheet' => './callout.css'}
+
     assert document.blocks[0].context == :listing
     assert document.blocks[0].lines.length == 30
     assert document.blocks[0].lines[2].include? 'use_dsl <1>'

test/asciidoctor-external-callout_test.rb

@@ -0,0 +1,6 @@
+@import url(asciidoctor-default.css);
+
+div.external-callout-block i.conum {
+    margin-left: 10px;
+    margin-right: 10px;
+}