Topic: DMD0276
Element Documentation Editor
The Element Documentation Editor is used to manage the user-assigned documentation for the programming elements used in a Do-more Designer project. The Documentation Editor can be opened by selecting the Tools-> Documentation Editor menu selection, clicking the Documentation button on the Tools toolbar, or pressing Ctrl + D. If the edit cursor is over a programming element, the Documentation Editor will open with it's editor on that programming element.
The Element Documentation Editor also allows for the creation of symbolic constants for use in the project. These are constant values - values that do not change throughout the program execution - represented by some text. Rather than embed literal values in program logic, the use of appropriately named symbolic constants can clarify the intent of the code. In addition, if a specific value needs to be changed, reassigning a symbolic constant once is more efficient and less error prone than replacing every instance of the value.
The user-assigned documentation for an Element is stored as a database record with the following fields:
Element
The program element. As program elements are added to a project a documentation record is automatically created for that element. An asterisk beside an element indicates that it is used in the project but does not have any user-assigned documentation.
This column displays 'Symbolic Const' for all symbolic constants.
Nickname
A Nickname is a user-created, alternate name for an Element in the controller (other applications 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.
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 must also be unique within a project. Nicknames can be 1 to 16 characters in length and consist of any combination of alphanumeric characters and underscores ('_', 'a-z', 'A-Z', 0-9), no spaces or punctuation marks are allowed, and must begin with a letter or an underscore.
The Nickname field will display the name of a symbolic constant. Symbolic constant names must follow the same guidelines as Nicknames.
Extra Info
The Extra Info field is a 16 character field. For programming elements this field 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.
For Symbolic constants the Extra Info field will contain the constant value.
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. If the text for the Description is longer than the column width line breaks will be automatically inserted as necessary to make the Description fit within the column width. The editor allows for the manual addition of line breaks (CTRL + CR) within the Description text to control the formatting of the multi-line Descriptions. The Description can be one to six lines of text. The text in each line will be centered over the Element.
The following Description has the automatically inserted line breaks:
Here is the same Description with a manually entered line break after the word ’used’ and another after the word ’in’:
Adding Documentation for an Element
Entering documentation for any of the fields for a programming element or a symbolic constant is done by navigating to a field and beginning to type, or double-clicking on the field. If the field already contains documentation text, pressing the F2 key will edit the existing text.
The data entered in a field will be saved as soon as the text cursor is moved off of that field. Pressing the ESC will leave the field editor without saving any changes that have been made to the contents of that field.
Add Record - will open the Add Documentation Record dialog to create a documentation record for a programming element that is NOT currently being used in the project.
As stated before, any elements used in the project will have a documentation record created automatically, the primary use for the Add Record dialog is bulk creation of element documentation before they are used in the ladder logic. For example, many programmers will start with a P & I diagram that has the I/O points labeled and will use those labels as Nicknames. The Add Record dialog allows the programmer to quickly step through the process of creating all of the Nicknames before the programming elements they reference are added to the ladder logic.
Enter the values for the Element, Nickname, Extra Info, and Description as desired then click Add Record to create the new database record. The Element field will auto-increment to the next element in the same block.
Add Symbolic Constant - will open the Add Symbolic Constant dialog to create a symbolic constant that is NOT currently being used in the project.
As stated before, any symbolic constants used in the project will have a documentation record created automatically, the primary use for the Add Symbolic Constant dialog is bulk creation of these constants before they are used in the ladder logic.
Enter the values for the Constant Name, and the Constant Value as desired then click Add Record to create the new database record.
Clean Database - will open the Clean documentation Database dialog that is used to remove documentation database records for programming elements and symbolic constants that are NOT used in the project.
Select the Element, or Elements to remove then click Delete Selected to remove the documentation record for each element selected.
Find / Find Again - will open the Find dialog to search through the documentation database for the selected item.
Element - enter the programming element or symbolic constant to search for.
Text - enter the text to search for
Case Sensitive - check to require the case to match in the text search
Search in - selects which fields to search in
Nicknames
- check to search the Nickname fields
Extra Info - check to search the Extra Info fields
Descriptions - check to search the Description fields
Cut / Copy / Paste Element Documentation
The Documentation Editor allows the programmer to copy all of the documentation for an element, or any of the individual documentation fields from one element to another. When using the Documentation Editor many of the familiar Windows keyboard shortcuts for editing functions are available, such as selecting text (SHFT+ Arrow keys), Cut (CTRL + X), Copy (CTRL + C), Paste (CTRL + V), and Undo (CTRL + Z).
Note:
Since Nicknames must be unique, they may be modified when pasted to guarantee
uniqueness, the new nickname will have an underscore before number _1.
For example, if an element with the Nickname "Start" is copied
and then pasted into a project that already has an element with the Nickname
"Start", the Nickname for the pasted element
Copy/Paste All of the Documentation Fields of an Element
To copy all of the documentation from one element to another element,
follow these steps:
Click in the Element column for the source Element to select the entire row (it will appear in reverse video).
Enter CTRL + C on the keyboard - or select Edit -> Copy from the Menu bar - to copy the selected text.
Move the cursor to the target element.
Enter CTRL + V on the keyboard - or Select Edit -> Paste from the menu - to paste the documentation into the fields of that Element.
Copy/Paste an Individual Documentation Field of an Element
To copy an individual documentation field from one element to another
element, follow these steps:
Double-Click in the field for the source element - the text in that field will appear in reverse video.
Enter CTRL +C on the keyboard - or select Edit -> Copy from the Menu bar - to copy the selected text.
Double-Click in the desired field of the target element - this puts the Documentation Editor into ’edit mode’ for that field.
Enter CTRL + V on the keyboard - or Select Edit -> Paste from the menu - to paste the documentation into the field of that Element.
Cut/Paste (move) All Documentation Fields of an Element
To cup/Paste (move) all of the documentation from one element to another element, follow these steps:
Click in the Element column for the source Element to select the entire row (it will appear in reverse video).
Enter CTRL + X on the keyboard - or select Edit -> Cut from the Menu bar - to cut the selected text.
Move the cursor to the target element.
Enter CTRL + V on the keyboard - or Select Edit -> Paste from the menu - to paste the documentation into the fields of that Element.
Cut/Paste (move) Individual Documentation Fields of an Element
To copy an individual documentation field from one element to another element, follow these steps:
Double-Click in the field for the source element &endash; the text in that field will appear in reverse video.
Enter CTRL + X on the keyboard - or select Edit -> Copy from the Menu bar - to cut the selected text.
Double-Click in the desired field of the target element - this puts the Documentation Editor into ’edit mode’ for that field.
Enter CTRL + V on the keyboard - or Select Edit -> Paste from the menu - to paste the documentation into the field of that Element.
Saving Element Documentation
Notice that the Documentation editor displays the controller elements in rows. If any of the fields on a row have been changed, the contents of the fields on that row will be automatically written to disk when the programmer navigates away from that row. If the Nickname field has been changed, the contents of the Nickname field will be validated to enforce the valid Nickname rules.
Pressing the ESC key will leave the field editor without saving any changes that have been made to the contents of that field.
Note: As mentioned earlier, a copy of the documentation will be stored in the controller. Any time the documentation is changed and written to disk, the ’Save to PLC’ icon on the main toolbar will be enabled to remind you that the documentation in the PLC and the disk are no longer in sync.
See Also: