Language Support

	Arabic	Table of Contents	Internet connection required, results not guaranteed
	Chinese	Table of Contents	Internet connection required, results not guaranteed
	Deutsch	Table of Contents	Internet-Verbindung erforderlich, ergebnisse nicht garantiert
	English	Table of Contents
	Espanol	Tabla de contenidos	Requiere conexion a Internet, los resultados no garantizados
	Francaise	Table des matieres	Connexion Internet requise, resultats non garantis
	Indonesia	Daftar isi	Koneksi internet diperlukan, hasil tidak dijamin
	Italiano	Indice dei contenuti	Richiesta una connessione Internet, I risultati non garantiti
	Japanese	Table of Contents	Internet connection required, results not guaranteed
	Korean	Table of Contents	Internet connection required, results not guaranteed
	Nederlands	Inhoudsopgave	Internetverbinding nodig, resultaten niet gegarandeerd
	Norske	Innholdsfortegnelse	Internett-tilkobling kreves, resultater Ikke Garantert
	Russian	Table of Contents	Internet connection required, results not guaranteed
	Suomalainen	Sisallysluettelo	Vaatii Internet-yhteyden, tulokset ole taattu
	Svenska	Inneholl	Internetanslutning kravs, resultat garanteras inte

Table of Contents

• Introduction
  • Copyright
  • Language Support
    
  • Table of Contents
  • About this Document
    • Customize this Document
  • How to Get Help
    • Before Contacting Support
• Process Overview
• Computer Environment
  • Text Editor
  • Git
  • XAMPP
  • Additional Utilities
• Project Setup
  • Configuring DynaDoc
  • Git Repository
  • Dynadoc Preparation
• Content Creation
  • DynaDoc Script
  • HTM
  • Images
  • JavaScript
  • CSS
  • Advanced Features
    • View and Print
    • Document Structure
    • Glossary
• Publishing
  • PDF
  • Self Extracting Zip
  • Posting via FTP
• Archiving
  • Commit and Push to GitHub
• Using DynaDoc Online

About this Document

This document provides information about developing documentation projects from an administrative and implementation perspective. Technical aspects of using DynaDoc can be found in the DyanDoc Operator's Manual.

Document Navigation

You can navigate through the documentation to specific topics using the menu, or step through sequentially using the Next and Previous arrowhead buttons. The Next button will step you from the current topic to the next topic at the same level unless the current topic has a sub-topic. If the current topic has a sub-topic, the Next button will step you into the first sub-topic. The Previous button works similarly, but in reverse sequence. Your current location within the document is shown as a "breadcrumb" trail at the top of each page under the document title. You can click on any level of the breadcrumb hierarchy to go that location. You can also use the following keyboard shortcuts:

ACTION	KEYSTROKE or BUTTON
Previous Page	Alt-p or
Next Page	Alt-n or
Up one level of the breadcrumb hierarchy	Alt-u

Links are shown in brown font.

Finding Information

This document includes a Table of Contents, Glossary / Index and Google search on each page. You must be connected to the Internet in order to be able to use the Google search, and you can select whether to search VideoRay's online document library only (the default) or the Internet.

Document Conventions

Several symbols are used throughout this documentation to add emphasis and to assist in relocating important information. The following table describes these symbols and their uses.

SYMBOL	DESCRIPTION
	The Danger icon is used to indicate there is a potential risk of personal injury or death. Extra care should be taken to understand the risks, and all personnel should exercise caution. It may also be appropriate to warn others in the immediate vicinity.
	The Caution icon is used to indicate there is a potential risk of damage to the equipment or surrounding property. Personnel should receive training in the appropriate procedures before attempting to operate or maintain the equipment.
	The Do Not icon is used to indicate that an action or activity should NOT be performed.
	The Note icon is used to highlight a specific detail or point of information.
	The Tip icon is used to highlight a suggestion or recommendation.
	The Manual Cross Reference icon is used to link to reference material elsewhere in this document or in an external resource. To view the reference, click on the Manual Cross Reference icon.
	The Play Video icon is used to link to a video about the topic. To view the video, click on the Play Video icon.
	The Hand icon is used to indicate an interactive element of the page. When you hover your mouse over the Hand icon, an image on the page will change to reflect the information in the text immediately prior to the hand icon. Try it here - hover your mouse over the following text and Hand icon to turn the Hand icon to the left blue: Interactive Text .

Document Customization - My_Notes

