reverse_adoc 0.2.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8003d7dcf58a0561295e898bbcc93ce2c4f6168f5b9e2bcb17791fc183a48d04
+  data.tar.gz: 1229e27b2b00ce61d1004bf3348552b8c3749d3b15f0490c3ab85d63bec94964
+SHA512:
+  metadata.gz: 5e162c8c8a83ca274faed8247ff8fde809118e1a2fa02e3cfaf75f1804d9163d6019ee5bd79a33fe3b2dd00aee2780e8809f2139ffbc118899a8985689feedf8
+  data.tar.gz: d8c715a4ccb49082a832590f89b4b434b1502e1d7c2bcc9539fb0c5b47ddc09afb8b87236a48913ebe8dbecb02f848ffa20d83f9b7f2100bc3ed57355309bb25

data/.github/workflows/macos.yml

@@ -0,0 +1,27 @@
+# Auto-generated !!! Do not edit it manually
+# use ci-master https://github.com/metanorma/metanorma-build-scripts
+name: macos
+
+on: [push]
+
+jobs:
+  test-macos:
+    name: Test on Ruby ${{ matrix.ruby }} macOS
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        ruby: [ '2.6', '2.5', '2.4' ]
+    steps:
+      - uses: actions/checkout@master
+      - name: Use Ruby
+        uses: actions/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          architecture: 'x64'
+      - name: Update gems
+        run: |
+          sudo gem install bundler -v "~> 2" --force
+          bundle install --jobs 4 --retry 3
+      - name: Run specs
+        run: |
+          bundle exec rake

data/.github/workflows/ubuntu.yml

@@ -0,0 +1,27 @@
+# Auto-generated !!! Do not edit it manually
+# use ci-master https://github.com/metanorma/metanorma-build-scripts
+name: ubuntu
+
+on: [push]
+
+jobs:
+  test-linux:
+    name: Test on Ruby ${{ matrix.ruby }} Ubuntu
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: [ '2.6', '2.5', '2.4' ]
+    steps:
+      - uses: actions/checkout@master
+      - name: Use Ruby
+        uses: actions/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          architecture: 'x64'
+      - name: Update gems
+        run: |
+          gem install bundler -v "~> 2"
+          bundle install --jobs 4 --retry 3
+      - name: Run specs
+        run: |
+          bundle exec rake

data/.github/workflows/windows.yml

@@ -0,0 +1,30 @@
+# Auto-generated !!! Do not edit it manually
+# use ci-master https://github.com/metanorma/metanorma-build-scripts
+name: windows
+
+on: [push]
+
+jobs:
+  test-windows:
+    name: Test on Ruby ${{ matrix.ruby }} Windows
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        ruby: [ '2.6', '2.5', '2.4' ]
+    steps:
+      - uses: actions/checkout@master
+      - name: Use Ruby
+        uses: actions/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          architecture: 'x64'
+      - name: Update gems
+        shell: pwsh
+        run: |
+          gem install bundler -v "~> 2"
+          bundle config --local path vendor/bundle
+          bundle update
+          bundle install --jobs 4 --retry 3
+      - name: Run specs
+        run: |
+          bundle exec rake

data/.hound.yml

@@ -0,0 +1,3 @@
+ruby:
+  Enabled: true
+  config_file: .rubocop.yml

data/.rubocop.yml

