如何写一个texinfo文件
简述
Texinfo是一个文档系统,它使用单一的源文件来产生在线信息和打印输出。这意味着你不需要写几个不同的文件,每个输出格式一个,而只需要写一个文件,然后你可以将你写好的单文件转换为html,pdf等不同格式的文件。
你可以官方介绍文档中学习如何使用它,下面是一个教你如何按格式去写一个texinfo文件,如果需要学习的更多,建议还是直接查看官方文档。
安装和使用工具
在linux上安装texinfo工具
1 | sudo apt-get install texinfo |
通过makeinfo --version
查看安装的版本。
如何写一个texinfo文件
扩展名
texinfo文件支持使用.texi, .texinfo, .taxi, .tex
等几种扩展名。
文件开头和结尾
文件的开头必须包含下面两句:
1 | \input texinfo |
文件需要以@bye
结尾。
指定文档的格式
@documentencoding
enc用来指定文档的格式,例如中文文档指定:@documentencoding UTF-8
查看texinfo支持的格式。
如果需要支持中文文档,先安装中文man手册工具。
1 | sudo apt install manpages-zh |
注释
单行注释@comment
或者@c
注意:不要在@settitle
这种作用于一整行的命令中使用单行注释。
多行注释
将需要多行注释的内容置于@ignore
和@end ignore
之间。
设置输出文件名字
@setfilename info-file-name
如果需要指定输出文件名字,这一行最好写在\input texinfo
之后,作为第一个texinfo命令。
注意,这个名字必须与texinfo文件本身的名字不同。
@setfilename
之前的行不会被写到输出文件中,这也是为什么\inptut texinfo
不会被写入输出文件的原因。
设置标题
@settitle title
任何文档都应该有一个标题,表明自己是谁。通过@settitle title
来设置
设置文档权限
@copying
@end copying
如果你需要为文档保留创作权限,就在上面命令中加入权限声明,权限声明应该在文档靠前的位置。
1 | @copying |
@quotation
只是为了在某些情况下提高可读性。
@insertcopying
,这个命令是为了在版权页面中插入@copying
权限声明,而不用每次都去写一遍@copying
。
标题和权限页面
在手册中,手册名称和作者通常被印在标题页上。版权信息通常印在标题页的背面(背面)。这一段必须包含在@titlepage
和@end titlepage
命令之间。
1 | @titlepage |
@page
表示新起一页
@vskip
命令在TeX输出中插入空白;在所有其他输出格式中,它被忽略。0pt plus 1filll “意味着插入零点的强制性空白,以及尽可能多的可选空白,以便将下面的文字推到页面底部。注意’filll’这个词中要使用了三个’i’。
另外,在@titlepage
和@end titlepage
中间可以添加@title @subtitle @author
这些信息,
可以使用
@titlefont
使用该t命令来选择适合标题本身的大字体。如果你有一个特别长的标题,你可以不止一次地使用它。
@center
将该行的文本居中
@sp
插入空白行
等来调整标题格式。
1 | @titlepage |
更多的关于title页面以及权限页面的内容可以查看第2.7章。
生成目录
@chapter @section
和其他的一些结构命令构成了目录信息,但是他们并不能让输出手册中生成一个实际的目录。
需要生成目录,必须使用@contents
或者@summarycontens
命令,输出手册会在该命令处生成目录。
“Top”节点和主菜单
Top节点是读者进入信息手册的节点,它应该包含一个非常简单的描述(包括版本号)。该节点的内容不会出现在输出文件中。
1 | @node Top |
关于top和menu细节参考文档2.9章。
文档主体部分
主体部分包含文件的所有文本。一本手册被分为一个或多个节点(见节点)。这个例子说明了一个由三个节点组成的章节,一个是本章的介绍性材料,还有两个部分。介绍性材料包含一个列举式列表。
1 | @node First Chapter |
结束
texinfo文件结束时候最好包含一个创建引索号的命令,然后以@bye
结尾,例如:
1 | @node Index |
案例
官方案例:点击查看。
用texi2pdf
工具转成pdf文件,点击查看。