Logictran RTF Converter (R2Net) - FAQ

The Logictran RTF Converter FAQ provides answers to commonly asked questions about using the Logictran RTF converter, how to customize the output, creating XML, etc.

A. General


  1. What is the Logictran RTF converter?
    The Logictran RTF converter is a utility that allows customized translation of RTF’s to an alternative document format. Typically, but not required, this would be a tag based format such as HTML or XML. The converter is provided with ‘translation files’ that map to HTML, XHTML, XML (Docbook DTD), OEB, and LIT. HTML and XHTML formats may optionally produce Cascading Stylesheets (CSS). Extensive customization options exist, ranging from simply altering the background color, through splitting the output files along major heading boundaries, to completely changing the output format (eg to PML for display on devices running Palm OS).

    File based and string based translations are provided. Where string based translations may be used for such tasks as mapping database held RTF fragments to HTML without needing to write an intermediate file.

    The translation process may be embedded into applications written in C/C++/Visual Basic/Delphi/etc., or provided on an ASP page.

  2. What platforms does it run on?

    Windows 95/98/ME/2K/NT, Macintosh, Linux, and Solaris.

  3. What input formats are supported?
    The translation engine understands RTF’s. Any file that can be saved to RTF format may be converted through the converter. Microsoft Word (.doc) files are automatically translated to RTF on a Windows system when Microsoft Word is installed. Likewise Excel spreadsheets may be converted using the converter after they are saved to RTF.

    On non-Windows systems, RTF is the only supported input format.

  4. Is an evaluation copy available?

    Yes. Download from www.logictran.com/latest.html. Register when downloading, or via www.logictran.com/eval.html to enable the 30 day evaluation. The evaluation copy provides all of the capabilities of the converter and is only restricted in how many days it may be used.

  5. What output formats may be generated?
    By default: HTML (versions 3 and 4), XHTML, OEB (Open E-book), XML (Docbook DTD), LIT (for viewing in Microsoft Reader – Windows platform only). Full customization is possible to generate any output format, typically, but not necessarily, tag based.

  6. What if the output isn’t quite as I want it?
    The output generated may be customized. Two documents describe this process, both provided with the evaluation download from www.logictran.com/latest.html,Guide.html and CustomRef.html. Typically, customization will involve creating or modifying a ‘translation file’. For more local changes to an existing format (eg HTML), these changes will normally be applied to trnfile.trn. See additional questions/answers for how to use trnflag.trn, or Guide.html/CustomRef.html for details.

  7. Can I embed the converter into my application?
    Yes. On Windows, DLL, ActiveX and ASP accessible interfaces are provided. Examples of using these interfaces are provided with the download, including (a) a C++ sample and Visual C++ workspace, (b) a Visual Basic sample using the ActiveX interface, (c) a Visual Basis sample using the DLL interface, and (d) an ASP based sample. Documents are provided in the ‘docs’ folder of the download describing each of these interfaces.

    On Linux and Solaris, a library interface is provided to allow the converter to be embedded within an application. A sample application and documentation is provided.

    Redistribution of any applications that embed the converter requires a license agreement with Logictran. Please contact us for details.

  8. Can I embed the converter into my web page for dynamic RTF translation?
    Yes. Through the ASP interface on Windows and various customers have embedded the Linux/Solaris versions into a web server environment on those platforms.

  9. Do I need the ‘Developers’ version?

    The Developers license is needed whenever the converter is embedded into a separate application. That is, through the DLL/ActiveX/ASP or Unix library interfaces. One developer license is required per developer working on embedding the converter into separate application(s).

    Users who just make use of the provided Logictran interfaces (eg the r2net GUI, r2netcmd, etc) require the run-time (end-user) license.

  10. Do I need the ‘Server’ license?

    If the Logictran RTF converter is made available in a ‘server’ environment, such that multiple users have access, then a server license is required. If the converter is only available on an individual users desktop system, then the single-user license is required.

  11. Are images supported?
    Yes. Images will be extracted from the RTF, saved to disk, and references written to the output file. By default, PNG and JPG files are left in those formats and all other image formats (eg WMF and PICT) are converted to PNG, JPG or GIF depending on the setting of

    .Strings
    ImageExt,’1’

    See CustomRef.html for details on renaming or changing the directory of saved images (search for GenImageFileName).


  12. Are tables supported?
    Yes.

  13. What is string2net?
    String2net is a desktop utility which allows text to be typed, cut&pasted or drag&dropped into one text area, then converted to equivalent HTML in a second text area. It is useful for converting snippets of text (eg from open word processors, text documents, etc) into HTML.

  14. What is doc2net?
    Doc2net converts Microsoft Word files into HTML or XML. It uses Microsoft Word to convert the document into an RTF before using the Logictran converter to map to the output format. Doc2net functionality is now included in r2net.

  15. What is img2net?
    Img2net converts WMF or BMP image format files to PNG or JPG. It will also convert JPG to/from PNG. Img2net is used as part of the translation process to map extracted images to the appropriate web-ready format.

  16. How much does the converter cost?
  17. What are the licensing restrictions?

    An agreement with Logictran is required before redistribution of the converter technology, in part or whole, is required. Please contact us for details.

  18. What support is provided?

    General support is provided with any license purchased. That is to answer general questions about the converter and customizing the same. Extended support contracts are available to answer more specific questions and provide more guaranteed response times. Further, Logictran will provide contract services to customize translations for specific purposes, or added custom features to the converter. Please contact us for details.

  19. What are ‘translation’ (.trn) files?

    Translation files drive the conversion process. They have a .trn extension. For example, HTML output is controlled by the files base.trn and html.trn, with Docbook XML controlled by base.trn and docbook.trn. Customization to these translation files is usually done in trnflag.trn. Translation files are simple text files which may be edited to customize the translation. For details of where they reside and their contents, please see Guide.html and CustomRef.html.

  20. What is trnflag.trn?

    Trnflag.trn is the main file used to customize a conversion. Strings, Functions, etc. defined in trnflag.trn override of extend strings, functions, etc. defined in the underlying translation files (eg html.trn). trnflag.trn may be placed next to the input documents being converted, or in the Logictran install folder (ie next to base.trn and html.trn) to affect all translations. Only one trnflag.trn is opened. For details of what can go into trnflag.trn, please see Guide.html and CustomRef.html.

  21. What is cmd.trn?

    Cmd.trn is a translation file that is created by the Windows GUI, r2net. It may be hand edited to include the same contents as trnflag.trn, but is typically left under the control of the GUI to read/write. For hand-made translation file changes, it is best to modify trnflag.trn.

  22. How do I create XML output?

    On Windows, start the GUI (r2net.exe), select “Set translation options” toolbar icon, select “General” options, select XML Docbook DTD. Press the “Save” command at the bottom of that dialog. Then load in a sample RTF and use the “Translate RTF” toolbar icon. Two XML files are produced by default, conforming to the Docbook DTD. One is an index file (filebook.xml), the other has the contents of the RTF in xml format.

    To create XML from outside of the GUI, edit or create file cmd.trn to contain

    .Strings
    trnfile,’docbook.trn.

    Note that this has to go into cmd.trn and not in trnfile.trn due to the processing order of translation files. Alternatively, the same can be achieved from the command line, eg:

    r2netcmd –D’trnfile=docbook.trn’ file.rtf


  23. Is XSL supported?

    No. CSS formatting is supported for HTML output.

    XSL files to map the Docbook XML to HTML are available via www.nwalsh.com .

  24. Can I convert RTF’s as strings, eg coming from, or going to a database?
    Yes, through the programmatic interfaces to the converter: DLL, ActiveX, ASP or library interface on Unix. Each interface is described in a document (eg docs\DLLReadMe.html), including how to convert RTF strings to HTML (or XML) strings.

  25. When will the Mac version get a new GUI?

    There are no immediate plans to update the Mac GUI. However, we are always interested in feedback concerning new features, so please send requests for Mac updates (or any product enhancements) to our support form.

  26. What if I find a bug?

    Please contact us with details, including a small test case (as appropriate), information about the platform being used, and the version of the converter.


