Html2Doc

result

is the Html document to be converted into Word, as a string.

filename

is the name the document is to be saved as, without a file suffix

imagedir

base directory for local image file names in source XML

stylesheet

is the full path filename of the CSS stylesheet for Microsoft Word-specific styles. If this is not provided, the program will used the default stylesheet included in the gem, lib/html2doc/wordstyle.css. The stylsheet provided must match this stylesheet; you can obtain one by saving a Word document with your desired styles to HTML, and extracting the style definitions from the HTML document header.

header_file

is the filename of the HTML document containing header and footer for the document, as well as footnote/endnote separators; if there is none, use nil. To generate your own such document, save a Word document with headers/footers and/or footnote/endnote separators as an HTML document; the header.html will be in the {filename}.fld folder generated along with the HTML. A sample file is available at https://github.com/metanorma/metanorma-iso/blob/master/lib/asciidoctor/iso/word/header.html

dir

is the folder that any ancillary files (images, headers, filelist) are to be saved to. If not provided, it will be created as {filename}_files. Anything in the directory will be attached to the Word document; so this folder should only contain the images that accompany the document. (If the images are elsewhere on the local drive, the gem will move them into the folder. External URL images are left alone, and are not downloaded.)

asciimathdelims

are the AsciiMath delimiters used in the text (an array of an opening and a closing delimiter). If none are provided, no AsciiMath conversion is attempted.

liststyles

a hash of list style labels in Word CSS, which are used to define the behaviour of list item labels (e.g. i) vs i.). The gem recognises the hash keys ul, ol. So if the appearance of an ordered list’s item labels in the supplied stylesheet is governed by style @list l1 (e.g. @list l1:level1 {mso-level-text:"%1\)";} appears in the stylesheet), call the method with liststyles:{ol: "l1"}. The lists that the ul and ol list styles are applied to are assumed not to have any CSS class. If there any additional hash keys, they are assumed to be classes applied to the topmost ordered or unordered list; e.g. liststyles:{steps: "l5"} means that any list with class steps at the topmost level has the list style l5 recursively applied to it. Any top-level lists without a class named in liststyles will be treated like lists with no CSS class.

Note that the local CSS stylesheet file contains a variable FILENAME for the location of footnote/endnote separators and headers/footers, which are provided in the header HTML file. The gem replaces FILENAME with the file name that the document will be saved as. If you supply your own stylesheet and also wish to use separators or headers/footers, you will likewise need to replace the document name mentioned in your stylesheet with a FILENAME string.

We include a script in this distribution that processes files from the command line, optionally including header and stylesheet:

The generated Word document is not quite in the most “native” format used by Word, .docx: it outputs the older .doc format. (See https://github.com/metanorma/html2doc/wiki/Why-not-docx%3F for the reasons why.)

Here are the steps to convert our output into native-docx.

The good news is that Word understands HTML.

The bad news is that Word’s understanding of HTML is HTML 4. In order for bookmarks to work, for example, this gem has to translate <p id=""> back down into <p><a name="">. Word (and this gem) will not do much with HTML 5-specific elements (or SVG graphics), and if you’re generating HTML for automated generation of Word documents, you need to keep your HTML old-fashioned.

The good news with generating a Word document via HTML is that Word understands CSS, and you can determine much of what the Word document looks like by manipulating that CSS. That extends to features that are not part of HTML CSS: if you want to work out how to get Word to do something in CSS, save a Word document that already does what you want as HTML, and inspect the HTML and CSS you get.

The bad news is that Word’s implementation of CSS is poorly documented — even if Office HTML is documented in a 1300 page document (online here and here), and the CSS selectors are only partially and selectively implemented. For list styles, for example, mso-level-text governs how the list label is displayed; but it is only recognised in a @list style: it is ignored in a CSS rule like ol li, or in a style attribute on a node. CSS selectors only support classes, in ancestor relations: p.class1 ol.class2 is supported, but #id1 is not, and neither is p > ol. Working out the right CSS for what you want will take some trial and error, and you are better placed to try to do things Word’s way than the right way.

Word uses OMML instead of W3C’s MathML which is now the de-facto standard of XML math representation.

The Plurimath gem is used to convert Metanorma’s MathML into OMML.

By default, mathematical formulas that are the only content of their paragraph are rendered as centered in Word. If you want your AsciiMath or MathML to be left-aligned or right-aligned, add style="text-align:left" or style="text-align:right" to its ancestor div, p or td node in HTML.

Natively, Word does not use <ol>, <ul>, or <dl> lists in its HTML exports at all: it uses paragraphs styled with list styles. If you save a Word document as HTML in order to use its CSS for Word documents generated by HTML, those styles will still work (with the caveat that you will need to extract the @list style specific to ordered and unordered lists, and pass it as a liststyles parameter to the conversion). Word HTML understands <ol>, <ul>, <li>, but its rendering is fragile: in particular, any instance of <p> within a <li> is treated as a new list item (so Word HTML will not let you have multi-paragraph list items if you use native HTML.) This gem now exports lists as Word HTML prefers to see them, with MsoListParagraphCxSpFirst, MsoListParagraphCxSpMiddle, MsoListParagraphCxSpLast styles. You will need to include these in the CSS stylesheet you supply, in order to get the right indentation for lists.