summaryrefslogtreecommitdiff
path: root/info/texinfo-3
blob: 8941531ca2b566e3445a025a032a38ea2334301e (plain)
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
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
Info file ../info/texinfo, produced by Makeinfo, -*- Text -*- from
input file texinfo.texinfo.

This file documents Texinfo, a documentation system that uses a
single source file to produce both on-line help and a printed manual.

This is edition 1.1 of the Texinfo documentation, and is for the
Texinfo that is distributed as part of Version 18 of GNU Emacs.

Copyright (C) 1988 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.



File: texinfo,  Node: Breaks Blank-Lines Groups,  Prev: Refilling & Noindent,  Up: Formatting Paragraphs

Breaks, Blank Lines and Groups
==============================

Texinfo has several commands for making blank lines, for forcing
paragraph and page breaks in the printed manual and for preventing
text from running from one page to the next.

`@*'
     Force a line break in the printed manual.  This command has no
     effect on the Info file.

`@sp'
     Generate blank lines in both the printed manual and in the Info
     file.

`@br'
     Force a paragraph break in the printed manual.  This command has
     no effect on the Info file.

`@w'
     Prevent text from being split across two lines in the printed
     manual.  This command has no effect on the Info file.

`@page'
     Start a new page in the printed manual.  This command has no
     effect on the Info file.

`@group'
     Hold text together that must appear on one printed page.  This
     command has no effect on the Info file.

`@need'
     Start a new printed page if required space not on this one. 
     This command has no effect on the Info file.

* Menu:

* Line Breaks:: Force a line break in the printed manual.
* Sp::		Generate blank lines.
* Br::		Force a paragraph break in the printed manual.
* W::		Prevent a paragraph break in the printed manual.
* Page::	Start a new page in the printed manual.
* Group::	Hold text together that must appear on one printed page.
* Need::	Start a new printed page if required space not on this one.

 

File: texinfo,  Node: Line Breaks,  Next: Sp,  Prev: Breaks Blank-Lines Groups,  Up: Breaks Blank-Lines Groups

@*
--

`@*' forces a line break in the printed manual.  It has no effect on
the Info file output, where line breaks follow those in the source
file.  If you want a line break at a certain spot in both forms of
output, break the line there in the source file and put `@*' at the
end of the line.



File: texinfo,  Node: Sp,  Next: Br,  Prev: Line Breaks,  Up: Breaks Blank-Lines Groups

@sp
---

A line containing `@sp N' generates N blank lines of space in either
the printed manual or the Info file.  For example,

     @sp 2

generates two blank lines.



File: texinfo,  Node: Br,  Next: W,  Prev: Sp,  Up: Breaks Blank-Lines Groups

@br
---

In a printed manual, a line containing `@br' forces a paragraph
break; in the Info file output, it does nothing (not even a blank
line results from it).



File: texinfo,  Node: W,  Next: Page,  Prev: Br,  Up: Breaks Blank-Lines Groups

@w
--

In a printed manual, `@w{TEXT}' outputs TEXT and prohibits line
breaks within TEXT.  `@w' has no effect on the Info file output; it
is the same as would result from just TEXT.



File: texinfo,  Node: Page,  Next: Group,  Prev: W,  Up: Breaks Blank-Lines Groups

@page
-----

A line containing `@page' starts a new page in a printed manual.  The
line has no effect on Info files since they are not paginated.



File: texinfo,  Node: Group,  Next: Need,  Prev: Page,  Up: Breaks Blank-Lines Groups

@group
------

A line containing `@group' begins an unsplittable vertical group,
which must appear entirely on one page.  The group is terminated by a
line containing `@end group'.  These two lines produce no output of
their own, and in the Info file output they have no effect at all.

If you forget to end a group, you may get strange and unfathomable
error messages when you run TeX.  This is because TeX keeps trying to
put the rest of the Texinfo file into the group and error messages do
not start to get generated until TeX has gone a long way.  It's a
good rule of thumb to look for a missing `@end group' if you get
incomprehensible error messages in TeX.



File: texinfo,  Node: Need,  Prev: Group,  Up: Breaks Blank-Lines Groups

@need
-----

A line containing `@need N' starts a new page in a printed manual if
fewer than N mils (thousandths of an inch) remain on the current
page.  The line has no effect on Info files since they are not
paginated.



File: texinfo,  Node: Marking Text,  Next: Conditionals,  Prev: Formatting Paragraphs,  Up: Top

Marking Text Within a Paragraph
*******************************

In Texinfo, text within a paragraph can be marked in a variety of ways.
The most important way is to specify whether a word or phrase is a
definition, a metasyntactic variable, a literal example of a program
or what not.

In addition, there are special commands for inserting single
characters  that have special meaning in Texinfo, such as braces, and
for inserting symbols with special handling, such as dots and
bullets.  Finally, there are ways to emphasize words.

* Menu:

