惯性聚合 高效追踪和阅读你感兴趣的博客、新闻、科技资讯
阅读原文 在惯性聚合中打开

推荐订阅源

The Last Watchdog
The Last Watchdog
freeCodeCamp Programming Tutorials: Python, JavaScript, Git & More
GbyAI
GbyAI
Y
Y Combinator Blog
CTFtime.org: upcoming CTF events
CTFtime.org: upcoming CTF events
The GitHub Blog
The GitHub Blog
博客园_首页
小众软件
小众软件
I
InfoQ
J
Java Code Geeks
月光博客
月光博客
S
Secure Thoughts
Microsoft Security Blog
Microsoft Security Blog
V
Visual Studio Blog
Hacker News - Newest:
Hacker News - Newest: "LLM"
钛媒体:引领未来商业与生活新知
钛媒体:引领未来商业与生活新知
Stack Overflow Blog
Stack Overflow Blog
cs.CV updates on arXiv.org
cs.CV updates on arXiv.org
N
News and Events Feed by Topic
Exploit-DB.com RSS Feed
Exploit-DB.com RSS Feed
Threat Intelligence Blog | Flashpoint
Threat Intelligence Blog | Flashpoint
The Cloudflare Blog
T
Threat Research - Cisco Blogs
A
About on SuperTechFans
H
Help Net Security
MongoDB | Blog
MongoDB | Blog
博客园 - 聂微东
人人都是产品经理
人人都是产品经理
H
Hackread – Cybersecurity News, Data Breaches, AI and More
Recent Commits to openclaw:main
Recent Commits to openclaw:main
Latest news
Latest news
G
GRAHAM CLULEY
IT之家
IT之家
C
Cisco Blogs
Last Week in AI
Last Week in AI
Engineering at Meta
Engineering at Meta
L
LangChain Blog
The Register - Security
The Register - Security
SecWiki News
SecWiki News
M
MIT News - Artificial intelligence
NISL@THU
NISL@THU
T
Tenable Blog
博客园 - Franky
美团技术团队
I
Intezer
U
Unit 42
雷峰网
雷峰网
cs.AI updates on arXiv.org
cs.AI updates on arXiv.org
S
SegmentFault 最新的问题
C
Cyber Attacks, Cyber Crime and Cyber Security

Roy的个人站

天天在网站上填材料?简单配置,让AI替你操作 | Roy的个人站 只是组件 使用手册 | Roy的个人站 IOS常用URL Scheme整理 | Roy的个人站 Anchor 专业版手册 | Roy的个人站 MacOS在NSImage里提供了哪些系统图标 | Roy的个人站 即刻寻找果果活动技术向剧透收集 | Roy的个人站 借助amis通过json构建前端页面 | Roy的个人站 浅析Pandownload作者可能面临的责任 | Roy的个人站 实现可被链接调用的IOS应用 | Roy的个人站 避免docker挂载时产生root权限文件 | Roy的个人站 一些有关幽默的理论 | Roy的个人站 手绘一个苹果手表的动图表盘 | Roy的个人站 简化scp命令文件上传下载 | Roy的个人站 PPT中使用ECharts实现可拖拽关系图 | Roy的个人站 博客代码框设置换行 | Roy的个人站 畅言更名相关商标权的探究 | Roy的个人站 畅言PC版emoji显示 | Roy的个人站 畅言评论插件优化 | Roy的个人站
用markdown编写man文档 | Roy的个人站
2019-09-09 · via Roy的个人站

晚上有些碎片时间可以用,想着接一接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文档。