This section covers some of the more pragmatic concerns when dealing with Dynamic Converter. The following topics are explained:
For Classic HTML Conversion templates, it is recommended that you do not use multi-byte characters in your content IDs, security groups, content types, and account names, even if Dynamic Converter is used in a multi-byte environment (Japanese, Korean, or other non-Roman alphabets). This content metadata information is included in the URL of a content item, and limitations in current web technology may prevent web servers and web browsers from handling multi-byte character URLs correctly. (Dynamic Converter, for example, will fail to locate content items if the links are broken.)
If you want to use multi-byte characters in content IDs, security groups, content types, or accounts, you need to make sure that the entire Content Server environment (servers and clients) runs on operating systems that support multi-byte languages (for example, Japanese or Korean versions of Microsoft Windows).
Note:
The new Dynamic Converter HTML Template Editor will not support working with multi-byte content IDs for the templates or the content items being converted.Conversion of PDF files under UNIX may be slow and may time out after three minutes (the default timeout value for the conversion process).
To increase the conversion timeout, complete the following tasks:
Open the Dynamic Converter Admin page (see "Dynamic Converter Admin Page").
Click Configuration Settings.
The Dynamic Converter Configuration page is displayed (see "Dynamic Converter Configuration Page").
Enter a new value in the Time Out field (increasing it from 3 minutes, which is the default).
Click Update to enable your changes.
The changed setting takes effect immediately, so you do not need to restart the Content Server.
Some source documents contain embedded OLE objects. Embedded OLE objects are usually accompanied by a graphic "snapshot" in the form of a Windows metafile. On both Windows and UNIX, Dynamic Converter can use the metafile snapshot to convert the OLE object. When the metafile is not available, Dynamic Converter reverts to OLE technologies for the conversion. In that event, the conversion will still succeed on Windows, but it will fail on UNIX.
If you are converting vector graphics, Dynamic Converter requires access to a running X-Server. This is because Dynamic Converter depends on the X-Server system to draw the pixels.
Vector graphics formats describe lines and fills. Common formats are WMF, EMF, CorelDRAW, Adobe Illustrator, Excel charts, Word autoshapes, and PowerPoint presentations. Raster graphics, on the other hand, contain pixel information of an image. Common file formats are BMP, JPEG, and GIF.
One way to tell the difference between a vector and a raster graphic is to try to stretch the image. Since vector graphics describe lines, they will re-compute the placement of the lines and the image should still look nice. Raster graphics, however, will become pixelated when you resize.
See the Dynamic Converter Installation Guide for instructions on how to set up rendering of graphics and fonts in UNIX.
Dynamic Converter requires access to a running X-Server in UNIX in order to convert vector graphics and to properly measure text that spans multiple columns in spreadsheets.
See the Dynamic Converter Installation Guide for instructions on how to set up rendering of graphics and fonts in UNIX.
Dynamic Converter wraps the dcUrl('url', reserved_type) Idoc Script extension function around all hyperlinks and image source links (src). The default implementation of this script function is to do a simply pass-through, but external integration technologies (such as CIS) can modify this behavior by defining a filter plug-in for "dcUrlFilter."
Dynamic Converter evaluates the link URL, applies the "dcUrlFilter" filter if it exists, and then return the URL value. If the dcUrlFilter filter is not defined, then the original URL is unchanged. Links to internal bookmarks always remain unchanged.
The reserved_type function argument is a number 1001, 1002, etc., which indicates where in the Dynamic Converter core engine the URL is being written. This value can be used to distinguish the type of URL. For example, gallery graphic, inter-document link, etc. The reserved type values and their meanings are as follows:
| Value | Description |
|---|---|
| 1001 | Link (different split) |
| 1002 | Previous element (different split) |
| 1003 | Previous page (TOC frame) |
| 1004 | Previous page |
| 1005 | Next page (TOC frame) |
| 1006 | Next page |
| 1007 | Next element (different split) |
| 1008 | Previous page (TOC frame) |
| 1009 | Previous page |
| 1010 | Next page (TOC frame) |
| 1011 | Next page |
| 1018 | Image link |
| 1019 | Image link |
| 1020 | Image link |
| 1021 | Image link |
| 1022 | Background graphic (not from source) |
| 1023 | Background graphic (from source) |
Consider the following image tag: <IMG SRC="image.gif">. In most implementations of Dynamic Converter, it is likely that the output files will end up in a different location than the template files. If the developer uses the template above in this scenario, the output files produced will have a reference to image.gif, which the browser will assume has the same path as the output files. The problem is that image.gif is likely to be back in the directory where the template file is located. This is a problem for anything referenced in the template using a relative URL. There are several possible solutions to this problem.
Solution 1: Ensure That the References Are Good
If the developer knows exactly which files all of the templates reference, the correct files (such as image.gif) can be moved to or located in the output directory or directories. This solution requires the developer to have exact knowledge of the contents of the templates, and may propagate the same set of files into many output locations.
The developer can design templates to contain absolute URLs to any referenced files. The template in the example would then look something like this.
<HTML>
<BODY>
<P><IMG SRC="http://www.company.com/templates/image.gif"></P>
{## INSERT ELEMENT=Sections.1.Body}
</BODY>
</HTML>
If <$HTTPWEBROOT$> is used instead, you eliminate the problem of output files tied to a specific domain.
Solution 3: Make Path Statements in a Separate File
The developer can create a separate Idoc Script file that states the path, for example:
<@dynamichtml Image_Dir@><$HttpWebRoot$>groups/public/documents/graphic/<@end@>
The developer can then load the Idoc resource and reference the path statement from the included Idoc Script file as follows:
<img src="<$include Image_Dir$>logo.gif">
All long as the graphics (or related files) are checked in with the security group and document type to match the stated path (in this example, a security group "Public" and a document type "Graphic"), then the paths will resolve, and the page will display properly.
In the process of building and debugging templates, you are likely to run the same source file through Dynamic Converter repeatedly with slightly different templates. Depending on how you are naming the output files, this may have a tendency to produce the same set of file names repeatedly. In this scenario, especially if the output is being read directly from a file system and not through a web server, browsers will have the tendency to show the old cached results and not the new ones.
If it looks like bad output, click Refresh on every frame before deciding that it is a problem with the template or the software.
Tip:
You may find it simpler to empty and turn off caching in your browser while creating and testing your templates.There are a large number of factors that affect the size of the final exported image. The precedence of rules for how those factors work is as follows:
Any images that the template specifies with the {## graphic} macro are subtracted from the space available for graphics on that particular deck. In general, you should be wary of templates that require images on every deck as they will eat into the overall amount of room available for document graphics.
The SCCOPT_EX_GRAPHICBUFFERSIZE option, which is only used to reduce image size if necessary. It preserves the image aspect ratio.
The SCCOPT_GRAPHIC_SIZELIMIT option, which is only used to reduce image size if necessary. It preserves the image aspect ratio.
The SCCOPT_GRAPHIC_WIDTHLIMIT and SCCOPT_GRAPHIC_HEIGHTLIMIT options. These are only used to reduce image size if necessary. They preserve the image aspect ratio, even if both are specified.
'Width=' and 'height=' parameters in the {## INSERT} statement of the template. This reduces or enlarges the image to match the specified dimension(s). The image aspect ratio is changed if both are specified. The aspect ratio does not change if only one or none of these parameters is specified.
Original image dimensions based on the information in the source file and the DPI setting, if applicable.
The styles discussed in this section relate only to script templates (see Chapter 7, "Script Templates"). Styles in Classic HTML Conversion templates (see Chapter 5, "HTML Conversion Templates") are handled differently.
One of the most powerful features of cascading style sheets (CSS) is the ability to override the styles suggested in various ways. Dynamic Converter has designed its CSS support to permit users to override the style sheets that it produces. This, in turn, enables the user to help blend documents from many authors into a collection that has a more unified look. In order to make this override work, one first needs to understand style names.
In addition, it should be remembered that the output from Dynamic Converter might be placed into many HTML files. Special attention must be paid to ensure that <LINK REL=STYLESHEET HREF="{## INSERT ELEMENT=Pragma.cssFile}"> statements are placed in the appropriate locations.
Style names are taken from the original style names in the source document. There is an inherent limitation in the style names the CSS standard permits. The standard only permits the characters a-z, A-Z, 0-9, and dash (-) . Source document style names do not necessarily have this restriction. In fact, they may even contain Unicode characters at times. For this reason, the original style names may need to be modified to conform to this standard. To avoid illegal style names, Dynamic Converter performs the following substitutions on all source style names:
If the character is "-," then it is replaced with "--."
If the character is not one of the remaining characters (a-z, A-Z, or 0-9), then it is replaced by "-xxxx" where "xxxx" is the hexadecimal Unicode value of the character.
If neither of the preceding situations is applicable, the character appears in the style name normally.
An example of one of the most common examples of this substitution is that spaces in style names are replaced with "-0020." For a more complete example of this character substitution in style names, consider the source style name "My Special H1-Style!" (with a space and an exclamation mark in its name). This would be transformed to "My-0020Special-0020H1--Style-0021."
While admittedly this system lacks a certain aesthetic, it avoids the problem of how the document looks when the browser gets duplicate or invalid style names. Developers should also appreciate the simplicity of the code needed to parse or create these style names.
In addition, Dynamic Converter creates special list versions of styles. These have the same name as the style they are based on with "--List" appended to the end. These styles differ from their original counterparts in that they contain no block-level CSS.
Once style names are understood, it is easy to override the CSS file produced by Dynamic Converter. Follow the CSS file link in the template with another link to the CSS override file. For more information on the link to Dynamic Converter's CSS file, see "Pragma.CSSFile and {## LINK}". This override file should then contain styles with the same names as the ones used by Dynamic Converter's CSS file.
Remember that many file formats allow styles to be based on other previously defined styles. Dynamic Converter supports this by nesting styles. In this way each nested style inherits and may override items defined in the styles that surround it.
One {## INSERT Element=Pragma.CSSFile} statement should appear at the top of each HTML file produced when a CSS flavor of HTML is used. It should therefore be remembered that the ## LINK statement may be used to trigger the creation of additional HTML files. As a result, each ## Linked template will typically contain a <Link> tag to the CSS file generated.
Using a ## LINK statement, it is possible, though, to link to a template that does not have any {##} statements that would need to reference the CSS file. In that case, the <Link> to the CSS file may safely be omitted. Consider, for example, a template that has only two ## statements, both of which are ## links (perhaps to put the results into two separate frames). This template file would not need a <Link> to the CSS file.
Regardless of how many HTML files are produced by Dynamic Converter, only one CSS file is generated. It is also worth repeating here that the <Link> to the CSS file must occur in the <HEAD> section of the document and each resulting HTML file may have only one <HEAD> section.
The output of Dynamic Converter has been tested to ensure that it is well-formed. This is meaningless, however, unless the template used by Dynamic Converter is also well-formed. To assist with creating well-formed templates, here is a list of common problems that may cause documents to not be well formed:
All tags must be properly nested.
All tags that are opened must also be closed. This includes tags that are not normally thought of as needing closing tags, including <META>, <LINK>, <FRAME>, <HR>, and <BR>.
Everything after an is-equal-to sign (=) must be in double quotes. Hence, <FONT COLOR="0000FF"> is OK, but <FONT COLOR=0000FF> is not.
In order for to appear in a document, a <!DOCTYPE> statement must be in the HTML code. Since Dynamic Converter cannot know if the template included the <!DOCTYPE> statement when the SCCHTML_FLAG_STRICT_DTD flag is set,   is always used instead of .
Characters in the range 0x80 - 0xFF are to be written in the form &#xxx;.
The only three characters < 0x20 allowed in any document are: \t, \n, and \r.
All attributes of a tag must be followed by "=value". Thus, the NoWrap in <Table NoWrap> is not well formed. Dynamic Converter uses <Table NoWrap=NoWrap> instead.
Dynamic Converter 7.7 and higher uses DHTML to position objects. However, only two types of object positioning are supported: paragraph anchored objects and page anchored objects. Here are some important notes about this initial support for positional frames:
Dynamic Converter generates paragraph objects separately from page objects even if it appears that they should be placed in the same location.
Transparency is not supported when separate graphics items are placed on top of one another. The SCCOPT_EX_PREVENTGRAPHICOVERLAP option does not apply to these graphics. The graphics will appear relative to where the anchor point is, not relative to the text in the document. Additionally, Dynamic Converter does not support certain graphics effects, such as rotation or stretching.
It is important to note that the SCCOPT_EX_GRAPHICOUTPUTDPI option must be set properly to achieve best results.
In some cases, Dynamic Converter will produce output with inaccurately placed objects when the input document features positional frame objects. However, this end result is no worse than the end result when handling positional frame objects in pre-7.7 versions of Dynamic Converter (i.e., the graphics would be placed in a long column).
This Element only works in the 4.0 flavors of HTML.
Given the limited amount of space in each deck, it is important to maximize the amount of usable data in each deck produced by Dynamic Converter. Some ways to reduce the amount of space wasted in each deck include the following:
Eliminate unnecessary whitespace characters in the template. While the presence of these characters makes reading, editing and maintaining the template easier, they also get written to each output deck "as is." When writing templates for devices with small deck sizes, it may prove worthwhile to remove the extra whitespace characters to increase the amount of usable data in each deck. Please note that the SCCOPT_EX_COLLAPSEWHITEPSACE option does not affect white space coming from the template.
Eliminate any extra links between decks. While good navigation is essential, redundant or unnecessary links eat into the amount of space left in each deck for data. In addition to the markup used for navigation, space is set-aside for the URL of the link, which is determined by the SCCOPT_EX_MAXURLLENGTH option. Currently, space is not reclaimed if URLs are shorter than this length. In addition, if URLs are longer than this length, deck overflow may happen.