This document has been developed to allow local online versions to be customized using the My_Notes feature. Users can add their own notes to each page. See the Customizing this Document page for more information about how to customize this document.

Beyond this Document

There is no substitute for experience and/or training, especially with respect to the real purpose for which you plan to use this equipment. We encourage you to explore options beyond the scope of these materials to expand your knowledge and skills necessary to support your applications. In addition to this documentation, VideoRay offers training and technical support and hosts a general user discussion forum and user image gallery.

We also realize that collectively, users of our products spend considerably more time operating our systems than we do ourselves. Users also encounter more diverse operating environments across an extremely broad range of applications. We highly value this vast experience base, and invite and encourage you to share your experiences and suggestions with us. Please feel free to contact us by any of the methods listed below.

Quality Commitment

VideoRay strives to design, manufacture, deliver and support the highest quality products and services, including this documentation. We have made every effort to ensure that this documentation is accurate and provides you with the most up-to-date information.

If you find any errors in this documentation or have suggestions for improvements, each page contains a "Help us improve this document" feedback link in the left margin (you must be connected to the Internet to use this link).

Disclaimer

This document is deemed accurate at the time of its writing, however it is not a legal contract and the information contained herein should not be construed to represent any form of commitment. This document as well as the associated products and services are subject to change without notice.

Alternate Formats

Single HTML Page Format
This document is available as a single HTML page that can be viewed and/or printed by the viewer.

Portable / Printable Format
An abbreviated print version of this document is also available in HTML and PDF formats in Letter and A4 sizes for viewing and/or printing. A free PDF Reader is available from Adobe. Printed versions of this document are available from VideoRay.

HTML File Set
This document set is also available for download as a self extracting zip archive for installation on your local device.

Customize this Documentation - My_Notes

My_Notes are easy to incorporate directly into the pages of this manual. They can be used to clarify content, add additional information, or document your custom settings, operational tactics or procedures. My_Notes are page specific and display at the bottom of the desired page under the "My_Notes" heading. No programming is required - it is as simple as saving a file with your notes.

Creating My_Notes

My_Notes can be written in HTML or plain text. HTML allows for more flexible formatting and inclusion of images or links to other web pages.

To add a My_Note, create an HTML or text file containing the note and save it in the VideoRay\My_Notes\ folder, which can be found in the computer account user's documents folder (Documents\ for Windows 7, or My Documents\ for Windows XP).

The file should be named the same as the page in which you want the note to appear, with a "my_" prefix (without the quotes). For example, if you want a My_Note to appear at the bottom of this page, the name of the file to create is: my_custom_my_notes.html. The name of the page being viewed can be found in the address bar of the browser being used to display this documentation.

Even if you are using a text file, the file name must end with the ".html" extension.

All My_Notes files are processed as HTML, so if you are using a plain text file, you will need to add "<pre>" (without the quotes) at the beginning of the file and "</pre>" (without the quotes) at the end of the file if you want to preserve the layout. The "<pre>" and "</pre>" will not show up in the display.

When using HTML, the My_Notes folder serves as the root for relative links. An images folder is included for you to store images. You may add other folders or files as desired.

Viewing My_Notes

When you reload the page, your My_Note will appear - there is nothing else to install or configure. A sample My_Note file has been included to display the My_Note below. You can use this file as a model for creating your own My_Notes.

Updating My_Notes

To update a My_Note, simply edit and re-save the My_Note file.

Removing My_Notes

My_Notes can be removed by deleting or renaming the My_Note file.

Sizing My_Notes Display (Optional)

The default vertical size for My_Notes is set to 200 pixels, which is used for the sample My_Note below. Due to browser limitations, My-Notes do not size dynamically. This means that a long My_Note may display a scroll bar in order to view the whole My-Note. You can adjust the size to eliminate the need for the scroll bar. To set the size of a My_Note, you need to edit the file named "my_notes_size_table.js" in the My_Notes\ folder (location defined above). The file contains one line for each page of this document using the following format:

    window.page_name = size_in_pixels;

Find the line for the page that includes the My_Note you want to resize and replace the value of size_in_pixels with the desired size in pixels. The page names are listed alphabetically. Example line from the "my_notes_size_table.js" file for this page:

    window.custom_my_notes = 200;

Note that ".html" in not included in the page name, and the line must end with a ";" Also, the optimum size required is dependent upon the size and aspect ratio of the browser window.

Before Contacting Support

Please make sure to consider the following information before contacting VideoRay's Technical Support to report a problem. The following information should available:

