怎样在Linux上创建手册页

希望您的新Linux程序看起来专业吗?给它一个 man 页。我们将向您展示最简单,最快的方法。

佩奇

在旧的Unix笑话中有一个真理的核心,“ 您只需要的命令 知道是 man。”的 man 页面包含丰富的知识,当您想了解命令时,它们应该是您打开的第一位。

提供一个 man 您编写的实用程序或命令的页面将其从有用的代码片段升级为完整的Linux程序包。人们期望 man 专为Linux编写的程序提供的页面。如果您本机支持Linux,则 man 如果您想认真对待程序,则必须填写该页面。

历史上 man 页面是使用一组格式化宏编写的。当您要求 man 打开一个页面,它调用 groff读取文件并生成格式化的输出,根据文件中的宏。输出通过管道传输到 less, 然后 为您显示

除非您创建 man 经常翻页,编写一个页面并手动插入宏是一项艰巨的工作。创建一个行为 man 正确解析并看起来正确的页面可能会超越您的目标,从而为您的命令提供简洁而透彻的描述。

您应该专注于自己的内容,而不是与模糊的宏作斗争。

如何使用Linux的man命令:隐藏的秘密和基础

抢救潘多克

pandoc 程序 读取markdown文件并以大约40种不同的标记语言和文档格式生成新文件,包括 man 页。它完全改变了 man 页面编写过程,因此您不必费心象形文字。

首先,您可以安装 pandoc 在Ubuntu上使用以下命令:

sudo apt-get install pandoc

终端窗口中的“ sudo apt-get install pandoc”命令。

在Fedora上,您需要的命令如下:

sudo dnf install pandoc

sudo dnf在终端窗口中安装pandoc。

在Manjaro上,输入:

sudo pacman -Syu pandoc

sudo pacman -Syu pandoc在终端窗口中。“ width =” 648“ height =” 59“ onload =” pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“ onerror =” this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this );

如何在Linux命令行上使用pandoc转换文件

手册页

man 页面包含遵循标准命名约定的部分。您的部分 man 页面需求由您所描述的命令的复杂程度决定。

大多数手册页至少包含以下部分:

名称:命令名称和描述其功能的简单代码。
概要:简短的描述,说明有人可以用来启动程序的调用。这些显示了可接受的命令行参数的类型。
描述:命令或功能的描述。
选件:命令行选项及其作用的列表。
例子:一些常用用法示例。
退出值:可能的返回码及其含义。
虫子:已知错误和怪癖的列表。有时,可以用指向项目问题跟踪器的链接来补充(或代替)链接。
作者:编写命令的人。
版权:您的版权信息。这些通常还包括发布程序所依据的许可证类型。

如果您看一些更复杂的 man 页面上,您还会看到其他许多部分。例如,尝试 man man。不过,您不必包括所有内容,而只是您真正需要的。 man 页面上没有冗长的地方。

您会经常看到的其他部分是:

也可以看看:与主题相关的其他命令可能会有用或相关。
档案:软件包中包含的文件列表。
注意事项:要了解或提防的其他要点。
历史:命令的更改历史记录。

手册各节

Linux手册由所有 man 页,然后将其分为以下编号部分:

可执行程序: 或者,shell命令。
系统调用: 内核提供的功能。
图书馆电话: 程序库中的功能。
特殊文件。
文件格式和约定: 例如,“ / etc / passwd”。
游戏。
杂: 宏包和约定,例如 groff
系统管理命令: 通常保留给root。
内核例程: 默认情况下通常不安装。

每一个 man 该页面必须指明它属于哪个部分,并且还必须将其存储在该部分的适当位置,我们将在后面看到。的 man 有关命令和实用程序的页面在第一部分中。

手册页的格式

groff 宏格式不容易直观地解析。相反,降价很容易。

以下是手册页 groff

groff格式的手册页顶部。“ width =” 646“ height =” 277“ onload =” pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“ onerror =” this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this) ;

降价显示在同一页面。

