本页使用了标题或全文手工转换

维基百科:格式手册/命令行范例

维基百科,自由的百科全书
跳转至: 导航搜索

命令行范例指的是一段程序或者shell命令的具体用法,用户可以将其输入计算机终端或者命令提示符运行。本页面是为维基百科上与计算机科学相关的作者与编辑者提供一份样式指引。

通用指导[编辑]

当提供命令行范例时应当保持清晰和简单。这不仅会显得更专业,同时也防止读者产生困惑。下面的指南界定了什么是清晰,简单的范例。

  • 命令行的例子应当采用等宽字体。范例的开头应该使用维基百科的方式,包括命令行前缀和一个空格。进一步的引用应当加上<tt> (teletype)标签。
  • 维基百科不是一个展示作者的个人偏好的媒介。因此除非有必要,否则不应包含任何环境变量日期工作目录用户名主机名称
  • 术语:选项(option)是一种开关(一些修改一般行为的命令) 。参数(parameter)是一个特定值,如文件或主机名称。引用(argument)这个词是用来指任何空格分隔的字符串按照命令的名字,其中包括选项和参数。
  • 列举引用时,应注意保持简单。不加解释地定义引用会混淆读者。
  • 维基百科不能取代手册页。条目不应该列出与命令相关的整个选项列表,除非这样的选项非常少,或者这样的描述方式是绝对必要的。
  • 当指定参数时,应当使用合理的名称来指代他们。这些名称应该是斜体,不应包含空格,因为空格通常用来分隔命令行的多个引用。以下是一些例子:
(提示符) command parameter-name
(提示符) command parameterName
(提示符) command parameter_name
(提示符) command parametername
  • 一致性是很重要的。不要在同一个条目里同时使用上述四种方法来命名参数,以免混淆读者。
  • 非必须并且可以完全省略的引用应放在方括号[ ]中。
  • 有很多方法指定重复的参数。以下两个是最常见的:
(提示符) command parameter0 [.. parameterN]
(提示符) command [parameter ...]

具体平台的指导方针[编辑]

DOS,Windows与OS/2[编辑]

目前最常见的DOS平台是Windows平台下的MS-DOS。因此,仅在MS-DOS下适用的例子一般不需要特别说明。但是,如果该实例仅针对某个特定版本的MS-DOS,那么应当标明相关信息。如果已知其他的DOS平台下该范例有不同的效果,也应当加以说明。 适用于DOS命令行的例子应遵循下列额外的指导方针:

  • 程序或命令名应全部大写。
  • 标准的MS-DOS风格的选项(例如/C,其中C可能是其他字符)也应该大写,除非它们是区分大小写的。
  • 程序名称应当附加适当的文件扩展名,以与内置的命令名称相区别。如果某些版本的MS-DOS中不包含某个特定的程序(如MOVE.EXEEDIT.COM),那么应当注明包含这些程序的版本。

类 Unix 系统[编辑]

  • 大部分类Unix系统的命令实际上都是可执行文件。Shell内建的命令(如cdhistory)也在我们讨论的范围内。
  • 类Unix系统中常见的Shell相互之间有着一定的差异。因此,与特定的Shell相关的命令或者实用程序(如for循环或者流特性)应当尽可能地避免。
  • 如果为了正确地作出说明必须使用一串与特定Shell类型相关的命令,那么你应当同时提供类ALGOLshkshbash代码,以及C语言风格的cshtcsh代码。两者的语法没有差别时无需这么做。
  • 类Unix系统中的大部分命令都是全部使用小写字母的。然而,由于shell和操作环境区分大小写的特性,应注意大小写格式与命令或文件名匹配。如果有必要,建议使用标题错误模板
  • 通常情况下需要权限的命令与不需要权限的那些应当加以区别。如果某个命令确实需要特定权限,那么应当给出一份免责声明指出在无限制的权限下执行命令所具有的风险。
  • 在某些情况下,命令行参数很可能包含一些shell元字符(如通配符等)。在这种情况下,明智的做法是在例子中使用引号,以防止用户收到让他们感到奇怪或者毫无来由的错误。

提供范例输出[编辑]

为一个命令提供输出范例是一种保守的做法。这种情况下应当给出在终端中实际键入的完整的命令和所有的参数。命令的输出因此将只依赖于运行环境和其他变量。依顺序使用标签<pre><nowiki>可以确保输出文字的格式正确。

使用范例[编辑]

DOS[编辑]

  • DOS 預設命令DIR,這用於列出檔案和資料夾:
> DIR [options] [pattern ..]
  • MS-DOS (其行为模拟了先前版本DOS的功能)上的程序 MOVE.EXE:
> MOVE.EXE source target

常规Unix[编辑]

  • 用Unix风格系统上的ls命令列出文件和目录:
$ ls [options] [file ..]
  • mkfs命令创建新的文件系统,通常需要一定的权限:
# mkfs [-t fstype] [fs-options] device
  • wget程序,GNU实用工具之一,根据给出的URI获取文件。URI可以包含shell的元字符,因此参数需要加引号以防止出错。
$ wget [options] "URI"

Shell特性[编辑]

  • sh/ksh/bash中内置if结构的语法异同:
$ if command ; then command ; .. ; fi

在csh/tcsh中:

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

输出举例[编辑]

  • df命令的输出举例,列出了挂载的文件系统磁盘空间使用情况:
$ df -P
Filesystem          512-blocks      Used Available Capacity Mounted on
/dev/hda2             39331760   7398904  29834768      20% /