NIMAS Conversion Tool

Overview

The NIMAS Conversion Tool creates XML or HTML outputs using a single XML source file. It converts NIMAS-conformant XML filesets into leveled XML files and/or into leveled HTML files that can be opened and viewed in a browser. The Conversion Tool may be used to check the completeness and accuracy of the content (text and images) of NIMAS filesets. Leveled XML segments may be useful to Braille transcribers who prefer to work with segments smaller than a single file of a complete work. Note that results may not be completely predictable since levels used in the source file will determine the number and size of segments. The downloadable NIMAS Conversion Tool zip file includes basic documentation and a GNU license as well as the application. Source code for the Conversion Tool is also available in a separate zip file. Code for the NIMAS Conversion Tool is open source and is provided in the hope that additions and improvements may be made by interested parties. Please notify the NIMAS Technical Assistance Center of any changes and modifications by email: aim [at] cast [dot] org. Further developments to the Conversion Tool are welcomed. Users without access to the NIMAC may test the Conversion Tool using files available on the NIMAS Exemplars page.
You may download a small HTML book that was created with the NIMAS Conversion Tool that is part of our Exemplar 10 page. This small exemplar conversion is less than 300 KB and may be rendered in a browser or in one of many reading software tools that display and read HTML pages.
Latest version: 2.1 (April 2009)
  • Resolved issues with Internet Explorer not opening certain pages of created books.
  • Small improvements were made to design and keyboard navigation.
  • Includes all improvements and bug fixes from earlier versions, as listed below.
Changes in version 2.0 (March 2009)
  • Generated HTML files have been completely re-designed. Our goal was to create simple, clear, accessible, attractive pages.
  • Table of contents has been simplified: a single TOC page now lists all sections.  Sections can be collapsed to look at an overview of the book, or individually expanded to reveal their sub-sections.
  • Navigation by page number: the table of contents includes page numbers from the print version, so you can directly link to any page in a book.  When paging through the HTML files, the current  page number is always shown at the top of the screen.
  • Navigation clarified: each page now has "previous" and "next" links that allow for simple navigation through a book, available both at the top and the bottom of each page.
  • Image bug fixes: various issues with image conversion and resolution reduction have been fixed. All image types, including JPG, PNG, and SVG, should work properly.
  • Link bug fixed: hyperlinks between pages of a book, if provided, should now work.
Changes in version 1.1 (February 2008):
  • Mathematical content is now recognized, converted, and displayed properly; and accessible to MathML-aware web browsers and tools.
  • SVG images are now recognized and copied into output.
The NIMAS Conversion Tool 2.1 version zip file contains the following:
  • Application (-.exe)
  • GNU license (-.txt)
  • Documentation (-.doc; -.rtf)
Source code for the NIMAS Conversion Tool is available in the following zip file:
  • The executable's development environment is currently Windows-based, using ActiveState Perl and wxWidgets for Windows XP and 2000. The environment and Tool could be ported to any operating system that supports Perl, wxWidgets, GD, LibXML, LibXSLT, and PAR. Be sure to read the README file after downloading the source files for additional information.

Installation

Install the nimas2h.exe file onto a Windows XP computer in an accessible directory.

Running the Conversion Tool

Double-click nimas2h.exe to start the converter. The first time you start it, the Conversion Tool will do some unpacking/installation steps, which will take a minute or two during which it will appear that nothing is happening. Subsequent opening of the Tool will be as fast as opening other applications on your computer. Once unpacked, the initial pane of the Tool will be displayed:
NIMAS Conversion Tool


File menu

The File menu at the top left of the pane contains two choices:
  • About: Displays a window listing the purpose of and license information for the tool. The keyboard shortcut for this function is F1. Pressing Enter will close the About box.
  • Exit: Closes the tool. The keyboard shortcut for this function is ALT+F4.

XML file to convert

If you know the location of the XML file you want to convert, type it in the XML file to convert field starting with the correct drive name (for example: C:\foldername\filename.xml). Otherwise, use the Browse button just below the field to open a file browser dialogue box and navigate to the appropriate file:
NIMAS Conversion Tool File Browser

Click on the XML file you want to convert with the tool and click Open. The file and its pathname will appear in the XML file to convert field.
Note: The directory containing the XML file should also contain the corresponding -.opf file for the XML file being converted. This will be used to create a cover page as part of the HTML output.

Output directory

If you know the output location you'd like to use, type it in the Output directory field starting with the correct drive name (for example: C:\name\outputname). Otherwise, use the Browse button just below the field to open a directory browser dialogue box and navigate to the appropriate directory:
NIMAS Conversion Tool - Output Directory

Click on the output directory you want to save the conversion (output) to and click OK. The output directory and its pathname will appear in the Output directory field. If you need to create a new output directory in which to save the conversion, navigate to the base location you want and use the Make New Folder button to create a new directory and then click OK. The output directory and its pathname will appear in the Output directory field.

Output choices