• User name and contact information
• Name of the owner if not the same as the user
• System model
• Serial Number of the affected component(s)
• Accessories in use
• Detailed information about the issue:
  • Symptoms
  • Operating conditions that create the symptoms
  • Anything new or unusually about the system or operations

Once you have collected the recommended information, visit the "How to Get Help" page for contact information.

In addition, please review VideoRay's Support website for additional information about:

• Principles of Customer Interactions
• Customer Care Philosophy
• Technical Support Policy
• Third Party Accessory Support Statement
• Use of Non-VideoRay Supplied Computers

Text Editor

Documentation is written primarily in HTML. Most HTML editors are either expensive or produce poorly formatted results. Several good choices for advanced text editors are listed below:

• Notepad++ (Recommended)
• EditPad
• SublimeText
• Atom
• Vim

If you have a preferred text editor, feel free to use it instead.

Configure windows to display file extensions.

1. If using Windows 7, open Windows Explorer and click Organize in the top left.
2. Select Folder and Search Options.
3. Navigate to the View tab.
4. Uncheck the checkbox next to Hide Extensions For Known File Types. This allows you to see and alter file extensions.

Configure your editor to automatically open .txt, .htm and .php files.

1. Create a blank .txt file on your desktop. Rename it and replace the .txt with .htm
2. Right click the new .htm file and select Properties.
3. In the General tab, click Change next to the Opens With field.
4. Navigate to the executable for your editor and select it. This will configure all .htm files to open with your editor.
5. Repeat this process for .php files.

Git

Git is a version control and archiving platform. Files and changes to the files are stored in repositories. VideoRay uses private repositories on BitBucket to store DynaDoc and other proprietary utilities and public repositories on GitHub to store the document source (The source is the same as the published content, except in a different format, so it does not need to be protected).

Git Client

1. Download and install SourceTree, or any other Git client.
2. Other Git client choices can be found on the Git website.
3. If you are familiar with using Git via the command line, you can use that as well.

BitBucket

You will need to clone the www repository from BitBucket before you can start creating documents.

1. Visit BitBucket.
2. Create an account if you don't already have one. Your username should be easily recognizable by other employees.
3. Inform your supervisor of your account name, and have your permissions configured for the VideoRay Documentation team.
4. Using BitBucket or SourceTree, Clone the www repository to your local computer in the following location: C:\www.

   If using SourceTree, click on the Clone/New button.

   1. Enter the Source Path / URL:, https://bitbucket.org/videoraydoc/www
   2. Enter the Destination Path using the location from above.
   3. You may be prompted for your BitBucket account credentials.

   If using BitBucket, navigate to the www repository on BitBucket.

   1. Click Clone in the Actions section of the sidebar (indicated by "...").
   2. Click on the Clone in SourceTree button.
   3. Allow the SourceTree application to launch.
   4. Enter Destination Path using the location from above.

GitHub

GitHub is required to clone a document set to your local computer for editing and to push documents back to GitHub for version control and archiving.

1. Visit GitHub.
2. Create an account if you don't already have one. Your username should be easily recognizable by other employees.
3. Inform your supervisor of your account name, and have your permissions configured for the VideoRay Documentation group.

At this point, you will not need to access GitHub any further for preparing your environment. You will need to access GitHub when you start to work on documentation projects as explained in the Document Setup section.

XAMPP

XAMPP provides a suite of products for hosting a local web server on your computer to run DynaDoc and other PHP scripts.

1. Download the latest version of XAMPP for Windows.
2. Install XAMPP. Do not install XAMPP in a Program Files folder. Instead use C:\xampp.
3. Start XAMPP Control Panel. On the right side, click the Config button with the wrench in it.
4. In Editor, navigate to your text editor's executable and select it.
5. In Autostart, check the box next to Apache.
6. Click Save.
7. In the main control panel window, click the Config option across from Apache. Click the first item in the menu that appears, httpd.conf
8. A text file should open in your text editor. There are two lines that need to be changed:
   1. Change
        DocumentRoot "C:/xampp/htdocs"
      to
        DocumentRoot "C:/www"
   2. Change
        <Directory "C:/xampp/htdocs">
      to
        <Directory "C:/www">
      Do not remove the < > brackets.
9. Restart Apache for the settings to take effect.

The www repository (which should have been downloaded earlier) has an index.htm file that is set up with links for DynaDoc and other required PHP programs. To access the web server, open a browser and enter http://localhost or http://127.0.0.1 in the address bar. You should see a page with Web tools, Apps, DynaDoc and Glossary links.

