Wikipedia:Manual of Style/Command-line examples

Manual of Style
Content Accessibility Article message boxes Biographies Disambiguation pages Infoboxes Linking Self-references Words to watch
Dates and numbers Dates and numbers
Formatting Abbreviations Capitalization Dates and numbers Pronunciation Proper names Spelling Text formatting Titles
Images Captions Galleries Icons Images Layout
Layout Footnotes Layout Lead section Tables Trivia sections
Lists Embedded lists Lists of works Lists Road junctions
Legal Legal Trademarks
Arts topics Anime & Manga Comics Film Lyrics and Poetry Novels Television Visual arts Writing about fiction
Music topics Music Samples Record charts
Regional topics Canada France Hawaii Ireland Japan Korea Philippine Poland
Religion topics Islam Latter Day Saints
Science topics Chemistry Mathematics Medicine Computer commands Taxonomy
Sports topics Cue sports Snooker more specifically
Related guidelines Article size Article titles Categories, lists, and navigation templates Categorization Footnotes Template namespace Hatnotes Signatures Talk page guidelines Subpages User pages

Command-line examples are used to illustrate the syntax of shell commands or programs as a user would type them into a terminal or command-line interpreter on a computer. This page is a style guide for articles related to computer science on Wikipedia.

General guidelines

When providing command-line examples, maintain clarity and simplicity. It prevents the reader from becoming confused. The following guidelines help define clear and simple examples.

• Command-line examples should be presented in a monospaced font. The initial presentation should use the Wikipedia method that involves prefixing commands with a space. Further references should be contained in <code> tags.
• Avoid referencing environment variables, dates, working directories, usernames, and hostnames unless they are relevant in the example.
• Terminology: An option is a switch (something that modifies the general behavior of the command). A parameter is a specific value, such as a file or hostname. The term argument is used to refer to any of the strings that follow a command name, including both options and parameters. See Parameter (computing)#Parameters and arguments.
• When presenting arguments, maintain simplicity. Specifying them without explanation can confuse the reader.
• Do not document the entire list of options associated with a command unless there are very few such options or such descriptiveness is necessary. Wikipedia is not a substitute for manual pages.
• Use logical names in italics for parameters. These names should not contain spaces, as spaces are used to separate multiple arguments on the command line. The following are some examples:
  • (prompt) command parameter-name
  • (prompt) command parameterName
  • (prompt) command parameter_name
  • (prompt) command parametername

Consistency is important. For example, do not confuse the reader by using all four methods of naming parameters in the same article.

• Enclose optional arguments with square brackets: [ and ].
• The following are the two most common ways of specifying repeating parameters:
  • (prompt) command parameter0 [.. parameterN]
  • (prompt) command [parameter ...]

Platform-specific guidelines

DOS, Microsoft Windows, and OS/2

The most common operating system in use today is Microsoft Windows, whose command-line syntax is based on that of MS-DOS. As such, examples that might be specific to MS-DOS or Windows do not need to indicate this. However, if the examples are specific to a certain version of the operating system, then this should be indicated. If equivalents in other versions of DOS differ and are known, provide them.

The following additional guidelines are for DOS command-line examples:

• Write the names of commands and programs all upper-case letters.
• Standard MS-DOS–style options (of the form /C where C is some character) should also be upper-case, unless they are case sensitive.
• Contrast program names against built-in command names by appending their file extension. If a program is not included with certain versions of MS-DOS (such as MOVE.EXE or EDIT.COM), then the versions for which it is known to be included should be indicated.

Unix-like systems

• Commands that are shell builtins (such as cd and history) should be indicated as such.
• Avoid shell-specific commands or utilities (such as the for loop or certain stream behaviors) whenever possible, because of the great variation in shells across Unix-like systems.
• If a shell-specific sequence is required for proper explanation, provide an example for the ALGOL-like shells (Bourne shell, Korn shell, and Bash) as well as one for the C-like syntax of C shell and tcsh.
• The names of most commands on Unix-like systems are entirely in lower-case characters. Ensure that the capitalisation given matches that of the command or file name, because the shell and operating environment is case-sensitive. Use the wrongtitle template when necessary.
• Differentiate commands that normally require privileged access from those that do not require it.
• In some cases, the value of a parameter will commonly contain shell metacharacters. In these cases, it may be wise to specify quoting in the example to prevent users from receiving errors that to them will seem strange and unrelated.

Providing sample output

It may often be useful to provide a sample of the output that a command generates. In these cases, the full command and all arguments as they were typed are given. The output of the command will therefore be specific to environment and other variables. The tags <pre><nowiki> (in that order) will usually avoid conflicts with the wiki markup syntax.

Examples of usage

DOS

The DIR built-in command on DOS, which lists files and directories:

> DIR [options] [pattern ...]

The program MOVE.EXE on MS-DOS (whose behavior had to be emulated prior to its introduction):

> MOVE.EXE source target

General Unix

The ls command on Unix-like systems, which lists files and directories:

$ ls [options] [file ...]

The mkfs command, which creates new file systems and as such usually requires privileged access:

# mkfs [-t fstype] [fs-options] device

The Wget program, one of the GNU utilities, which retrieves files given a Uniform Resource Identifier (URI). URIs can sometimes contain shell meta-characters, and so the parameter is usually quoted to prevent errors.

$ wget [options] "URI"

Shell-specific

The if built-in structure, whose syntax varies. In Bourne shell, Korn shell and Bash:

$ if command ; then command ; ... ; fi

In C shell and tcsh:

% if (expression) then command ; ... ; endif

Sample output

Sample output of the df command, which lists disk space usage on mounted file systems:

$ df -P
Filesystem          512-blocks      Used Available Capacity Mounted on
/dev/hda2             39331760   7398904  29834768      20% /

See also

• Manual of Style/Computing (essay)
• WikiProject Computer science/Manual of style (draft)