* Specifying::			Specifying commands, files and so on.
* Braces Atsigns Periods::	Inserting braces, `@' and periods.
* Dots Bullets Tex::		Inserting dots, bullets and the TeX logo
* Emphasis::			Emphasizing text.

 

File: texinfo,  Node: Specifying,  Next: Braces Atsigns Periods,  Up: Marking Text

Specifying Definitions, Files, Commands etc.
============================================

Texinfo has a variety of commands for specifying just what kind of
object a piece of text refers to.  Metasyntactic variables, for
example, are marked by one @-command and code by another.  Texinfo
uses this information to determine how to highlight the text.  Since
the pieces of text are labelled by commands that tell what kind of
object they are, it is easy to change the way Texinfo formats and
typesets such text.  For example, code is usually illustrated in a
typewriter font, but it would be easy to change the way Texinfo
highlights code to use another font.  This change would not effect
how metasyntatic variables are highlighted.  If straight typesetting
commands were used in the body of the file, you would have to check
every single occurrence to make sure that you were changing code and
not something else that should not be changed.

In addition, the commands can be used to generate useful information
from the file, such as lists of functions or file names.  It is
possible, for example, to write code in Emacs Lisp (or a keyboard
macro) to insert an index entry after every paragraph that contains
the text labelled by a specified command.  You could do this to
construct an index of functions if you had not already made the
entries.

The commands serve a variety of purposes:

`@code'
     Indicates text that is a literal example of a piece of a program.

`@samp'
     Indicates text that is a literal example of a sequence of
     characters.

`@file'
     Indicates the name of a file.

`@kbd'
     Indicates the names of keys on the keyboard or characters you
     type.

`@key'
     Used for the conventional name for a key on a keyboard.

`@ctrl'
     Indicates an ASCII control character.

`@var'
     Indicates a metasyntactic variable.

`@dfn'
     Indicates the introductory or defining use of a term.

`@cite'
     Indicates the name of a book.

* Menu:

* Code::	A literal example of a piece of a program.
* Samp::	A literal example of a sequence of characters.
* File::	The name of a file.
* Kbd::		The names of keys or else characters you type.
* Key::		The conventional name for a key on a keyboard.
* Ctrl::	Indicates the ASCII control character.
* Var::		A variable.
* Dfn::		The introductory or defining use of a term.
* Cite::	The name of a book.

 

File: texinfo,  Node: Code,  Next: Samp,  Up: Specifying

@code
-----

`@code' is used to indicate text that is a piece of a program which
consists of entire syntactic tokens.  The text follows, enclosed in
braces.

For example, `@code' is used for an expression in a program, the name
of a variable or function used in a program, or a keyword.  `@code'
is not used for a piece of a token, such as when speaking about the
characters used in a token; for example, when you are explaining what
letters or printable symbols can be used in the names of functions. 
It is also not used for input to programs unless the input is written
in a language that is like a programming language.  For example, it
is not used for the single character commands of GNU Emacs although
it is used for the names of Emacs Lisp functions that the keyboard
commands invoke.

You should also `@code' for command names in command languages that
resemble programming languages, such as Texinfo or the shell.  Note,
however, that `@code' is not used for options such as `-c' when such
options stand alone.  There is some argument as to whether an entire
shell command incorporating an option should be written using `@code'
or `@samp'.

It is an error to alter the case of a word inside an `@code' command.
This is a particularly insidious error if the language being
documented is case sensitive.  If the command is `printf', then
`Printf' is a misspelling.  If you do not like having such a command
with lower case at the beginning of a sentence, you may wish to
rearrange the sentence.

In the printed manual, `@code' puts the argument in bold face.  In
the Info file, it uses `...' quotation.  For example:

     To compare two files, showing text inserted or removed, use @code{diff}.

 produces

     To compare two files, showing text inserted or removed, use
     `diff'.



File: texinfo,  Node: Samp,  Next: File,  Prev: Code,  Up: Specifying

@samp
-----

`@samp' is used to indicate text that is a literal example of a
sequence of characters in a file, string, pattern, etc.  The text
follows, enclosed in braces.  The argument appears within `...'
quotation in both the Info file and the printed manual; in addition,
it is printed in a fixed-width font.

     To match @samp{foo} at the end of the line, use the regexp @samp{foo$}.

 produces

     To match `foo' at the end of the line, use the regexp `foo$'.

Any time you are referring to single characters, you should use
`@samp' unless `@kbd' is more appropriate.  Basically, `@samp' is a
catchall for whatever is not covered by `@code', `@file', `@kbd'.

Punctuation marks that are part of the English text that surrounds
the strings you are specifying are *never* included within the
braces.  In the following sentence, for example, the commas and
period are outside of the braces:

     A symbol name ends in @samp{a}, @samp{b}, or @samp{c}.

 

File: texinfo,  Node: File,  Next: Kbd,  Prev: Samp,  Up: Specifying

@file
-----

`@file' is used to indicate text that is the name of a file or
directory.  Currently, it is equivalent to `@samp' in its effects on
the output.  For example,

     The @file{.el} files are in 
     the @file{/gnu/emacs/lisp} directory.

 produces

     The `.el' files are in  the `/gnu/emacs/lisp' directory.



File: texinfo,  Node: Kbd,  Next: Key,  Prev: File,  Up: Specifying

@kbd
----

`@kbd' is used much like `@code'.  The difference is that `@kbd' is
for names of keys on the keyboard, or of characters you can type. 
For example, to refer to the command `M-a', you would use

     @kbd{M-a}

and to refer to `M-x shell', you would use

     @kbd{M-x shell}

The `@kbd' command has the same effect as `@code' in Info, but may
produce a different font in a printed manual.

You can embed another @-command inside the braces of a `@kbd'
command.  This is the way to describe a command that would be
described more verbosely as "press an `r' and then press the RET key":

     @kbd{r @key{RET}}