You can create an index.php file and include your own links, then at the bottom use the PHP include command to include the index.htm file with the DynaDoc links.

Additional Recommended Utilities

There are several other utilities that you may find useful in developing documentation projects. These utilities are all free.

• 7-Zip - allows for creation of compressed archives and extraction of files from these archives.

• FileZilla - is an ftp utility for uploading and downloading files to/from a server.

• GIMP - is an image editing utility for working with document images.

• grepWin - is a search utility that allows searching of phrases in multiple text files. grepWin can search HTML or script files for key strings, and even supports mass find and replace in multiple files. It is very useful if you ever need to change things like folder paths in your files.

• LinkChecker - can be used to validate all links in your documents and should be used before publishing a document to ensure that all links in the document are valid.

As with all software recommendations, if you have another tool that you you are more comfortable with that performs similar functions, feel free to use that instead.

Configuring DynaDoc

All DynaDoc PHP programs can be accessed directly, or through dynadoc_manage.php. dynadoc_manage.php is preferred and provides an easy to use interface with buttons and links on the home and categories pages. Information about creating a new dynadoc environment or setting up your computer to work in an existing DynaDoc environment is provided below.

Creating a New DynaDoc Project Environment

If you are setting up your computer for working in an existing DynaDoc environment (when you have cloned the www repository), you can skip this section.

If starting from scratch, you will need to create a category list file (dynadoc_create.lst) and a dynadoc_catName.lst file for each category. An example category list file is shown below:

    categoryName|displayName|
    _rov|ROVs|

The first line is a header that describes the record format. The second and subsequent lines include a category mnemonic and display name. In this example, _rov is the catName and ROVs is the display name. This file must be created and updated manually to add categories. At least one category must exist, and the trailing "|" is required.

An example category project list file (dyandoc_rov.lst) is shown below:

    Name|Project|Source Dir|Out Dir|List?|

The first line is a header that describes the record format. Additional lines are automatically created by dynadoc_create.php.

• Name is the formal name of the project.
• Project is the name of the project's script.
• Source Dir is the name of the folder for the project.
• Out Dir is the name of the folder for the output. If left blank, it will default to the Source Dir. If defined, it can be used to create separate outputs from the same source.
• List? is either blank or any character. If a character is used, DynaDoc will process a list of documents rather than a single document. Each project script name is placed on a separate line in the list file. The first line of the list file should be blank.
• The trailing "|" is required.

If Name preceded by a space, this row will be indented when displayed. This may be helpful for projects that use multiple concurrent versions in separate html folders. If Name is preceded by a +, a second "view" link we be created to the html folder. See the Advanced Techniques and Multiple Versions Example sections for more information.

The easiest way to use dynadoc_manage.php is to create a link to it in an HTML file such as index.html. An example line in an index.html file is shown below:

    <a href="dynadoc_manage.php?category=_rov">ROVs</a>

Additional lines can be created for each category. This file must be created and updated manually.

Setting Up Your Computer for Working in an Existing DynaDoc Environment

If you are creating a new DynaDoc environment, you can skip this section.

If you are setting up your computer for working in an existing DynaDoc environment, DynaDoc and its utilities are included in the www repository. DynaDoc will already be configured for all of the projects that exist at the time you clone the www repository to your system and will be updated each time you "pull" the www repository to your system. This does not include the actual projects. If you want to edit an existing project, you will need to clone the project repository to your system (as described in the previous section about Git Repository Creation / Cloning). This only needs to be done once for each project. Then as you make changes to the project, you will "push" your changes to the project repository on GitHub.

Git Repository Creation / Cloning

If creating a new document, you need to create a GitHub repository to store a copy of your documentation project online and manage changes to it, and then clone this repository to your local computer for editing.

If you are editing an existing document that you have not yet configured locally, you need to clone the existing repository to your local computer and then you can edit it.

Creating a Document Repository

If you are planning to edit an existing document, skip this section.

1. Navigate to the VideoRay-Documentation GitHub site. You will need to log in to view it.
2. Click New Repository in the top right corner. If you are not logged in or are not an Owner in the VideoRay Documentation group, this option will not appear and you will either need to log in or contact your supervisor.
3. Give the repository a name. The convention for repository naming is:
   1. All letters are lower case.
   2. Spaces are replaced with underscores.
   3. The name should provide a general idea of the document's contents.
4. Include an informative description of your project in the Description.
5. Leave the privacy setting on Public.
6. Check the box next to Initialize this Repository with a README.
7. Click Create Repository.

