Advanced Techniques

DynaDoc has some sophisticated capabilities that can be used to make document creation and managing complex documents easy.

Restructuring Documents

Documents can be easily restructured by changing the sequence of the lines in the script. It is easy to move pages, or split or combine pages, and you don't have to worry about updating the navigation links.

Using Conditional Pages and Text

Conditional pages and text allow one set of source files to generate several to many different outputs. For example, links and JavaScript have no value in a printed document. Conditional text can be used to eliminate this superfluous information from the print file. For product documentation of a "lite" version of a product that has fewer features than the main product, the higher level features can be included only in the main product documentation.

Using Includes

Includes can be a valuable tool for reusing the same content in multiple places. Content included in many projects only needs to be created once and can be updated in one place.

Boilerplate

Many documentation projects have common files. For example, every document will typical include a copyright page and may include a logo image. DynaDoc allows these files to be stored in a common folder. The script for this document (shown in the previous section) includes the following line:

• !INCLUDE,required/intro_.txt,1

Click on the filename above to view the intro_.txt file.

DynaDoc also automatically includes a script preface, which can contain additional global commands and pages. It is called, "script_preface.txt" and can be located in a convenient location. DynaDoc uses the variable $common to define this location.

Using NUL

Using NUL for the output file in the script will prevent DynaDoc from generating output. This is useful for including files that already exist.

Using NUL for the input file in the script will prevent DynaDoc from creating a link in the menu. A static entry is included instead.

Renaming Output Pages

In general, output files are named after the input file, using .html instead of .htm. In some cases, it is preferable to force the output file to use a different name.

Case 1: If you want to use a page from another project, you can rename the output to exclude the path from the input file and the output will be included in the current document's output structure.

Case 2: If you want to reuse a page more than one time in a document, you can rename the output so that the previous and next links will not be broken. Otherwise the next link on the first occurrence of the page would jump to the page after the last occurrence of the page.

Training Documents

DynaDoc uses two special conditional page identifiers, "i" and "s." The "i" can be used to create companion instructor notes pages for each page and the "s" can be used to create student notes pages.

Working with Multiple Documentation Projects

If the project and project directory are not included in the URL, DynaDoc is designed to read a project list. It then displays a page with all of the projects. Document lists can be categorized allowing projects to be grouped.

The project list is a text file with the following structure:

• <projectDescriptiveName>|<projectName>|<projectDir>|<OutputDir>|<docList>|

The project list should be named, "dynadoc_???.lst" where ??? is a three character reference of your choice.

mkdoc.php is a PHP program that can be used to create new projects. It creates the folder structure and adds a line to the project list.