Parameter and variable names

DITA has four elements for distinguishing parameters, arguments and variables, depending on the context in which they are specified.

In computer science, a parameter is a type of variable which is passed to a program or sub-routine. The term parameter is closely associated with the term argument; a parameter is defined in the procedure definition itself, while the argument is the value passed to the procedure in the procedure call. (In this context, a procedure means a program function, routine or sub-routine.)

For example, in the CalcCharge procedure following, the parameters are hourlyRate and numHours..

Function CalcCharge(hourRate as Integer, numHours as Integer) as Integer
  Return (hourRate * numHours)
End Function

When the CalcCharge procedure is called, the values passed to the procedure are the arguments; in this case, the values 55 and 130.

grossFee = CalcCharge(55,130)

In some cases, the values of variables will be passed as arguments; that is, they will be a named substitute for the value.

hr = 55
co = 130
grossFee = CalcCharge(hr,co)

The three terms parameter, argument, and variable are often used interchangeably, to the point that their specific meanings are often confused. To further confuse matters, their meaning in documentation is subtly different. For example, a variable in documentation is a placeholder in the text that the reader needs to substitute with values particular to the reader.

DITA has four elements used for identifying parameters, arguments, and variables: parmname (parameter name), parml (parameter list), varname (variable name), and var (variable).

parmname: Used to identify programming parameters and arguments in commands, calls, and functions. Documentation usually focusses on the parameters (the information passed to a procedure), rather than the procedure's arguments, so parmname is appropriately named. The parmname element belongs to DITA's programming domain; it is intended for documenting APIs rather than applications.
parml: Used to identify a list of programming parameters and arguments in commands, calls, and functions. The parml element has a list structure, comprising plentry (row), pt (parameter term), and pd (parameter definition). The parmname element belongs to DITA's programming domain; it is intended for documenting APIs rather than applications.
varname: Used when the reader has to substitute a value that might be specific to their own context or environment. For example, when documenting how to log on to a system, the user name (which will vary from user to user) will be marked up as <varname>. The varname element belongs to DITA's software domain; it is intended for documenting software applications.
var: Used only in syntax diagrams (syntaxdiagram), which are special devices used to document programming languages, and application programming interfaces (APIs). The var element belongs to DITA's programming domain; it is intended for documenting programming environments.

When documenting the example CalcCharge function, the following approach might be used.

<p>The <apiname>CalcCharge</apiname> has two parameters: 
   <parml>
    <plentry>
     <pt>rate</pt>
     <pd>The hourly rate charged to the client.</pd>
    </plentry>
    <plentry>
     <pt>hours</pt>
     <pd>The total number of hours spent on the client's project.</pd>
    </plentry>
   </parml>
  </p>
  <p>Both <parmname>rate</parmname> and <parmname>hours</parmname> must be integer values. </p>

By contrast, the varname element might be used in a description of a Vehicle Identification Number in a car owner's manual as:

<p>The VIN number has the following structure:
 <varname>Place of Manufacture</varname>
 <varname>Model</varname>
 <varname>Make</varname>
 <varname>Engine</varname>
 <varname>Type</varname>
 <varname>Equipment</varname>
 <varname>Check Digit</varname>
 <varname>Year of Manufacture</varname>
 <varname>Production Number</varname>
</p>

In a software user guide, the varname element might be used when describing a directory location, as in:

<p>The transfer file is generated by the <cmdname>Build</cmdname> application into the
<filepath><varname>My Documents</varname>\acme\xfer</filepath> folder.</p>

In summary, use parmname for programming variables, parameters, and arguments, and varname for other documentation variable placeholders.

Do not use square brackets or other syntactical conventions for simple variable names. If your publishing tool does not insert those conventions during processing, you may need to configure the tool so that it does so.