Generating and Customizing Mapping Documentation

www.altova.com Print this Topic Previous Page Up One Level Next page

Home >  Customizing MapForce >

Generating and Customizing Mapping Documentation

The Generate Documentation command generates detailed documentation about your mapping in HTML, MS Word, RTF or PDF. The documentation generated by this command can be freely altered and used; permission from Altova to do so is not required.

 

Documentation is generated for components you select in the Generate Documentation dialog box. You can either use the fixed design, or use a StyleVision Power Stylesheet (SPS) for the design. Using a StyleVision SPS enables you to customize the design of the generated documentation (see User-Defined Design).

 

Notes

To use an SPS to generate mapping documentation, you must have StyleVision installed on your machine. Related elements are typically hyperlinked in the onscreen output, enabling you to navigate from component to component.
To generate documentation in MS Word format, you must have MS Word (version 2000 or later) installed.

 

The screenshot below shows a portion of the Lookup-standard.mfd file available in the ...\MapForceExamples folder.

document-mapping03

Having opened a mapping file e.g. Lookup-standard.mfd:

 

Select the menu option File | Generate Documentation. This opens the "Generate documentation" dialog box. The screenshot below shows the default dialog box settings.

document-mapping02

 

Documentation Design

Select "Use fixed design..." to use the built-in documentation template.
Select "Use user-defined..." to use a predefined StyleVision Power Stylesheet created in StyleVision. The SPS files are available in the ...\Documents\Altova\MapForce2019\Documentation\MapForce\ folder.
Click Browse to browse for a predefined SPS file.
Click Edit to launch StyleVision and open the selected SPS in a StyleVision window.

 

The following predefined SPS stylesheets are available in the ...MapForce2019\Documentation\MapForce folder:

 

FunctionCallGraph.sps - shows the call graph of the main mapping and any user-defined functions.
FunctionsUsedBy.sps - shows which functions are used directly, or indirectly, in the mapping.
ImpactAnalysis.sps - lists every source and target node, and the route taken via various functions, to the target node.
OverallDocumentation.sps - shows all nodes, connections, functions, and target nodes. The output using this option outputs the maximum detail and is identical to the built-in "fixed design..." output.

 

Output Format

The output format is specified here: either HTML, Microsoft Word, RTF, or PDF. Microsoft Word documents are created with the .doc file extension when generated using a fixed design, and with a .docx file extension when generated using a StyleVision SPS. The PDF output format is only available if you use a StyleVision SPS to generate the documentation.
Select "Split output to multiple files" if you would like separate input, output, constant components, user-defined functions from the Library component documentation. In fixed designs, links between multiple documents are created automatically.
The "Show Result File..." option is enabled for all output options. When checked, the result files are displayed in default browser (HTML output), MS Word (MS Word output), and the default application for .rtf files (RTF output).

 

Path length limit

Allows you to define the maximum "path" length to be shown for items.

E.g. .../ShortPO/LineItems/LineItem, which would be the maximum length for the default setting 3.

 

Include

Allows you to define the specific components to appear in the documentation.

 

Details

Allows you to set the specific details to appear in the documentation.

selecting "Library Names" would insert the "core" prefix for functions.
You can document both connected, as well as unconnected nodes.

 

Note:
The Check/Uncheck All buttons allow you to check/uncheck all check boxes of that group.

 

Having used the default settings shown above, clicking OK, prompts you for the name of the output file and the location to which it should be saved. A portion of the fixed design generated documentation is shown below. Note that this shows a single output file.

 

This table shows the connections from the source component to the target component(s).

document-mapping01

The sequence in which the components are documented is: Input, Output, Constant, User-defined functions, then Library functions.

 

E.g. Input component ShortPO:

 

The first two items ShortPO and ShortPO/CustomerNr are not connected to any item in the target, thus the Connections column is empty.
ShortPO/LineItems is directly connected to CompletePO/LineItems in the target.
/LineItems/LineItem/ArticleNr has two connections:

 

directly to LineItem/Article/Number in the target
to the User-defined function LookupArticle, with ArticleNr as the input parameter, and Name as the output parameter of the user-defined function.

 

The contents of the user-defined function are shown below.

document-userdef

Output component CompletePO: This table shows the connections to the target component from the source component(s).

document-outpcmp

The first two items CompletePO and CompletePO/Customer are not connected to any item in the source component, thus the Connections column is empty.
CompletePO/LineItems is directly connected to ShortPO/LineItems in the source component.
LineItem/Article/Name is connected to the User-defined function LookupArticle, with LineItems/LineItem/ArticleNr as the source item.

 

document-userfunc


© 2019 Altova GmbH