@@ -0,0 +1,10 @@
+# This project follows the Ribose OSS style guide.
+# https://github.com/riboseinc/oss-guides
+# All project-specific additions and overrides should be specified in this file.
+
+inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+AllCops:
+  TargetRubyVersion: 2.3
+Rails:
+  Enabled: true

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+  
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in reverse_asciidoctor.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2018, Ribose
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,290 @@
+= AsciiDoc from HTML and Microsoft Word: reverse_adoc
+
+image:https://img.shields.io/gem/v/reverse_adoc.svg["Gem Version", link="https://rubygems.org/gems/reverse_adoc"]
+image:https://img.shields.io/travis/metanorma/reverse_adoc/master.svg["Build Status", link="https://travis-ci.org/metanorma/reverse_adoc"]
+image:https://codeclimate.com/github/metanorma/reverse_adoc/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/reverse_adoc"]
+image:https://ci.appveyor.com/api/projects/status/s4st0ft8moay90m6?svg=true["Appveyor Build Status", link="https://ci.appveyor.com/project/ribose/reverse-asciidoctor"]
+
+== Purpose
+
+Transforms HTML and Microsoft Word into AsciiDoc.
+
+Based on https://github.com/xijo/reverse_markdown
+
+
+== Installation
+
+Install the gem:
+
+[source,console]
+----
+[sudo] gem install reverse_adoc
+----
+
+or add it to your `Gemfile`:
+
+[source,ruby]
+----
+gem 'reverse_adoc'
+----
+
+
+== Command-line usage
+
+=== HTML to AsciiDoc: `reverse_adoc`
+
+Convert HTML files to AsciiDoc:
+
+[source,console]
+----
+$ reverse_adoc file.html > file.adoc
+$ cat file.html | reverse_adoc > file.adoc
+----
+
+[source,console]
+----
+$ reverse_adoc -h
+Usage: reverse_adoc [options] <file>
+    -m, --mathml2asciimath           Convert MathML to AsciiMath
+    -o, --output=FILENAME            Output file to write to
+    -e, --external-images            Export images if data URI
+    -u [pass_through, drop, bypass, raise],
+        --unknown_tags               Unknown tag handling (default: pass_through)
+    -v, --version                    Version information
+    -h, --help                       Prints this help
+----
+
+
+
+=== Microsoft Word to AsciiDoc: `w2a`
+
+Convert Word `.doc` or `.docx` files to AsciiDoc:
+
+[source,console]
+----
+$ w2a file.docx > file.adoc
+----
+
+[source,console]
+----
+$ w2a input.docx -o output.adoc
+----
+
+Help:
+
+[source,console]
+----
+$ w2a -h
+Usage: w2a [options] <file>
+    -a, --mathml2asciimath           Convert MathML to AsciiMath
+    -o, --output=FILENAME            Output file to write to
+    -e, --external-images            Export images if data URI
+    -v, --version                    Version information
+    -h, --help                       Prints this help
+----
+
+
+NOTE: `w2a` requires LibreOffice to be installed. It uses LibreOffice's
+export to XHTML. LibreOffice's export of XHTML is superior to the native Microsoft Word export
+to HTML: it exports lists (which Word keeps as paragraphs), and it exports OOMML into MathML.
+On the other hand, the LibreOffice export relies on default styling being used in the
+document, and it may not cope with ordered lists or headings with customised appearance.
+For best results, reset the styles in the document you're converting to those in
+the default `Normal.dot` template.
+
+NOTE: Some information in OOMML is not preserved in the export to MathML from LibreOffice;
+in particular, font shifts such as double-struck fonts.
+The LibreOffice exporter does seem to drop some text (possibly associated with
+MathML); use with caution.
+
+NOTE: Adapted from `w2m` of
+https://github.com/benbalter/word-to-markdown[Ben Balter's word-to-markdown]
+
+
+=== Common options
+
+
+==== MathML to AsciiMath conversion
+
+If you wish to convert the MathML in the document to AsciiMath, run the script with the
+`--mathml2asciimath` option:
+
+[source,console]
+----
+$ w2a --mathml2asciimath document.docx > document.adoc
+----
+
+
+==== Extracting images
+
+Images referred by the HTML can be extracted into the destination output folder by using:
+
+[source,console]
+----
+$ reverse_adoc input.docx -o output/file.adoc -e
+$ reverse_adoc input.docx --output output/file.adoc --external-images
+----
+
+
+Word embedded images can be extracted into the destination output folder by using:
+
+[source,console]
+----
+$ w2a input.docx -o output/file.adoc -e
+$ w2a input.docx --output output/file.adoc --external-images
+----
+
+
+==== Handling unknown HTML tags
+
+The `--unknown_tags` option allows you to specify how to handle unknown tags
+(default `pass_through`).
+
+Valid options are:
+
+* `pass_through` - Include the unknown tag completely into the result
+* `drop` - Drop the unknown tag and its content
+* `bypass` - Ignore the unknown tag but try to convert its content
+* `raise` - Raise an error to let you know
+
+
+==== Tagging of borders
+
+Specify how to handle tag borders with the option `--tag_border` (default `' '`).
+
+Valid options are:
+
+* `' '` - Add whitespace if there is none at tag borders.
+* `''` - Do not not add whitespace.
+
+
+== Features
+
+=== General
+
+`reverse_adoc` shares features as a port of `reverse_markdown`:
+
+* Module based -- if you miss a tag, just add it
+* Can deal with nested lists
+* Inline and block code is supported
+* Supports blockquote
+
+It supports the following HTML tags (these are supported by `reverse_markdown`):
+
+* `a`
+* `blockquote`
+* `br`
+* `code`, `tt` (added: `kbd`, `samp`, `var`)
+* `div`, `article`
+* `em`, `i` (added: `cite`)
+* `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `hr`
+* `img`
+* `li`, `ol`, `ul` (added: `dir`)
+* `p`, `pre`
+* `strong`, `b`
+* `table`, `td`, `th`, `tr`
+
+[NOTE]
+====
+* reverse_adoc does *not* support `del` or `strike`, because Asciidoctor does not out of the box.
+* As with reverse_markdown, `pre` is only treated as sourcecode if it is contained in a `div@class = highlight-` element, or has a `@brush` attribute naming the language (Confluence).
+* The gem does not support `p@align`, because Asciidoctor doesn't
+====
+
+In addition, it supports:
+
+* `aside`
+* `audio`, `video` (with `@src` attributes)
+* `figure`, `figcaption`
+* `mark`
+* `q`
+* `sub`, `sup`
+* `@id` anchors
+* `blockquote@cite`
+* `img/@width`, `img/@height`
+* `ol/@style`, `ol/@start`, `ol/@reversed`, `ul/@type`
+* `td/@colspan`, `td/@rowspan`, `td@/align`, `td@/valign`
+* `table/caption`, `table/@width`, `table/@frame` (partial), `table/@rules` (partial)
+* Lists and paragraphs within cells
+** Not tables within cells: Asciidoctor cannot deal with nested tables
+
+The gem does not support:
+
+* `col`, `colgroup`
+* `source`, `picture`
+* `bdi`, `bdo`, `ruby`, `rt`, `rp`, `wbr`
+* `frame`, `frameset`, `iframe`, `noframes`, `noscript`, `script`, `input`, `output`, `progress`
+* `map`, `canvas`, `dialog`, `embed`, `object`, `param`, `svg`, `track`
+* `fieldset`, `button`, `datalist`, `form`, `label`, `legend`, `menu`, `menulist`, `optgroup`, `option`, `select`, `textarea`
+* `big`, `dfn`, `font`, `s`, `small`, `span`, `strike`, `u`
+* `center`
+* `data`, `meter`
+* `del`, `ins`
+* `footer`, `header`, `main`, `nav`, `details`, `section`, `summary`, `template`
+
+
+=== MathML support
+
+If you are using this gem in the context of https://www.metanorma.com[Metanorma],
+Metanorma Asciidoctor accepts MathML as a native mathematical format. So you do not need
+to convert the MathML to AsciiMath.
+
+The gem will optionally invoke the https://github.com/metanorma/mathml2asciimath
+gem, to convert MathML to AsciiMath. The conversion is not perfect, and will need to be
+post-edited; but it's a lot better than nothing.
+
+NOTE: Asciidoctor does not support MathML input. HTML uses MathML.
+The gem will recognize MathML expressions in HTML, and will wrap them in Asciidoctor
+`stem:[ ]` macros. The result of this gem is not actually legal Asciidoctor for `stem`:
+Asciidoctor will presumably
+think this is AsciiMath in the `stem:[ ]` macro, try to pass it into MathJax as
+AsciiMath, and fail. But of course, MathJax has no problem with MathML, and some postprocessing
+on the Asciidoctor output can ensure that the MathML is treated by MathJax (or whatever else
+uses the output) as such; so this is still much better than nothing for stem processing.
+
+
+== Ruby library usage
+
+=== General
+
+Simple to use.
+
+[source,ruby]
+----
+result = ReverseAsciidoctor.convert input
+result.inspect # " *feelings* "
+----
+
+=== Configure with options
+
+Just pass your chosen configuration options in after the input. The given options will last for this operation only.
+
+[source,ruby]
+----
+ReverseAsciidoctor.convert(input, unknown_tags: :raise, mathml2asciimath: true)
+----
+
+
+=== Preconfigure using an initializer
+
+Or configure it block style on a initializer level. These configurations will last for all conversions until they are set to something different.
+
+[source,ruby]
+----
+ReverseAsciidoctor.config do |config|
+  config.unknown_tags      = :bypass
+  config.mathml2asciimath  = true
+  config.tag_border  = ''
+end
+----
+
+
+== Related stuff
+
+* https://github.com/xijo/reverse_markdown[Xijo's original reverse_markdown gem]
+* https://github.com/xijo/reverse_markdown/wiki/Write-your-own-converter[Write custom converters] - Wiki entry about how to write your own converter
+* https://github.com/harlantwood/html_massage[html_massage] - A gem by Harlan T. Wood to convert regular sites into markdown using reverse_markdown
+* https://github.com/benbalter/word-to-markdown[word-to-markdown] - Convert word docs into markdown while using reverse_markdown, by Ben Balter
+* https://github.com/asciidocfx/HtmlToAsciidoc[HtmlToAsciidoc] - Javascript regexp-based converter of HTML to Asciidoctor
+* https://asciidoctor.org/docs/user-manual/[The Asciidoctor User Manual]
+

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler/gem_tasks'
+
+if File.exist?('.codeclimate')
+  ENV["CODECLIMATE_REPO_TOKEN"] = File.read('.codeclimate').strip
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec
+
+desc 'Open an irb session preloaded with this library'
+task :console do
+  sh 'irb -rubygems -I lib -r reverse_asciidoctor.rb'
+end