The repository exists on the GitHub server now, but it needs to be cloned to you local machine as well in order to work on it.

Cloning the Document Repository to Your Local Computer.

These steps apply to newly created project repositories as well as for preparing to edit an existing project that you have not yet configured locally.

1. Start SourceTree or your preferred Git client or use the command line. The following instructions assume you are using SourceTree
2. Click on the Clone/New button.
3. Enter the Source Path / URL: to the repository on GitHub:
     https://www.github.com/VideoRay-Documentation/repositoryName
   (replace repositoryName with the name of the desired repository).
4. Enter the Destination Path for the local copy of the repository:
     C:\VideoRay\www\repositoryName
   (replace repositoryName with the name of the desired repository). You can set up C:\\www\ as the default path in SourceTree.
5. Click the Clone button.
6. You may be prompted for your GitHub account credentials.

You should now have the repository (including its contents if editing) on your local machine. There are few more steps required to configure DynaDoc to work with this document. These steps are explained in the next section.

Dynadoc New Project Preparation

If you are creating a new project, in addition to creating and cloning the project (as described in the previous section about Git Repository Creation / Cloning), you will need to configure DynaDoc to recognize the project and then "push" the www repository to GitHub so that others can keep their system up-to-date with all projects as well.

Configuring DynaDoc for a new project is a semi-automated process which uses the dynadoc_create.php program for these steps. dynadoc_create.php is included in the www repository and is accessed using the dynadoc_manage.php program, which runs when you click on a category link on the home page. If you are creating a new project, these steps will configure DynaDoc and copy the project template files to the project folder.

If you are editing an existing project, you do not need to perform these steps.

1. Ensure that XAMPP is running, and type localhost into your browser's address bar, and press enter. This should load your local home page with the dynadoc category links.
2. Click on the category in which you want the project to reside.
3. You should see a list of various projects in that category.
4. Click Create New Document Project at the top. This will display a form for you to fill out.
   • Project Type: Select whether this is a new documentation project or you will be editing and existing documentation project.
   • Category: This will default to the current category.
   • Project Name: This will define the document's title and be displayed at the top of each page.
   • Project Folder: This should be the name of the repository you created on GitHub and cloned on your local computer.
   • Output Folder: This should be left blank unless there are special requirements.
   • Document Type: This should be "Operator's Manual," "Maintenance Manual" or some other description of the type of document you are creating / editing.
   • Quick Start: This setting determines whether or not the document will have a Quick Start section, not have a Quick Start section, or be a blank document.
5. Click Prepare Documentation Project when all settings are correctly configured.

The dynadoc_create.php program will prepare DyanDoc to work with your document. The next section will describe content creation - for more information about using DynaDoc to create and edit documents, see the following sections and the DynaDoc Operator's Manual.

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.

HTM Files

HTM files represent the body of the document. DynaDoc takes the information within the HTM files as directed by the script file, and puts them into a template to make everything look nice for the website.

.htm is used for input source files, and DynaDoc will convert the output file name automatically to .html.

HTML is a markup language, and usually uses an opening sequence and closing sequence of unique characters to tell a browser how to display text. We'll only cover a few basic HTML tags here. If you'd like to know more HTML tags to improve the appearance of your documents, try W3Schools HTML Tutorial.

• Headers: A Header makes text larger and automatically gives a bit of space under it. Headers shouldn't be used to enlarge text for general use, instead use them for page titles and sub-sections. A smaller header number is larger.
  • Example: <h1>Writing HTML</h1> or <h3>Writing HTML</h3> for a smaller version.
• Paragraphs: Paragraph tags format text properly so that it wraps correctly on all displays. Generally if a text has no other formatting tags on it, it should be wrapped in paragraph tags to ensure proper formatting with Dynadoc.
  • Example: <p>I'm a paragraph! Use me for good formatting!</p>
• Bold and Italics: Old favorites.
  • <b>I'm Bold!</b> and <i>I'm Italic!</i>
• Web Links: Clicking on the text in one of these will take the viewer to the webpage you define.
• Example: <a href="www.videoray.com">VideoRay</a>
• Here's an example of an internal link. This link would take a user to this page.
  <a href="../../document_creation/html/content_html.html">VideoRay</a>
