RAM 6.0 BUX II Series Guía de usuario descargar pdf (Pagina 169)

B Documentation Guidelines

B.5 Format and Style

161

Placeholder Text

A placeholder (also known as a text variable) is a word that represents a value that is

to be supplied by the user, such as a command argument, routine parameter, or a

portion of a directory path. Text variables are employed most frequently in syntax

displays or pathnames. Surround placeholder words with the angle brackets < and

>. In the following example, hostOs is a value supplied by the reader:

The script is located in the directory ’host/<hostOs>/bin’.

Resulting output:

The script is located in the directory host/hostOs/bin.

Parameters

When referring to routine parameters, treat them as placeholders; that is, bracket

the argument name with the angle brackets < and >. For example, consider a

routine getName( ) with the following declaration:

VOID getName

(

int tid, /* task ID */

char * pTname /* task name */

)

For the description, you might say something like the following:

This routine fetches the name associated with the specified task ID <tid>

and copies it to <pTname>.

Book References

References to books or book chapters should be tagged with \tb, which sets them

in italics. For more information about standards for book references, see SEE ALSO

Section, p.152. Example input:

For more information, see the

\tb VxWorks Programmer’s Guide: I/O System.

Resulting output:

For more information, see the VxWorks Programmer’s Guide: I/O System.

NOTE: Although C routine parameters are variables from the perspective of the

code’s author, they are placeholders from the perspective of the user; therefore we

format them as any other placeholder and apply angle brackets. Note, however,

that global variables and structure members should be treated as literals, not

placeholders; see Literal Names of Commands, Global Variables, Files, and Other

Elements, p.159.

1 2 ... 164 165 166 167 168 169 170 171 172 173 174 ... 188 189

Sin comentarios

RAM 6.0 BUX II Series Guía de usuario Pagina 169