降价格式的手册页顶部。“ width =” 646“ height =” 277“ onload =” pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“ onerror =” this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this) ;

前事

前三行形成称为前线的事物。这些都必须以百分号(%),后面没有空格,后面跟着一个:

第一行: 包含命令名称,后跟括号中的手册部分,不带空格。该名称将成为该名称的左部分和右部分 man 页面标题。按照惯例,命令名称是大写的,尽管您会发现很多不是的。命令名称和手册部分编号之后的所有内容都将成为页脚的左侧部分。使用它作为软件版本号很方便。
第二行: 作者的姓名。这些内容显示在 man 页。您无需添加“作者”部分,只需在此处至少包含一个名称即可。
第三行: 日期,它也成为页脚的中心部分。

名称

这些部分由以数字符号(#),即表示markdown中的标头的标记。数字符号(#) 必须是该行的第一个字符,后跟一个空格。

名称部分包含一个活泼的单行代码,其中包含命令的名称,空格,连字符(-),空格,然后是该命令的简短描述。

概要

内容提要包含命令行可以采用的不同格式。该命令可以接受搜索模式或命令行选项。两个星号(**)在命令名称的两侧表示该名称将以粗体显示在 man 页。单个星号(*)在某些文本的两边会导致 man 页下划线显示。

默认情况下,换行符后是空白行。要强制硬中断而没有空白行,可以使用尾随反斜杠()。

描述

markdown手册页的描述部分。“ width =” 646“ height =” 177“ onload =” pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“ onerror =” this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this) ;

该说明解释了命令或程序的功能。它应该简要地涵盖重要的细节。请记住,您并不是在编写用户指南。

使用两个数字符号(##)在一行的开头创建一个二级标题。您可以使用它们将描述分成较小的块。

选件

markdown手册页的“选项”部分。“ width =” 646“ height =” 132“ onload =” pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“ onerror =” this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this) ;

选项部分包含可与该命令一起使用的所有命令行选项的说明。按照惯例,它们以粗体显示,因此请添加两个星号(**)之前和之后。在下一行中包含选项的文本描述,并以冒号(:),后跟一个空格。

如果描述足够简短, man 将其显示在与命令行选项相同的行上。如果太长,则会显示为缩进的段落,该段落从命令行选项下方的行开始。

例子

markdown手册页的示例部分。“ width =” 646“ height =” 227“ onload =” pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“ onerror =” this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this) ;

示例部分包含不同的命令行格式的选择。请注意,我们在描述行中以冒号(:),就像我们在“选项”部分所做的一样。

退出值

markdown中手册页的退出值部分。“ width =” 646“ height =” 132“ onload =” pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“ onerror =” this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this );

本节列出了命令发送回调用过程的返回值。如果是从命令行调用的,则可能是shell;如果是从shell脚本启动的,则可能是脚本。我们以冒号(:)。

虫子

Markdown手册页的Bug部分。

错误部分列出了人们需要了解的已知错误,陷阱或怪癖。对于开源项目,通常在此处包含指向项目的问题跟踪器的链接,以检查任何错误的状态或报告新的错误。

版权

markdown手册页的版权部分。“ width =” 646“ height =” 112“ onload =” pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“ onerror =” this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this) ;

版权部分包含您的版权声明,通常包括对发布该软件所依据的许可证类型的描述。

高效的工作流程

您可以编辑 man 您喜欢的编辑器中的页面。支持语法高亮显示的大多数代码将意识到降价并为文本加上颜色以高亮显示标题,以及将其加粗和加下划线。就目前而言,这是很好的,但您并不是在看渲染的 man 页面,这是布丁中的真实证明。

在包含您的markdown文件的目录中打开一个终端窗口。在编辑器中将其打开后,定期将文件保存到硬盘中。每次您都可以在终端窗口中执行以下命令:

pandoc ms.1.md -s -t man | /usr/bin/man -l -

潘多克ms.1.md -s -t man | / usr / bin / man -l-在终端窗口中。“ width =” 646“ height =” 57“ onload =” pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“ onerror =” this.onerror = null; pagespeed.lazyLoadImages .loadIfVisibleAndMaybeBeacon(this);

