voikya/swordfish

Document parser

Swordfish is a simple document processing library for Ruby. It enables the conversion of Microsoft Word XML documents (.docx) into clean, semantic HTML5, without all the mess that normal export tools or copy-and-paste would produce.

Features

Swordfish currently supports identifying the following features:

• Paragraphs
• Formatting: bold, italic, underline, superscript, subscript, strikethrough
• Links
• Lists (including nested lists)
• Tables
• Footnotes and Endnotes
• Images (except for Word Drawings)

Installation

Swordfish is available through RubyGems, so you can install it with gem install swordfish.

Converting a Document

Converting a Word document into HTML just requires two calls: one to parse the document, and one to generate the markup:

require 'swordfish'
Swordfish.open('~/Documents/my_word_doc.docx').to_html

Additional configuration options may be provided by calling settings with a hash of parameters prior to generating the final markup. For instance, if you want to enable footnotes (appearing as a block at the end of the HTML document), enable the footnotes option:

Swordfish.open('~/Documents/my_word_doc.docx').settings(:footnotes => true).to_html

The following settings are currently available (all are boolean, and default to false)

• guess_headers — When true, attempt to identify headers within the text and assign them the appropriate <h1> through <h6> tags. When false, all text will be presented as normal paragraphs.
• footnotes — When true, preserve footnote and endnote content in a block at the end of the generated HTML, including links back to the original reference points in the text. When false, footnotes will be ignored.
• smart_br — When true, attempt to clean up unnecessary linebreaks often present in Word markup, such as at the very beginning or end of a paragraph. When false, linebreaks will be preserved exactly as in the original Word markup.
• full_document — When true, the generated HTML will represent a complete HTML document, including a doctype and header. When false, the output will be an HTML fragment suitable for insertion into the DOM, for example.

Images within the Word document are available after parsing by calling the images method, which returns a hash of file names and temporary files.

# Print the file name and size of each image in a document
doc = Swordfish.open('~/Documents/my_word_doc.docx')
doc.images.each do |filename, tempfile|
  puts "#{filename}: #{tempfile.size}"
end

swordfish's Issues

Docx "Track Changes" markup

Support needs to be added for Word "track changes" markup, which includes a history of elements that have been inserted, deleted, or moved. Right now any document with changes tracked (that haven't been accepted) will result in incorrect rendered content, such as missing certain text or including text that has been deleted.

UTF-8 support

I am really keen on Swordfish, I'd been searching for such an utility for ages!

However, is there any way how to preserve another languages next to English?

When I am parsing a Czech file, the result includes many errors on diacritical marks places...

I am sorry I am writing my question here, don't now how to do that better. It could be a feature request!

Thanks!

Headers

I see headers are supported (early stage) but can't reach any result when testing that. I guess it searches and evaluates the paragraph font size in comparison with its surroundings (this does not work for me). In my test file the header is typically marked like:

<w:pPr>
  <w:pStyle w:val="Nadpis1" />

The "Nadpis1" value would change according to the users language of Office. Do you count with this or are you convinced it would be more smart and take the values it probably takes now (sizes)? How to make that working, please?

Swordfish is really inspiring, I will fork it again and try to shape it to produce xml files. Our publishing house would use it for much quicker publication (we are non-profit academic house). That means, you helped a lot with the gem 👍

Collapse together tags with identical markup

If an imported Word document includes multiple text runs with identical formatting, it will be rendered with redundant tags by swordfish.

    <w:p w14:paraId="2B8680DD" w14:textId="15414D41" w:rsidR="006A368B" w:rsidRPr="00313672" w:rsidRDefault="000D3167" w:rsidP="006A368B">
        <w:pPr>
            <w:rPr>
                <w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman" w:cs="Times New Roman"/>
                <w:b/>
                <w:color w:val="222222"/>
            </w:rPr>
        </w:pPr>
        <w:r>
            <w:rPr>
                <w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman" w:cs="Times New Roman"/>
                <w:b/>
                <w:color w:val="222222"/>
            </w:rPr>
            <w:t>ABC</w:t>
        </w:r>
        <w:r w:rsidR="006A368B">
            <w:rPr>
                <w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman" w:cs="Times New Roman"/>
                <w:b/>
                <w:color w:val="222222"/>
            </w:rPr>
            <w:t xml:space="preserve">
            </w:t>
        </w:r>
        <w:r w:rsidR="006A368B" w:rsidRPr="00A171DF">
            <w:rPr>
                <w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman" w:cs="Times New Roman"/>
                <w:i/>
                <w:iCs/>
                <w:color w:val="222222"/>
            </w:rPr>
            <w:t>123</w:t>
        </w:r>
    </w:p>

becomes

<p><b>ABC</b><b> </b><i>123</i></p>

Docx Complex Fields

Add support for docx "complex fields"—a series of five or more runs that define a control flow rather than regular text. In particular, this is needed for the "HYPERLINK" field, since that corresponds to a distinct non-plaintext HTML element.

        <w:r w:rsidRPr="00A171DF">
            <w:rPr>
                <w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman" w:cs="Times New Roman"/>
                <w:color w:val="222222"/>
            </w:rPr>
            <w:fldChar w:fldCharType="begin"/>
        </w:r>
        <w:r w:rsidRPr="00A171DF">
            <w:rPr>
                <w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman" w:cs="Times New Roman"/>
                <w:color w:val="222222"/>
            </w:rPr>
            <w:instrText xml:space="preserve"> HYPERLINK "https://docs.google.com/spreadsheet/ccc?key=..." \t "_blank" </w:instrText>
        </w:r>
        <w:r w:rsidRPr="00A171DF">
            <w:rPr>
                <w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman" w:cs="Times New Roman"/>
                <w:color w:val="222222"/>
            </w:rPr>
            <w:fldChar w:fldCharType="separate"/>
        </w:r>
        <w:r w:rsidRPr="00A171DF">
            <w:rPr>
                <w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman" w:cs="Times New Roman"/>
                <w:i/>
                <w:iCs/>
                <w:color w:val="1155CC"/>
                <w:u w:val="single"/>
                <w:shd w:val="clear" w:color="auto" w:fill="FFFFFF"/>
            </w:rPr>
            <w:t>here</w:t>
        </w:r>
        <w:r w:rsidRPr="00A171DF">
            <w:rPr>
                <w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman" w:cs="Times New Roman"/>
                <w:color w:val="222222"/>
            </w:rPr>
            <w:fldChar w:fldCharType="end"/>
        </w:r>

Write Word Doc

Would it be difficult to add the ability to update an existing document or output a new a word doc built up programmatically in swordfish?