kramdown 0.14.2 → 2.3.0

data/lib/kramdown/utils/html.rb

@@ -1,25 +1,14 @@
-# -*- coding: utf-8 -*-
+# -*- coding: utf-8; frozen_string_literal: true -*-
 #
 #--
-# Copyright (C) 2009-2012 Thomas Leitner <t_leitner@gmx.at>
+# Copyright (C) 2009-2019 Thomas Leitner <t_leitner@gmx.at>
 #
-# This file is part of kramdown.
-#
-# kramdown is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# This file is part of kramdown which is licensed under the MIT.
 #++
 #
 
+require 'rexml/parsers/baseparser'
+
 module Kramdown
 
   module Utils
@@ -38,12 +27,13 @@ module Kramdown
       def entity_to_str(e, original = nil)
         entity_output = @options[:entity_output]
 
-        if e.char.respond_to?(:encoding) && entity_output == :as_char &&
-            (c = e.char.encode(@root.options[:encoding]) rescue nil) && !ESCAPE_MAP.has_key?(c)
+        if entity_output == :as_char &&
+            (c = e.char.encode(@root.options[:encoding]) rescue nil) &&
+            ((c = e.char) == '"' || !ESCAPE_MAP.key?(c))
           c
         elsif (entity_output == :as_input || entity_output == :as_char) && original
           original
-        elsif (entity_output == :symbolic || ESCAPE_MAP.has_key?(e.char)) && !e.name.nil?
+        elsif (entity_output == :symbolic || ESCAPE_MAP.key?(e.char)) && !e.name.nil?
           "&#{e.name};"
         else # default to :numeric
           "&##{e.code_point};"
@@ -52,7 +42,11 @@ module Kramdown
 
       # Return the HTML representation of the attributes +attr+.
       def html_attributes(attr)
-        attr.map {|k,v| v.nil? || (k == 'id' && v.strip.empty?) ? '' : " #{k}=\"#{escape_html(v.to_s, :attribute)}\"" }.join('')
+        return '' if attr.empty?
+
+        attr.map do |k, v|
+          v.nil? || (k == 'id' && v.strip.empty?) ? '' : " #{k}=\"#{escape_html(v.to_s, :attribute)}\""
+        end.join('')
       end
 
       # :stopdoc:
@@ -60,24 +54,27 @@ module Kramdown
         '<' => '&lt;',
         '>' => '&gt;',
         '&' => '&amp;',
