The IBM Style Guide: Conventions for Writers and Editors (Eiji Yamane's Library) by Francis DeRespinis & Peter Hayward & Jana Jenkins & Amy Laird & Leslie McDonald & Eric Radzinski

Author:Francis DeRespinis & Peter Hayward & Jana Jenkins & Amy Laird & Leslie McDonald & Eric Radzinski
Language: eng
Format: epub
Publisher: IBM Press
Published: 2012-03-14T16:00:00+00:00

* * *

Examples

copy filename[filetype]

filename

The name of the file. This value is required.

filetype

The file type. This value is optional.

set monitor on|off

on

Turns on the monitor.

off

Turns off the monitor. This value is the default.

* * *

Using diagrams to specify command syntax

Syntax diagrams visually represent command syntax. An example of a syntax diagram follows.

.-,--------------.

V |

>>-LOAD--+--------+--FROM----+-filename---+-+--OF--filetype----><

'-CLIENT-' +-pipename---+

'-devicename-'

Important: Because syntax diagrams are inaccessible to users of screen readers, you must also provide an alternative accessible format. Both the dotted decimal format and Backus-Naur Form (BNF) are accessible by screen readers.

Follow these guidelines to specify syntax by using a syntax diagram:

• Explain the syntax conventions in your documentation. For example, in a book, include the explanation of syntax conventions in the preface or in an introductory chapter. In topic-based information, provide a topic about command-syntax conventions.

• Use the following basic components in the syntax diagram. If your authoring tool supports syntax diagrams, see the tool documentation for detailed information about how to create these components.

• Use two right-facing arrowheads and a dash (>>-) to indicate the beginning of a syntax diagram. Use a dash, a right-facing arrowhead, and a left-facing arrowhead (-><) to indicate the end of a syntax diagram. If you cannot show all the syntax on a single line, use a dash and a right-facing arrowhead (->) to indicate that the syntax is continued on the next line. Use a right-facing arrowhead and a dash (>-) to indicate that the syntax is continued from the previous line.

• Put required items on the main path. The following diagram shows that the db2idrop command name is required.

>>-db2idrop----------------------------------------------><

• Put optional items below the main path. The following diagram shows that the SHOW DETAILS parameter is optional.

>>-LIST INSTANCE--+--------------+-------------------------><

'-SHOW DETAILS-'

• Put choices in a stack. If users must choose at least one of the items, put the first item in the stack on the main path. The following diagram shows that users must choose between the on and off parameters.

>>-db2iauto--+-on--+---------------------------------------><

'-off-'

If users do not have to choose any of the items in a stack, put the entire stack below the main path. The following diagram shows that users can specify the BACKUP parameter, the ROLLFORWARD parameter, or neither parameter.

>>-LIST HISTORY--+-------------+---------------------------><

+-BACKUP------+

'-ROLLFORWARD-'

If one of the items in a stack is the default, put it above the main path. The following diagram shows that verbose is the default parameter.

.-verbose-.

>>-db2sampl--+---------+-----------------------------------><

'-quiet---'

• Use a monospaced font for a command name and for parameters and options that are not variable values. For variable values, use an italic monospaced font. If you must use a multiple-word variable name, remove the spaces between the words, or connect the words with underscores. The following diagram shows that users must provide a database name and can optionally specify an alias name.

>>-CATALOG--+-DATABASE-+--dbname--+-----------+------------><

'-DB-------' '-AS--alias-'

• Indicate that users can specify an item more than once or can specify more than one item by using an arrow above the main path that returns to the left. The following diagram shows that users can specify a file name, pipe name, or device name multiple times. The separator for multiple or repeated values, if required, is shown on the arrow.

Download

Copyright Disclaimer:
This site does not store any files on its server. We only index and link to content provided by other sites. Please contact the content providers to delete copyright contents if any and email us, we'll remove relevant links or contents immediately.