如何写一个texinfo文件

简述

Texinfo是一个文档系统，它使用单一的源文件来产生在线信息和打印输出。这意味着你不需要写几个不同的文件，每个输出格式一个，而只需要写一个文件，然后你可以将你写好的单文件转换为html，pdf等不同格式的文件。

你可以官方介绍文档中学习如何使用它，下面是一个教你如何按格式去写一个texinfo文件，如果需要学习的更多，建议还是直接查看官方文档。

安装和使用工具

在linux上安装texinfo工具

sudo apt-get install texinfo
sudo apt-get install texlive

通过makeinfo --version查看安装的版本。

如何写一个texinfo文件

扩展名

texinfo文件支持使用.texi, .texinfo, .taxi, .tex等几种扩展名。

文件开头和结尾

文件的开头必须包含下面两句：

\input texinfo
@settitle name-of-manual

文件需要以@bye结尾。

指定文档的格式

@documentencoding enc用来指定文档的格式，例如中文文档指定：@documentencoding UTF-8

查看texinfo支持的格式。

如果需要支持中文文档，先安装中文man手册工具。

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
如果你需要为文档保留创作权限，就在上面命令中加入权限声明，权限声明应该在文档靠前的位置。

@copying
This is a short example of a complete Texinfo file, version 1.0.

Copyright @copyright{} 2016 Free Software Foundation, Inc.
@quotation
Permission is granted to …
@end quotation
@end copying

@quotation只是为了在某些情况下提高可读性。

@insertcopying,这个命令是为了在版权页面中插入@copying权限声明，而不用每次都去写一遍@copying。

标题和权限页面

在手册中，手册名称和作者通常被印在标题页上。版权信息通常印在标题页的背面（背面）。这一段必须包含在@titlepage和@end titlepage命令之间。

@titlepage
@title Sample Title

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@page表示新起一页

@vskip命令在TeX输出中插入空白；在所有其他输出格式中，它被忽略。0pt plus 1filll “意味着插入零点的强制性空白，以及尽可能多的可选空白，以便将下面的文字推到页面底部。注意’filll’这个词中要使用了三个’i’。

另外，在@titlepage和@end titlepage中间可以添加@title @subtitle @author这些信息，

可以使用

@titlefont 使用该t命令来选择适合标题本身的大字体。如果你有一个特别长的标题，你可以不止一次地使用它。

@center 将该行的文本居中

@sp 插入空白行

等来调整标题格式。

@titlepage
@sp 10
@center @titlefont{name-of-manual-when-printed}
@sp 2
@center subtitle-if-any
@sp 2
@center author
…
@end titlepage

更多的关于title页面以及权限页面的内容可以查看第2.7章。

生成目录

@chapter @section和其他的一些结构命令构成了目录信息，但是他们并不能让输出手册中生成一个实际的目录。
需要生成目录，必须使用@contents 或者@summarycontens命令，输出手册会在该命令处生成目录。

“Top”节点和主菜单

Top节点是读者进入信息手册的节点，它应该包含一个非常简单的描述（包括版本号）。该节点的内容不会出现在输出文件中。

@node Top
@top Short Sample

This is a short sample Texinfo file.
(version @value{VERSION}, @VALUE{UPDATED})
@menu
* First Chapter::    The first chapter is the
                       only chapter in this sample.
* Index::            Complete index.
@end menu

关于top和menu细节参考文档2.9章。

文档主体部分

主体部分包含文件的所有文本。一本手册被分为一个或多个节点（见节点）。这个例子说明了一个由三个节点组成的章节，一个是本章的介绍性材料，还有两个部分。介绍性材料包含一个列举式列表。

@node First Chapter
@chapter First Chapter

@cindex chapter, first
This is the first chapter.
@cindex index entry, another

Here is a numbered list.

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate


@node First Section
@section First Section

First section of first chapter.


@node Second Section
@section Second Section

Second section of first chapter.

结束

texinfo文件结束时候最好包含一个创建引索号的命令，然后以@bye结尾，例如：

@node Index
@unnumbered Index

@printindex Index

@bye  

案例

官方案例：点击查看。

用texi2pdf工具转成pdf文件，点击查看。