• Images: Images will be discussed in more detail in the Images Section.
• Lists, Ordered and Unordered: Making a list involves a slightly more complicated tag. Ordered lists will number every entry in them automatically, while unordered lists will display bullet points. We're actually in an unordered list right now!
  • Example: An unordered list

          <ul>
            <li>I'm the first bullet point!</li>
            <li>I'm another bullet point!</li>
            <li>I'm the last bullet point!</li>
            </ul>
              

  • Example: An ordered list

          <ol>
            <li>I'll be numbered 1!</li>
            <li>I'll be numbered 2!</li>
            <li>I'll be numbered 3!</li>
            </ol>
              

There are many more HTML tags, but these should get you started.

Recommended HTML Conventions

All tags should be in lower case.

All <h>, <p>, <ul>, etc. tags should begin on a new line.

<li> and </ul> tags should also begin on a new line and be indented two spaces for each level.

Heading order is <h1>, <h2>, <h3>, <b>

When referencing local images, the following format should be used. ../../projectName/images/imageName.

When referencing local links, the following format should be used. ../../projectName/html/htmlName.

Images

Including an image in an HTM page is fairly simple, but first we need one to include. The most likely images you'll need while making a document are pictures of relevant hardware, or screenshots of various software elements. We may need to edit the images a bit as well, but let's start with acquiring them.

Taking a Picture

While taking a photograph for a document, ensure that you have good lighting and a uniform, preferably white, background. This makes removing the background and any further editing we need to do to the picture easy. Take several photographs of each piece to ensure that there is at least one crisp picture to use. Good backgrounds and clear pictures with good lighting are critical to maintaining the professional appearance of a document.

Uploading a picture to your computer will vary depending on your camera, but plugging the camera into your computer will normally allow you to open it's internal storage. Source images should be stored in the projects source folder.

Taking a Screenshot

We can also use the keyboard's "Print Screen" button to capture an image of a computer screen. This is especially useful if you need to take a screenshot of a software program. Bring up the item you'd like to capture, and then press the Print Screen button (which may vary by keyboard). This will capture the screen, which you can then paste into an image editing program like GIMP or Paint. Source images should be stored in the projects source folder.

Editing

There are two primary edits you'll want to do perform on images, cropping and highlighting.

Cropping

In GIMP, the crop tool allows you to select an area and cut away everything else. It appears as a small razor in the toolbar.

To use it, select an area. After you make your initial selection you can pull on individual corners of your selection box to get a cleaner crop. When satisfied with your selection, press enter to crop the image.

Highlighting

Highlighting allows us to use the shadow and color functions of GIMP to create a nice looking highlight around a section of an image we'd like to emphasize. Image highlighting in all documents should remain consistent, so there is a specific process for this.

1. Open the image in GIMP
2. Using the rectangular selection tool, select the section you'd like to highlight as closely as possible.
3. Press "Shift+Q" on the keyboard. This will activate Quick Mask mode, which shows the non-selected parts of the image covered in red.
4. Use the pencil tool with a size of 1 to paint in individual pixels to get a more precise selection.
5. Press "Shift+Q" again when finished with your selection to toggle Quick Mask off.
6. Press "Ctrl+I" to invert your selection to select all of the image except your object.
7. Go to "Filters" in the top bar, then to "Artistic", then click on "Softglow."
8. Set glow Radius to 50.00, Brightness to 1.00, and Sharpness to 0.00. Click Ok.
9. Go to "Colors" in the top bar, then select "Desaturate." Select Choose shade of gray based on: Lightness, then click ok. This will desaturate the colors of everything besides your object.
10. Press "Ctrl+I" again to invert selection back to your object.
11. Go to "Filters", "Light and Shadow", and click "Drop Shadow."
12. Set Offset X to 0, Offset Y to 0, Blur Radius to 10, and the color HTML notation to "fcff00". Click Ok.
13. Press "Ctrl+F" five times to duplicate the shadow to achieve the desired brightness.

Saving

Saving in GIMP is a bit different than usual for image files. By default the image will save a .xcf file, which contains all of the metadata about how the image was edited. This is useful if you need to edit the image again at some time. If you are ready to use the image, instead you will want to go to "File" and then to "Export As." Export your image as a .png to the project's images folder. Keep the default settings for the GIMP prompts and click Export.

Including an Image

Now we have an image, but it's not in the webpage yet. The format to include an image is another HTML tag, similar to the ones described in the last section. The tag below was used to display the image on this page.

<img src="../../document_creation/images/con_save.png" width="650" alt="An Example of Highlighting">

The src field specifies the image location. In this case, replace "document_creation" with your own project folder, and replace "con_save.png" with your own image name. Title specifies mouseover text. Width is the width of the image in pixels. There is also a height attribute, which controls the height of the image in pixels. If only one of these attributes is set, the image will retain it's aspect ratio as it is resized.

