|Syntax and mark-up / Phrases|
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.)
Function CalcCharge(hourRate as Integer, numHours as Integer) as Integer Return (hourRate * numHours) End FunctionWhen 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.
<p>The <apiname>CalcCharge</apiname> has two parameters: <parml> <plentry> <pd>rate</pd> <pt>The hourly rate charged to the client.</pt> </plentry> <plentry> <pd>hours</pd> <pt>The total number of hours spent on the client's project.</pt> </plentry> </parml> </p> <p>Both <parmname>rate</parmname> and <parmname>hours</parmname> must be integer values. </p>
<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>
<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.