This produces: `r RET'

You also use the `@kbd' command if you are spelling out the letters
you type; for example:

     To give the @code{logout} command, 
     type the characters @kbd{l o g o u t @key{RET}}.

 This produces

     To give the `logout' command,  type the characters `l o g o u t
     RET'.



File: texinfo,  Node: Key,  Next: Ctrl,  Prev: Kbd,  Up: Specifying

@key
----

`@key' is used for the conventional name for a key on a keyboard, as in

     @key{RET}

Often, `@key' is used within the argument of a `@kbd' command,
whenever the sequence of characters to be typed includes one or more
keys that are described by name.

For example, to produce `C-x ESC' you would use

     @kbd{C-x @key{ESC}}

The recommended names to use for keys are in upper case and are

SPC
     Space.

RET
     Return.

LFD
     Linefeed.

TAB
     Tab.

BS
     Backspace.

ESC
     Escape.

DEL
     Delete.

SFT
     Shift.

CTL
     Control.

META
     Meta.

There are subtleties to handling words like `meta' or `ctrl' which
are names of shift keys.  When mentioning a character in which the
shift key is used, such as `Meta-a', use the `@kbd' command alone
without the `@key' command, but when you are referring to shift key
in isolation, use the `@key' command.  For example, you would use
`@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce META.



File: texinfo,  Node: Ctrl,  Next: Var,  Prev: Key,  Up: Specifying

@ctrl
-----

`@ctrl' is used to describe an ASCII control character.  The pattern
of usage is `@ctrl{CH}', where CH is an ASCII character whose
control-equivalent is wanted.  Thus, you put in an `f' when you want
to indicate a `control-f'

Thus, to specify `control-f', you would enter

     @ctrl{f}

which produces

     f

In the Info file, this generates the specified control character,
output literally into the file.  This is done so a user can copy the
specified control character (along with whatever else he or she
wants) into another Emacs buffer and use it.  Since the
`control-h',`control-i', and `control-j' characters are formatting
characters, they should not be indicated this way.

In a printed manual, this generates text to describe or identify that
control character: an uparrow followed by the character CH.



File: texinfo,  Node: Var,  Next: Dfn,  Prev: Ctrl,  Up: Specifying

@var
----

`@var' is used to indicate metasyntactic variables.  A metasyntactic
variable is something that stands for another piece of text.  You
would use a metasyntactic variable in the documentation of a function
to describe the arguments that are passed to that function.

`@var' is not used for names of particular variables in programming
languages.  For example, the Texinfo variable `texinfo-tex-command'
is not a metasyntactic variable.

Its effect in the Info file is to upcase the argument; in the printed
manual, to italicize it.  Example:

     To delete file @var{filename}, type @code{rm @var{filename}}.

 produces

     To delete file FILENAME, type `rm FILENAME'.

In some documentation styles, metasyntactic variables are shown with
angle brackets, for example:

     ..., type rm <filename>



File: texinfo,  Node: Dfn,  Next: Cite,  Prev: Var,  Up: Specifying

@dfn
----

`@dfn' is used to identify the introductory or defining use of a
technical term.  The command should be used only in a passage whose
purpose is to introduce a term which will be used again or which the
reader ought to know.  Mere passing mention of a term for the first
time doesn't deserve `@dfn'.  It generates italics in the printed
manual, and double quotation marks in the Info file.  Example:

     Getting rid of a file is called @dfn{deleting} it.

 produces

     Getting rid of a file is called "deleting" it.



File: texinfo,  Node: Cite,  Prev: Dfn,  Up: Specifying

@cite
-----

`@cite' is used for the name of a book.  It produces italics in the
printed manual, and quotation marks in the Info file.



File: texinfo,  Node: Braces Atsigns Periods,  Next: Dots Bullets Tex,  Prev: Specifying,  Up: Marking Text

Inserting Braces, `@' and Periods
=================================

`@' and curly braces are special characters in Texinfo.  This means
that you have to put an `@' in front of these characters in order to
insert them into text.

Periods are also special.  Depending on whether the period is inside
of or at the end of a sentence, less or more space is inserted after
a period in a typeset manual.  Since it is not always possible for
Texinfo to determine when a period ends a sentence and when it is
used in an abbreviation, special commands are needed.  (Usually,
Texinfo figures out how to handle periods, so you don't have to use
the special commands; you just enter a period as you would if you
were using a typewriter, which means you put two spaces after the
period that ends a sentence and after a colon.)

* Menu:

* Inserting an Atsign::		inserting an atsign.
* Insert Left Brace::		Inserting a left brace.
* Insert Colon::		Preventing unintended additional whitespace.
* Insert Period:: 		Inserting a period that does end a sentence.

 

File: texinfo,  Node: Inserting An Atsign,  Next: Insert Left Brace,  Up: Braces Atsigns Periods

@@
--

`@@' stands for a single @ in either printed or Info output.



File: texinfo,  Node: Insert Left Brace,  Next: Insert Colon,  Prev: Inserting an Atsign,  Up: Braces Atsigns Periods

@{
--

`@{' stands for a single { in either printed or Info output.

@}
--

`@}' stands for a single } in either printed or Info output.



File: texinfo,  Node: Insert Colon,  Next: Insert Period,  Prev: Insert Left Brace,  Up: Braces Atsigns Periods

@:
--

`@:' is used after a character such as period or colon which normally
causes TeX to increase the width of the following whitespace, to
suppress that effect.  For example, it can be used after periods that
end abbreviations and do not end sentences.  `@:' has no effect on
the Info file output.

     It displays @code{Foo:}@: at that time.

 produces

     It displays `Foo:' at that time.

The meanings of `@:' and `@.' in Texinfo are designed to work well
with the Emacs sentence motion commands.  This means they are
different from their meanings in some other formatting systems that
use @-commands.



File: texinfo,  Node: Insert Period,  Prev: Insert Colon,  Up: Braces Atsigns Periods

@.
--

`@.' stands for a period that really does end a sentence, useful when
TeX would otherwise assume by its heuristics that that is not so. 
This happens when there is a single-capital-letter word at the end of
a sentence: TeX normally guesses that it is an abbreviation.

In the Info file output, `@.' is equivalent to a simple `.'.  The
Texinfo program preserves the amount of space that you use, so put
two spaces after a period if you intend it to be the end of a
sentence (as well as using `@.', if necessary, for the printed
manual's sake).

     Give it to X. Give it to X@.  Give it to X@.

 produces

     Give it to X. Give it to X.  Give it to X.



File: texinfo,  Node: Dots Bullets Tex,  Next: Emphasis,  Prev: Braces Atsigns Periods,  Up: Marking Text

Inserting Dots, Bullets and TeX
===============================

An ellipsis, a line of dots, is typeset differently than a string of
periods; more whitespace is put between the dots in the ellipsis than
is put between the periods.  Because of this, a special command is
used in Texinfo for inserting dots.  Also, the trademark, TeX, is
typeset in a special fashion and it needs an @-command, as does the
command for inserting the copyright symbol.  The `@bullet' command is
special, too.  Each of these commands is followed by a pair of
braces, `{}', without any whitespace between the name of the command
and the braces.

* Menu:

* Dots::		Inserting dots.
* Bullet::		Inserting bullets.
* Tex::			Inserting the TeX trademark.

 

File: texinfo,  Node: Dots,  Next: Bullet,  Up: Dots Bullets Tex

@dots{}
-------

`@dots{}' generates an ellipsis which is three dots in a row,
appropriately spaced, like this: `...'.  Do not simply write three
periods in the input file; that would work for the Info file output,
but would produce the wrong amount of space between the periods in
the printed manual.



File: texinfo,  Node: Bullet,  Next: Tex,  Prev: Dots,  Up: Dots Bullets Tex

@bullet{}
---------

`@bullet{}' generates a large round dot, or the closest possible
thing to one.

Here is a bullet: *



File: texinfo,  Node: Tex,  Prev: Bullet,  Up: Dots Bullets Tex

@TeX{}
------

`@TeX{}' generates `TeX'.  In a printed manual, this is a special
logo that is different from three ordinary letters.



File: texinfo,  Node: Emphasis,  Prev: Dots Bullets Tex,  Up: Marking Text

Emphasizing Text
================

Usually, Texinfo changes the font automatically to mark words in the
text according to what category the words belong to.  The `@code'
command, for example, does this.  Most often, this is the best way to
mark specified words.  However, sometimes you will want to emphasize
text directly.  Texinfo has two ways to do this: commands that tell
Texinfo to emphasize the text but leave the method to the program,
and commands that specify the font to use.  The first method is
generally the best and it makes it possible to change the style of a
document without have to re-edit it line by line.

* Menu:

* Emph and Strong::	Emphasizing text.
* Fonts::		Selecting italic, bold or typewriter fonts.

 

File: texinfo,  Node: Emph and Strong,  Next: Fonts,  Up: Emphasis

@emph and @strong
-----------------

`@emph' and `@strong' are two forms of emphasis.  `@strong' is
stronger.

In printed output, `@emph' produces *italics* and `@strong' produces
*bold*.

In the Info file, both of these commands put asterisks around the
argument.



File: texinfo,  Node: Fonts,  Prev: Emph and Strong,  Up: Emphasis

@i,  @b and @t
--------------

These three commands specify font changes in the printed manual and
have no effect in the Info file.  `@i' requests italic font (in some
versions of TeX, a slanted font is used), `@b' requests bold face,
and `@t' requests the fixed-width font used by `@kbd'.  All three
commands apply to an argument that follows, surrounded by braces.

If possible, you should avoid using these three commands.  If you
find a need to use one, it probably indicates a lack in the Texinfo
language.



File: texinfo,  Node: Conditionals,  Next: Printing Hardcopy,  Prev: Marking Text,  Up: Top

Conditionals
************

You may not always be able to use the same text for both the printed
manual and the on-line Info file.  In this case, you can use the
conditional commands to specify which text is for the printed manual
and which is for the Info file.

`@ifinfo' begins text that should be ignored by TeX when it typesets
the printed manual.  The text appears only in the Info file.  The
`@ifinfo' command should appear on a line by itself.  End the
info-only text with a line containing `@end ifinfo' by itself.  At
the beginning of a Texinfo file, the Info permissions are contained
within a region marked by `@ifinfo' and `@end ifinfo'.

Likewise, `@iftex' and `@end iftex' lines delimit text that will not
appear in the Info file but will appear in the printed manual.

For example,

     @iftex
     This text will appear only in the printed manual.
     @end iftex
     
     
     @ifinfo
     However, this text will appear only in the info manual.
     @end ifinfo

The preceding example produces the following.  Note how you only see
one of the two lines, depending on whether you are reading the
on-line Info version or the printed version of this manual.

However, this text will appear only in the info manual.

The `@titlepage' command is a special variant of `@iftex' that is
used for making the title and copyright pages of the printed manual.

* Menu:

* Using Tex Commands::		Using commands from regular TeX.

 

File: texinfo,  Node: Using Tex Commands,  Prev: Conditionals,  Up: Conditionals

Using TeX Commands
==================

Inside a region delineated by `@iftex' and `@end iftex', you can
embed ordinary TeX commands.  Info will ignore these commands since
they are only in that part of the file that is seen by TeX.  The TeX
commands are the same as any TeX commands except that an `@' replaces
the `\' used by TeX.  For example, in the `@titlepage' section of a
Texinfo file, the TeX command `@vskip' is used to format the
copyright page.

You can enter TeX completely, and use `\' in the TeX commands by
delineating a region with the `@tex' and `@end tex' commands.  (These
commands automatically put the region inside of `@iftex' and `@end
iftex' commands.)  For example,

     @tex
     Here you would put text with TeX commands;
     such as $\bigl(x\in A(n)\bigm|x\in B(n)\bigr)$
     that will appear only  in the printed manual.
     @end tex

In the Info file, nothing between `@tex' and `@end tex' will appear.



File: texinfo,  Node: Printing Hardcopy,  Next: Creating an Info File,  Prev: Conditionals,  Up: Top

Printing Hardcopy
*****************

There are three shell commands for printing a hardcopy of a Texinfo
file.  One is for formatting the file, the second is for sorting the
index and the third is for printing the formatted document.  When you
use the shell commands, you can either work directly in the operating
system shell or work within a shell inside of GNU Emacs.

The typesetting program TeX is used for formatting a Texinfo file. 
TeX is a very powerful typesetting program and, if used right, does
an exceptionally good job.  The @-commands in a Texinfo file are
translated by a file called `texinfo.tex' into commands that TeX
understands.  (That is why the beginning of every Texinfo file starts
with the line that says `\input texinfo'; this command tells TeX to
use the `texinfo.tex' file in processing the Texinfo file. 
Customarily, `texinfo.tex' is in a directory called
`/usr/lib/tex/macros'.) `texinfo-format-buffer' reads the very same
@-commands in the Texinfo file and processes them differently from
TeX to make an Info file.

Usually, the TeX formatting command is the shell command `tex'
followed by the name of the Texinfo file.  The TeX command produces a
formatted DVI file as well as several auxiliary files containing
indices, cross references, etc.  The DVI file (for "DeVice
Independent" file) can be printed on a wide variety of printers.

The TeX formatting command itself does not sort the indices.  This is
a misfeature of TeX.  Hence, to generate a printed index, you first
need a sorted index to work from.

TeX outputs raw, unsorted index files under names that obey a
standard convention.  These names are the name of your main input
file to TeX, with everything after the first period thrown away, and
the two letter names of indices added at the end.  For example, the
raw index output files for the input file `foo.texinfo' would be
`foo.cp', `foo.vr', `foo.fn', `foo.tp', `foo.pg' and `foo.ky'.  Those
are exactly the arguments to give to `texindex'.  Or else, you can
use `??' as "wild-cards" and give the command in this form:

     texindex foo.??

 For each file specified, `texindex' generates a sorted index file
whose name is made by appending `s' to the input file name.  The
`@printindex' command knows to look for a file of that name. 
`texindex' does not alter the raw index output file. After you have
sorted the indices, you need to rerun the TeX command on the Texinfo
file.  This regenerates a formatted DVI file with the index entries
in the correct order.

To summarize, this is a three step process:

  1. Run the TeX command on the Texinfo file.  This generates the
     formatted DVI file as well as the raw index files with two
     letter extensions.

  2. Run the shell command `texindex' on the raw index files to sort
     them.  The arguments to `texindex' are the names of the raw
     index files.  `texindex' creates sorted index files whose names
     are the names of the raw index files with an `s' appended.  To
     cause `texindex' to sort all the raw index files, append `??' to
     the Texinfo file name in place of the `.texinfo' extension.

  3. Rerun the TeX command on the Texinfo file.  This regenerates a
     formatted DVI file with the index entries in the correct order. 
     This second run also makes all the cross references correct as
     well.  (The tables of contents are always correct.)

You need not run `texindex' after each TeX run.  If you don't, the
next TeX run will use whatever sorted index files happen to exist
from the previous use of `texindex'.  This is usually ok while you
are debugging.

Finally, the document can be printed out with the DVI print command
(a shell command).  Depending on the system used, the DVI print
command will be a command such as `lpr -d'.  The DVI print command
may require a file name without any extension or with a `.dvi'
extension.

The following commands, for example, sort the indices, format and
print the ``Bison Manual'' (where `%' is the shell prompt):

     % tex bison.texinfo
     % texindex bison.??
     % tex bison.texinfo
     % lpr -d bison.dvi

(Remember that the words for the shell commands may be different at
your site; but these are commonly used versions.)

It is often most convenient to give formatting and printing commands
from a shell within GNU Emacs.  This way, you can easily keep track
of errors.  To create a shell within Emacs, type `M-x shell'.  In
this shell, you can format and print the document.  You can switch to
and from this shell while it is running and do other things.  If you
are formatting a very long document on a slow machine, this can be
very convenient; on a VAX 750, for example, formatting often takes 8
seconds or more per page depending on how loaded the computer is. 
Faster machines take correspondingly less time.

* Menu:

* Requirements::	Formatting requirements.
* Compile-Command::	Formatting with the compile command.

 

File: texinfo,  Node: Requirements,  Next: Compile-Command,  Up: Printing Hardcopy

Formatting Requirements
=======================

Every Texinfo file that is to be input to TeX must begin with a line
that looks like

     \input texinfo   @c -*-texinfo-*-

This serves two functions.

  1. When the file is processed by TeX, it loads the macros needed
     for processing a Texinfo file.

  2. When the file is edited in Emacs, it causes Texinfo mode to be
     used.

Every Texinfo file must end with a line saying

     @bye

which terminates TeX processing and forces out unfinished pages.

You also have to include two lines that specify the Info file name
and the title of the printed manual:

     @setfilename NAME-OF-TEXINFO-FILE
     @settitle NAME OF MANUAL

You might also want to include a line saying

     @setchapternewpage odd

to cause each chapter to start on a fresh odd-numbered page.

By default, TeX typesets pages for printing in an 8.5 by 11 inch
format.  However, you can direct TeX to typeset a document in a 7 by
9.25 inch format that is suitable for bound books by inserting the
following command on a line by itself at the beginning of the Texinfo
file, before the `@setchapternewpage' command:

     @smallbook

The Free Software Foundation distributes printed copies of the ``GNU
Emacs Manual'' in this size.

Finally, TeX sometimes is unable to typeset a line without extending
it into the right margin.  This can occur when TeX comes upon what it
interprets as a long word that it cannot hyphenate, like a net
address, or a very long title.  When this happens, TeX prints an
error message like this:

     Overfull \hbox (20.76302pt too wide)

and gives the line number along with the text of the offending line
marked at all the places that TeX knows to hyphenate words.  (In TeX
lines are in `horizontal boxes', hence the term, `hbox'.)

If the Texinfo file has an overfull hbox, you can rewrite the
sentence so the overfull hbox does not occur or you can decide to
leave it.  A small excursion into the right margin often does not
matter and may not even be noticable.  However, unless told
otherwise, TeX will print a large, ugly, black rectangle beside every
line that is overfull.  This is so you will notice the location of
the problem if you are correcting a draft.  To prevent such
monstrosities from marring your final printout, put the following in
the beginning of the Texinfo file on lines of their own, before the
`@setchapternewpage' command:

     @iftex
     @finalout
     @end iftex

*Note Titlepage::, for information about creating a title page. 
*Note Contents::, for information about creating a table of contents.



File: texinfo,  Node: Compile-Command,  Prev: Requirements,  Up: Printing Hardcopy

Using Local Variables and the Compile Command
=============================================

Another way to give the TeX formatting command to Texinfo is to put
that command in a "local variables list" at the end of the Texinfo
file.  You can then specify the TeX formatting command as a
`compile-command' and have Emacs run the TeX formatting command by
giving the command `M-x compile'.  This creates a special shell
called the `*compilation buffer*'.  For example, at the end of the
`gdb.texinfo' file, after the `@bye', you would put the following:

     @c Local Variables:
     @c compile-command: "tex gdb.texinfo"
     @c End:

This technique is most often used by programmers who compile programs
this way.



File: texinfo,  Node: Creating an Info File,  Next: Catching Mistakes,  Prev: Printing Hardcopy,  Up: Top

Creating an On-line Info file
*****************************

In GNU Emacs, using Texinfo mode, you can see what part or all of a
Texinfo file will look like in Info by using the keyboard command
`C-c C-f' (`texinfo-format-region').  This formats a region and
displays in a temporary buffer called `*Info Region*'; however, this
command does not turn on Info reading program--it just displays what
the region will look like.  The `texinfo-format-region' command is
described more extensively in the chapter on using Texinfo mode. 
*Note Info on a Region::.

In GNU Emacs, the way to create a working Info file is to visit the
file and invoke

     `M-x texinfo-format-buffer'

A new buffer is created and the Info file text is generated there. 
`C-x C-s' will save it under the name specified in the `@setfilename'
command.

If the Texinfo file has more than 30,000 bytes,
`texinfo-format-buffer' will automatically create a "tag table" for
it.  With a tag table, Info can jump to new nodes more quickly than
it can otherwise.  In addition, if the file has more than 100,000
bytes in it, `texinfo-format-buffer' will split the file into shorter
Indirect subfiles of about 50,000 bytes each.  Files are split so
that Info does not have to make a large buffer to hold the whole of a
large Info file; instead, Info allocates just enough memory for the
small, split off file that is needed at the time.  This way, Emacs
avoids wasting memory when you run Info.  (Before splitting was
implemented, Info files were always short and "include" files were
designed as a way to create a single, large printed manual out of the
smaller Info files. *Note Include Files::, for more information.)

When the file is split, Info itself works through a shortened version
of the original file that contains the tag table and references to
the files that were split off.  The split off files are called
"indirect" files.

The split off files have names that are created by appending `-1',
`-2', `-3' and so on to the file names specified by the
`@setfilename' command.  The shortened version of the original file
continues to have the name specified by `@setfilename'.

At one stage in writing this document, for example, the Info file was
saved as `test-texinfo' and that file looked like this:

     Info file: test-texinfo,    -*-Text-*-
     produced by texinfo-format-buffer
     from file: new-texinfo-manual.texinfo
     
     ^_
     Indirect:
     test-texinfo-1: 102
     test-texinfo-2: 50422
     test-texinfo-3: 101300
     ^_^L
     Tag table:
     (Indirect)
     Node: overview^?104
     Node: info file^?1271
     Node: printed manual^?4853
     Node: conventions^?6855
     ...

 (But `test-texinfo' had far more nodes than are shown here.)  Each of
the split off, indirect files, `test-texinfo-1', `test-texinfo-2',
and `test-texinfo-3', is listed in this file after the line that says
`Indirect:'.  The tag table is listed after the line that says `Tag
table:'.

You cannot run the `M-x Info-validate' node checking command on
indirect files.  For information on how to prevent files from being
split and how to validate the structure of the nodes, *note
Info-Validating a Large File::.

* Menu:

* Installing an Info File::	Putting the Info file in the info directory.

 

File: texinfo,  Node: Installing an Info File,  Prev: Creating an Info File,  Up: Creating an Info File

Installing an Info file
=======================

An Info file is usually installed in the GNU Emacs directory called
`info'.  For Info to work, this directory must contain all the Info
files, including the split off files.  In addition, the `info'
directory must have a file that serves as a top level directory for
the Info system.  This file is called `dir'.

For example, in the `info' directory, the file called `dir' has the
top level menu for all the Info files in the system.  This file has a
master menu that looks like this:

     * Menu:
     
     * Info:    (info).      Documentation browsing system.
     * Emacs:   (emacs).     The extensible self-documenting text editor.
     * Texinfo: (texinfo).   With one source file, make either a printed 
                             manual using TeX or an Info file using
                             Texinfo.

 To add a new Info file, just add it to this menu.  For example, if
you were adding documentation for GDB, you would make the following
entry:

     * GDB: (gdb).           The source-level C debugger.

 The first item is the menu item name; it is followed by a colon.  The
second item is the name of the Info file, in parentheses; it is
followed by a period.  The third part of the entry is the description
of the item.

The top node of the file, named `top', should have as its parent the
name of a node in another file, where there is a menu that leads to
this file.  Specify the file name in parentheses.  If the file is to
be installed directly in the Info directory file, use `(dir)' as the
parent of the top node; this is short for `(dir)top', the node `top'
in the file `dir', which is the main menu of Info.



File: texinfo,  Node: Catching Mistakes,  Next: Command Syntax,  Prev: Creating an Info File,  Up: Top

Catching Mistakes
*****************

Besides mistakes with the content of what ever you are describing,
there are two kinds of mistake you can make with Texinfo:  you can
make mistakes with @-commands, and you can make mistakes with the
structure of the nodes and chapters.

There are two tools for catching the first kind of mistake and two
for catching the second.

For finding problems with @-commands, your best action is to run `M-x
texinfo-format-region' on regions of your file as you write it.  In
Texinfo mode, the `texinfo-format-region' command is bound to `C-c
C-f'.  In addition, you can run TeX on the whole file.

For finding problems with the structure of nodes and chapters, you
can use `C-c C-s' (`texinfo-show-structure') (and the related `occur'
command) and you can use the `M-x Info-validate' command.

* Menu:

* Debugging with Info::    	    Catching errors with info formatting.
* Debugging with Tex::		    Catching errors with TeX formatting.
* Using texinfo-show-structure::    Using `texinfo-show-structure'
				    to catch mistakes.
* Running Info-Validate::	    Checking for unreferenced nodes.

 

File: texinfo,  Node: Debugging with Info,  Next: Debugging with Tex,  Up: Catching Mistakes

Catching Errors with Info Formatting
====================================

After you have written part of a Texinfo file, you can use the `M-x
texinfo-format-region' command to see whether the region formats
properly.  In Texinfo mode, this command is bound to the keyboard
command `C-c C-f'.

If you have made a mistake with an @-command, `M-x
texinfo-format-region' will stop processing at or after the error and
give an error message.  To see where in the file the error occurred,
switch to the `*Info Region*' buffer; the cursor will be in a
position that is after the location of the error.  Also, the text
will not be formatted after the place the error occurred.

For example, if you accidently end a menu with the command `@end
menus' with an `s' on the end, instead of with `@end menu', you will
get an error message that says:

     @end menus is not handled by texinfo.

 The cursor will stop at the point in the file where the error occurs,
or not long after it.  It will look like this:

     @menu
     * Using texinfo-show-structure::    Using `texinfo-show-structure'
                                         to catch mistakes.
     * Running Info-Validate::           Checking for unreferenced nodes.
     @end menus

The `texinfo-format-region' command does not always recognize errors.
For example, no errors were reported when `texinfo-format-region' was
run on the whole itemized list of which the following is a part:

     name of the Texinfo file as an extension.  The @samp{??} are `wildcards'
     that cause the shell to substitute all the raw index files.  (@xref{sorting
     indices), for more information about sorting indices.) @refill
     @cindex Sorting indices
     @cindex Indices, sorting
     
     @item 
     @emph{Third}, rerun the @TeX{} command on the Texinfo file.  This
     regenerates a formatted DVI file with the index entries in the correct
     order.  This second run also makes all the cross references and table of
     contents correct as well.

 Instead, `texinfo-format-region' ran without reporting the error, but
it produced output with very long lines, containing some of the
original `@cindex' commands mixed in.  (It is not practical to
display these over long lines here.

However, when `texinfo-format-region' was run on part of the list
that is shown, it did give an error message, `Search failed: "[{,}"'.
(This error message is explained in the section on using the Emacs
Lisp Debugger, *note Using the Emacs Lisp Debugger::.)

Sometimes `texinfo-format-region' will stop long after the original
error;  this is because it does not discover the problem until then. 
In this case, you will have to backtrack.



File: texinfo,  Node: Using the Emacs Lisp Debugger,  Up: Debugging with Info

Using the Emacs Lisp Debugger
-----------------------------

If an error is especially elusive, you can turn on the Emacs Lisp
debugger and look at the backtrace; this tells you where in the
`texinfo-format-region' function the problem occurred.  You can turn
on the debugger with the command:

     M-x set-variable RET debug-on-error RET t

and turn it off with

     M-x set-variable RET debug-on-error RET nil

Often, when you are using the debugger, it is easier to follow what
is going on if you use the Emacs Lisp files that are not
byte-compiled.  The byte-compiled sources send octal numbers to the
debugger that may look mysterious.  To use the uncompiled source
files, load `texinfmt.el' and `texinfo.el' with the `M-x load-file'
command.

The debugger will not catch an error if `texinfo-format-region' does
not detect one.  In the example shown above, `texinfo-format-region'
did not find the error when the whole list was formatted, but only
when part of the list was formatted.  When `texinfo-format-region'
did not find an error, the debugger did not find one either.

However, when `texinfo-format-region' did report an error, it invoked
the debugger.  This is the backtrace it produced:

     Signalling: (search-failed "[},]")
       re-search-forward("[},]")
       (while ...)
       (let ...)
       texinfo-format-parse-args()
       (let ...)
       texinfo-format-xref()
       funcall(texinfo-format-xref)
       (if ...)
       (let ...)
       (if ...)
       (while ...)
       texinfo-format-scan()
       (save-excursion ...)
       (let ...)
       texinfo-format-region(103370 103631)
     * call-interactively(texinfo-format-region)

The backtrace is read from the bottom up.  `texinfo-format-region'
was called interactively; and it, in turn, called various functions,
including `texinfo-format-scan', `texinfo-format-xref' and
`texinfo-format-parse-args'.  Inside the function
`texinfo-format-parse-args', the function `re-search-forward' was
called; it was this function that could not find the missing right
hand brace.

*Note : (emacs)Lisp Debug, for more information.



File: texinfo,  Node: Debugging with Tex,  Next: Using texinfo-show-structure,  Prev: Debugging with Info,  Up: Catching Mistakes

Catching Errors with TeX Formatting
===================================

You can also catch mistakes when you format a file with TeX.

Usually, you will want to do this after you have run
`texinfo-format-buffer' on the same file.  `texinfo-format-buffer' is
usually faster and sometimes gives error messages that make more
sense.  *Note Debugging with Info::, for more information.

For example, TeX was run on the same itemized list discussed in the
section on the use of  `texinfo-format-region' (*note Debugging with
Info::.); the fragment with the error looked like this:

     name of the texinfo file as an extension.  The @samp{??} are `wildcards'
     that cause the shell to substitute all the raw index files.  (@xref{sorting
     indices, for more information about sorting indices.) @refill

This produced the following output, after which TeX stopped:

     Runaway argument?
     {sorting indices, for more information about sorting indices.) @refill @ETC.
     ! Paragraph ended before \xref was complete.
     <to be read again> 
                        \par 
     l.27 
          
     ?

In this case, TeX produced an accurate and understandable error
message: `Paragraph ended before \xref was complete.' (Note, however,
that TeX translated the `@' into a `\'.)  Also, `\par' is an internal
TeX command of no relevance to Texinfo.)

Unfortunately, TeX is not always so helpful, and sometimes you have
to be truly a Sherlock Holmes to discover what went wrong.

In any case, if you run into a problem like this, you can do one of
two things.

  1. You can tell TeX to continue running and to ignore errors  as
     best it can by typing `r RET' at the  `?' prompt.

     This is often the best thing to do.  However, beware: the one
     error may produce a cascade of additional error messages as it
     consequences are felt through the rest of the file.

  2. You can tell TeX to stop this run by typing `x RET'  at the `?'
     prompt.

Sometimes TeX will format a file without producing error messages
even though there is a problem.  This usually occurs if a command is
not ended but TeX is able to continue processing anyhow.  For
example, if you fail to end an itemized list with the `@end itemize'
command, TeX will write a DVI file that you can print out.  The only
error message that TeX will give you is the somewhat mysterious
comment that

     (\end occurred inside a group at level 1)

However, if you print the DVI file, you will find that the text of
the file that follows the itemized list is entirely indented as if it
were part of the last item in the itemized list.  The error message
is the way TeX says that it expected to find an `@end' command
somewhere in the file; but that it could not locate where it was
needed.

Another source of notoriously hard to find errors is a missing `@end
group' command.  If you ever are stumped by incomprehensible errors,
look for a missing `@end group' command first.

If you do not have the header lines in the file, TeX may stop in the
beginning of its run and display output that looks like the following.
The `*' indicates that TeX is waiting for input.

     This is TeX, Version 2.0 for Berkeley UNIX (preloaded format=plain-cm 
     87.10.25) (#tz-bar-a02987.tex [1])
     *

In this case, simply type `\end RET' after the asterisk.  Then put
the header lines into the Texinfo file and run the TeX command again.