Document Composer, Windows

Command

DocumentComposer -license <filename | license_key> -inputdoc <filename> [options]

Parameters/Options

Parameter/OptionsDescriptionDefault value
-license <filename | license_key>specifies the path and filename for the license file or a license keyrequired input
-inputdoc <filename>specifies the path and file name for the document to be transformedrequired input
-outputdoc <filename>specifies the path and file name for the transformed document<inputdoc directory>/inputdoc filename + "_out" + inputdoc suffix
-outputtype <mathml | images>specifies whether to write out MathML or image tagsmathml
-alttext <true | false>specifies whether to include the spoken text of an equation as an alttext attribute of the math tagfalse
-altimg <true | false>specifies whether to include an altimg if MathML is usedtrue
-overwrite <true | false>specifies whether an existing altimg or alttext is overwrittentrue
-imagefolder <dirpath>specifies the path to a directory that will contain the image files<input file directory>/inputdoc filename + "_images"
-imagename <filename>specifies the base file name for the resulting images (e.g. "abc" might result in "abc1.gif")inputdoc filename + sequence number + "." + imagetype
-imagetype <gif | eps | png>specifies the format for the imagesgif
-breakwidth <int>sets the width for line wrapping long equations6in
-pointsize <double>specifies the base font point size for the equations12.0
-dpi <int>specifies the resolution of the resulting images in dots per inch96
-bg <CSS color name | transparent | #rrggbb>specifies the background color for the equationswhite
-fg <CSS color name | #rrggbb>specifies the foreground color for the equationsblack
-basefont <fontname>specifies the font to use as the base font for alpha numeric characters"Times New Roman"
-fontmetrics <true | false>specifies whether metrics data should be included in the transformed documenttrue
-fontconfig <filename>specifies the path and file name of a file that contains a list of font face namesnone
-fontinfo <filename>specifies the path and file name of a file that provides additional font informationnone
-fontencodingsdir <dirpath>specifies the path to a directory with font encoding files<fontinfo directory>, if fontinfo is specified
-useantialias <true | false | automatic>specifies whether to use antialiasing if possible, not to use it, or use it if heuristics thinks it helpsnone
-scriptsatsameheight <true | false>specifies if nested msup/msub etc. may have scripts at same heightfalse
-logfile <filename>specifies the path and file name for a log filenone
-verbosity <mute | normal | debug>specifies what processing messages should be displayed; mute - none; normal - any error messages and whether the image was generated successfully; debug - additional processing informationnormal
-readoptions <filename>specifies the path and file name of an XML file for reading in options valuesnone
-saveoptions <filename>specifies the path and file name of an XML file for saving out options valuesnone
-speechrulesdir <dir>identifies the location of the rules that specify how an expression is spoken<version>\auxiliary\SpeechRules
-speechlang <lang>specifies the ISO 639-1 two-letter code for the language to be spoken (e.g., it for Italian, es for Spanish, zh for Chinese)en
-speechstyle <style>specifies a named speech style to use for speaking expressions in a given languageSimple Speech
-tts <ttsname>specifies the text-to-speech (TTS) engine standard to use for speech controls. This is useful if the text is meant to be spoken by a known voices and results in better quality speech (with pauses, pitch, and pronunciation changes). Legal values are "None", "SAPI4" (older voices), "SAPI5" (newer voices), "SSML" (very new voices)None
-opdict <filename>specifies the path and file name of the configurable operator dictionary. See Configuring the operator dictionary for more information.None

Using the command line

To illustrate the use of the Document Composer, there is a file located in the samples directory that demonstrates how to call it from the command line:

<path-to-mathflow-sdk>/windows/samples/document_composer_cmd32.bat (for 32-bit systems)
<path-to-mathflow-sdk>/windows/samples/document_composer_cmd64.bat (for 64-bit systems)

About the Script

The document_composer_cmd32.bat (or document_composer_cmd64.bat) file calls the DocumentComposer with several options. It contains the following command (formatted for clarity):

"../bin/DocumentComposer32[or 64]"
-license "dessci.lic"
-inputdoc "input.html"
-outputdoc "output.html"
-imagefolder "images"
-saveoptions "opts.xml"
  • The DocumnentComposer program is located in bin/DocumentComposer.
  • The license is a FlexNet license file named dessci.lic, located in the same directory as the document_composer_cmd32[or 64].bat file. This option is always required.
  • The inputdoc file to be processed is named input.html, also located in the same directory as the .bat file. This option is always required.
  • The name of the outputdoc file will be output.html, also located in the same directory as the .bat file.
  • Images generated by the MathML in the inputdoc file will be written to the images subdirectory.
  • Finally, the options used to process this document will be saved to a file named opts.xml.

For a complete list of the command line options, see Command line parameters above.

Sample VB.NET application

The sample Visual Basic program below illustrates how to use the DocumentComposer (DocumentComposer32 or DocumentComposer64 for Windows operating systems) class to process a document with MathML. The source code is provided so that you can experiment with different techniques for use in your own programs.

Prerequisites for running the program

  • You must have the .NET 2.0 Framework installed.
  • The DocumentComposer32.dll (for Windows 32-bit systems) or DocumentComposer64.dll (for Windows 64-bit systems) must be registered. Use the command regsvr32 <path to your operating system's specific DLL> to register it.
  • The dessci.lic file should be in the same directory as the sample code executable. If it's not, be sure to provide the correct path in the License File block of the application window.

Running the program

We don't provide a sample application to illustrate the use of the Document Composer, but since we provide the source code it should be a simple matter to build your own sample application.

To run the program, double-click the file. The sample program allows you to change the input parameters used to process an input document with MathML (see below). After changing the input parameters and telling the program where to save the output document, click the Generate Output Document button.

When the Document Composer successfully processes the document, it will display a confirmation dialog similar to this one:

Document Composer tells you how many equations it found and how many it processed in the input document.

Document Composer tells you how many equations it found and how many it processed in the input document. Dismiss the dialog to see the application window:

Document Composer Windows

Source Code

The source code for the sample program is located in the following directory:

<path-to-mathflow-sdk>/windows/samples/DocumentComposerApplication/src/DocumentComposerApplication

Use Visual Studio to open the DocumentComposerApplication.sln file.

Programming Notes

The main functions/subroutines in this program are as follows:

New()

  • Instantiates a MathFlowSDK.DocumentComposer object, which is used throughout the program.
  • Initializes the program controls with default values
  • Sets the options for the Document Composer using the values of the program controls

ProcessDocument()

Within a Try/Catch block:

  • Sets the options for the Document Composer using the values of the program controls
  • Calls the method to process the input document

SetOptions()

  • Sets the value of each option for the Document Composer from the corresponding program control
  • The general strategy in the sample application for handling exceptions in the SetOption methods is:
    • If an option is required (i.e., license or inputdoc) and an exception is thrown by the SetOption method, throw an exception with the error message returned from the SetOption method
    • If an option is optional and has a default value (e.g., pointsize), catch any exception thrown by the SetOption method, retain the warning message for display later and continue processing, using the default value for that option
    • If an option is optional and does not have a default value (e.g., logfile), catch any exception thrown by the SetOption method, retain the resulting message for display later, and call the SetOption method again with an empty string to tell the system not to use that option and continue processing

Note that this only one way in which the options for a Document Composer can be set. Another possible approach would be to call each set method when the value of a program control changes.

GetOptions()

Sets the value of the program controls from the corresponding options of the Document Composer