= docuvert

https://www.npmjs.com/package/docuvert:[image:https://img.shields.io/npm/v/docuvert.svg?style=flat-square[npm version badge]] image:https://img.shields.io/david/zorceta/docuvert.svg?style=flat-square[David dependencies badge] image:https://img.shields.io/david/dev/zorceta/docuvert.svg?style=flat-square[David dev dependencies badge]

A **document convert**er for JavaScript.

== Quick start

[shell]

$ npm i docuvert docuvert-format-what-you-need --save

[source,javascript]

import * as docuvert from 'docuvert' docuvert.loadFormats([ require('docuvert-format-asciidoc'), require('docuvert-format-html') ])

let content = `= docuvert

A document converter for JavaScript. `

let converted = docuvert.convert('asciidoc', 'html', content)

== Usage

docuvert itself is only a shell for formatters to unleash their power.

So, before using it, prepare formatters of all the formats you need.

[source,javascript]

import * as docuvert from 'docuvert' docuvert.loadFormats([ require('docuvert-format-asciidoc'), require('docuvert-format-html') ])

Then, if your content needs to be converted to only one format

[source,javascript]

let converted = docuvert.convert( 'asciidoc', 'html', = docuvert A document converter for JavaScript. )

Or, if more than one format is needed

[source,javascript]

let formatsNeeded = ['html', 'markdown', 'restructuredtext', 'pdf'], document = docuvert.Document.from('asciidoc', content), converted = {}

formatsNeeded.forEach(formatName => { converted[formatName] = document.to(formatName) })

Or, if you are not sure which formats are needed

[source,javascript]

let document = docuvert.Document.from('asciidoc', content), toFormat = input('Which format do you want?'), converted = document.to(toFormat)

== API

=== docuvert

==== docuvert.Document

===== Document.from(fromFormat, content, options)

Returns a Document instance representing content.

• fromFormat required the format content is in
• content required names itself
• options optional passed to formatter

===== document.to(toFormat, options)

Returns document (a Document instance) in toFormat format.

• toFormat required the format you want document in
• options optional passed to formatter

==== docuvert.convert(fromFormat, toFormat, content, options)

Returns content, which is originally in fromFormat, in toFormat.

• fromFormat required the format content is in
• toFormat required the format you want content in
• content required names itself
• options optional ** from optional passed to formatter ** to optional passed to formatter

== Formatters

docuvert relies heavily on formatters. Itself without formatters is like a company without its staff.

A formatter must have these properties

• string formatName required full name of the format this formatter is for
• .from(content, options) turns content into a Document instance ** content required names itself ** options optional names itself
• .to(options) turns a Document instance into a text in the format this formatter is for ** options optional names itself

Implementation details are not cared about.

=== Document tree and elements

docuvert abstracts the structure of a document into a tree, and several elements that form a tree.

==== Common characteristics of elements

• All elements have following properties

** parent parent of that element on the document tree, an instance of an Element sub"class" ** attributes attributes of that element, an object acting as a dictionary, with the name Attributes an object acting as a dictionary, with the name Style

• All listed attributes are always present, generated by the constructor. + An attribute marked required is immutable, thus must be provided on element creation. + Similarly, an attribute marked optional is mutable, and can be later changed (which usually can not be filled on element creation).

• content attribute, if not explicitly specified, is an Array containing child elements of that element.

• Image, Audio and Video elements have the source attribute that may be a URI or path that points to their source, rather than containing the content. + Formatters dealing with formats that contain all resources in a single file, such as PDF, should notice this.

==== Element

This is the base class (prototype). It sets the default attributes. Not for direct use.

==== ElementWithContents

A convenience base class.

• Array children names itself
• .addContent(content) equivalent to .children.push(content)

==== Document

a.k.a. docuvert.Document.

This is a special element, the instance of which represents a document, the tree of it, and the root of its tree.

Its parent attribute always is and must be null.

==== Text(content)

Names itself. The most basic element.

• string type required ** text a piece of text ** span a group of text
• children required ** type='text' a string ** type='span' an Array of Text
• .addContent(content) ** type='text' equivalent to .children = content ** type='span' equivalent to .children.push(content)

Here are a number of possible attributes

bold, italic, strikethrough, underline, monospace, strong, emphasis, small, mark (highlight), superscript, subscript

that all name themselves and are very common.

==== Image(source)

__Represent__s an image.

• string source required names itself

==== Audio(source)

__Represent__s an audio.

• string source required names itself

==== Video(source)

__Represent__s a video.

• string source required names itself

==== Link(link) extends ElementWithContents

The most basic element for the Internet.

• string link required names itself

==== Heading(level) extends ElementWithContents

Names itself.

• number level required names itself

==== List(ordered) extends ElementWithContents

Names itself.

• boolean ordered required names itself

===== List.Item extends ElementWithContents

Names itself.

==== Table

Names itself.

• Table.Body body optional names itself
• Table.Header header optional names itself
• Table.Footer footer optional names itself

===== Table.Body extends ElementWithContents

Names itself.

===== Table.Header extends ElementWithContents

Names itself.

===== Table.Footer extends ElementWithContents

Names itself.

===== Table.Row extends ElementWithContents

Names itself.

===== Table.Cell extends ElementWithContents

Names itself.

==== Paragraph extends ElementWithContents

Names itself.

==== Quotation(inline, type) extends ElementWithContents

Names itself.

• boolean inline required is this quotation inline or a block, i.e. <q> or <blockquote> using HTML as an example.
• string type required can be the following ** "text" names itself ** "code" names itself

==== Block extends ElementWithContents

A section that divides an area from its parent, whether for content grouping or styling purpose.

==== Raw extends ElementWithContents

A not escaped piece of content, usually in another format, embedded in current format.

==== Comment extends ElementWithContents

Uh. Seems every single language in this world supports comment.

==== LineBreak

When a piece of text needs to be in two separate lines, meanwhile needs not be in two paragraphs. The same for other types of content.

No content.

== License

Copyright (c) 2015 https://github.com/zorceta[Zorceta Moshak].

Code licensed under https://opensource.org/licenses/BSD-3-Clause[BSD 3-Clause]. LICENSE.txt under the root directory is a copy of the license text.