= 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]