Next, click one or more checkboxes to choose output options:
  • Create split HTML: This option creates an HTMLOUT directory under your chosen output directory, then populates it with a cover page (index.html) and an HTML directory containing the files for each page.
  • Create split XML: This option creates an XMLOUT directory under your chosen output directory, then populates it with XML files divided by levels.
  • Reduce images: This option copies any images referenced in the XML source file into the HTMLOUT\HTML directory created by the Conversion Tool for use in split HTML pages. Reducible images will be reduced in display size and in file size. Although publishers are required to provide images that are 300 dpi (dots per inch) in NIMAS filesets, in cases where images are provided in an appropriate physical size for an HTML version, users may elect not to have images reduced. If the Reduce images checkbox is not selected, the images must be manually copied to the HTMLOUT\HTML folder in order for images to be rendered within the HTML conversion output. An images folder is always created automatically, but when Reduce images is not selected, it contains only a bookcover image and a next button image.
When you have chosen the options that you want for a conversion, click the Convert button at the bottom right of the pane to begin conversion. A progress dialogue box will display while the conversion is in process—this may take several minutes for a large book:
NIMAS Conversion Tool Converting File

When a conversion is complete, a message will be displayed showing the location of created files:
NIMAS Conversion Tool Conversion Complete

Click OK to close this message. If split HTML was created, you should be able to view the HTMLOUT/index.html file (the cover page) in a browser and navigate through the split HTML from there. If an index.html page was not created, use the start.html file (the first page of converted content) instead.
New locations and options can be entered in the Tool to execute more conversions. If you would like to convert another NIMAS fileset, click the Reset button to the left of the Convert button and enter new information in the cleared fields. When all conversions are complete, click the NIMAS Conversion Tool Close Button at the top right of the box, click the Exit button at the bottom right of the box, or use the keyboard shortcut ALT+F4 to close the Tool.

Images

If you use the Conversion Tool to create a split HTML output without choosing to reduce associated images, the Conversion Tool creates an image folder in the HTML output folder with only a bookcover image and a next button image. Drag and drop or copy and paste those two images into your original images folder and discard the now-empty HTML output images folder. Then move or copy the original images folder into the HTMLOUT output folder. See also the Reduced images paragraph above.
NOTE: Microsoft's Internet Explorer (IE) versions 6 and 7 are able to render SVG images if the Adobe SVG Viewer is installed as a browser plug-in. It is available for free from Opens new windowhttp://www.adobe.com/svg/viewer/install/. The Viewer is not available for Internet Explorer 8 so please know in advance that HTML conversions that include SVG images will not display properly within IE8. Firefox, Opera, Google Chrome, and Safari browsers are able to support SVG without the need for a plug-in or extension.

Memory

Due to memory creep, it is recommended that you perform no more than five (5) conversions in a row without closing the application and re-opening it. Simply close and re-open the Tool to convert more than five files.

Troubleshooting

Program Refuses to Start

Check that your temporary file location (TEMP variable) is set to a directory with at least 10MB of free space. From the Start button, follow this sequence:
  • Settings
  • Control Panel
  • System
  • Advanced
  • Environment Variables
Make sure that your user value for TEMP is correct.

Program creates HTMLOUT directory, but no leveled HTML

Check that your XML source file contains an appropriate DOCTYPE declaration for the DTBook DTD. As of this writing, the appropriate settings are:
PUBLIC ID—one of:
"-//NISO//DTD dtbook 2005-1//EN"
"-//NISO//DTD dtbook 2005-2//EN"
"-//NISO//DTD dtbook 2005-3//EN"
SYSTEM ID—one of:
"http://www.daisy.org/z3986/2005/dtbook-2005-1.dtd"
"http://www.daisy.org/z3986/2005/dtbook-2005-2.dtd"
"http://www.daisy.org/z3986/2005/dtbook-2005-3.dtd"
or a local copy of one of the above DTD files whose location is accessible.

Program cannot create directories or files

Check that the directory containing the NIMAS XML source file to be converted has enough space for the XML and HTML output files and that you have the ability to create files in this directory.

Images are too small

If the reduced images created by the Conversion Tool are too small, it may be that the original images were not at the expected 300 dpi resolution. In this case, do not select the Reduced images checkbox. Instead, copy and paste the original images folder into the HTMLOUT output folder (remember to move the conversion tool bookcover and next button images into the original images folder and then to delete the empty images folder).

Credits

The NIMAS Conversion Tool is maintained by the NIMAS Development and Technical Assistance centers. The source code for the Tool has been made open source in order to encourage other interested parties in expanding and improving the Tool. Please send an email to aim [at] cast [dot] org if you have questions about or contributions to make to the Tool. Visit the NIMAS Center pages for more information about NIMAS.
The NIMAS Conversion Tool was programmed by Paul Crook under contract to CAST. The CAST in-house development team included Chuck Hitchcock, Valerie Hendricks, and Boris Goldowsky. The conversion stylesheets were developed by the DSIDTB project (Opens new windowhttp://dsidtb.sourceforge.net/) and the DAISY Pipeline (Opens new windowhttp://daisymfc.sourceforge.net/). Development of the features for supporting MathML was generously contributed by Design Science: Opens new windowhttp://www.dessci.com/.
Share

Last Updated: 10/18/2013

ClickSpeak Play Pause Stop