-        '"' => '&quot;'
+        '"' => '&quot;',
       }
       ESCAPE_ALL_RE = /<|>|&/
       ESCAPE_TEXT_RE = Regexp.union(REXML::Parsers::BaseParser::REFERENCE_RE, /<|>|&/)
       ESCAPE_ATTRIBUTE_RE = Regexp.union(REXML::Parsers::BaseParser::REFERENCE_RE, /<|>|&|"/)
-      ESCAPE_RE_FROM_TYPE = {
-        :all => ESCAPE_ALL_RE,
-        :text => ESCAPE_TEXT_RE,
-        :attribute => ESCAPE_ATTRIBUTE_RE
-      }
+      ESCAPE_RE_FROM_TYPE = {all: ESCAPE_ALL_RE, text: ESCAPE_TEXT_RE, attribute: ESCAPE_ATTRIBUTE_RE}
       # :startdoc:
 
       # Escape the special HTML characters in the string +str+. The parameter +type+ specifies what
-      # is escaped: :all - all special HTML characters as well as entities, :text - all special HTML
-      # characters except the quotation mark but no entities and :attribute - all special HTML
-      # characters including the quotation mark but no entities.
+      # is escaped: :all - all special HTML characters except the quotation mark as well as
+      # entities, :text - all special HTML characters except the quotation mark but no entities and
+      # :attribute - all special HTML characters including the quotation mark but no entities.
       def escape_html(str, type = :all)
-        str.gsub(ESCAPE_RE_FROM_TYPE[type]) {|m| ESCAPE_MAP[m] || m}
+        str.gsub(ESCAPE_RE_FROM_TYPE[type]) {|m| ESCAPE_MAP[m] || m }
+      end
+
+      REDUNDANT_LINE_BREAK_REGEX = /([\p{Han}\p{Hiragana}\p{Katakana}]+)\n([\p{Han}\p{Hiragana}\p{Katakana}]+)/u
+      def fix_cjk_line_break(str)
+        while str.gsub!(REDUNDANT_LINE_BREAK_REGEX, '\1\2')
+        end
+        str
       end
 
     end

data/lib/kramdown/utils/lru_cache.rb

@@ -0,0 +1,41 @@
+# -*- coding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# Copyright (C) 2009-2019 Thomas Leitner <t_leitner@gmx.at>
+#
+# This file is part of kramdown which is licensed under the MIT.
+#++
+#
+
+module Kramdown
+  module Utils
+
+    # A simple least recently used (LRU) cache.
+    #
+    # The cache relies on the fact that Ruby's Hash class maintains insertion order. So deleting
+    # and re-inserting a key-value pair on access moves the key to the last position. When an
+    # entry is added and the cache is full, the first entry is removed.
+    class LRUCache
+
+      # Creates a new LRUCache that can hold +size+ entries.
+      def initialize(size)
+        @size = size
+        @cache = {}
+      end
+
+      # Returns the stored value for +key+ or +nil+ if no value was stored under the key.
+      def [](key)
+        (val = @cache.delete(key)).nil? ? nil : @cache[key] = val
+      end
+
+      # Stores the +value+ under the +key+.
+      def []=(key, value)
+        @cache.delete(key)
+        @cache[key] = value
+        @cache.shift if @cache.length > @size
+      end
+
+    end
+
+  end
+end

data/lib/kramdown/utils/string_scanner.rb

@@ -0,0 +1,81 @@
+# -*- coding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# Copyright (C) 2009-2019 Thomas Leitner <t_leitner@gmx.at>
+#
+# This file is part of kramdown which is licensed under the MIT.
+#++
+#
+
+require 'strscan'
+
+module Kramdown
+  module Utils
+
+    # This patched StringScanner adds line number information for current scan position and a
+    # start_line_number override for nested StringScanners.
+    class StringScanner < ::StringScanner
+
+      # The start line number. Used for nested StringScanners that scan a sub-string of the source
+      # document. The kramdown parser uses this, e.g., for span level parsers.
+      attr_reader :start_line_number
+
+      # Takes the start line number as optional second argument.
+      #
+      # Note: The original second argument is no longer used so this should be safe.
+      def initialize(string, start_line_number = 1)
+        super(string)
+        @start_line_number = start_line_number || 1
+        @previous_pos = 0
+        @previous_line_number = @start_line_number
+      end
+
+      # Sets the byte position of the scan pointer.
+      #
+      # Note: This also resets some internal variables, so always use pos= when setting the position
+      # and don't use any other method for that!
+      def pos=(pos)
+        if self.pos > pos
+          @previous_line_number = @start_line_number
+          @previous_pos = 0
+        end
+        super
+      end
+
+      # Return information needed to revert the byte position of the string scanner in a performant
+      # way.
+      #
+      # The returned data can be fed to #revert_pos to revert the position to the saved one.
+      #
+      # Note: Just saving #pos won't be enough.
+      def save_pos
+        [pos, @previous_pos, @previous_line_number]
+      end
+
+      # Revert the position to one saved by #save_pos.
+      def revert_pos(data)
+        self.pos = data[0]
+        @previous_pos, @previous_line_number = data[1], data[2]
+      end
+
+      # Returns the line number for current charpos.
+      #
+      # NOTE: Requires that all line endings are normalized to '\n'
+      #
+      # NOTE: Normally we'd have to add one to the count of newlines to get the correct line number.
+      # However we add the one indirectly by using a one-based start_line_number.
+      def current_line_number
+        # Not using string[@previous_pos..best_pos].count('\n') because it is slower
+        strscan = ::StringScanner.new(string)
+        strscan.pos = @previous_pos
+        old_pos = pos + 1
+        @previous_line_number += 1 while strscan.skip_until(/\n/) && strscan.pos <= old_pos
+
+        @previous_pos = (eos? ? pos : pos + 1)
+        @previous_line_number
+      end
+
+    end
+
+  end
+end

data/lib/kramdown/utils/unidecoder.rb

@@ -0,0 +1,50 @@
+# -*- coding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# Copyright (C) 2009-2019 Thomas Leitner <t_leitner@gmx.at>
+#
+# This file is part of kramdown which is licensed under the MIT.
+#++
+#
+# This file is based on code originally from the Stringex library and needs the data files from
+# Stringex to work correctly.
+
+module Kramdown
+  module Utils
+
+    # Provides the ability to tranliterate Unicode strings into plain ASCII ones.
+    module Unidecoder
+
+      gem 'stringex'
+      path = $:.find do |dir|
+        File.directory?(File.join(File.expand_path(dir), "stringex", "unidecoder_data"))
+      end
+
+      if !path
+        def self.decode(string)
+          string
+        end
+      else
+
+        CODEPOINTS = Hash.new do |h, k|
+          h[k] = YAML.load_file(File.join(path, "stringex", "unidecoder_data", "#{k}.yml"))
+        end
+
+        # Transliterate string from Unicode into ASCII.
+        def self.decode(string)
+          string.gsub(/[^\x00-\x7f]/u) do |codepoint|
+            begin
+              unpacked = codepoint.unpack("U")[0]
+              CODEPOINTS[sprintf("x%02x", unpacked >> 8)][unpacked & 255]
+            rescue StandardError
+              "?"
+            end
+          end
+        end
+
+      end
+
+    end
+
+  end
+end

data/lib/kramdown/version.rb

@@ -1,28 +1,15 @@
-# -*- coding: utf-8 -*-
+# -*- coding: utf-8; frozen_string_literal: true -*-
 #
 #--
-# Copyright (C) 2009-2012 Thomas Leitner <t_leitner@gmx.at>
+# Copyright (C) 2009-2019 Thomas Leitner <t_leitner@gmx.at>
 #
-# This file is part of kramdown.
-#
-# kramdown is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# This file is part of kramdown which is licensed under the MIT.
 #++
 #
 
 module Kramdown
 
   # The kramdown version.
-  VERSION = '0.14.2'
+  VERSION = '2.3.0'
 
 end

data/man/man1/kramdown.1

@@ -1,353 +1,346 @@
-.TH "KRAMDOWN" 1 "May 2012"
+.\" generated by kramdown
+.TH "KRAMDOWN" "1" "January 2019"
 .SH NAME
-kramdown \- a fast, pure-Ruby Markdown-superset converter
-.SH SYNOPSIS
-.B kramdown
-[\fIoptions\fR]
-[\fIFILE\fR ...]
-.SH DESCRIPTION
-kramdown is primarily used for parsing a superset of Markdown and converting it to different output
-formats. It supports standard Markdown (with some minor modifications) and various extensions like
-tables and definition lists. Due to its modular architecture it also allows other input formats than
-Markdown, for example, HTML.
-
-If \fIFILE\fR is not specified, kramdown reads from the standard input. The result is written to the
-standard output.
-
-There are two sets of options that kramdown accepts: The first one includes the options that are
-used directly by the kramdown binary. The second set of options controls how kramdown parses and
-converts its input.
-.SH OPTIONS
-.TP
-.B \-i, \-\-input ARG
-Specify the input format. Available input formats: kramdown (this is the default) or html.
-.TP
-.B \-o, \-\-output ARG
-Specify one or more output formats separated by commas: html (default), kramdown, latex or
-remove_html_tags.
-.TP
-.B \-v, \-\-version
-Show the version of kramdown.
-.TP
-.B \-h, \-\-help
-Show the help.
-
-.SH KRAMDOWN OPTIONS
-
-.TP
-.B \-\-template ARG
-
-The name of an ERB template file that should be used to wrap the output
-
-This is used to wrap the output in an environment so that the output can
-be used as a stand-alone document. For example, an HTML template would
-provide the needed header and body tags so that the whole output is a
-valid HTML file. If no template is specified, the output will be just
-the converted text.
-
-When resolving the template file, the given template name is used first.
-If such a file is not found, the converter extension is appended. If the
-file still cannot be found, the templates name is interpreted as a
-template name that is provided by kramdown (without the converter
-extension).
-
-kramdown provides a default template named 'document' for each converter.
-
-Default: ''
-Used by: all converters
-
-
-.TP
-.B \-\-[no\-]auto-ids
-
+kramdown \- a fast, pure\-Ruby Markdown\-superset converter
+.SH "SYNOPSIS"
+\fBkramdown\fP [\fIoptions\fP] [\fIFILE\fP\.\.\.]
+.SH "DESCRIPTION"
+kramdown is primarily used for parsing a superset of Markdown and converting it to different output formats\. It supports standard Markdown (with some minor modifications) and various extensions like tables and definition lists\. Due to its modular architecture it also allows other input formats than Markdown, for example, HTML or Github Flavored Markdown\.
+.P
+If \fIFILE\fP is not specified, kramdown reads from the standard input\. The result is written to the standard output\.
+.P
+There are two sets of options that kramdown accepts: The first one includes the options that are used directly by the kramdown binary\. The second set of options controls how kramdown parses and converts its input\.
+.P
+Default values for this second set can be set using YAML via the configuration file \fBkramdownrc\fP\&\. Note that configuration option names use underscores, not dashes (dashes are just used in the CLI options names), and boolean options do not have a \fBno\fP variant but a value of \fBtrue\fP or \fBfalse\fP\&\. This file has to be in XDG_CONFIG_HOME on Linux/Unix, ~/Library/Preferences on macOS and ~/AppData/Local on Windows\.
+.SH "CLI\-ONLY OPTIONS"
+.TP
+\fB\-i\fP \fIFORMAT\fP, \fB\-\-input\fP \fIFORMAT\fP
+Specify the input format\. Available input formats: \fIkramdown\fP (this is the default), \fImarkdown\fP, or \fIhtml\fP\&\. The input format \fIGFM\fP is available through the \fBkramdown\-parser\-gfm\fP gem\.
+.TP
+\fB\-o\fP \fIFORMAT\fP, \fB\-\-output\fP \fIFORMAT\fP
+Specify one or more output formats separated by commas: \fIhtml\fP (default), \fIkramdown\fP, \fIlatex\fP, \fIman\fP or \fIremove_html_tags\fP\&\. The converter \fIpdf\fP is available through the \fBkramdown\-converter\-pdf\fP gem\.
+.TP
+\fB\-x\fP \fIEXT\fP, \fB\-\-extension\fP \fIEXT\fP
+Load one or more extensions\. The name of the extension should not include the \fBkramdown\-\fP prefix, e\.g\. just \fBparser\-gfm\fP\&\. Multiple extensions can be loaded by separating them with commas\.
+.RS
+.P
+Note: This option has to be used before any other options that rely on the extension already being loaded\.
+.RE
+.TP
+\fB\-\-no\-config\-file\fP
+Do not read any configuration file\. Default behavior is to check for a configuration file and read it if it exists\.
+.TP
+\fB\-\-config\-file\fP \fIFILE\fP
+Override the default path and name of the configuration file\.
+.TP
+\fB\-v\fP, \fB\-\-version\fP
+Show the version of kramdown\.
+.TP
+\fB\-h\fP, \fB\-\-help\fP
+Show the help\.
+.SH "KRAMDOWN OPTIONS"
+.TP
+\fB\-\-auto\-id\-prefix\fP \fIARG\fP
+Prefix used for automatically generated header IDs
+.RS
+.P
+This option can be used to set a prefix for the automatically generated header IDs so that there is no conflict when rendering multiple kramdown documents into one output file separately\. The prefix should only contain characters that are valid in an ID!
+.P
+Default: \[u2018]\[u2019] Used by: HTML/Latex converter
+.RE
+.TP
+\fB\-\-[no\-]auto\-id\-stripping\fP
+Strip all formatting from header text for automatic ID generation
+.RS
+.P
+If this option is \fBtrue\fP, only the text elements of a header are used for generating the ID later (in contrast to just using the raw header text line)\.
+.P
+This option will be removed in version 2\.0 because this will be the default then\.
+.P
+Default: false Used by: kramdown parser
+.RE
+.TP
+\fB\-\-[no\-]auto\-ids\fP
 Use automatic header ID generation
-
-If this option is `true`, ID values for all headers are automatically
-generated if no ID is explicitly specified.
-
-Default: true
-Used by: HTML/Latex converter
-
-
-.TP
-.B \-\-auto-id-prefix ARG
-
-Prefix used for automatically generated heaer IDs
-
-This option can be used to set a prefix for the automatically generated
-header IDs so that there is no conflict when rendering multiple kramdown
-documents into one output file separately. The prefix should only
-contain characters that are valid in an ID!
-
-Default: ''
-Used by: HTML/Latex converter
-
-
-.TP
-.B \-\-[no\-]parse-block-html
-
-Process kramdown syntax in block HTML tags
-
-If this option is `true`, the kramdown parser processes the content of
-block HTML tags as text containing block-level elements. Since this is
-not wanted normally, the default is `false`. It is normally better to
-selectively enable kramdown processing via the markdown attribute.
-
-Default: false
-Used by: kramdown parser
-
-
-.TP
-.B \-\-[no\-]parse-span-html
-
-Process kramdown syntax in span HTML tags
-
-If this option is `true`, the kramdown parser processes the content of
-span HTML tags as text containing span-level elements.
-
-Default: true
-Used by: kramdown parser
-
-
-.TP
-.B \-\-[no\-]html-to-native
-
-Convert HTML elements to native elements
-
-If this option is `true`, the parser converts HTML elements to native
-elements. For example, when parsing `<em>hallo</em>` the emphasis tag
-would normally be converted to an `:html` element with tag type `:em`.
-If `html_to_native` is `true`, then the emphasis would be converted to a
-native `:em` element.
-
-This is useful for converters that cannot deal with HTML elements.
-
-Default: false
-Used by: kramdown parser
-
-
-.TP
-.B \-\-link-defs ARG
-
-Pre-defines link definitions
-
-This option can be used to pre-define link definitions. The value needs
-to be a Hash where the keys are the link identifiers and the values are
-two element Arrays with the link URL and the link title.
-
-If the value is a String, it has to contain a valid YAML hash and the
-hash has to follow the above guidelines.
-
-Default: {}
-Used by: kramdown parser
-
-
-.TP
-.B \-\-footnote-nr ARG
-
-The number of the first footnote
-
-This option can be used to specify the number that is used for the first
-footnote.
-
-Default: 1
-Used by: HTML converter
-
-
-.TP
-.B \-\-[no\-]enable-coderay
-
-Use coderay for syntax highlighting
-
-If this option is `true`, coderay is used by the HTML converter for
-syntax highlighting the content of code spans and code blocks.
-
-Default: true
-Used by: HTML converter
-
-
-.TP
-.B \-\-coderay-wrap ARG
-
-Defines how the highlighted code should be wrapped
-
-The possible values are :span, :div or nil.
-
-Default: :div
-Used by: HTML converter
-
-
-.TP
-.B \-\-coderay-line-numbers ARG
-
-Defines how and if line numbers should be shown
-
-The possible values are :table, :inline or nil. If this option is
-nil, no line numbers are shown.
-
-Default: :inline
-Used by: HTML converter
-
-
-.TP
-.B \-\-coderay-line-number-start ARG
-
-The start value for the line numbers
-
-Default: 1
-Used by: HTML converter
-
-
-.TP
-.B \-\-coderay-tab-width ARG
-
-The tab width used in highlighted code
-
-Used by: HTML converter
-
-
-.TP
-.B \-\-coderay-bold-every ARG
-
-Defines how often a line number should be made bold
-
-Default: 10
-Used by: HTML converter
-
-
-.TP
-.B \-\-coderay-css ARG
-
-Defines how the highlighted code gets styled
-
-Possible values are :class (CSS classes are applied to the code
-elements, one must supply the needed CSS file) or :style (default CSS
-styles are directly applied to the code elements).
-
-Default: style
-Used by: HTML converter
-
-
-.TP
-.B \-\-coderay-default-lang ARG
-
-Sets the default language for highlighting code blocks
-
-If no language is set for a code block, the default language is used
-instead. The value has to be one of the languages supported by coderay
-or nil if no default language should be used.
-
-Default: nil
-Used by: HTML converter
-
-
-.TP
-.B \-\-entity-output ARG
-
+.RS
+.P
+If this option is \fBtrue\fP, ID values for all headers are automatically generated if no ID is explicitly specified\.
+.P
+Default: true Used by: HTML/Latex converter
+.RE
+.TP
+\fB\-\-entity\-output\fP \fIARG\fP
 Defines how entities are output
-
-The possible values are :as_input (entities are output in the same
-form as found in the input), :numeric (entities are output in numeric
-form), :symbolic (entities are output in symbolic form if possible) or
-:as_char (entities are output as characters if possible, only available
-on Ruby 1.9).
-
-Default: :as_char
-Used by: HTML converter, kramdown converter
-
-
-.TP
-.B \-\-toc-levels ARG
-
-Defines the levels that are used for the table of contents
-
-The individual levels can be specified by separating them with commas
-(e.g. 1,2,3) or by using the range syntax (e.g. 1..3). Only the
-specified levels are used for the table of contents.
-
-Default: 1..6
-Used by: HTML/Latex converter
-
-
-.TP
-.B \-\-line-width ARG
-
-Defines the line width to be used when outputting a document
-
-Default: 72
-Used by: kramdown converter
-
-
-.TP
-.B \-\-latex-headers ARG
-
+.RS
+.P
+The possible values are :as_input (entities are output in the same form as found in the input), :numeric (entities are output in numeric form), :symbolic (entities are output in symbolic form if possible) or :as_char (entities are output as characters if possible, only available on Ruby 1\.9)\.
+.P
+Default: :as_char Used by: HTML converter, kramdown converter
+.RE
+.TP
+\fB\-\-footnote\-backlink\fP \fIARG\fP
+Defines the text that should be used for the footnote backlinks
+.RS
+.P
+The footnote backlink is just text, so any special HTML characters will be escaped\.
+.P
+If the footnote backlint text is an empty string, no footnote backlinks will be generated\.
+.P
+Default: \[u2018]\[u0026]8617;\[u2019] Used by: HTML converter
+.RE
+.TP
+\fB\-\-[no\-]footnote\-backlink\-inline\fP
+Specifies whether the footnote backlink should always be inline
+.RS
+.P
+With the default of false the footnote backlink is placed at the end of the last paragraph if there is one, or an extra paragraph with only the footnote backlink is created\.
+.P
+Setting this option to true tries to place the footnote backlink in the last, possibly nested paragraph or header\. If this fails (e\.g\. in the case of a table), an extra paragraph with only the footnote backlink is created\.
+.P
+Default: false Used by: HTML converter
+.RE
+.TP
+\fB\-\-footnote\-nr\fP \fIARG\fP
+The number of the first footnote
+.RS
+.P
+This option can be used to specify the number that is used for the first footnote\.
+.P
+Default: 1 Used by: HTML converter
+.RE
+.TP
+\fB\-\-footnote\-prefix\fP \fIARG\fP
+Prefix used for footnote IDs
+.RS
+.P
+This option can be used to set a prefix for footnote IDs\. This is useful when rendering multiple documents into the same output file to avoid duplicate IDs\. The prefix should only contain characters that are valid in an ID!
+.P
+Default: \[u2018]\[u2019] Used by: HTML
+.RE
+.TP
+\fB\-\-forbidden\-inline\-options\fP \fIARG\fP
+Defines the options that may not be set using the {::options} extension
+.RS
+.P
+Default: template Used by: HTML converter
+.RE
+.TP
+\fB\-\-header\-offset\fP \fIARG\fP
+Sets the output offset for headers
+.RS
+.P
+If this option is c (may also be negative) then a header with level n will be output as a header with level c+n\. If c+n is lower than 1, level 1 will be used\. If c+n is greater than 6, level 6 will be used\.
+.P
+Default: 0 Used by: HTML converter, Kramdown converter, Latex converter
+.RE
+.TP
+\fB\-\-[no\-]html\-to\-native\fP
+Convert HTML elements to native elements
+.RS
+.P
+If this option is \fBtrue\fP, the parser converts HTML elements to native elements\. For example, when parsing \fB<em>hallo</em>\fP the emphasis tag would normally be converted to an \fB:html\fP element with tag type \fB:em\fP\&\. If \fBhtml_to_native\fP is \fBtrue\fP, then the emphasis would be converted to a native \fB:em\fP element\.
+.P
+This is useful for converters that cannot deal with HTML elements\.
+.P
+Default: false Used by: kramdown parser
+.RE
+.TP
+\fB\-\-latex\-headers\fP \fIARG\fP
 Defines the LaTeX commands for different header levels
-
-The commands for the header levels one to six can be specified by
-separating them with commas.
-
-Default: section,subsection,subsubsection,paragraph,subparagraph,subparagraph
-Used by: Latex converter
-
-
-.TP
-.B \-\-smart-quotes ARG
-
-Defines the HTML entity names or code points for smart quote output
-
-The entities identified by entity name or code point that should be
-used for, in order, a left single quote, a right single quote, a left
-double and a right double quote are specified by separating them with
-commas.
-
-Default: lsquo,rsquo,ldquo,rdquo
-Used by: HTML/Latex converter
-
-
-.TP
-.B \-\-[no\-]remove-block-html-tags
-
+.RS
+.P
+The commands for the header levels one to six can be specified by separating them with commas\.
+.P
+Default: section,subsection,subsubsection,paragraph,subparagraph,subparagraph Used by: Latex converter
+.RE
+.TP
+\fB\-\-line\-width\fP \fIARG\fP
+Defines the line width to be used when outputting a document
+.RS
+.P
+Default: 72 Used by: kramdown converter
+.RE
+.TP
+\fB\-\-link\-defs\fP \fIARG\fP
+Pre\-defines link definitions
+.RS
+.P
+This option can be used to pre\-define link definitions\. The value needs to be a Hash where the keys are the link identifiers and the values are two element Arrays with the link URL and the link title\.
+.P
+If the value is a String, it has to contain a valid YAML hash and the hash has to follow the above guidelines\.
+.P
+Default: {} Used by: kramdown parser
+.RE
+.TP
+\fB\-\-math\-engine\fP \fIARG\fP
+Set the math engine
+.RS
+.P
+Specifies the math engine that should be used for converting math blocks/spans\. If this option is set to +nil+, no math engine is used and the math blocks/spans are output as is\.
+.P
+Options for the selected math engine can be set with the math_engine_opts configuration option\.
+.P
+Default: mathjax Used by: HTML converter
+.RE
+.TP
+\fB\-\-math\-engine\-opts\fP \fIARG\fP
+Set the math engine options
+.RS
+.P
+Specifies options for the math engine set via the math_engine configuration option\.
+.P
+The value needs to be a hash with key\-value pairs that are understood by the used math engine\.
+.P
+Default: {} Used by: HTML converter
+.RE
+.TP
+\fB\-\-[no\-]parse\-block\-html\fP
+Process kramdown syntax in block HTML tags
+.RS
+.P
+If this option is \fBtrue\fP, the kramdown parser processes the content of block HTML tags as text containing block\-level elements\. Since this is not wanted normally, the default is \fBfalse\fP\&\. It is normally better to selectively enable kramdown processing via the markdown attribute\.
+.P
+Default: false Used by: kramdown parser
+.RE
+.TP
+\fB\-\-[no\-]parse\-span\-html\fP
+Process kramdown syntax in span HTML tags
+.RS
+.P
+If this option is \fBtrue\fP, the kramdown parser processes the content of span HTML tags as text containing span\-level elements\.
+.P
+Default: true Used by: kramdown parser
+.RE
+.TP
+\fB\-\-[no\-]remove\-block\-html\-tags\fP
 Remove block HTML tags
-
-If this option is `true`, the RemoveHtmlTags converter removes
-block HTML tags.
-
-Default: true
-Used by: RemoveHtmlTags converter
-
-
-.TP
-.B \-\-[no\-]remove-span-html-tags
-
+.RS
+.P
+If this option is \fBtrue\fP, the RemoveHtmlTags converter removes block HTML tags\.
+.P
+Default: true Used by: RemoveHtmlTags converter
+.RE
+.TP
+\fB\-\-[no\-]remove\-line\-breaks\-for\-cjk\fP
+Specifies whether line breaks should be removed between CJK characters
+.RS
+.P
+Default: false Used by: HTML converter
+.RE
+.TP
+\fB\-\-[no\-]remove\-span\-html\-tags\fP
 Remove span HTML tags
-
-If this option is `true`, the RemoveHtmlTags converter removes
-span HTML tags.
-
-Default: false
-Used by: RemoveHtmlTags converter
-
-
-.TP
-.B \-\-header-offset ARG
-
-Sets the output offset for headers
-
-If this option is c (may also be negative) then a header with level n
-will be output as a header with level c+n. If c+n is lower than 1,
-level 1 will be used. If c+n is greater than 6, level 6 will be used.
-
-Default: 0
-Used by: HTML converter, Kramdown converter, Latex converter
-
-
-.SH EXIT STATUS
-The exit status is 0 if no error happened. Otherwise it is 1.
-.SH SEE ALSO
-The kramdown website, http://kramdown.rubyforge.org/ for more information, especially on the supported
-input syntax.
-.SH AUTHOR
-kramdown was written by Thomas Leitner <t_leitner@gmx.at>.
-.PP
-This manual page was written by Thomas Leitner <t_leitner@gmx.at>.
-
+.RS
+.P
+If this option is \fBtrue\fP, the RemoveHtmlTags converter removes span HTML tags\.
+.P
+Default: false Used by: RemoveHtmlTags converter
+.RE
+.TP
+\fB\-\-smart\-quotes\fP \fIARG\fP
+Defines the HTML entity names or code points for smart quote output
+.RS
+.P
+The entities identified by entity name or code point that should be used for, in order, a left single quote, a right single quote, a left double and a right double quote are specified by separating them with commas\.
+.P
+Default: lsquo,rsquo,ldquo,rdquo Used by: HTML/Latex converter
+.RE
+.TP
+\fB\-\-syntax\-highlighter\fP \fIARG\fP
+Set the syntax highlighter
+.RS
+.P
+Specifies the syntax highlighter that should be used for highlighting code blocks and spans\. If this option is set to +nil+, no syntax highlighting is done\.
+.P
+Options for the syntax highlighter can be set with the syntax_highlighter_opts configuration option\.
+.P
+Default: rouge Used by: HTML/Latex converter
+.RE
+.TP
+\fB\-\-syntax\-highlighter\-opts\fP \fIARG\fP
+Set the syntax highlighter options
+.RS
+.P
+Specifies options for the syntax highlighter set via the syntax_highlighter configuration option\.
+.P
+The value needs to be a hash with key\-value pairs that are understood by the used syntax highlighter\.
+.P
+Default: {} Used by: HTML/Latex converter
+.RE
+.TP
+\fB\-\-template\fP \fIARG\fP
+The name of an ERB template file that should be used to wrap the output or the ERB template itself\.
+.RS
+.P
+This is used to wrap the output in an environment so that the output can be used as a stand\-alone document\. For example, an HTML template would provide the needed header and body tags so that the whole output is a valid HTML file\. If no template is specified, the output will be just the converted text\.
+.P
+When resolving the template file, the given template name is used first\. If such a file is not found, the converter extension (the same as the converter name) is appended\. If the file still cannot be found, the templates name is interpreted as a template name that is provided by kramdown (without the converter extension)\. If the file is still not found, the template name is checked if it starts with \[u2018]string://\[u2019] and if it does, this prefix is removed and the rest is used as template content\.
+.P
+kramdown provides a default template named \[u2018]document\[u2019] for each converter\.
+.P
+Default: \[u2018]\[u2019] Used by: all converters
+.RE
+.TP
+\fB\-\-toc\-levels\fP \fIARG\fP
+Defines the levels that are used for the table of contents
+.RS
+.P
+The individual levels can be specified by separating them with commas (e\.g\. 1,2,3) or by using the range syntax (e\.g\. 1\.\.3)\. Only the specified levels are used for the table of contents\.
+.P
+Default: 1\.\.6 Used by: HTML/Latex converter
+.RE
+.TP
+\fB\-\-[no\-]transliterated\-header\-ids\fP
+Transliterate the header text before generating the ID
+.RS
+.P
+Only ASCII characters are used in headers IDs\. This is not good for languages with many non\-ASCII characters\. By enabling this option the header text is transliterated to ASCII as good as possible so that the resulting header ID is more useful\.
+.P
+The stringex library needs to be installed for this feature to work!
+.P
+Default: false Used by: HTML/Latex converter
+.RE
+.TP
+\fB\-\-typographic\-symbols\fP \fIARG\fP
+Defines a mapping from typographical symbol to output characters
+.RS
+.P
+Typographical symbols are normally output using their equivalent Unicode codepoint\. However, sometimes one wants to change the output, mostly to fallback to a sequence of ASCII characters\.
+.P
+This option allows this by specifying a mapping from typographical symbol to its output string\. For example, the mapping {hellip: \.\.\.} would output the standard ASCII representation of an ellipsis\.
+.P
+The available typographical symbol names are:
+.IP \(bu 4
+hellip: ellipsis
+.IP \(bu 4
+mdash: em\-dash
+.IP \(bu 4
+ndash: en\-dash
+.IP \(bu 4
+laquo: left guillemet
+.IP \(bu 4
+raquo: right guillemet
+.IP \(bu 4
+laquo_space: left guillemet followed by a space
+.IP \(bu 4
+raquo_space: right guillemet preceeded by a space
+.P
+Default: {} Used by: HTML/Latex converter
+.RE
+.SH "EXIT STATUS"
+The exit status is 0 if no error happened\. Otherwise it is 1\.
+.SH "SEE ALSO"
+The kramdown website 
+.UR http://kramdown\.gettalong\.org
+.UE
+for more information, especially on the supported input syntax\.
+.SH "AUTHOR"
+kramdown was written by Thomas Leitner 
+.MT t_leitner@gmx\.at
+.UE
+\&\.
+.P
+This manual page was written by Thomas Leitner 
+.MT t_leitner@gmx\.at
+.UE
+\&\.