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.

Common Elements Across Multiple Document Projects

Often, when creating and managing multiple document projects, some elements may be common to many or all of the projects. These elements might include boilerplate text, icons, javascript and other items. DynaDoc users can leverage the use of a common folder for these items. VideoRay uses a folder named required to store these items. The common folder will typically be published along with the project's output folder set if files in this folder are required for viewing the documents.

Print Version Page Breaks

By default, page breaks are added to each top level page (based on menu hierarchy). You can change the level at which page breaks are applied by using the PAGE_BREAK_LEVEL command. You can also force a page break for any page. You can also prevent pagrbreaks by using: <div style="page-break-inside: avoid"> ...content... <div>. To force a page break for a page, you can add "%" to the page definition.

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. Includes can be used in the script and within content pages. Includes can be defined as static text or file names, or variables that are replaced with a value, or for instances where a file name is required, the variable can be used to define the file name. Using variables allow you to create a script that can be used to generate many document variations.

Text Substitutions

Placeholders can be inserted in the content for replacement with formatted text at the time the document is generated. Substitution is based on using includes. Rather than specify a file or variable name to include, a user defined placeholder is included. The placeholder and the value to substitute for this placeholder is specified in the script using the SUB command, or if more than one substitution is desired, a separate file of placeholders and substitute text strings can be created. An example might be to customize multiple instances of a document with users' names.

This approach creates DynaDoc PHP variables at execution time, so it is important that the user defined placeholders do not conflict with existing variables. Therefore, tsub has been reserved as a prefix for user defined text substitution strings. Text substitution placeholders should always start with tsub.

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 file name 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 $required to define this location.

Dynamic Content During Document Generation

Boilerplate or other content can take advantage of dynamic content based on the values of DynaDoc variables at content generation time. For example, boilerplate content can include the name of the product so that without having to edit the boilerplate, each project will contain its own name. See Content Block Tags in the Content Blocks section for more information about including DynaDoc variables as content.

Boilerplate or other content can take advantage of dynamic content based on the values of DynaDoc variables at content generation time.

Using "NUL"

Using "NUL" for the input file will create an entry in the menu and table of contents, but a page will not be generated and this menu entry will not be linked to any destination URL. This is useful for creating headings in the menu or table of contents without having to include content for that heading.

Using "NUL" for the output file in the script will prevent DynaDoc from generating output. This is useful for including files in the menu and table of contents that already exist. The name of the existing file should be entered as the input file.

Using "^"

Using "^" in a page definition in the script will prevent DynaDoc from generating a menu entry for the item. The page will be generated as normal. This may be valuable for creating pages (using the template) for links in a page footer when you don't want these pages in the menu.

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. Any name can be provided as the output file.

Case 1: If you want to reuse a page more than one time in a document, use an output name and add a suffix, such as 1, 2, etc. This will ensure that the previous and next links preserve their context when viewing the pages. Otherwise the next link on the first occurrence of the page would jump to the page after the last occurrence of the page.

Case 2: If you want to use a page from another project in your current document, specify the location of the input page relative to the location of the dynadoc.php program, and specify the output page with the desired name (no path) using ".html."

Referencing Pages

If you want to include a link to a page in another document, specify the location of the input page relative to the location of where the current document will published (typically ../../otherDoc/), and make sure to set the output page to NUL (otherwise DynaDoc will overwrite that page in the other document). If the external page destination is ".html," but the input page is ".htm," do not include the "l," and just use ".htm" - DynaDoc will add the "l."

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 Concurrent Versions of a Document

Multiple versions of a document can be created using conditional pages and text. To make managing the project's files easier, you can create the output for the different versions in separate html output folders rather than separate project folder. The value of HTML_VERSION is appended to the html output name. JavaScript file choose.js allows you to present a choice to the user in projectName/index.html. The user's selection will then present projectName/html_htmlVersion/index.html. See Multiple Versions Example for more information.

Working with Multiple Documentation Projects

Document lists can be categorized allowing projects to be grouped. dyandoc_manage.php is designed to help manage projects categorized in lists. It displays a page with all of the projects in a particular category. Link on that page can launch DynaDoc, help stage files for publication, or view documents

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.

Dynamic Content Post Generation

There are several ways to include dynamic content after a document has been generated, for example, at the user level or by a user.

The easiest method is to include an iframe in a content block that references the dynamic content.

Where dynamic_content.html is a local file that will be included at display time, and error_message will be displayed if there is an error while trying to display dynamic_content.html. The user can create or edit dynamic_content.html to include their desired content. As an example, training materials can be created with a welcome slide that can be updated with the customer and instructor names for each class.

My_Notes

The second method is to use the My_Notes feature.

My_Notes is a JavaScript tool that allows users to add their own margin notes on a page-by-page basis. The capabilities and use of My_Notes are described in the Customize this Document section.

Automatic Content Generation

DynaDoc can be coupled with systems that generate automatic documentation. Examples include:

A Parts Navigator that creates linked pages of parts BOMs using an export of parts data from an ERP system.
A set of sequential removal and replacement instructions for repair purposes. The unique feature of this system is that the instructions for each part are written only once, even though the file may be used in multiple places because the part must be removed to get to many other parts in the assembly.
A troubleshooting decision tree exported from a spreadsheet.

[ Help us improve this document ]