Topic: DMD0240
Managing Project Documentation
Project documentation refers to all of the user-supplied text that is associated with a Do-more Designer project. There are five areas of a project that can be documented by the programmer: Element Documentation (Nickname, Extra info, Description), Rung Comments, the Title Page, the Project Properties Page, and the User Document. Each of the areas has it's own editing facility that enforces any rules that the areas have.
All of this documentation is an integral part of a project, so when a project is saved to the controller, a copy of all of the project documentation is saved to the controller as well. The controller now contains a copy of the project documentation in addition to the ladder program and the system configuration data.
Note: Because the documentation is part of a project, any time the programmer adds any new project documentation or edits any existing project documentation, both the Write to Disk and Save to PLC icons on the online toolbar will become enabled.
Enabling Documentation Display on the Options Dialog
The Ladder
tab of the Options dialog allows the programmer control over which of
the individual areas of documentation will be displayed in each view.
The Options dialog is opened through the View-> Options menu selection, the ’Options’ button on the Offline toolbar, or right-clicking in a Ladder View and selecting 'Options...' from the pop-up menu.
Once the Options dialog is open select the Ladder tab to get to the Documentation selections.
The 'Apply Options to' selections at the top specify which Data views the changes to the options will be applied to.
Current View - the changes apply only to the currently selected Ladder View.
All Open Views - the changes apply to all of the currently open Ladder Views.
New Views - the changes do not apply to the currently selected Ladder Views, only to Ladder Views that are opened from this point forward.
The Documentation group of the Ladder Options dialog has entries for
each type of documentation.
Elements - display the element
name
Nicknames - display the Nickname
for any element that has one
Extra Info - display the Extra
Info for any element that has this information
Description - display the Description
for any element that has this information
Comments - display the Rung Comments for any rung that has one.
The Documentation group of the Ladder tab currently shows all of the documentation types checked, meaning they will be displayed in the Ladder view. Leaving a selection checked turns ON that documentation type to be shown in the view. Un-checking the documentation type will turn it OFF in the any view that can display element documentation.
Element Documentation
The individual
Elements of the ladder logic program are the most commonly documented
items of a project. There are three pieces of documentation that can be
added to any Element in a ladder logic program, they are: the Nickname,
Extra Info and the Description.
Nicknames
A Nickname is a user-created, alternate name for an Element in the controller (other applications you’re familiar with may use the term ”Tags” instead of Nickname). Because Element references can sometimes be cryptic, Nicknames are created by the programmer to give a human-readable, and more easily remembered name to an element in the controller. Once a Nickname has been assigned to an Element, the Nickname can be used interchangeably with the controller element within Do-more Designer.
Nickname Naming Conventions
All Element references in the controller are unique, that is, there
are no duplicate Element references. And since Nicknames directly correspond
to these unique elements in the controller, Nicknames themselves must
also be unique within a project. This means that there are rules the programmer
must follow in creating Nicknames. These rules are as follows:
Nicknames can be 1 to 16 characters in length.
Nicknames must begin with an alphabetic character or an underscore. For example, _1stPUMP is a valid nickname, but 1stPUMP is not a valid Nickname.
Nicknames can consist of any combination of alphanumeric characters and underscores ('_', 'a-z', 'A-Z', 0-9), no spaces or punctuation marks are allowed.
Extra Info
The Extra Info field is a 16 character field that can be used to identify panel wiring for the project. Text in the Extra Info field can consist of any alphabetic character, alphanumeric value, punctuation mark, and arithmetic operator.
Description
The Description field is a 132 character field that can be used to provide a detailed description of the element. Text in the Description field can consist of any alphabetic character, alphanumeric value, punctuation mark, and arithmetic operator.
See the Help Topic for the Element Documentation Editor for more information about creating and editing Element Documentation.
Using the Element Browser to Enter Documentation
Documentation
for an Element can also be managed through the Element Browser. The Element
Browser is opened
To use the Element Browser to manage the documentation for an Element, enter the desired Element in the Source Element field, then enter the Nickname, Extra Info, and/or Description text in the appropriate fields then click the Write Detail button to save the documentation for that Element.
If the edit cursor is over an Element in the ladder program when the Element Browser is invoked, that Element will be selected and any existing documentation will be preloaded when the browser is displayed. For example, if the edit cursor is over the Element X40 in the ladder program when you invoke the Element Browser, X40 will be displayed in the browser and any existing documentation will be loaded.
When editing an Element that has existing documentation, as soon as any of the documentation is changed the Read Detail button will be enabled. This button will reset the text in all of the fields back to the last version of documentation written to disk.
Selecting any of the items in the Nicknames list will display all of the existing documentation for that element and allow you to change that documentation.
The option to ’Include System Nicknames’ is enabled by default. If you want to exclude the predefined system Nicknames, uncheck this option and the resulting list will only display the user-assigned Nicknames in the currently opened project.
See the Help topic for the Element Browser for a complete discussion of using the Element Browser to manage Element Documentation.
Adding
Rung Comments
Each rung of ladder logic in a Program or Task can have a text Comment associated with it. The rung comment editor is used to create and edit these comments. Text for the rung comment can be entered directly into the comment field, or the programmer can use cut and paste from another comment or another editor.
Each rung comment can contain up to 20 lines of text, with a maximum of 2400 characters. The number of characters per line will depend on the font and the width of the characters. Text in the rung Comment can consist of any alphabetic character, alphanumeric value, punctuation mark, and arithmetic operator; essentially any printable ASCII character can be used.
The Edit Comments dialog provides a free-form edit window. This allows the programmer to enter the comment text any way they want, within the confines of the edit window. All the traditional Windows editing keystrokes are available for editing, and for cutting and pasting text into and out of the comment editor.
See the Help topic for the Rung Comment Editor for a complete discussion of using the Comment editor to manage Rung Comments.
Title
Page
The Title Page provides an additional way the programmer can document a Do-more Designer project. The Title page will be the first page when the project is printed.
Whereas Element Documentation contains information about the individual program elements, and a Rung Comment contains information about an entire rung of ladder logic, the Title Page typically contains an overview of the whole project.
The Title Page can contain up to 20 lines of text, with a maximum of 2400 characters. The number of characters per line will depend on the font and the width of the characters.
Text in the Title Page can consist of any alphabetic character, alphanumeric value, punctuation mark, and arithmetic operator; essentially any printable ASCII character can be used.
See the Help topic for the Title Page Editor for a complete discussion of using that editor to manage the contents of the Title Page.
Project
Properties Page
The File Properties Page dialog provides an additional way the programmer can document a Do-more Designer project. The information entered on the Properties page will be displayed on the Title Page.
The Properties Page dialog is automatically invoked the first time a project is saved to disk. The Properties dialog can be invoked at any time by selecting File-> Properties from the Offline toolbar.
Enable & Disable Printing of the Properties
Since the information on the Properties Page is included with the text from the Title page, any time the project is printed the Title Page will also be printed which will include the Project Properties information.
To disable the Printing of the Project Properties Page, uncheck the ’Print it!’ option on any of the Print dialogs.
Attach a User Document
Individual
Do-more Designer projects can
be configured to display a file (called the User Document) in the Start
Page in place of the default Start Page content. This user document
can be any file type that can be displayed in a web browser, such as a
text file (.txt), a web file (.html or .htm), a PDF document (.pdf), a
picture (.jpg), etc.. The size of the user document is limited to a maximum
of 10 megabytes.
To attached an existing file to an open project as the User Document do the following:
Select Tools-> Select User Document... from the menu. This dialog appears:
Select Include File
Click the Select File... button which will open the standard file open dialog to browse to the file that will be used as the User document.
A confirmation dialog will be displayed, and once confirmed, the document will be displayed on the Start Page.
Selecting No File will remove the association to an existing User Document.
A global User Document can be set through the Start Page Content selection of the Global Options dialog, refer to the Start Page help topic for more information.
See Also:
Related Topics: