如何为我的 shell 脚本制作手册页？

Question

如何为我的 shell 脚本创建手册页？
我找不到关于如何在 Google 上制作手册页的初学者方法。

根据模板制作我自己的手册页并使用我的脚本安装它的最简单方法是什么？

Answer 1

示例手册页，来自 link:

.\" Manpage for nuseradd.
.\" Contact vivek@nixcraft.net.in to correct errors or typos.
.TH man 8 "06 May 2010" "1.0" "nuseradd man page"
.SH NAME
nuseradd \- create a new LDAP user
.SH SYNOPSIS
nuseradd [USERNAME]
.SH DESCRIPTION
nuseradd is high level shell program for adding users to LDAP server.  On Debian, administrators should usually use nuseradd.debian(8) instead.
.SH OPTIONS
The nuseradd does not take any options. However, you can supply username.
.SH SEE ALSO
useradd(8), passwd(5), nuseradd.debian(8)
.SH BUGS
No known bugs.
.SH AUTHOR
Vivek Gite (vivek@nixcraft.net.in)

使用脚本安装：

install -g 0 -o 0 -m 0644 nuseradd.1 /usr/local/man/man8/
gzip /usr/local/man/man8/nuseradd.1

手动安装：

cp nuseradd /usr/local/man/man8/nuseradd.1
gzip /usr/local/man/man8/nuseradd.1

Answer 2

使用 pandoc. You can write document in markdown（甚至 html、latex）怎么样，可以转换为 html、pdf、word、手册页 , epub, .... 这样您就可以用一种格式编写文档，convert/distribute 可以用您喜欢的任何格式编写文档

Answer 3

help2man 在给定 --help 标志时使用脚本的输出来生成像样的联机帮助页。

这需要很少的努力并提供合理的输出。因为它依赖于你的脚本在传递 --help 和 --version 时的输出，所以它也迫使你写一个像样的 --help :-)

Answer 4

我建议您使用在线手册页编辑器 Grapse，因为您可以在 real-time 中看到结果。相信对初学者很有用

Answer 5

C1sc0 您的回答有误。

要制作您自己的手册页，请按照以下步骤操作：

1- 成为超级用户：

$ sudo -i

2- 转到此目录：

$ cd /usr/bin
$ nano your_function

3- 复制粘贴此手册页模板，然后根据您的项目对其进行个性化设置：

./" Manpage for your_fonction
.TH man 1 "10 September 2017" "1.0" "your_fonction man page"
.SH NAME
your_fonction - do.... 
.SH SYNOPSIS
your_fonction [optionnal argument] [optionnal argument]
.SH DESCRIPTION
your_fonction is a function which .....
.SH OPTIONS
your_fonction does not take any options
.SH BUGS
No known bugs.
.SH AUTHOR
written by your_name (your_website or your_github or whatever)
.SH REPORTING BUGS
you_github_repository/isssues for example

4-你必须选择你的文件必须在哪个目录中，看：

$ cd/usr/share/man/ && ls

你看 man1, man2,.... 这些是类别：

(man1) 1 - 用户可用的命令
(man2) 2 - Unix 和 C 系统调用
(man3) 3 - C 程序的 C 库例程
(man4) 4 - 特殊文件名
(man5) 5 - Unix
使用的文件的文件格式和约定 (man6) 6 - 游戏
(man7) 7 - 文字处理包
(man8) 8 - 系统管理命令和程序

此处的示例目的地为 man1，因此：

5- 回到 usr/bin

$ cd /usr/bin

6- 制作一份带有 good 后缀的副本：

$ cp your_function your_function.1

7- gzip your_function.1

$ gzip your_function.1

8-发送到good目录下，这里以man1为例：

$ cp your_function.1.gz /usr/share/man/man1/

大功告成，你可以测试你漂亮的手册页了！

 $ man your_function

如何为我的 shell 脚本制作手册页？

How to make a man page for my shell script?

unix

linux

bash

shell

manpage