Resources - Using Modules

Divide and Conquer

Most - if not all - software is developed in a modularized way. Modules are packages that help maintaining the source code and make teamwork a lot easier. So it's only logical for a documentation tool to allow for that modularization to be reflected in the software documentation.

Doc-O-Matic supports defining modules in a documentation project to reflect the modules in your software. To add a module to your Doc-O-Matic project follow these steps:

1. Create a Topic for each module in the Content Manager.
2. Create a Module in the Project Manager.
3. Assign files and folders that belong to the Module.

Step 1: Create a Topic for the new Module

Each module in the documentation is represented by a topic. This topic acts as a container that will be filled with symbol reference folders automatically when Doc-O-Matic analyzes your project. Although there is no technical limitation that would enforce it, topics for modules should be generic topics.

To create a topic for the new Module follow these steps:

1. Switch to the Content Manager.
2. Click the New Topic toolbar button.
3. Enter a topic ID for the module topic. As all topic IDs in the project it has to be unique. It is advisable to choose some sort of identification to make remembering the topic ID easier in case you want to create links to the topic later, like for example prefixing the name by "mod_".
4. Click OK.
5. The Editor opens the new topic, save it and select an external DTX file as storage location.

Step 2: Create the Module in the Project Manager

The actual module definition happens in the Project Manager. To create a new module follow these steps:

1. Switch to the Project Manager.
2. Click the New Module toolbar button.
3. Name the new module. It should be the same name that you use in your software project to make it easier to identify later.
4. Select the topic you have just created as container.
5. Click OK.

Step 3: Assign Files to the Module

Doc-O-Matic determines which symbol belongs to which module by looking at the file the symbol is defined in. In this last step we assign the files to the new module which enables Doc-O-Matic to separate the project.

To assign individual files to a module follow these steps:

1. Select a file in the Project Files and Folders->Parsed Source Files branch.
2. Right click the selected file and choose Assign to Module->[Module] .

In bigger projects assigning files to modules on a file-by-file basis can be a time consuming tasks. Also, most projects' source files are distributed over a folder hierarchy that reflects the module structure in some way. This is why Doc-O-Matic allows you to add a complete folder to a module, so you don't have to do it file by file.

To assign a folder to a module follow these steps:

1. Select the Module you would like to assign a folder to.
2. Right-click the selected Module and choose Add Folder to Module... .
3. In the folder selection dialog you can select both the desired folder and a file mask. Only those source files matching the file mask will belong to the Module.

As your project grows, you may need to change module file assignments. The Project Manager's file tree can be sorted by module and you can make assignment changes on multiple files at once.