Javascript

JavaScript is a useful programming language that we can leverage to create more interactive and dynamic web pages. While the instructions presented here are fairly simple, they are recommended for document writers that are a bit more tech savvy, rather than general use. In the example here we'll be creating text that changes an image when the text is moused over, and then changed back when the mouse leaves the text. Our implementation will be split into a JavaScript and HTM file, and will then be put together by DynaDoc.

JavaScript File

If you don't already have one, create a folder named javascript in your project folder. In the javascript folder, create a text file. Rename the text file to have the same name as the HTM page you want to include JavaScript on. The file extension for JavaScript files is .js. If your HTM page is "software_cockpit.htm", your javascript file should be "software_cockpit.js".

We'll start with a useful example. We'll use Javascript to preload some images and then have an image swap between different highlights when the relevant text is moused over. Let's take a look at the JavaScript file first.

Not a lot of text, but most of it doesn't make sense on it's own. Let's explain what's going on.

• //Videoray: In JavaScript, comments are indicated with two forward slashes. We won't read this line as code, but it's useful for searching files that are relevant to VideoRay.
• if (document.images): This is a short check to see if there are any images in the document at all. If there are, it executes all of the indented code.
• [name] = new Image;: These lines create images and assign them names. The images don't actually have any information in them besides names, but we'll get to that later. You'll need at least three images. Base will be the image that the page defaults to when no text is moused over. View will be the current image being displayed, and will therefore have the same value as base to start. You'll also need at least one image that you'll actually be swapping to.
• [name].src = '[imagelocation]': This assigns the actual image data to the names we created earlier. View and base should be the same as mentioned above.
• function reset(): This is a simple function that sets the currently disabled image back to the base one.

Make sure that you set the names and paths correctly. Next, we'll take a look at the htm file that implements the JavaScript.

HTM File

This might look a bit more intimidating at first glance, but most of it is just regular text. Let's take a look at the relevant parts for the image.

• <p align = "center"><img src ="../../pam/images/con_view.png" width = "550" height = "400" name = "view"></p>: Here the image that will be replaced and it's base state are defined. The image has been named view to match the syntax of the JavaScript file, and the width and height have been manually set. Manually setting the size ensures that the image remains the same size even when it's swapped to a new image. This avoids shifting text around on the page as the image changes in size. The image is also wrapped in paragraph tags with align="center" to center the image on the page.
• <a name = "[image]" onmouseover = "view.src=[image].src" onmouseout = "reset()">[Link Text]<img src="../../required/images/icon_hand.png"></a>: Here's an example of the text that actually executes what we want. This creates a hyperlink that, instead of taking you somewhere when you click it, does things on mouseover and on mouseout. In this case, we've set it so that the view image has it's source changed when the mouse is over the text, and have it call the reset function we defined earlier when the mouse leaves. Just make sure to replace the relevant fields with the appropriate names, and an interactive page is just about ready.

DynaDoc Script File

We separate the HTM and JavaScript files for ease of use, but we need to combine them to display a proper webpage. DynaDoc is built to do this for us. One of the fields we discussed earlier is used to include a JavaScript file. Here's an example of a page with an included JavaScript file in the DynaDoc script.

**,Device Configuration,,software_device.htm,software_device.js,,

The JavaScript include is one field after the htm file. If the file has incorrect comma placement it will not read correctly, so make sure to double check the syntax.

CSS

CSS defines page style characteristics. There is a default CSS set in the required folder. If you want to use project specific CSS, you can add it to the project's css folder.

Advanced Features

DynaDoc is a powerful program with a lot of advanced features. The following section describes a few of these features. See the DynaDoc Operator's Manual for more information about these and additional features.

View and Print

DynaDoc can create view and print versions of a document simultaneously from a single source. This allows you to improve the user's reading experience depending upon whether they are viewing the document online or in print.

The view version can be accessed at projecName/index.html or projecName/html/index.html.

The print version can accessed at projecName/html/_print.html.

If you are using HTML_VERSION, the index.html in the root folder should be set up as a selection page to choose the desired version of the document.

Document Structure

DynaDoc is very flexible when it comes to a document's structure. You can use "includes" to replicate boilerplate text or pull document pages from other documents to include in your current document. You can also use conditional text and conditional pages to create different outputs from the same source.

DynaDoc also has provisions for including sidebar content (below the menu) and images for the menu and table of contents.

