晚上有些碎片时间可以用，想着接一接CMPP的man翻译。一直很好奇man文档都是怎么编写出来的，背后是什么格式的文本，于是就接触到了roff格式。这篇文章介绍了三种文件格式，md、roff、富文本，就scpp作为例子展示了从md如何生成man文档并安装。如果你想要生成自己的man文档，或者想要了解这几个文档格式，不妨看一下这篇文章。

准备内容

本文中介绍三种文件格式的区别的时候，转换roff语言与富文本使用到了groff命令，可能需要安装。

在md转化为富文本的时候除了groff命令，还使用到了pandoc命令，可以进行一个安装。

三种文档

以scpp的文档展示一下三种格式的区别。

富文本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
SCPP(1)                                                                SCPP(1)



NNAAMMEE
       scpp - scp plus

SSYYNNOOPPSSIISS
       ssccpppp [ push | pull ] [ scp options ] source target

DDEESSCCRRIIPPTTIIOONN
       ssccpppp  simplifys  file  transformation between two machines by extending
       basic command scp. scpp is a one-line command that added to  your  bash
       profile.   You  need  to  specific username ,server address and options
       before using.

   OOppttiioonnss
       ppuusshh   Push files to remote machine.

       ppuullll   Pull files from remote machine.

       ssoouurrccee Specify the source file.

       ttaarrggeett Specify the target file.

SSEEEE AALLSSOO
       scp

BBUUGGSS
       Please report to minjie_gu@126.com.



                               9 September 2019                        SCPP(1)

根据不同的终端，富文本的显示是通过加入不同的特殊字符达到效果。

由于是放在代码框里面，特殊字符不会被处理成加粗、倾斜等格式，这些在终端中会显示。

下文生成的scpp.1就是包含特殊字符的文档。

终端不同，特殊字符的约定不同。也就是说Windows终端上生成的富文本放到Linux的终端上显示就可能不正常。

由于书写麻烦也不通用，而源文档需要书写简单而且通用，所以有了下面两种格式。

roff格式

roff是gnu默认的标记语言，用纯文本就可以写出有格式的文档，大量我们man命令看到的内容都是用这个格式写成的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
.TH SCPP 1 "9 September 2019"
.SH NAME
scpp \- scp plus
.SH SYNOPSIS
\fBscpp\fP [ push | pull ] [ scp options ] source target
.SH DESCRIPTION
\fBscpp\fP simplifys file transformation between two machines
by extending basic command scp. scpp is a one-line command
that added to your bash profile.  You need to specific
username ,server address and options before using.
.SS Options
.TP
\fBpush\fP
Push files to remote machine.
.TP
\fBpull\fP
Pull files from remote machine.
.TP
\fBsource\fP
Specify the source file.
.TP
\fBtarget\fP
Specify the target file.
.SH "SEE ALSO"
scp
.SH BUGS
Please report to minjie_gu@126.com.

其中例如.TH、\fB\fP等内容让文档可以产生加粗、标题等各种格式。

将这个文件存储为scpp.roff，之后输入这个命令就可以看到显示效果：

1
groff -Tascii -man scpp.roff | more

是不是就看到了目标文档的效果，如果你想看到特殊字符可以把他输出到文件：

1
groff -Tascii -man scpp.roff > scpp.1

roff格式的文件有大量的标记，如果你感兴趣，可以在这里扩展阅读。

md格式

markdown是目前非常常用的标记语言，也是纯文本编写有格式的文档，大量现在的博客都是用这个语言写成的。

相较而言，markdown的标记更少但也更简单，入门方便，也提供图片、表格等的插入。

本文档使用md格式就是这个样子：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
---
title: scpp
section: 1
date: 9 September 2019
---

# NAME
scpp - scp plus

# SYNOPSIS
**scpp** [push|pull] [scp options] source target

# DESCRIPTION
scpp simplifys file transformation between two machines
by extending basic command scp. scpp is a one-line command
that added to your bash profile.  You need to specific
username ,server address and options before using.

## Options

**push**    Push files to remote machine.

**pull**    Pull files from remote machine.

**source**  Specify the source file.

**target**  Specify the target file.

# SEE ALSO
**scp**

# BUGS
Please report to minjie_gu@126.com.

将这个文件存储为scpp.md，之后输入这个命令就可以看到显示效果：

1
pandoc --standalone -f markdown -t man -o scpp_md.roff scpp.md | groff -Tascii -man scpp_md.roff | more

其中--standalone标签是为了给文档生成的独立的文件头。

开头的那些元数据提供了生成roff所需的一些必要内容。

为了让其与所有其他的man文档格式相同，我们先转为roff格式，再通过groff转化为富文本。

安装scpp的man文档

到了这一步，已经了解了三种不同的文件格式，也可以用最熟悉的markdown格式写man文档。

下一步就是将写好的内容进行安装，让帮助文件生效了。

不同的系统有不同的man手册目录，linux是/usr/man，osx是/usr/share/man。

将文件生成在该目录就可以了。

1
groff -Tascii -man scpp.roff > /usr/man/man1/scpp.1

之后使用man scpp就能看到你自己写的man文档。