使用此命令后,可以按向上箭头重复该命令,然后按Enter。

该命令还调用 pandoc 在降价文件上(在这里称为“ ms.1.md”):

-s (独立)选项生成一个从上到下的完整 man 页面,而不仅仅是其中的一些文本 man 格式。
-t (输出类型)选项与“ man”运算符告诉 pandoc 产生它的输出 man 格式。我们还没有告诉 pandoc 将其输出发送到文件中,以便将其发送到 stdout

我们还将管道输出到 man-l (本地文件)选项。它说 man 不要搜索 man 数据库寻找 man 页。而是应打开命名文件。如果文件名是 -man 将从 stdin

归结为您可以从编辑器中保存并按Q关闭 man 如果它在终端窗口中运行。然后,您可以按向上箭头,然后按Enter以查看您的渲染版本 man 页面,就在里面 man

什么是Linux上的stdin,stdout和stderr?

创建您的手册页

完成后, man 页面上,您需要为其创建最终版本,然后将其安装在系统上。以下命令告诉 pandoc 产生一个 man 称为“ ms.1”的页面:

pandoc ms.1.md -s -t man -o ms.1

pandoc ms.1.md -s -t man -o ms.1在终端窗口中。“ width =” 646“ height =” 57“ onload =” pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“ onerror =” this。“ onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);

这遵循命名惯例 man 在命令描述后的第一个页面,并附加手册的章节号,就好像它是文件扩展名一样。

这将创建一个“ ms.1”文件,这是我们的新文件 man 页。我们放在哪里?该命令将告诉我们在哪里 man 搜索 man 页面:

manpath

终端窗口中的人路径。“ width =” 646“ height =” 97“ onload =” pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“ onerror =” this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);

结果为我们提供了以下信息:

/ usr / share / man: 标准库的位置 man 页面。我们不会将页面添加到该库中。
/ usr / local / share / man: 此符号链接指向“ / usr / local / man”。
/ usr / local / man: 这是我们需要放置新的地方 man 页。

请注意,不同的手册部分包含在它们自己的目录中:man1,man2,man3等。如果该部分的目录不存在,我们需要创建它。

为此,我们键入以下内容:

sudo mkdir /usr/local/man/man1

然后,我们将“ ms.1”文件复制到正确的目录中:

sudo cp ms.1 /usr/local/man/man1

man 期望 man 要压缩的页面,因此我们将使用 gzip 压缩它

sudo gzip /usr/local/man/man1/ms.1

使 man 将新文件添加到其数据库中,键入以下内容:

sudo mandb

终端窗口中的sudo mkdir / usr / local / man / man1。“ width =” 646“ height =” 122“ onload =” pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“ onerror =” this.onerror = null; pagespeed。 lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);

而已!现在我们可以叫新 man 通过键入以下内容来使页面与其他页面相同:

man ms

“ msg。”“” =“ =” =“ =”“”“,在终端窗口中的ms。

我们新的 man 找到并显示页面。

“ new =” man“页面顶部。” width =“ 646” height =“ 382” onload =“ pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);” onerror =“ this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);”

看起来就像其他任何东西 man 页面,在适当的位置带有粗体,带下划线和缩进的文本。

“。新宽度的中间部分。” width =“ 646” height =“ 382” onload =“ pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);” onerror =“ this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);”

与其描述的选项相邻的描述行显示在同一行上。太长而无法容纳的行显示在它们描述的选项下方。

新手册页的底部。“ width =” 645“ height =” 382“ onload =” pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“ onerror =” this.onerror = null; pagespeed.lazyLoadImages.loadIfVisibleAndMaybeBeacon(this);“

我们还自动生成了一个“作者”部分。页脚还包括软件版本号,日期和命令名称,如前所述。

如果你想 。 。 。

一旦 pandoc 创建了您的 man 页面上,您也可以直接在 groff 宏格式,然后再将其移至 man 页面目录,以及 gzip 它。