See the DynaDoc Operator's Manual for more information.

Glossary

DynaDoc includes a script that will automatically generate a glossary of terms page with links to pages where the terms appear. You need to define the terms and definitions.

Generally, the glossary is updated only when the script is ready for publishing. You do not need to update the glossary links during the normal edit and review cycles.

Building the glossary is fairly easy, and uses very basic syntax. The glossary source should be created as a text file in the glossary folder and named glossary.csv. Each line contains the following elements separated by "|". The trailing "|" is required.

case_control|word|description|

Case Control can have the following

• * - Forces case sensitive match, and can be used for acronyms.
• ~ - Separates variations of words, example: "video ~video, ~video." will not match VideoRay

If case control is not used, the "|" is still required before the word.

To create a glossary, follow these steps:

1. open glossary\glossary.csv in your editor.

2. The first line in the file should be: case_control|word|description|
3. After this required line, we can start adding entries. Entry format is always |Keyword|Definition or Description| as shown in the above image.
4. Create a new line after every glossary entry.
5. Once you've saved your file with the entries, we need to run the dynadoc_glossary.php script using the Glossary button.
6. Open localhost, and navigate to your project's category.
7. Click on the "Glossary" button to create the glossary.
8. The glossary is generated.
9. Make sure to regenerate your document with the regular DynaDoc script to include the newly created _glossary.htm file.

exclude.csv provides the glossary script with a list of pages that should be ignored when the glossary links are created. For example, links should not be created to the table of contents. A master exclude.csv is included in the required folder. If you want to exclude pages on a project basis, create an exclude.csv file in the project's local glossary folder. See the required exclude.csv for the file's format.

Creating the PDF

The pdf of the document can be created from the print version (_print.html).

1. Create two pdfs of _print.html, one for Letter size named videoray_doc_projectName.pdf, and one for A4 size named videoray_doc_projectName_a4.pdf, in the staged project's pdf folder. If working with a document for which the script is automatically generated (VITAL, Parts Navigator, etc.), the projectName should be preceded by an extra "_" because the script is automatically generated and includes the "_" prefix, such as _productName.

2. >Review the pdf for errors, and check to ensure that the pdf link in side bar of the "About this Document" page (intro_about.html) works (using the staged location).

Any relative URL links in the document must be addressed. There are two options:

1. Since many links in a typical document are relative, links in the pdf will be based upon the server path where the file is located. If the document is located in a server/path where the relative links can be resolved, the pdf should be created using the _print.html file on that server/path. Otherwise the links will resolve to the source server/path where the file is located when the pdf is created, and if this is localhost/, the the links will not work properly when published. An issue with this method is that internal links will typically have an html page as the target and not link to the expected location within the pdf.

2. Remove all relative links from the print version using <--v--> <--/v--> around the <a href=""> and </a> tags.

Creating the Self Extracting Zip

A self extracting zip file makes the document set more portable.

1. Stage the product using dynadoc_prepare.php or dynadoc_stage.php.
2. Navigate to the DynaDoc stage folder.
3. Select the product and "required" folders.
4. Right click on the document folder and select 7-Zip->Add to Archive.
5. Set the Archive name to the product folder name. If working with a VITAL document, the product folder name should be preceded by an "_" because the script is automatically generated and named _productName.
6. Select 7z as the Archive Format.
7. Select the Create SFX archive setting.
8. Click on the Okay button to create the zip exe file.
9. Run dynadoc_zip.php using the Zip button.
10. Copy the zip file from stage/ to the project's zip/ folder.

Verify the zip file works.

Posting

The distribution set should be posted to the following locations:

• The VideoRay public site: https://download.videoray.com/documentation.
• The rovdoc site: http://www.rovdoc.com.
• The build set for production systems.

Check to ensure that the zip file link in the side bar of the "About this Document" page (intro_about.html) works.

Posting can be completed using FileZilla or any FPT client. Account credentials will be provided by a manager.

Commit and Push to GitHub

All projects should be "pushed" to the GitHub repository when completed.

1. Open SourceTree (or use your preferred git method).
2. On the left sidebar, double click the name of your document project.
3. In the project window, check the status of the files and update .gitignore if necessary to remove any unwanted files from being included in the repository.
4. Stage all of the changes.
   Make sure "All Files" is selected to ensure all modifications and additions are committed.
5. Enter the version number and any additional desired notes in the Commit Message section.
6. Click on the Commit button.
7. Click the Push button at the top.