asciidoctor-dita-topic 1.3.4 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62056b90729ed2ccfcfad7a3fa3613938cf943c67b535d4f6653b1aa009a79a9
-  data.tar.gz: 558a40909a4eea3b5a1bae2327e12c3116d679d5fbbd71cf4f70f990fd23fabf
+  metadata.gz: e2450b8d59daacc0f3b75a5d1d30e4527260f5c41696dd4eca6180b2dd922c8d
+  data.tar.gz: 3d1fbc5d40698c9fbfa3045e8319d2d8a774b97419287c5bfbd082f35f5dae51
 SHA512:
-  metadata.gz: 84b3e6f51d7712fb8974fce8c4c3f184b90f1853cf442306ec24d8ab3a32e01f49ee9cec24885baeb26eafb6f7837a76117ffce14f4c7187436f153209864013
-  data.tar.gz: 2c53bb543c270dcc48597b8cc9c16e914ec62393dec275064ae6e5423ed7b8c4898e3df59ffa83145779ef9f8124555b1f6cae5c2a51e6d539ac39356276ea6a
+  metadata.gz: 7eb3def3e75ac2d610667cacdf1f247aba118dea8f758895c5e2ef2ab5d1e0c0133a67506cc1b1b57bf72e8f5cdf212ef01a1e67787de07cf7a1f3682f8dd3d4
+  data.tar.gz: a44b76667c70adea284ad5ce7078c74a1271ddaa6ff6628cf75959e0e0957f1cff9dce07103d8026da2e06003495ba918116d23fb1a3edb50b78bdd050962c6a

data/README.adoc

@@ -15,7 +15,7 @@ $ *vale _source_file.adoc_*
 +
 [literal,subs="+quotes"]
 ....
-$ *asciidoctor -r dita-topic -b dita-topic _source_file.adoc_*
+$ *dita-topic _source_file.adoc_*
 ....
 
 . Convert the generic DITA topic to a specialized DITA concept, reference, or task:
