DynaDoc Script

The DynaDoc script is a text file that you create in the root folder of your project. It defines some document parameters and the sequence of pages of the document. The DynaDoc script is described in more detail in the DynaDoc Operator's Manual.

The DynaDoc script for this document is shown below.

The display below is dynamically included as part of the document generation process using the <--i--> and <--i--> tags and will reflect the state of the script file when this document was generated.

#Document Commands
!PRODUCT,Document Creation
!VERSION, 1.00.00
!DOC_TYPE,Manual
!OUT_DIR,document_creation/
!INCLUDED_PAGES,
!VALID_TEXT,
!TEMPLATE_COVER,required/htm/template_index_print.htm,index_print.htm

#Documentation Generation
!INCLUDE,required/intro_.txt,1

*,Process Overview,,overview_.htm,,,

*,Computer Environment,,environment_.htm,,,
**,Text Editor,,environment_text_editor.htm,,,
**,Git,,environment_git.htm,,,
**,XAMPP,,environment_xampp.htm,,,
**,Additional Utilities,,environment_additional.htm,,,

*,Project Setup,,project_setup.htm,,,
**,Configuring DynaDoc,,configuring_dynadoc.htm,,,
**,Git Repository,,project_setup_git.htm,,,
**,Dynadoc Preparation,,project_setup_dynadoc.htm,,,

*,Content Creation,,content.htm,,,
**,DynaDoc Script,,content_dynadoc.htm,,,
**,HTM,,content_htm.htm,,,
**,Images,,content_images.htm,,,
**,JavaScript,,content_javascript.htm,,,
**,CSS,,content_css.htm,,,
**,Advanced Features,,advanced_features.htm,,,
***,View and Print,,view_print.htm,,,
***,Document Structure,,document_structure.htm,,,
***,Glossary,,content_glossary.htm,,,

*,Publishing,,publishing.htm,../../required/javascript/get_get.js,,
**,PDF,,publishing_pdf.htm,,,
**,Self Extracting Zip,,publishing_zip.htm,,,
**,Posting via FTP,,publishing_posting.htm,,,

*,Archiving,,archiving.htm,,,
**,Commit and Push to GitHub,,archiving_git.htm,,,

*,Using DynaDoc Online,,dynadoc_online.htm,,,

This may look a bit complex, but there's really not much we need to worry about. Let's start with the first section, under #Document Commands. Most of these were already set when we ran the script to create the configure DynaDoc for the project. The only options we need to worry about for a basic document are the PRODUCT, VERSION and DOC_TYPE.

• PRODUCT: This value plus DOC_TYPE control the title of the document, and will be separated with a space. It will be set when you create the project, but can be edited here.
• VERSION: The number at the bottom of every page indicates the version number of the document. You should update this as you make changes, with development versions being decimals such as 0.7.00, initial public releases usually numbered as 1.00.00, and versions that have been updated after initial release having greater values, such as 1.01.00
• DOC_TYPE: This is the type of document,such as "Operator's Manual." It is used in the title.

Under #Documentation Generation, the script starts with two !INCLUDEs. These are used to include boilerplate text to the start of each document. The second !INCLUDE will typically be !INCLUDE,required/overview_.txt,1 if the document does not have a Quick Start section, and !INCLUDE,required/overview_qs_.txt,1 if it does.

Now that the basic settings are out of the way, the next section determines the content of the document. Each page of the document requires a separate line with the following fields.

  *,title,outName,htmName,jsName,sbName,imgName

Each field page is separated by a comma, and for most pages only three fields are required (these are shown in bold underline above). These three fields are described below.

• *: The number of asterisks at the beginning of a page declaration determine it's level in the document hierarchy. A single asterisk is a primary topic, with a two asterisk page being a sub topic under it, and a three asterisk page under that, and so on. DynaDoc currently supports seven topic levels, but the code could be modified to support more if necessary. The hierarchy of this document is fairly flat and only has primary topics and two levels of subtopics, so let's take a look at a sample with a little bit more depth. The example below has one primary topic, under which are two sub-topics. The first sub-topic also has three sub-topics of it's own, of which one of those has another sub-topic and is four levels deep. The second-sub topic has no sub-topics. In general, if your pages start becoming very long, you should consider splitting them into multiple pages using sub-topics.

    *,Equipment Guide,,equip_.htm,,,
    **,ROV,,equip_rov.htm,,,
    ***,ROV Connections,,rov_connections.htm,,,
    ****,ROV Pin Out,,rov_pin_out.htm,,,
    ***,Buoyancy,,rov_buoyancy.htm,,,
    ***,Propulsion,,rov_thrusters.htm,,,
    **,Optional Utilities,,environment_optional.htm,,,
    

• title: The title is used in the table of contents, which is automatically generated, and for the heading on the page.
• htmName: This points DynaDoc to the content file source in your htm folder to build the document.

The additional fields are optional. Make sure that your page definition is formatted with the commas as shown, or DynaDoc will not be able to read your script file correctly.