-
Notifications
You must be signed in to change notification settings - Fork 2
/
texinfo-ed.7.1-en_US.texi
23781 lines (18842 loc) · 809 KB
/
texinfo-ed.7.1-en_US.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
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
\input texinfo.tex @c -*-texinfo-*-
@setfilename texinfo.info
@c Automake automatically updates version.texi to @set VERSION and
@c @set UPDATED to appropriate values.
@include version.texi
@settitle GNU Texinfo @value{VERSION}
@c Define a new index for command-line options.
@defcodeindex op
@c Put everything except function (command, in this case) names in one
@c index (arbitrarily chosen to be the concept index).
@syncodeindex op cp
@syncodeindex vr cp
@syncodeindex pg cp
@c finalout
@c flag to index command names without extra text in the entry
@ifinfo
@set commandlookup
@end ifinfo
@ifhtml
@set commandlookup
@end ifhtml
@microtype on
@copying
This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
a documentation system that can produce both online information and a
printed manual from a single source using semantic markup.
Copyright @copyright{} 1988-2023 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying
@dircategory Texinfo documentation system
@direntry
* Texinfo: (texinfo). The GNU documentation format.
* install-info: (texinfo)Invoking install-info. Update info/dir entries.
* texi2any: (texinfo)Invoking texi2any. Translate Texinfo source.
* makeinfo: (texinfo)Invoking texi2any. Translate Texinfo source.
* pod2texi: (pod2texi)Invoking pod2texi. Translate Perl Pod to Texinfo.
* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
* texi2pdf: (texinfo)PDF Output. PDF output for Texinfo.
* pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo.
* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
@end direntry
@set txiindexatsignignore
@set txiindexbackslashignore
@set txiindexlessthanignore
@set txiindexhyphenignore
@clear txicodevaristt
@titlepage
@title Texinfo
@subtitle The GNU Documentation Format
@subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
@author Robert J. Chassell
@author Richard M. Stallman
@page
@vskip 0pt plus 1filll
@insertcopying
@sp 1
Published by the Free Software Foundation @*
51 Franklin St, Fifth Floor @*
Boston, MA 02110-1301 @*
USA @*
ISBN 1-882114-67-1 @c for version 4.0, September 1999.
@c ISBN 1-882114-65-5 is for version 3.12, March 1998.
@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995.
@ignore
@sp 1
Cover art by Etienne Suvasa.
@end ignore
@end titlepage
@summarycontents
@contents
@node Top
@top Texinfo
This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
a documentation system that can produce both online information and a
printed manual from a single source using semantic markup.
@ifinfo
The first part of this master menu lists the major nodes in this Info
document, including the @@-command and concept indices. The rest of
the menu lists all the lower-level nodes in the document.
@end ifinfo
@node Copying Conditions
@nodedescription Your rights.
@unnumbered Texinfo Copying Conditions
@cindex Copying conditions
@cindex Conditions for copying Texinfo
@cindex Free software
@cindex Libre software
GNU Texinfo is @dfn{free software}; this means that everyone is free
to use it and free to redistribute it on certain conditions. Texinfo
is not in the public domain; it is copyrighted and there are
restrictions on its distribution, but these restrictions are designed
to permit everything that a good cooperating citizen would want to do.
What is not allowed is to try to prevent others from further sharing
any version of Texinfo that they might get from you.
Specifically, we want to make sure that you have the right to give away
copies of the programs that relate to Texinfo, that you receive source
code or else can get it if you want it, that you can change these
programs or use pieces of them in new free programs, and that you know
you can do these things.
To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights. For example, if you distribute
copies of the Texinfo related programs, you must give the recipients all
the rights that you have. You must make sure that they, too, receive or
can get the source code. And you must tell them their rights.
Also, for our own protection, we must make certain that everyone finds
out that there is no warranty for the programs that relate to Texinfo.
If these programs are modified by someone else and passed on, we want
their recipients to know that what they have is not what we distributed,
so that any problems introduced by others will not reflect on our
reputation.
The precise conditions of the licenses for the programs currently
being distributed that relate to Texinfo are found in the General
Public Licenses that accompany them. This manual is covered by the
GNU Free Documentation License (@pxref{GNU Free Documentation
License}).
@node Overview
@nodedescription Texinfo in brief.
@chapter Overview of Texinfo
@cindex Overview of Texinfo
@cindex Texinfo overview
@cindex Using Texinfo in general
@cindex Texinfo, introduction to
@cindex Introduction to Texinfo
@anchor{Using Texinfo} @c merged node
@dfn{Texinfo} is a documentation system that uses a single source file
to produce both online information and printed output. This means
that instead of writing several different documents, one for each output
format, you need only write one document.
Using Texinfo, you can create a printed document (via the @TeX{}
typesetting system) in PDF format, including chapters,
sections, cross-references, and indices. From the same Texinfo source
file, you can create HTML output suitable for use with a web
browser, you can create an Info file for use in GNU Emacs or other
Info-reading programs, and also create DocBook, EPUB 3, or @LaTeX{} files.
@cindex Source file format
@cindex Semantic markup
A Texinfo source file is a plain text file containing text interspersed
with @dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
Texinfo processors what to do. Texinfo's markup commands are almost
entirely @dfn{semantic}; that is, they specify the intended meaning
of text in the document, rather than physical formatting instructions.
GNU Emacs has a special mode, called Texinfo mode, that provides various
Texinfo-related features. (@xref{Texinfo Mode}.)
@cindex Limited scope of Texinfo
Texinfo was devised specifically for the purpose of writing software
documentation and manuals. If you want to write a good manual for
your program, Texinfo has many features which we hope will make your
job easier. However, Texinfo is not intended to be a general-purpose
formatting program. It provides almost no commands for controlling
the final formatting, so may be inappropriate for your needs if you
want to lay out a newspaper, devise a glossy magazine ad, or follow
the exact formatting requirements of a publishing house.
@cindex Spelling of Texinfo
@cindex Pronunciation of Texinfo
Spell ``Texinfo'' with a capital ``T'' and the other letters in
lowercase. The first syllable of ``Texinfo'' is pronounced like
``speck'', not ``hex''. This odd pronunciation is derived from the
pronunciation of @TeX{}. Pronounce @TeX{} as if the @samp{X} were
the last sound in the name `Bach'. In the word @TeX{}, the @samp{X}
is, rather than the English letter ``ex'', actually the Greek letter
``chi''.
Texinfo is the official documentation format of the GNU project.
More information, including manuals for GNU packages, is available
at the @uref{http://www.gnu.org/doc/, GNU documentation web page}.
@node Reporting Bugs
@nodedescription Submitting effective bug reports.
@section Reporting Bugs
@cindex Bugs, reporting
@cindex Suggestions for Texinfo, making
@cindex Reporting bugs
We welcome bug reports and suggestions for any aspect of the Texinfo
system: programs, documentation, installation, etc. Please email them
to @email{bug-texinfo@@gnu.org}. You can get the latest version of
Texinfo via its home page, @uref{http://www.gnu.org/software/texinfo}.
@cindex Checklist for bug reports
For bug reports, please include enough information for the maintainers
to reproduce the problem. Generally speaking, that means:
@itemize @bullet
@item The version number of Texinfo and the program(s) or manual(s) involved.
@item The contents of any input files necessary to reproduce the bug.
@item Precisely how you ran any program(s) involved.
@item A description of the problem and samples of any erroneous output.
@item Hardware and operating system names and versions.
@item Anything else that you think would be helpful.
@end itemize
When in doubt whether something is needed or not, include it. It's
better to include too much than to leave out something important.
It is critical to send an actual input file that reproduces the
problem.
Any problems with the Info reader in Emacs should be reported to
the Emacs developers: see @ref{Bugs,,, emacs, The GNU Emacs Manual}.
@cindex Patches, contributing
Patches are welcome; if possible, please make them with @samp{@w{diff -c}},
@samp{@w{diff -u}} (@pxref{,,, diffutils, Comparing and Merging Files}),
or @samp{git diff} and include @file{ChangeLog} entries (@pxref{Change Log,,,
standards, GNU Coding Standards}), and follow the existing coding style.
@node Output Formats
@nodedescription Overview of the supported output formats.
@section Output Formats
@cindex Output formats
@cindex Back-end output formats
Here is an overview of the output formats currently supported by Texinfo.
@table @asis
@cindex Info output, overview
@item Info
(Generated via @command{texi2any}.) Info format is mostly a plain
text transliteration of the Texinfo source. It adds a few control
characters to provide navigational information for cross-references,
indices, and so on. The Emacs Info subsystem (@pxref{Top,,, info,
Info}), and the standalone @command{info} program (@pxref{Top,,,
info-stnd, GNU Info}), among others, can read these files. @xref{Info
Files}, and @ref{Creating and Installing Info Files}.
@cindex Plain text output, overview
@item Plain text
(Generated via @command{texi2any --plaintext}.) This is almost the
same as Info output with the navigational control characters are
omitted.
@cindex HTML output, overview
@item HTML
@c @cindex Mozilla
@c @cindex Lynx
@c @cindex Emacs-W3
(Generated via @command{texi2any --html}.) HTML, standing for Hyper
Text Markup Language, is the language for writing documents on the World
Wide Web. Web browsers
@c such as Mozilla, Lynx, and Emacs-W3
can render this language online. There
are many versions of HTML, both different standards and
browser-specific variations. @command{texi2any} uses a subset
of the language that can be interpreted by any common browser,
intentionally not using many newer or less widely-supported tags.
Although the native output is thus rather plain, it can be customized
at various levels, if desired. @xref{Generating HTML}.
@cindex EPUB 3 output, overview
@item EPUB 3
(Generated via @command{texi2any --epub3}.)
EPUB is a format designed for reading electronic books on
portable devices. It is a derivative of HTML@. The format was
developed by the International Digital Publishing Forum (IDPF),
which is now part of the World Wide Web Consortium (W3C)@. The
latest major revision, EPUB 3, dates from 2011.
@cindex DVI output, overview
@pindex dvips @r{(program)}
@pindex xdvi
@item DVI
(Generated via @command{texi2dvi}.) The DeVIce Independent binary
format is output by the @TeX{} typesetting program
(@uref{http://tug.org}). This is then read by a DVI `driver', which
knows the actual device-specific commands that can be viewed or
printed, notably Dvips for translation to PostScript (@pxref{Top,,,
dvips, Dvips}) and Xdvi for viewing on an X display
(@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy
with @TeX{}}. (Be aware that the Texinfo language is very different
from @TeX{}'s usual languages: plain @TeX{}, @LaTeX{}, Con@TeX{}t,
etc.)
@cindex PostScript output, overview
@item PostScript
(Generated via @command{texi2dvi --ps}.) PostScript is a page
description language that became widely used around 1985 and is still
used today. @uref{https://en.wikipedia.org/wiki/PostScript} gives a
basic description and more preferences. By default, Texinfo uses the
@command{dvips} program to convert @TeX{}'s DVI output to PostScript.
@xref{Top,,, dvips, Dvips}.
@cindex PDF output, overview
@cindex Beebe, Nelson
@item PDF
(Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This
format was developed by Adobe Systems for portable document
interchange, based on their previous PostScript language. It can
represent the exact appearance of a document, including fonts and
graphics, and supporting arbitrary scaling. It is intended to be
platform-independent and easily viewable, among other design goals;
@uref{https://en.wikipedia.org/wiki/Portable_Document_Format} and
@uref{http://tug.org/TUGboat/tb22-3/tb72beebe-pdf.pdf} have some
background. By default, Texinfo uses the @command{pdftex} program, an
extension of @TeX{}, to output PDF; see
@uref{http://tug.org/applications/pdftex}. @xref{PDF Output}.
@cindex LaTeX output, overview
@item @LaTeX{}
(Generated via @command{texi2any --latex}.) This is a typesetting
system built on top of @TeX{}. It was originally released by
Leslie Lamport in 1984. @LaTeX{} adds more definitions to those
of @TeX{} and has a wide range of packages built on it. @LaTeX{} is
ubiquitous in academic literature. The current version of @LaTeX{}
is under active development; more information is available online
at @uref{https://www.latex-project.org/}.
The @LaTeX{} output can be further processed into DVI, PostScript,
or PDF@. In theory, the @LaTeX{} output should allow for much more
customizability of the output than would be possible with the plain
@TeX{} implementation of Texinfo.
@cindex DocBook output, overview
@cindex XML DocBook output, overview
@item DocBook
(Generated via @command{texi2any --docbook}.) This is an XML-based
format, primarily for technical
documentation. It therefore bears some resemblance, in broad
outline, to Texinfo. See @uref{http://www.docbook.org}. Various
converters from DocBook @emph{to} Texinfo have also been developed;
see the Texinfo web pages.
@cindex XML Texinfo output, overview
@cindex Texinfo XML output, overview
@cindex DTD, for Texinfo XML
@pindex texinfo.dtd
@pindex txixml2texi
@item XML
(Generated via @command{texi2any --xml}.)
The @command{texi2any} XML output, unlike all the other output
formats, is a transliteration of the Texinfo source, rather than
finished output. Texinfo XML files cannot be viewed in web browsers
or other programs.
XML is a generic syntax specification usable for any sort of content.
(A reference is at @uref{http://www.w3.org/XML}.)
The purpose of the Texinfo XML output is to allow further processing by
XML tools. The output syntax is defined in an XML DTD,
which is contained in a file @file{texinfo.dtd} included in the
Texinfo source distribution.
The Texinfo source distribution includes a
utility script @file{txixml2texi} to do a backward transformation
to recreate the original Texinfo content (except for Texinfo macros
and conditionals).
@end table
@node Info Files
@nodedescription What is an Info file?
@section Info Files
@cindex Info files
As mentioned above, Info format is mostly a plain text transliteration
of the Texinfo source, with the addition of a few control characters
to separate nodes and provide navigational information, so that
Info-reading programs can operate on it.
Info files are nearly always created by processing a Texinfo source
document. @command{texi2any}, also known as @command{makeinfo}, is
the principal command that converts a Texinfo file into an Info file;
@pxref{Generic Translator @command{texi2any}}.
Generally, you enter an Info file through a node that by convention is
named `Top'. This node normally contains just a brief summary of the
file's purpose, and a large menu through which the rest of the file is
reached. From this node, you can either traverse the file
systematically by going from node to node, or you can go to a specific
node listed in the main menu, or you can search the index menus and then
go directly to the node that has the information you want. Alternatively,
with the standalone Info program, you can specify specific menu items on
the command line (@pxref{Top,,, info, Info}).
If you want to read through an Info file in sequence, as if it were a
printed manual, you can hit @key{SPC} repeatedly, or you get the whole
file with the advanced Info command @kbd{g *}. (@xref{Advanced,,
Advanced Info commands, info, Info}.)
The @file{dir} file in the @file{info} directory serves as the
departure point for the whole Info system. From it, you can reach the
`Top' nodes of each of the documents in a complete Info system.
@cindex URI syntax for Info
If you wish to refer to an Info file via a URI, you can use the
(unofficial) syntax exemplified by the following. This works with
Emacs/W3, for example:
@example
info:emacs#Dissociated%20Press
info:///usr/info/emacs#Dissociated%20Press
info://localhost/usr/info/emacs#Dissociated%20Press
@end example
The @command{info} program itself does not follow URIs of any kind.
@node Printed Books
@nodedescription Characteristics of a printed book or manual.
@section Printed Books
@cindex Printed book and manual characteristics
@cindex Manual characteristics, printed
@cindex Book characteristics, printed
@cindex Texinfo printed book characteristics
@cindex Characteristics, printed books or manuals
@cindex Knuth, Donald
A Texinfo file can be formatted and typeset as a printed book or
manual. To do this, you need @TeX{}, a sophisticated typesetting
program written by Donald Knuth of Stanford University. It is not part
of the Texinfo distribution.
Texinfo provides a file @file{texinfo.tex} that contains the definitions
that @TeX{} uses when it typesets a Texinfo file.
You can get the latest version of @file{texinfo.tex} from
the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}.
A Texinfo-based book is similar to any other typeset, printed work: it
can have a title page, copyright page, table of contents, and preface,
as well as chapters, numbered or unnumbered sections and subsections,
page headers, cross-references, footnotes, and indices.
@TeX{} is very powerful and has a great many features. However,
because a Texinfo file must be able to present information both on a
character-only terminal in Info form and in a typeset book, the
formatting commands that Texinfo supports are necessarily limited.
@xref{Hardcopy with @TeX{}}, for more information on processing a
manual with @TeX{}.
@node Adding Output Formats
@nodedescription Man pages and implementing new formats.
@section Adding Output Formats
@cindex Additional output formats
The output formats in the previous sections handle a wide variety of
usage, but of course there is always room for more.
@cindex Output formats, supporting more
@cindex SGML-tools output format
If you are a programmer and would like to contribute to the GNU
project by implementing additional output formats for Texinfo, that
would be excellent. The way to do this that would be most useful is
to write a new back-end for @command{texi2any}, our reference
implementation of a Texinfo parser; it creates a tree representation
of the Texinfo input that you can use for the conversion. The
documentation in the source file
@file{tp/Texinfo/Convert/Converter.pm} is a good place to start
(@pxref{Texinfo::Convert::Converter,,,texi2any_internals,Texinfo modules documentation}).
@xref{Generic Translator @command{texi2any}}.
Another viable approach is use the Texinfo XML output from
@command{texi2any} as your input. This XML is an essentially complete
representation of the input, but without the Texinfo syntax and option
peculiarities, as described above.
@cindex Texinfo parsers, discouraging more
If you still cannot resist the temptation of writing a new program
that reads Texinfo source directly, let us give some more caveats:
please do not underestimate the amount of work required. Texinfo is
by no means a simple language to parse correctly, and remains under
development, so you would be committing to an ongoing task. You
are advised to check that the tests of the language that come with
@command{texi2any} give correct results with your new program.
@cindex Man page output, not supported
From time to time, proposals are made to generate traditional Unix man
pages from Texinfo source. However, because man pages have a strict
conventional format, creating a good man page requires a completely
different source from that needed for the typical Texinfo applications
of writing a good user tutorial and/or a good reference manual. This
makes generating man pages incompatible with the Texinfo design
goal of not having to document the same information in different
ways for different output formats. You might as well write the man
page directly.
@pindex help2man
@cindex O'Dea, Brendan
As an alternative way to support man pages, you may find the program
@command{help2man} to be useful. It generates a traditional man page
from the @samp{--help} output of a program. In fact, the man pages
for the programs in the Texinfo distribution are generated with this.
It is GNU software written by Brendan O'Dea, available from
@uref{http://www.gnu.org/software/help2man}.
@node History
@nodedescription Acknowledgements, contributors and genesis.
@section History
@cindex Stallman, Richard M.
@cindex Chassell, Robert J.
@cindex Fox, Brian
@cindex Berry, Karl
@cindex Smith, Gavin
Richard M. Stallman invented the Texinfo format, wrote the initial
processors, and created Edition 1.0 of this manual. Robert@tie{}J.
Chassell greatly revised and extended the manual, starting with
Edition 1.1. Brian Fox was responsible for the standalone Texinfo
distribution until version 3.8. Karl Berry continued maintenance
from Texinfo 3.8 (manual edition 2.22), and Gavin Smith has continued
maintenance since Texinfo 6.0.
@cindex History of Texinfo
@cindex Texinfo history
@subheading Beginnings
@cindex NLS
Richard Stallman included an on-line, hypertext help system called
Info in the original implementation of Emacs (in 1975/6).
Stallman had been inspired after seeing a presentation a couple of years
earlier on the ``NLS'' hypertext system of Douglas Engelbart.
@ignore
From rms@santafe.edu Sat Jan 23 03:41:05 1999
Status: RO
X-VM-v5-Data: ([nil nil nil nil nil nil nil nil nil]
[nil nil nil nil nil nil nil nil nil nil nil nil "^Date:" nil nil nil ni
+l nil nil nil nil]
nil)
Reply-to: rms@gnu.org
Content-Length: 331
Date: Sat, 23 Jan 1999 01:40:59 -0700 (MST)
From: Richard Stallman <rms@gnu.org>
To: bob@rattlesnake.com
CC: karl@cs.umb.edu, kama@hippo.fido.de, bug-texinfo@gnu.org
Subject: Re: Q: Some history questions
People at MIT also developed a nifty on-line help format called Info.
That was me. I developed Info as a sort of "poor man's hypertext"
after I saw a presentation on NLS (Englebart's hypertext system). I
THINK this was in 1974, actually before Emacs, and that after
developing Emacs in 1975 I adapted Info to work with it.
@end ignore
@cindex Scribe
@cindex Reid, Brian
In another development, in the 1970's at CMU, Brian Reid developed
a program and format named Scribe to mark up documents for printing.
It used the @code{@@} character to introduce commands, as Texinfo does.
Much more consequentially, it strove to describe document contents
rather than formatting, an idea wholeheartedly adopted by Texinfo.
@cindex Bolio
@cindex Bo@TeX{}
Meanwhile, people at MIT developed another format called Bolio.
Richard Stallman (RMS) worked on converting Bolio to use @TeX{} as
its typesetting language, resulting in Bo@TeX{}. The earliest Bo@TeX{}
version seems to have been 0.02 on October 31, 1984.
Bo@TeX{} could only be used as a markup language for documents to be
printed, not for online documents. RMS combined Bo@TeX{} and Info
to create Texinfo, a mark-up language for text that is intended to
be read both online and as printed hard copy.
The original translator to create Info was written
(primarily by RMS and Bob Chassell) in Emacs Lisp, namely the
@code{texinfo-format-buffer} and other functions. In the early 1990s,
Brian Fox reimplemented the conversion program in C, now called
@command{makeinfo}, as well as the standalone @command{info} program.
@subheading Reimplementing in Perl
@cindex Cons, Lionel
@cindex Dumas, Patrice
In 2012, the C @command{makeinfo} was itself replaced by a Perl
implementation generically called @command{texi2any}. This version
supports the same level of output customization as
@command{texi2html}, an independent program originally written by
Lionel Cons, later with substantial work by many others. The many
additional features needed to make @command{texi2html} a replacement
for @command{makeinfo} were implemented by Patrice Dumas. The first,
never-released version of @command{texi2any} was based on the
@command{texi2html} code.
@cindex Tree representation of documents
@cindex Syntax tree representation of documents
@cindex Abstract syntax tree representation of documents
That implementation, however, was abandoned in favor of the current
program (also written by Patrice Dumas), which parses the Texinfo
input into a tree for processing. It inherited the design of
customization and other features from @command{texi2html} (for more
on @command{texi2html} compatibility, @pxref{@command{texi2html}}).
However, @command{texi2any} is a full reimplementation: it constructs
a tree-based representation of the input document for all back-ends
to work from.
The new Perl program is much slower than the old C program. The speed
gap has partially closed since first release, but it may not ever be
entirely comparable. So why did we switch? In short, we intend and
hope that the present program will be much easier than the previous C
implementation of @command{makeinfo} to extend to different output
styles, back-end output formats, and all other customizations.
In more detail:
@itemize @bullet
@item HTML customization. Many GNU and other free software packages
had been happily using the HTML customization features in
@command{texi2html} for years. Thus, in effect two independent
implementations of the Texinfo language had developed, and keeping
them in sync was not simple. Adding the HTML customization possible
in @command{texi2html} to a C program would have been an
enormous effort.
@item Unicode, and multilingual support generally, especially of east
Asian languages. At that time, doing it in C would have been tantamount
to rewriting the entire program. Since then, the parser and bits of
converter back-ends have been rewritten in C, but the converter
back-ends are still mostly in Perl which has good multilingual
support built in.
@item Additional back-ends. The @command{makeinfo} code had become
convoluted to the point where adding a new back-end was quite complex,
requiring complex interactions with existing back-ends. In contrast,
the new implementation provides a clean tree-based representation for
all back-ends to work from. People have requested numerous different
back-ends (@LaTeX{}, the latest (X)HTML, @dots{}); this change made them
much more feasible to implement. Which leads to the last item:
@item Making contributions easier. In general, due to the cleaner
structure, the separate parser/back-ends implementation
should be considerably easier than the former C @command{makeinfo}
implementation for anyone to read and contribute to, with the resulting
obvious benefits. After ten years, contributed back-ends were yet to
happen, but it is still believed that this structure could in theory
lend better to contributions.
@end itemize
@cindex @command{texi2any}, as reference implementation
@cindex Reference implementation
@cindex Implementation, @command{texi2any} as reference
@cindex Texinfo language tests
@cindex Tests, of Texinfo language
@anchor{Reference Implementation}@c
@command{texi2any} is intended to be a reference implementation
that defines parts of the language not fully specified by the manual.
Without such a reference, alternative implementations would be very
likely to have subtle, or not-so-subtle, differences in behavior,
and thus Texinfo documents would become dependent on the processor.
It is also important to have consistent command-line options for
all processors. Extensive tests of the language and processor were
developed at the same time as @command{texi2any}; we encourage anyone
thinking of writing a program to parse Texinfo input to make use of
these tests.
@cindex Future of Texinfo implementations
With the release of @command{texi2any} as the reference
implementation, development of both the C implementation of
@command{makeinfo} and @command{texi2html} has been halted. Going
forward, we ask authors of Texinfo documents to use only
@command{texi2any}.
@node Writing a Texinfo File
@anchor{Beginning and Ending a File}@c old name
@nodedescription Format of a Texinfo source file.
@chapter Writing a Texinfo File
This chapter describes Texinfo syntax and what is required in a Texinfo
file, and gives a short sample file.
@node Conventions
@nodedescription General rules for writing a Texinfo file.
@section General Syntactic Conventions
@cindex General syntactic conventions
@cindex Syntactic conventions
@cindex Conventions, syntactic
@cindex Characters, basic input
@anchor{Formatting Commands} @c old name
This section describes the general conventions used in all Texinfo documents.
@itemize @bullet
@item
@cindex Source files, characters used
All printable ASCII characters except @samp{@@}, @samp{@{} and
@samp{@}} can appear in a Texinfo file and stand for themselves.
@samp{@@} is the escape character which introduces commands, while
@samp{@{} and @samp{@}} are used to surround arguments to certain
commands. To put one of these special characters into the document, put
an @samp{@@} character in front of it, like this: @samp{@@@@},
@samp{@@@{}, and @samp{@@@}}.
@item
@cindex @sortas{at} @@-commands
@cindex Formatting commands
In a Texinfo file, the commands you write to describe the contents of
the manual are preceded by an @samp{@@} character; they are called
@dfn{@@-commands}. (The @samp{@@} in Texinfo has the same meaning that
@samp{\} has in plain @TeX{}.)
@cindex Braces, when to use
Depending on what they do or what arguments they take, you
need to write @@-commands on lines of their own, or as part of
sentences. As a general rule, a command requires braces if it mingles
among other text; but it does not need braces if it is on a line of its
own. For more details of Texinfo command syntax, see @ref{Command
Syntax}.
@item
Whitespace following an @@-command name is optional and (usually)
ignored if present. The exceptions are contexts when whitespace is
significant, e.g., an @code{@@example} environment.
@item
Texinfo supports the usual quotation marks used in English and in
other languages; see @ref{Inserting Quotation Marks}.
@item
@cindex Multiple dashes in source
@cindex Dashes in source
@cindex Hyphens in source, two or three in a row
@cindex Em dash, producing
@cindex En dash, producing
Use three hyphens in a row, @samp{---}, to produce a long dash---like
this (called an @dfn{em dash}), used for punctuation in sentences.
Use two hyphens, @samp{--}, to produce a medium dash (called an
@dfn{en dash}), used primarily for numeric ranges, as in ``June
25--26''. Use a single hyphen, @samp{-}, to produce a standard hyphen
used in compound words. For display on the screen, Info reduces three
hyphens to two and two hyphens to one (not transitively!). Of course,
any number of hyphens in the source remain as they are in literal
contexts, such as @code{@@code} and @code{@@example}.
@item
@emph{Whitespace}. Texinfo files are plain text files composed of lines
terminated by the usual newline character (line feed). Texinfo processors
read input one line at a time. Paragraphs are terminated by an empty
line or a line containing only spaces. A sequence of several spaces in
text is usually treated the same as a single space (except in
verbatim modes).
@cindex Form feed character
@cindex @kbd{CTRL-l}
Form feed (@kbd{CTRL-l}) characters in normal text end any open paragraph.
Other ASCII whitespace (tab, carriage return) may be treated
the same as space characters, although the results may differ depending
on output format. Hence, there is not much point in using these
in documents. Non-ASCII spaces, such as Unicode ``em space'', are
not recognized as whitespace at all and will be treated as regular,
non-whitespace characters.
However, in verbatim modes, for example in code samples, tab characters
may produce the correct formatting in the output.
@ignore @c Excessive detail?
To avoid this problem, Texinfo mode in GNU Emacs inserts
multiple spaces when you press the @key{TAB} key. Also, you can run
@code{untabify} in Emacs to convert tabs in a region to multiple
spaces, or use the @code{unexpand} command from the shell.
@end ignore
@ignore @c too detailed for the manual, but kept for implementation tips
@item
Form feed characters outside of a paragraph are handled as follows:
@table @asis
@item PDF/DVI
Ignored between paragraphs.
@item LaTeX
Ignored in contexts where spaces are ignored except after specific
commands closing braces (@code{@@caption} for example). Left as is
in the output otherwise.
@c Written as @code{\par@{@}}, a @LaTeX{} macro that starts a paragraph.
@item Info
Output as-is between paragraphs (their most common use); ignored in contexts
where spaces are ignored except after specific commands closing braces
(@code{@@caption} for example). In other contexts, they may be treated as
regular spaces (and thus consolidated with surrounding whitespace).
@item HTML
Written as a numeric entity except contexts where spaces are ignored;
for example, in @samp{@@footnote@{ ^L foo@}}, the form feed is
ignored.
@item XML
Keep them everywhere; in attributes, escaped as @samp{\f}; also,
@samp{\} is escaped as @samp{\\} and newline as @samp{\n}.
@item DocBook
Completely removed, as they are not allowed.
@end table
As you can see, because of these differing requirements of the output
formats, it's not possible to use form feeds completely portably.
@end ignore
@end itemize
@node Comments
@nodedescription Writing comments and ignored text in general.
@section Comments
@cindex Comments
@findex comment
@findex c
You can write comments in a Texinfo file by using the @code{@@comment}
command, which may be abbreviated to @code{@@c}. Such comments are
for a person looking at the Texinfo source file. All the text on a
line that follows either @code{@@comment} or @code{@@c} is a comment;
the rest of the line does not appear in the visible output. (To be
precise, the character after the @code{@@c} or @code{@@comment} must
be something other than a dash or alphanumeric, or it will be taken as
part of the command.)
Often, you can write the @code{@@comment} or @code{@@c} in the middle
of a line, and only the text that follows after the @code{@@comment}
or @code{@@c} command does not appear; but some commands, such as
@code{@@settitle}, work on a whole line. You cannot use @code{@@comment}
or @code{@@c} within a line beginning with such a command.
@findex DEL @r{(comment character)}
@cindex Catcode for comments in @TeX{}
In cases of nested command invocations, complicated macro definitions,
etc., @code{@@c} and @code{@@comment} may provoke an error when
processing with @TeX{}. Therefore, you can also use the @kbd{DEL}
character (ASCII 127 decimal, 0x7f hex, 0177 octal) as a true @TeX{}
comment character (catcode 14, in @TeX{} internals). Everything on
the line after the @kbd{DEL} will be ignored and the next line will
be merged.
@cindex Ignored text
@cindex Unprocessed text
@findex ignore
You can also have long stretches of text ignored by the Texinfo
processors with the @code{@@ignore} and @code{@@end ignore} commands.
Write each of these commands on a line of its own, starting each
command at the beginning of the line. Text between these two commands
does not appear in the processed output. You can use @code{@@ignore}
and @code{@@end ignore} for writing comments. (For some caveats
regarding nesting of such commands, @pxref{Conditional Nesting}.)
@node Minimum
@nodedescription What a Texinfo file must have.
@section What a Texinfo File Must Have
@cindex Minimal Texinfo file (requirements)
@cindex Required in Texinfo file
@cindex Texinfo file minimum
By convention, the name of a Texinfo file ends with one of the
extensions @file{.texi}, @file{.texinfo}, @file{.txi}, or
@file{.tex}. Using @file{.tex} is discouraged as this extension
is already used by @TeX{} and @LaTeX{} input files. The most common
and recommended extension is @file{.texi}. The name of a Texinfo
file should only contain ASCII characters.
The output name is based on the input file name, in the default case.
First, any of the extensions @file{.texi}, @file{.tex}, @file{.txi},
or @file{.texinfo} is removed from the input file name; then,
the output format specific extension is added---@file{.html} when
generating HTML, @file{.info} when generating Info, etc.
The output name should only contain ASCII
characters@footnote{@command{texi2any} can handle non ASCII characters
in input file names, but non ASCII characters in output name will create
problems for some output formats, especially for cross-references.}.
@cindex Requirements for formatting
@cindex Minimal requirements for formatting
@cindex Formatting requirements
In order to be made into a printed manual, a Texinfo file must begin
with a line like this:
@example
@group
\input texinfo
@end group
@end example
@noindent
The contents of the file follow this beginning, and then you
must end the Texinfo source with a line like this:
@example
@@bye
@end example
@findex \input @r{(raw @TeX{} startup)}
The @code{@@bye} line at the end of the file on a line of its own tells
@TeX{} that the file is ended and to stop formatting. If you
leave this out, you'll be dumped at @TeX{}'s prompt at the end of the
run.
Furthermore, you will usually provide a Texinfo file with a title,
a title page, indices, and the like, all of which are explained in
this manual. But the minimum, which can be useful for short
documents, is just the one line at the beginning and the one line
at the end.
Without additional information, the input and output encodings are
assumed to be UTF-8, an universal codeset compatible with 7-bit
ASCII.
@node Short Sample Texinfo File
@nodedescription A short sample Texinfo file.
@anchor{Short Sample}@c
@anchor{Sample Beginning}@c
@section Short Sample
@cindex Sample Texinfo file, no comments
Here is a short sample Texinfo file.
@example
\input texinfo
@@settitle Sample Manual 1.0
@@copying
This is a short example of a complete Texinfo file.
Copyright @@copyright@{@} 2016 Free Software Foundation, Inc.
@@end copying
@@titlepage
@@title Sample Title
@@page
@@vskip 0pt plus 1filll
@@insertcopying
@@end titlepage
@@contents
@@node Top
@@top GNU Sample
This manual is for GNU Sample
(version @@value@{VERSION@}, @@value@{UPDATED@}).
@@menu
* First Chapter:: The first chapter is the
only chapter in this sample.
* Index:: Complete index.
@@end menu
@@node First Chapter
@@chapter First Chapter