Overview of developing document definitions (Publisher)

This section of the Help is for users that want to create their own Document Definitions that can be used to generate documents and Publisher HTML.

A Document Definition defines which items, diagrams and properties are extracted from the model and how that information is presented in the generated document or Publisher HTML.

If this is the first time you have developed Document Definitions, we recommend that you look at the worked examples that are included in this section of the Help. Refer to see the worked examples that are provided:

• Worked example: extracting items through model item types

• Worked example: extracting items through child roles and child types

• Worked example: extracting items through extended model item types (stereotypes)

• Worked example: extracting diagrams and their items

• Worked example: extracting specific items

When developing Document Definitions, ensure that Publisher is showing all the panes you require, which you can do quickly by clicking the

Full Editor Layout toolbar button.

A Document Definition defines the document structure through document structure items. Document structure items define what information is extracted from a source model, and they also define how that information is presented in the generated output.

The Document Definition also specifies the default output format, which can be a Microsoft Word document, Publisher HTML output, Publisher XML output or a DocBook file.

When you create a new Document Definition, you can create an empty Document Definition or you can create a Document Definition based on a Document Template or another Document Definition:

• Create an empty Document Definition when you want to create a Document Definition or Document Template from nothing.

• Create a Document Definition from a Document Template or another Document Definition when you want to use that Document Template or Document Definition as a starting point for developing a new Document Definition.

To create a Document Definition from a Document Template: In the New Document pane, right-click the Document Template you want to use, and then click Create Document.

To create a Document Definition from another Document Definition: Open the other Document Definition and save it as the new Document Definition you are creating.

Document Definition files have a .ds extension. If you double-click a Document Definition file in Windows Explorer, that Document Definition is opened in Publisher.

You can distribute Document Definitions through Document Definition files or through Document Templates.

For more information about working with Document Definitions, see the following topics:

• Creating a Document Definition

• Making a Document Definition Active (Publisher)

• Opening a Document Definition

• Saving a Document Definition

The document structure defines the structure, content and presentation of information in the generated output.

The document structure is defined in the Document Structure pane, which is always shown in Publisher.

Within the default sections of the document structure (Prefaces, Body and Appendices), you can create sections through document structure items.

For more information about working with document structures, see Overview of Document Structures

An assignable item specifies input data that can be used in the Document Definition.

The buttons in the Document Structure pane allow you to quickly create document structure items that have assigned items: select the parent item in the document structure, and then click the appropriate button.

The following assignable items allow you to include information from a model in the generated output.

• Model Item Type - specifies a type of model item or diagram to include in the generated output. For example, including the Actor model item type in a Document Structure means that all Actors in the source model are included in the generated output.

When you extract items and diagrams through a model item type, you can specify which properties of the extracted items are included. In addition, you can extract items and diagrams that are associated with the extracted items and diagrams through specific roles. For example, if you use the Class model item type to extract Classes, you can use the Attribute role to also extract Class owned Attributes.

• Extended Model Item Type - specifies a Stereotype for defining which items and diagrams in the generated output, that is, items and diagrams that have the Stereotype applied are included the generated output.

When you extract items and diagrams through an extended model item type, you can specify which properties of the extracted items are included, including properties defined through Tag Definitions. In addition, you can extract items and diagrams that are associated with the extracted items and diagrams through specific roles, including roles defined through reference Tag Definitions.

• Model Item - specifies a specific model item or diagram to include in the generated output. For example, including a specific diagram in the Document Structure means that the specified model diagram is included in the generated output, irrespective of what the publication model is for the generation.

When you extract specific items and diagrams through a model item, you can specify which properties of the extracted items and diagrams are included. In addition, you can extract items and diagrams that are associated with the extracted item or diagram through specific roles. For example, if you use a Class item, you can use the Attribute role to also extract that Class' Attributes.

For detailed information about working with model item types and model items, click here Overview of working with model item types and model items (Publisher)

The following assignable items allow you to include information in your generated output that is not extracted from the publication model.

• Custom Revision History - includes a revision history table in the generated output. Through the Properties pane, you can specify the data to include in the revision history table. You can add new columns to the table, and remove default columns you do not require. If you add multiple Custom Revision History assigned items to your document definition, the generated tables will all show the same data.

• Custom Table - includes a custom table in the generated output. Through the Properties pane, you can specify the columns of the table and the data in the table. Each custom table in the document definition can show unique data.

• Distribution List - includes a distribution list in the generated output. Through the Properties pane, you can specify the data to include in the revision distribution list table. You can add new columns to the table, and remove default columns you do not require. If you add multiple Distribution List assigned items to your document definition, the generated tables will all show the same data

• External Image - specifies a BMP, JPG or PNG image to include in the generated output.

• Note - specifies text that can be included in the generated output.

• Revision History - includes a revision history table in the generated output. The revision history table is generated from the data that has been added to the Revision History tab.