ModuleHtmlPostprocessor

MacroModule

author	Wolf Spindler
package	FMEstable/ReleaseMeVis
definition	ModuleHtmlPostprocessor.def
keywords	documentation, comment, guide, handbook, help, html, mhelp

Purpose

The ModuleHtmlPostprocessor is dedicated to perform user-defined postprocessing on HTML files generated by the MeVisLab help file generation in order to transform the HTML file to a handbook-like appearance.

Writing documentation for applications built on top of MeVisLab is often done with external tools. Whenever an update or a new delivery is created, the external documentation also has to be revised and updated, which, however, is an error-prone, time consuming and tedious task. On the other hand-side, MeVisLab with MATE and its way to document modules with .mhelp files, is already a powerful way to write documents. Applications are already built as macro modules, whose parameters and sections can easily and fully be described and documented in this way.

ModuleHtmlPostprocessor provides an approach to transform generated HTML content of modules to a more convenient and handbook-like format. Although this has no layout of a professional quality, it can reach a respectable appearance usable for many deliveries. See How to Use, Advantages, and Disadvantages as well as the example network to get an impression about what is possible.

How to Use

Some hints how this module can be used:

• Getting started:
  • Open the example network.
  • Press Show Help to see the original version of the help file.
  • Press Apply and Show Help to see the postprocessed version of the help file.
  • Press Restore Original Html to reset the original HTML file.
• Disable or change some settings:
  • Check tabs 01 to 39, read Info to understand their meaning, and use Off in some Mode selectors to disable some modifications.
  • Disable section 30 and 31 if you want to maintain the parameter section in document and index. Then section 32 and 33 rename the section.
  • You may also want to change some Info contents to modify the results.
  • Press Restore Original Html, Apply, and Show Help to see which changes are disabled.
• Adapt setting for your own module:
  • Update Module Package Name Env Var and Module Name.
  • Replay the processes above with Restore Original Html, Apply, and Show Help.
  • Add your own replacements in tabs which Mode is still Off.
• Also changing the css style is possible, see Changing the css-Style for details.

Advantages and Disadvantages

Advantages

• Documentation of application macro and the final application is done synchronously and only in one document.

• Module can be integrated in application network and HTML can be postprocessed automatically during first application launch.

• Parameters documentation can automatically be used as tooltips in the released application.

• Many correctness-, completeness and cross-reference checks of parameters in the documentation is already integrated.

• No external tool (license) needed.

• Easy to integrate in/with normal application installer.

• Easy to launch from application code with ctx.showHtmlHelp().

• Fast.

• Document can easily be printed using any browser without any special tool.

• PDF-files can easily be created using many web-browsers with the print to pdf option (usually without cross-references).

• Supports all stuff supported in MeVisLab:

  • Sections, tables, and formatting as it is available with Sphinx which is used internally to generate HTML files.

  • Cross references such as Advantages and Disadvantages.

  • Index

  • MeVisLab-specific roles such as : field :`fieldReference` and : module :`moduleReference`

  • Spell checking.

  • Images such as

    

Disadvantages

• May need adaptions when HMTL output in MeVisLab is updated.
• Professional document quality may be difficult to reach.
• No language-specific spell or grammar checkers.
• Generating PDF files with correct in-document cross-references and correct image scaling may be a bit tricky.
• A bit like a hack.

Changing the css-style

The example network provides a deactivated replacement of the _static/mevislab.css statement with _static/$$(MODULE_NAME).css in tab 11. Enabling it, and providing a module-specific _static/$$(MODULE_NAME).css, allows redefining the style of the document.

Try, for example, copy and rename _static/mevislab.css and append the following block to change the width of the document index and some distances in item lists:

div.sphinxsidebar {
  width: 200px;
}

div.bodywrapper {
  margin: 0 0 0 200px;
}

ul {
  margin-bottom: 10px;
}

li {
  margin-bottom: 0px;
}

li:first-child {
  margin-top: 4px;
}

Note: at the time of writing this help, _static/mevislab.css includes _static/classic.css and indirectly _static/basic.css files which may be integrated in the new one or also be replaced. For example, the width of the document index (sphinxsidebar in the css-style), is defined in _static/basic.css and the width-space reserved for it (bodywrapper in css-style) in _static/classic.css. The upper code overwrites some of their properties.

Windows

Default Panel

Parameter Fields

Field Index

Apply: Trigger	Original String: String
Begin: String	Replace With: String
End: String	Restore Original Html: Trigger
Info: String	Show Help: Trigger
Mode: Enum
Module Name: String
Module Package Name Env Var: String
New Module Name: String

Visible Fields

Show Help

name: showHelp, type: Trigger

Shows the help file of Module Name in the web browser defined in the MeVisLab preferences.

Apply

name: applyPostprocessing, type: Trigger

Applies all replacements to the HTML document. This will only be performed if Original String is found in the document (or is empty), otherwise the document will be considered as already processed.

Restore Original Html

name: restoreOriginalHtml, type: Trigger, deprecated name: restoreAndOpenOriginalHtml

While finding and trying replacements the results usually are not perfect and one wants to restore the original HTML document suach as it was before it had been revised with the module. Restore Original Html runs the original HTML creation from the .mhelp file. Do not forget to reload the HTML file in the browser to see the update or to use Show Help.

Module Package Name Env Var

name: modulePackageNameEnvVar, type: String, default: MLAB_FMEProjects_MCubed

Requires the specification of the package the module is located in, prefixed with MLAB_, such as MLAB_FMEwork_ReleaseMeVis or MLAB_MeVis_Foundation.

Module Name

name: moduleName, type: String, default: ModuleHtmlPostprocessor

The name of the module whose HTML file is to be revised with ModuleHtmlPostprocessor. The placeholder $$(MODULE_NAME) can be used in the text fields of ModuleHtmlPostprocessor.

New Module Name

name: newModuleName, type: String

The new name of the module used in the revision. The placeholder $$(NEW_MODULE_NAME) can be used in the text fields of ModuleHtmlPostprocessor.

Original String

name: originalString, type: String, default: — MeVisLab  documentation

If Original String is empty then Apply will post process the HTML document always when it is triggered. Otherwise Original String is searched in the document and only if it found the post-processing takes place. This is especially useful to prevent replacements of already replaced stuff. A typical content of Original String could be — MeVisLab documentation, which is usually part of the title and can easily be removed while replacing the document title.

Info

name: stringToReplaceInfo01, type: String

A text field describing the meaning of the replacement strings in the corresponding Begin, End, Replace With, and Mode. It has no functional use in the module.

Begin

name: stringToReplaceBegin01, type: String

The begin of the string to be searched in the document and which must be located before the location End.

End

name: stringToReplaceEnd01, type: String

The end of the string to be searched in the document and which must be located after the location End. There may be any text between Begin and End.

Replace With

name: stringToReplaceInsert01, type: String

If a section is found with Begin and End, then the section is replaced with Replace With.

Mode

name: stringToReplaceMode01, type: Enum, default: Off

Describes how many times the contents of Begin, End, and Replace With shall be used to replace string sections in the HTML document.

Values:

Title	Name	Description
Off	Off	No replacement takes place.
First	First	Only the first occurrence of the string is replaced.
All	All	All occurrences of the string are replaced.