-
Notifications
You must be signed in to change notification settings - Fork 4
/
125.texi
173 lines (132 loc) · 5 KB
/
125.texi
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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
\input texinfo @c -*=texinfo-*-
@c %**start of header
@setfilename tip.info
@settitle TexInfo primer
@c %**end of header
@titlepage
@title Texinfo Primer
@subtitle How to get started in Texinfo
@author Peter Teuben
@vskip 0pt plus 1fill
Copyright @copyright{} 1992 Moi Le Roi
Published by AIPS++
@end titlepage
@ifinfo
@node Top, intro, (dir), (dir)
@top Texinfo Primer
The menu below selects for the online browsers. This text will
not be visible in the printed version of this document. It has
been compiled on @today{}.
@end ifinfo
@menu
* intro:: Introduction
* more:: More on info
* finally:: and Finally...
@end menu
@node intro, more, Top, Top
@chapter Intro
This document introduces you to the hypertext-like texinfo info system
that can be found within the GNU system. Being meant for texinfo
writers the printed form of this document, although readable, is also
to be used next to the electronic form in order to see how texinfo
is converted to a more a human readable format.
@menu
* tex basics:: TeX basics
* info basics:: Info basics
@end menu
@node tex basics, info basics, intro, intro
@section TeX Basics
Texinfo is a markup language, much like, and actually based on @TeX{} (the
first line in a texinfo file is @code{\input texinfo}). An immediate
visual difference is that the backslash (@code{\}), that @TeX{} uses to
signify commands, has been replaced with the at (@code{@@}) symbol. For
TeX users texinfo is hence nothing more than a (simple) TeX macro
package. The text you are reading now originates from a file
@file{tip.texi}@footnote{@code{tip} is short for TexInfo Primer...},
where @code{texi} is a frequently used extension name, though @code{tex}
would perhaps be more convenient since the @code{tex} program will be
run on this file:
@example
% tex tip.texi
@end example
@noindent
creates a @code{tip.dvi} file that can be previewed or printed:
@example
% xdvi tip # preview; or something like that
% dvips tip.dvi ; lpr tip.ps # convert and print; ...
@end example
@node info basics, , tex basics, intro
@section Info Basics
A texinfo file can also be converted to an info file:
@example
% makeinfo tip.texi
@end example
@noindent
which creates a file called @file{tip.info}.
This info file is a hypertext file, and to view
it as such you need smart readers. There are various
programs available to do this:
@itemize @bullet
@item
info: a simple ASCII-oriented (works on your plain vanilla VT100)
browser. Your terminal will be put in ``raw'' mode, such that
single character keystrokes become commands to browse around.
To test your local info file:
@example
% info -f tip.info
@end example
@item
xinfo: X-windows based version of the ASCII info reader. It also
understands the single character commands used in @code{info}
@item
ivinfo: Interviews based version of the ASCII info reader
@item
para: an info reader and writer within the emacs environment
@item
emacs: within emacs there is
@itemize @minus
@item
an info reader: @code{M-x info}
@item
an info writer: @code{M-x texinfo-mode} to switch to texinfo mode
@end itemize
@end itemize
The environment variable INFOPATH is normally used by the info
browsers to find directories with info files.
@node more, finally, intro, Top
@chapter More on info
The essential difference between a texinfo file and a classical
tex-based manual is it's hypertext feature. They are implemented as
nodes in the text, such that readers can jump to these locations in an
organized manner. Nodes are typically structured in an hierarchical
way, often following the manual-chapter-section-subsection tree
structure. It is however up to the author to define this structure: a
node is defined with a unique name, and will also need to know what it's
'previous', 'next' and 'up' nodes are. Obviously the printed manual
will not show any of this hypertext structure, since it is a simple
linear chain of text. All of the online info readers described earlier
(@xref{info basics}) allow the user to browse information in this
hypertext way. In texinfo this appears in two forms: menus and cross
references.
@enumerate
@item
A menu typically appears at the top
of a unit (manual/chapter/section/...) to show it's underlying
structure. The user can then linearly browse the material, or select
sub-parts thereof.
@item
A cross-reference may appear at any random point in the text, but must
point to a node anywhere (including other manuals) in your info
system. The user can select to visit that node and quickly
come back to the previous location. This work to a fair degree
of depth.
@end enumerate
@node finally, , more, Top
@chapter Finally
Of course texinfo contains much more the few highlights given here. The
best way to advance is use your favorite browser (I prefer @code{xinfo},
though @code{ivinfo} is not bad either), perhaps find an example
text that is close to what you want, and compose while using the online
info on texinfo itself to get familiar with reading as well as writing
these texinfo files.
@bye