Creating Text Variables

If you want to use text variables, you need to create them first.

  1. In Word, click the Variables view in the Doc-To-Help Project panel.
  2. Select one of the following in the Text Variables area:
    • Text A text variable is the type that has been used in previous versions of Doc-To-Help. This lets you enter simple text.

    • Version This lets you enter a version in one of four available formats:

      • 1
      • 1.0
      • 1.0.0
      • 1.0.0.0

      If you click the Build button, unchanged documents won't be processed, so variables won't be updated in those unchanged documents when you view the output, although they will be incremented in the Variables window where you created them.

      If you want to force variables to update in all documents, you need to click Rebuild instead. Each time you click the Rebuild button for a target that has the variable, the version values are incremented automatically—whether the documents have changed or not—in both the output and the Variables window.

      When version variables are updated, only the last part of the number is incremented automatically.

      Example  

      Let's say you create a version variable with the 1.0.0 format, insert it into a document, and build a target.

      If you rebuild the target, the variable changes in the output to 1.0.1.

      If you rebuild again, it changes to 1.0.2.

      If the variable value reaches 1.0.9 and you rebuild, it changes to 1.0.10, then 1.0.11, then 1.0.12, and so on.

      Note You can open the Variables window and change the variable value manually at any time.

      Note The variable value is incremented only if this variable was used in building the current target, so all variables that were excluded from the build process due to their condition won't be changed.

    • Date/Time These variables get their values either from current system date/time, or from file date/time attributes. This means that you cannot set its value manually (for this purpose, you can use simple "text" type variables).

  3. An editable field named "New Variable" displays in the Name cell. In the Name cell, enter a name for the variable.

  4. Depending on the variable type you selected, the Definition cell is populated with either simple text, 1.0.0.0, or a date/time format. Double-click in the Definition cell and provide the value for the variable.

    • Text If you double-clicked on a cell for a text variable, simply type text.
    • Version If you double-clicked on a cell for a version variable, enter the starting version number.
    • Date/Time If you double-clicked on a cell for a date/time variable, a popup displays. Complete the fields in it:

      • Format Specifiers This is the date/time format. You can select a format from the drop-down, or you can type a format manually. Specifiers are based on Microsoft's custom date and time format strings. For details of the specifiers available, see http://msdn.microsoft.com/en-us/library/8kb3ddd4.aspx.

        Note You can make a word part of the definition. For example, you might want the word Date with a colon and a space before a date string (e.g., Date: October 25, 2014). The issue is that certain characters are translated automatically as specifiers. So just typing the word Date wouldn't work. The easiest solution is to put the non-specifier characters within quotation marks. Therefore, you might enter "Date:" MMMM dd, yyyy.

      • Update Select how you want the variable to display the date and time. You can choose any of the following:

        • On Document Creation The variable displays the date and time that you created the document.
        • On Document Save The variable displays the date and time that you last saved the document.
        • On Build The variable displays the date and time of the most recent project build.

  5. (Optional) If want to associate a condition with the variable, double-click in the Condition column and choose a Platform, Target, or Attribute condition for the variable. See Conditions.

    • Platforms Set a platform-based condition for the variable. The text will be included in all of the target platform(s) selected. A platform includes all the targets that produce the output specified (Online Help, HTML Help, NetHelp, Printed Manual).

    • Targets Set a target-based condition for the variable. The text will be included in all the targets selected.

    • Attributes Set an attribute-based condition for the variable. The text will be included or excluded when creating conditional builds (e.g., internal or external). Use the Attributes dialog (Project ribbon > Attributes) to create custom attributes. See Creating and Using Attributes.

    If you would like to assign more than one condition to a variable, select the variable's name and click the Add Definition with Condition toolbar button. An additional definition row will be created. Enter the appropriate definition, then double-click in the Condition column to set a condition. One text variable can have multiple unique outputs.

    Tip It is recommended that you make a different version variable for each target and then assign conditions to those variables. This is quite useful because the version numbers are then incremented separately for each target. On the other hand, if you create only one version variable and use it in several targets, the version number will increment after each rebuild of any of those targets.

    Example  

    Let's say you have a NetHelp target and a Manual target.

    In the Variables window, you create a version variable named "NetHelp" with a starting value of 1.0. Then you create another version variable named "Manual" with a starting value of 1.26. Finally, you create a third version variable named "Shared" with a starting value of 3.9.

    Next, for the NetHelp variable, you double-click the Condition cell. In the Targets field (in the popup), you select NetHelp (or whatever your target is called).

    Then, for the Manual variable, you double-click the Condition cell. In the Targets field (in the popup), you select Manual (or whatever your target is called).

    Next, you insert all three variables in a source Word document.

    You build the NetHelp target for the first time. In the output, the variable numbers are as follows:

    • NetHelp 1.0
    • Shared 3.9
    • Manual Not shown because it was conditioned out

    Now you build the Manual target for the first time. In the output, the variable numbers are as follows:

    • Manual 1.26
    • Shared 3.10
    • NetHelp Not shown because it was conditioned out

    Next, you rebuild the NetHelp target. In the output, the variable numbers are as follows:

    • NetHelp 1.1
    • Shared 3.11
    • Manual Not shown because it was conditioned out

    Finally, you rebuild the Manual target. In the output, the variable numbers are as follows:

    • Manual 1.27
    • Shared 3.12
    • NetHelp Not shown because it was conditioned out

Note After creating a variable you cannot change its type.

Note Although you cannot create text variables while you are working in Word, you can hover over any text variable in the Variables window pane (Doc-To-Help > Project Panel) to view its definition.

After creating a text variable, you can insert it into any source document. See Inserting a Variable.