B. Customizing output for HTML


How do I...

  1. Customize the translation

    Translations may be customized by editing, or adding translation files. See What if the output isn’t quite as I want it?

  2. Improve font size accuracy, indenting, etc.?
    CSS (Cascading Style Sheet) formatting allows for a much closer representation of the RTF in HTML. Notably for font sizes and indenting. Not all browsers support CSS at this time, although support is being added quickly. To enable CSS output, create or extend trnflag.trn with

    .Strings
    css,’1’
    oldtags,’0’

    The oldtags line instructs the converter to not create non-CSS based formatting. In theory, non-CSS enabled browsers will ignore the CSS and use the old style attributes for font size, etc. However, some CSS enabled browsers have been seen to get confused when both old style formatting and CSS based formatting is used together.

    See Guide.html for related options to affect whether CSS is in lined, included at the top of each file, written to a separate css file, etc. Strings to look for include: InlineCSS, GenCSSFile and StyleSheet.

  3. Enable CSS based formatting?
    See Answer above.

  4. Create Table of Contents?
    Table of contents may be created at the top of each file, end of each file, or in a separate file. To create a TOC at the top and/or bottom of each output file, create trnflag.trn containing:

    .Strings
    SkipTrailingToc,’0’
    SkipLeadingToc,’0’


    To create a TOC in a separate file:

    .Strings
    GenContents,’1’

    GenFigureList and GenTableList are used to create figure and table contents listings.


  5. Create Framed output?

    Create or modify trnflag.trn to contain

    .Strings
    GenFrames,’1’


  6. Create JPG images rather than PNG?
    Create or extend your trnflag.trn with

    .Strings
    ImageExt,’JPG’
    SkipPng,’1’

    Without the SkipPng entry, any PNG format files found in the input document will be left as PNG.

  7. Split the output files into smaller chunks?
    Create or extend your trnflag.trn with

    .Strings
    SplitDepth,’1’

    This will split the output files along ‘Heading 1’ boundaries. That is, every Heading 1 will start a new output file. Setting splitdepth to 2 will split at every heading 2 boundary, etc.

  8. Add navigational panels?
    Create or extend your trnflag.trn with

    .Strings
    SkipNavPanel,’0’

    See the section on navigational panels in guide.html for further details.

  9. Change the generated filenames and output directories (including images)?
    To change the (main) output filename, create or edit trnflag.trn to contain:

    .Strings
    OutFilename,’$dirname(inputfile)\\whatever.html’

    See the file naming section in guide.html for details of changing the contents filename, index filename, etc.

    To change the names of ‘split files’ (that is when SplitIndex > 1 such that each heading starts a new output file) or image filenames, add the following functions to trnflag.trn:

    .Functions
    Function GenFilename
    set ‘$dirname(filename)\\output\\$basename(filename).$HtmlExt;’

    Function GenImageFilename
    set ‘$dirname(filename)\\images\\$basename(filename)$ext(filename)’

    These examples will write all output files to the folder ‘output’ and all images to the folder ‘images’. Both folders must exist already.

    In order for the generated <img> tags to point at these images, the following strings (defined in html.trn) need to be updated.

    .Strings
    '_inline_image_ref_','$IsBRNeeded()$CenterStart()\
    <img GetImageAlignMent()$ImageSize()\
    src="$ImageRef(_IMAGE_FILENAME_)$PickImgExt(_IMAGE_FILENAME_)" \
    alt="$altImageName()" border="0" $EE;>$CenterEnd()'

    'LinkedInlineIMG','$IsBRNeeded()$CenterStart()\
    <img $GetImageAlignMent()$ImageSize()\
    src="$ImageRef(_LinkFile)$PickImgExt(_LinkFile)" \
    alt="$altImageName()" border="0" $EE;>$CenterEnd()'

    Alter the src=”” attribute to point at the location where the images have been saved.

  10. Preserve spaces and tabs in the output?
    Spaces and tabs may be mapped to non-breaking spaces, or the whole paragraph may be tagged as a <pre> block in which space based formatting is preserved in browsers.

    To tag paragraphs as <pre> blocks, give them a style of ‘pre’ in the RTF editor. Or, if they currently have a style of ‘foo’, add or extend trnflag.trn with the following:

    .Pmatch
    ‘Normal’,0,’Normal’
    ‘foo’,0,’pre’

    To map spaces to non-breaking spaces, end of paragraph processing is required (see guide.html for details). For example:

    .Strings
    EndPar,’$ParEnd()’

    .Functions
    Function ParEnd
    RMatch,' ','','&nbsp;'


  11. Replace text in the RTF with new text in the HTML?

    End of paragraph processing (see guide.html for details) may be used to map text from the input file to different text in the output. For example:

    .Strings
    EndPar,’$ParEnd()’

    .Functions
    Function ParEnd
    RMatch,'foo','','bar'

    Will map any reference to foo, to bar. Use of $MatchName; allows this processing to take place only on selected paragraphs. Again, see guide.html for details.

  12. Customize the table of contents?

    See Tuning the Table of Contents in Customref.html.

  13. Include Headers and Footers?

    .Strings
    IncludeHeaders,’1’
    IncludeFooters,’1’

  14. Not output Unicode for Hebrew, Russian, etc. character sets?
    By default, the converter will map characters to Unicode format allowing display in a wide variety of browsers and locales. If a local mapping is required, ie assuming that a specific character set is available when the web page is displayed, then the translation can be set up to output the required characters. For a general description of this process, please see “Character Sets and Translations” in Customref.html. Two examples are provided with the download in folders 1251 (Cyrillic) and 1255 (Hebrew). Copy the files in the respective folders next to the input file to be translated and translation will map characters to their local values rather than Unicode equivalents. The Hebrew translation provided with thanks to Hanan Cohen at http://www.info.org.il .

C. Customizing output for XML


How do I...

  1. Switch on XML output?
  2. Create XML for a specific DTD?

    To create a specific XML DTD output format, changes are required to the translation files. See guide.html and CustomRef.html for details on changing translation files.

    Depending on the nature of the XML DTD and how closely it matches an existing, supported format, it may be faster to start from an existing translation file than start from scratch. For example, if similar to the Docbook DTD, starting with docbook.trn and modifying that (or applying changes to trnflag.trn to override docbook.trn).

  3. Create tag <abc>...</abc> for RTF style ‘xyz’?

    Create or extend trnflag.trn with:

    .Pmatch
    ‘xyz’,0,’abc’

    .Ptag
    ‘abc’,'<abc>','</abc>\n','\t','\t','','',1,0,0,1,0,1

    See CustomRef.html for details of the .Pmatch and .Ptag tables.
Last Updated 02/21/2002 12:00:37

© Copyright 2003 Logictran, Inc. All rights reserved. - Privacy Statement