@@ -50,27 +50,34 @@ On macOS, `asciidoctor` installed with Homebrew expects Ruby gems in a different
 [#use]
 == Usage
 
-To use the custom converter on the command line, load it with the `-r dita-topic` option and then select `dita-topic` as the backend output format with `-b dita-topic`:
+To convert an AsciiDoc file to a generic DITA topic, run the supplied `dita-topic` command-line interface as follows:
 
 [literal,subs="+quotes"]
 ....
-$ *asciidoctor -r dita-topic -b dita-topic _your_file_.adoc*
+$ *dita-topic _your_file_.adoc*
 ....
 
 This creates a new file, `_your_file_.dita`, in the same directory as `_your_file_.adoc`. You can also convert multiple files at the same time:
 
 [literal,subs="+quotes"]
 ....
-$ **asciidoctor -r dita-topic -b dita-topic *.adoc**
+$ **dita-topic *.adoc**
+....
+
+The command-line interface simplifies the code execution and provides a few options in addition to the conversion. However, if you prefer to use Asciidoctor directly, load the converter with the `-r dita-topic` option and then select `dita-topic` as the backend output format with `-b dita-topic`:
+
+[literal,subs="+quotes"]
+....
+$ *asciidoctor -r dita-topic -b dita-topic _your_file_.adoc*
 ....
 
 [IMPORTANT]
 ====
-`dita-topic` does not validate the converted content. If you have link:https://www.dita-ot.org/[DITA Open Toolkit] installed, you can check that the converted file can be built as follows:
+`dita-topic` does not validate the converted content. If you have link:https://www.dita-ot.org/[DITA Open Toolkit] installed, you can verify that the converted file can be built as follows:
 
 [literal,subs="+quotes"]
 ....
-$ **dita -i _converted_file_.dita -f xhtml**
+$ **dita -i _your_file_.dita -f xhtml**
 ....
 
 To produce slightly more readable errors, you can also use `xmlstarlet`:
@@ -82,45 +89,51 @@ $ **xmlstarlet val -e -s _path_to_dita-ot_directory_/plugins/org.oasis-open.dita
 ====
 
 [#attributes]
-=== Supplying attribute definitions
+=== Supplying individual attribute definitions
 
 If your AsciiDoc files use attributes that are defined outside of these files, you can supply the attribute definitions on the command line with the `-a _attribute_=_value_` option:
 
 [literal,subs="+quotes"]
 ....
-$ **asciidoctor -r dita-topic -b dita-topic -a _attribute_=_value_ _your_file_.adoc**
+$ **dita-topic -a _attribute_=_value_ _your_file_.adoc**
 ....
 
-You can provide multiple `-a _attribute_=_value_` options at the same time. Providing relevant attribute definitions is especially important if your document contains conditional content.
+If you prefer to use Asciidoctor directly, supply the attribute definitions with the `-a _attribute_=_value_` option as follows:
 
-.Providing a product version to resolve `ifeval` conditions
-====
-Your AsciiDoc files include a number of `ifeval` statements that provide different content for different versions of the product you are documenting:
+[literal,subs="+quotes"]
+....
+$ **asciidoctor -r dita-topic -b dita-topic -a _attribute_=_value_ _your_file_.adoc**
+....
 
-[source]
-----
-\ifeval::["{ProductNumber}" == "1"]
-...
-\endif::[]
-\ifeval::["{ProductNumber}" == "2"]
-...
-\endif::[]
-----
+You can provide multiple `-a` options at the same time. Providing relevant attribute definitions is especially important if your document contains conditional content.
 
-To ensure that the converted DITA files include all content for version 2 of your product, run:
+[#attribute_files]
+=== Supplying attribute definition files
+
+If listing individual attribute definitions is impractical, you can use the `-p _definition_file_.adoc` option to supply another AsciiDoc file with attribute definitions in it:
 
 [literal,subs="+quotes"]
 ....
-$ **asciidoctor -r dita-topic -b dita-topic -a ProductNumber=2 *.adoc**
+$ **dita-topic -p _definition_file_.adoc _your_file_.adoc**
 ....
-====
+
+The supplied file is automatically prepended to each AsciiDoc file during conversion. You can provide multiple `-p` options at the same time or use a combination `-p` and `-a` options to construct your attribute definitions. If you define the same attribute twice this way, the value defined by using the `-a` option takes precedence.
+
+This functionality is not available in standard Asciidoctor.
 
 [#authors]
 === Enabling author lines
 
 AsciiDoc topics are expected to be included in other files and therefore should not contain link:https://docs.asciidoctor.org/asciidoc/latest/document/author-line/[author line] definitions. In most cases, lines that directly follow the topic title are intended as first paragraphs. For this reason, author lines are disabled by default. To avoid losing content during conversion, as a workaround, the `dita-topic` converter interprets the raw content of the author line as a paragraph and issues a warning.
 
-To enable processing of author lines as metadata, set the value of the `dita-topic-authors` to `on`:
+To enable processing of author lines as metadata, run the `dita-topic` command with the `-l` option:
+
+[literal,subs="+quotes"]
+....
+$ **dita-topic -l _your_file_.adoc**
+....
+
+If you prefer to use Asciidoctor directly, set the value of the `dita-topic-authors` to `on`:
 
 [literal,subs="+quotes"]
 ....
@@ -137,7 +150,14 @@ Unlike AsciiDoc, DITA does not support floating titles and only allows titles to
 <p outputclass="title"><b>Floating title</b></p>
 ----
 
-To disable this behavior, set the value of the `dita-topic-titles` to `off`:
+To disable this behavior, run the `dita-topic` command with the `-T` option:
+
+[literal,subs="+quotes"]
+....
+$ **dita-topic -T _your_file_.adoc**
+....
+
+If you prefer to use Asciidoctor directly, set the value of the `dita-topic-titles` to `off`:
 
 [literal,subs="+quotes"]
 ....
@@ -149,7 +169,14 @@ $ **asciidoctor -r dita-topic -b dita-topic -a dita-topic-titles=off _your_file_
 
 Unlike AsciiDoc, DITA does not support callouts as a method to add annotations to specific lines in verbatim blocks. To avoid losing content during conversion, as a workaround, the `dita-topic` converter uses XML entities for circled numbers.
 
-To disable this behavior, set the value of the `dita-topic-callouts` to `off`:
+To disable this behavior, run the `dita-topic` command with the `-C` option:
+
+[literal,subs="+quotes"]
+....
+$ **dita-topic -C _your_file_.adoc**
+....
+
+If you prefer to use Asciidoctor directly, set the value of the `dita-topic-callouts` to `off`:
 
 [literal,subs="+quotes"]
 ....
@@ -159,13 +186,22 @@ $ **asciidoctor -r dita-topic -b dita-topic -a dita-topic-callouts=off _your_fil
 [#includes]
 === Disabling include directives
 
-By default, Asciidoctor resolves all `include` directives before converting the file. To only convert the contents of the selected file, specify the `-S secure` option:
+By default, Asciidoctor resolves all `include` directives before converting the file. To only convert the contents of the selected file, run the `dita-topic` command with the `-I` option:
+
+[literal,subs="+quotes"]
+....
+$ **dita-topic -I _your_file_.adoc**
+....
+
+If you prefer to use Asciidoctor directly, there is no direct equivalent to this functionality. As a workaround, you can specify the `-S secure` option:
 
 [literal,subs="+quotes"]
 ....
 $ **asciidoctor -r dita-topic -b dita-topic -S secure _your_file_.adoc**
 ....
 
+This disables processing of the include directives, but leaves cross references to the included files in the converted output.
+
 [#abstracts]
 === Adding short descriptions
 

data/bin/dita-topic

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+
+# Copyright (C) 2025 Jaromir Hradilek
+
+# MIT License
+#
+# Permission  is hereby granted,  free of charge,  to any person  obtaining
+# a copy of  this software  and associated documentation files  (the "Soft-
+# ware"),  to deal in the Software  without restriction,  including without
+# limitation the rights to use,  copy, modify, merge,  publish, distribute,
+# sublicense, and/or sell copies of the Software,  and to permit persons to
+# whom the Software is furnished to do so,  subject to the following condi-
+# tions:
+#
+# The above copyright notice  and this permission notice  shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY KIND,  EXPRESS
+# OR IMPLIED,  INCLUDING BUT NOT LIMITED TO  THE WARRANTIES OF MERCHANTABI-
+# LITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
+# SHALL THE AUTHORS OR COPYRIGHT HOLDERS  BE LIABLE FOR ANY CLAIM,  DAMAGES
+# OR OTHER LIABILITY,  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM,  OUT OF OR IN CONNECTION WITH  THE SOFTWARE  OR  THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
+require (cli = File.absolute_path '../lib/dita-topic/cli.rb', __dir__) ? cli : 'dita-topic/cli'
+
+begin
+  name = File.basename($0)
+  converter = AsciidoctorDitaTopic::Cli.new name, ARGV
+  converter.run
+rescue OptionParser::InvalidArgument, OptionParser::InvalidOption, OptionParser::MissingArgument => error
+  abort "#{name}: #{error.message}"
+end

data/lib/dita-topic/cli.rb

@@ -0,0 +1,139 @@
+# Copyright (C) 2025 Jaromir Hradilek
+
+# MIT License
+#
+# Permission  is hereby granted,  free of charge,  to any person  obtaining
+# a copy of  this software  and associated documentation files  (the "Soft-
+# ware"),  to deal in the Software  without restriction,  including without
+# limitation the rights to use,  copy, modify, merge,  publish, distribute,
+# sublicense, and/or sell copies of the Software,  and to permit persons to
+# whom the Software is furnished to do so,  subject to the following condi-
+# tions:
+#
+# The above copyright notice  and this permission notice  shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY KIND,  EXPRESS
+# OR IMPLIED,  INCLUDING BUT NOT LIMITED TO  THE WARRANTIES OF MERCHANTABI-
+# LITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
+# SHALL THE AUTHORS OR COPYRIGHT HOLDERS  BE LIABLE FOR ANY CLAIM,  DAMAGES
+# OR OTHER LIABILITY,  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM,  OUT OF OR IN CONNECTION WITH  THE SOFTWARE  OR  THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
+require 'optparse'
+require 'asciidoctor'
+require_relative 'version'
+require_relative '../dita-topic'
+
+module AsciidoctorDitaTopic
+  class Cli
+    def initialize name, argv
+      @attr = ['experimental']
+      @opts = {:output => true, :includes => true, :standalone => true}
+      @prep = []
+      @name = name
+      @args = self.parse_args argv
+    end
+
+    def parse_args argv
+      parser = OptionParser.new do |opt|
+        opt.banner  = "Usage: #{@name} [OPTION...] FILE...\n"
+        opt.banner += "       #{@name} -h|-v\n\n"
+
+        opt.on('-o', '--out-file FILE', 'output file; by default, the output file name is based on the input file') do |output|
+          @opts[:output] = (output.strip == '-') ? $stdout : output
+        end
+
+        opt.on('-a', '--attribute ATTRIBUTE', 'document attribute to set in the form of name, name!, or name=value pair') do |value|
+          @attr.append value
+        end
+
+        opt.on('-p', '--prepend-file FILE', 'file to prepend to all input files') do |file|
+          raise OptionParser::InvalidArgument, "not a file: #{file}" unless File.exist? file and File.file? file
+          raise OptionParser::InvalidArgument, "file not readable: #{file}" unless File.readable? file
+
+          @prep.append file
+        end
+
+        opt.on('-I', '--no-includes', 'disable processing of include directives') do
+          @opts[:includes] = false
+        end
+
+        opt.on('-s', '--no-header-footer', 'disable enclosing the content in <topic> and generating <title>') do
+          @opts[:standalone] = false
+        end
+
+        opt.separator ''
+
+        opt.on('-l', '--author-line', 'enable processing of author lines as metadata') do
+          @attr.append 'dita-topic-authors=on'
+        end
+
+        opt.on('-t', '--section-type', 'add content type as outputclass to sections') do
+          @attr.append 'dita-topic-type=on'
+        end
+
+        opt.on('-C', '--no-callouts', 'disable processing of callouts') do
+          @attr.append 'dita-topic-callouts=off'
+        end
+
+        opt.on('-S', '--no-sidebars', 'disable processing of sidebars') do
+          @attr.append 'dita-topic-sidebars=off'
+        end
+
+        opt.on('-T', '--no-titles', 'disable processing of floating titles') do
+          @attr.append 'dita-topic-titles=off'
+        end
+
+        opt.separator ''
+
+        opt.on('-h', '--help', 'display this help and exit') do
+          puts opt
+          exit
+        end
+
+        opt.on('-v', '--version', 'display version information and exit') do
+          puts "#{@name} #{VERSION}"
+          exit
+        end
+      end
+
+      args = parser.parse argv
+
+      if args.length == 0 or args[0].strip == '-'
+        return [$stdin]
+      end
+
+      args.each do |file|
+        raise OptionParser::InvalidArgument, "not a file: #{file}" unless File.exist? file and File.file? file
+        raise OptionParser::InvalidArgument, "file not readable: #{file}" unless File.readable? file
+      end
+
+      return args
+    end
+
+    def run
+      prepended = ''
+
+      @prep.each do |file|
+        prepended << File.read(file)
+        prepended << "\n"
+      end
+
+      @args.each do |file|
+        if file == $stdin
+          input  = $stdin.read
+          output = (@opts[:output] == true) ? $stdout : @opts[:output]
+        else
+          input  = File.read(file)
+          output = (@opts[:output] == true) ? Pathname.new(file).sub_ext('.dita').to_s : @opts[:output]
+        end
+
+        input.gsub!(Asciidoctor::IncludeDirectiveRx, '//\&') unless @opts[:includes]
+
+        Asciidoctor.convert prepended + input, backend: 'dita-topic', standalone: @opts[:standalone], safe: :unsafe, attributes: @attr, to_file: output
+      end
+    end
+  end
+end

data/lib/dita-topic/version.rb

@@ -0,0 +1,28 @@
+# Copyright (C) 2025 Jaromir Hradilek
+
+# MIT License
+#
+# Permission  is hereby granted,  free of charge,  to any person  obtaining
+# a copy of  this software  and associated documentation files  (the "Soft-
+# ware"),  to deal in the Software  without restriction,  including without
+# limitation the rights to use,  copy, modify, merge,  publish, distribute,
+# sublicense, and/or sell copies of the Software,  and to permit persons to
+# whom the Software is furnished to do so,  subject to the following condi-
+# tions:
+#
+# The above copyright notice  and this permission notice  shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY KIND,  EXPRESS
+# OR IMPLIED,  INCLUDING BUT NOT LIMITED TO  THE WARRANTIES OF MERCHANTABI-
+# LITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
+# SHALL THE AUTHORS OR COPYRIGHT HOLDERS  BE LIABLE FOR ANY CLAIM,  DAMAGES
+# OR OTHER LIABILITY,  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM,  OUT OF OR IN CONNECTION WITH  THE SOFTWARE  OR  THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
+# frozen_string_literal: true
+
+module AsciidoctorDitaTopic
+  VERSION     = '1.4.0'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-dita-topic
 version: !ruby/object:Gem::Version
-  version: 1.3.4
+  version: 1.4.0
 platform: ruby
 authors:
 - Jaromir Hradilek
@@ -74,14 +74,18 @@ dependencies:
 description: An extension for AsciiDoctor that converts a single AsciiDoc file to
   a DITA topic.
 email: jhradilek@gmail.com
-executables: []
+executables:
+- dita-topic
 extensions: []
 extra_rdoc_files: []
 files:
 - AUTHORS
 - LICENSE
 - README.adoc
+- bin/dita-topic
 - lib/dita-topic.rb
+- lib/dita-topic/cli.rb
+- lib/dita-topic/version.rb
 homepage: https://github.com/jhradilek/asciidoctor-dita-topic
 licenses:
 - MIT