-
Notifications
You must be signed in to change notification settings - Fork 2
/
texinfo-ed.6.1-en_US.texi
24131 lines (19115 loc) · 823 KB
/
texinfo-ed.6.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-*-
@c $Id: texinfo.texi 6987 2016-02-06 08:59:21Z gavin $
@c Everything between the start/end of header lines will be passed by
@c Emacs's {texinfo,makeinfo}-format region commands. See the `start of
@c header' node for more info.
@c %**start of header
@c Automake requires this
@setfilename texinfo.info
@c Automake automatically updates version.texi to @set VERSION and
@c @set UPDATED to appropriate values.
@include version-en_US.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
@tex
\global\usebracesinindexestrue
@end tex
@c finalout
@comment %**end of header
@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, 1990, 1991, 1992, 1993, 1995, 1996, 1997,
1998, 1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
2010, 2011, 2012, 2013, 2014, 2015, 2016 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, with the Front-Cover Texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation
License''.
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual. Buying copies from the FSF supports it in
developing GNU and promoting software freedom.''
@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.
* makeinfo: (texinfo)Invoking makeinfo. 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
@c Set smallbook if printing in smallbook format so the example of the
@c smallbook font is actually written using smallbook; in bigbook, a kludge
@c is used for TeX output. Do this through the -t option to texi2dvi,
@c so this same source can be used for other paper sizes as well.
@c smallbook
@c set smallbook
@c @@clear smallbook
@c If you like blank pages, add through texi2dvi -t.
@c setchapternewpage odd
@set txiindexatsignignore
@set txiindexbackslashignore
@set txiindexlessthanignore
@set txiindexhyphenignore
@titlepage
@title Texinfo
@subtitle The GNU Documentation Format
@subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
@author Robert J. Chassell
@author Richard M. Stallman
@c Include the Distribution inside the titlepage so
@c that headings are turned off.
@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.
@sp 1
Cover art by Etienne Suvasa.
@end titlepage
@summarycontents
@contents
@ifnottex
@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.
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 ifnottex
@menu
* Copying Conditions:: Your rights.
* Overview:: Texinfo in brief.
* Writing a Texinfo File:: Format of a Texinfo source file.
* Beginning and Ending a File:: Beginning and end of a Texinfo file.
* Nodes:: Writing nodes, the basic unit of Texinfo.
* Chapter Structuring:: Creating chapters, sections, appendices, etc.
* Cross References:: Writing cross-references.
* Marking Text:: Marking words and phrases as code,
keyboard input, meta-syntactic
variables, and the like.
* Quotations and Examples:: Block quotations, examples, etc.
* Lists and Tables:: Itemized or numbered lists, and tables.
* Special Displays:: Floating figures and footnotes.
* Indices:: Creating indices.
* Insertions:: Inserting @@-signs, braces, etc.
* Breaks:: Forcing or preventing line and page breaks.
* Definition Commands:: Describing functions and the like uniformly.
* Internationalization:: Supporting languages other than English.
* Conditionals:: Specifying text for only some output cases.
* Defining New Texinfo Commands:: User-defined macros and aliases.
* Include Files:: How to incorporate other Texinfo files.
* Hardcopy:: Output for paper, with @TeX{}.
* Generic Translator @command{texi2any}:: @command{texi2any}, an all-purpose converter.
* Creating and Installing Info Files:: Details on Info output.
* Generating HTML:: Details on HTML output.
@c * texi2any Output Customization:: Fine tuning with initialization files.
Appendices
* @@-Command Details:: Details of the Texinfo @@-commands.
* Tips:: Hints on how to write a Texinfo document.
* Sample Texinfo Files:: Complete examples, including full texts.
* Texinfo Mode:: Using the GNU Emacs Texinfo mode.
* Headings:: How to write page headings and footings.
* Catching Mistakes:: How to find mistakes in formatting.
* Info Format Specification:: Technical details of the Info file format.
* GNU Free Documentation License:: Copying this manual.
* Command and Variable Index:: A menu containing commands and variables.
* General Index:: A menu covering many topics.
@detailmenu
--- The Detailed Node Listing ---
Overview of Texinfo
* Reporting Bugs:: Submitting effective bug reports.
* Output Formats:: Overview of the supported output formats.
* Info Files:: What is an Info file?
* Printed Books:: Characteristics of a printed book or manual.
* Adding Output Formats:: Man pages and implementing new formats.
* History:: Acknowledgements, contributors and genesis.
Writing a Texinfo File
* Command Syntax:: @@-commands are used for formatting.
* Conventions:: General rules for writing a Texinfo file.
* Comments:: Writing comments and ignored text in general.
* Minimum:: What a Texinfo file must have.
* Short Sample:: A short sample Texinfo file.
Beginning and Ending a Texinfo File
* Sample Beginning:: A sample beginning for a Texinfo file.
* Texinfo File Header:: The first lines.
* Document Permissions:: Ensuring your manual is free.
* Titlepage & Copyright Page:: Creating the title and copyright pages.
* Contents:: How to create a table of contents.
* The Top Node:: Creating the `Top' node and master menu.
* Global Document Commands:: Affecting formatting throughout.
* Ending a File:: What is at the end of a Texinfo file?
Texinfo File Header
* First Line:: The first line of a Texinfo file.
* Start of Header:: Formatting a region requires this.
* @code{@@setfilename}:: Tell Info the name of the Info file.
* @code{@@settitle}:: Create a title for the printed work.
* End of Header:: Formatting a region requires this.
Document Permissions
* @code{@@copying}:: Declare the document's copying permissions.
* @code{@@insertcopying}:: Where to insert the permissions.
Title and Copyright Pages
* @code{@@titlepage}:: Create a title for the printed document.
* @code{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center},
and @code{@@sp} commands.
* @code{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle},
and @code{@@author} commands.
* Copyright:: How to write the copyright notice and
include copying permissions.
* Heading Generation:: Turn on page headings after the title and
copyright pages.
The `Top' Node and Master Menu
* Top Node Example::
* Master Menu Parts::
Global Document Commands
* @code{@@documentdescription}:: Document summary for the HTML output.
* @code{@@setchapternewpage}:: Start chapters on right-hand pages.
* @code{@@headings}:: An option for turning headings on and off
and double or single sided printing.
* @code{@@paragraphindent}:: Specify paragraph indentation.
* @code{@@firstparagraphindent}:: Suppressing first paragraph indentation.
* @code{@@exampleindent}:: Specify environment indentation.
Nodes
* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
* Node Names:: How to choose node names.
* Writing a Node:: How to write an @code{@@node} line.
* Node Line Requirements:: Keep names unique.
* First Node:: How to write a `Top' node.
* @code{@@top} Command:: How to use the @code{@@top} command.
* Node Menu Illustration:: A diagram, and sample nodes and menus.
* @command{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers.
* Menus:: Listing subordinate nodes.
Menus
* Writing a Menu:: What is a menu?
* Menu Example:: Two and three part menu entries.
* Menu Location:: Menus go at the ends of nodes.
* Menu Parts:: A menu entry has three parts.
* Less Cluttered Menu Entry:: Two part menu entry.
* Other Info Files:: How to refer to a different Info file.
Chapter Structuring
* Tree Structuring:: A manual is like an upside down tree @dots{}
* Structuring Command Types:: How to divide a manual into parts.
* @code{@@chapter}:: Chapter structuring.
* @code{@@unnumbered @@appendix}::
* @code{@@majorheading @@chapheading}::
* @code{@@section}::
* @code{@@unnumberedsec @@appendixsec @@heading}::
* @code{@@subsection}::
* @code{@@unnumberedsubsec @@appendixsubsec @@subheading}::
* @code{@@subsubsection}:: Commands for the lowest level sections.
* @code{@@part}:: Collections of chapters.
* Raise/lower sections:: How to change commands' hierarchical level.
Cross-references
* References:: What cross-references are for.
* Cross Reference Commands:: A summary of the different commands.
* Cross Reference Parts:: A cross-reference has several parts.
* @code{@@xref}:: Begin a reference with `See' @dots{}
* Referring to a Manual as a Whole:: Refer to an entire manual.
* @code{@@ref}:: A reference for the last part of a sentence.
* @code{@@pxref}:: How to write a parenthetical cross-reference.
* @code{@@anchor}:: Defining arbitrary cross-reference targets
* @code{@@inforef}:: How to refer to an Info-only file.
* @code{@@url}:: How to refer to a uniform resource locator.
* @code{@@cite}:: How to refer to books not in the Info system.
@code{@@xref}
* One Argument:: @code{@@xref} with one argument.
* Two Arguments:: @code{@@xref} with two arguments.
* Three Arguments:: @code{@@xref} with three arguments.
* Four and Five Arguments:: @code{@@xref} with four and five arguments.
@code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}}
* @code{@@url} Examples:: Examples of using all the forms of @code{@@url}.
* URL Line Breaking:: How lines are broken within @code{@@url} text.
* @code{@@url} PDF Output Format:: A special option to hide links in PDF output.
* PDF Colors:: Colorizing urls and other links in PDF output.
Marking Text, Words and Phrases
* Indicating:: How to indicate definitions, files, etc.
* Emphasis:: How to emphasize text.
Indicating Definitions, Commands, etc.
* Useful Highlighting:: Highlighting provides useful information.
* @code{@@code}:: Indicating program code.
* @code{@@kbd}:: Showing keyboard input.
* @code{@@key}:: Specifying keys.
* @code{@@samp}:: Indicating a literal sequence of characters.
* @code{@@verb}:: Indicating a verbatim sequence of characters.
* @code{@@var}:: Indicating metasyntactic variables.
* @code{@@env}:: Indicating environment variables.
* @code{@@file}:: Indicating file names.
* @code{@@command}:: Indicating command names.
* @code{@@option}:: Indicating option names.
* @code{@@dfn}:: Specifying definitions.
* @code{@@abbr}:: Indicating abbreviations.
* @code{@@acronym}:: Indicating acronyms.
* @code{@@indicateurl}:: Indicating an example url.
* @code{@@email}:: Indicating an electronic mail address.
Emphasizing Text
* @code{@@emph @@strong}:: How to emphasize text in Texinfo.
* Smallcaps:: How to use the small caps font.
* Fonts:: Various font commands for printed output.
Quotations and Examples
* Block Enclosing Commands:: Different constructs for different purposes.
* @code{@@quotation}:: Writing a quotation.
* @code{@@indentedblock}:: Block of text indented on left.
* @code{@@example}:: Writing an example in a fixed-width font.
* @code{@@verbatim}:: Writing a verbatim example.
* @code{@@verbatiminclude}:: Including a file verbatim.
* @code{@@lisp}:: Illustrating Lisp code.
* @code{@@small@dots{}}:: Examples in a smaller font.
* @code{@@display}:: Writing an example in the current font.
* @code{@@format}:: Writing an example without narrowed margins.
* @code{@@exdent}:: Undo indentation on a line.
* @code{@@flushleft @@flushright}:: Pushing text flush left or flush right.
* @code{@@raggedright}:: Avoiding justification on the right.
* @code{@@noindent}:: Preventing paragraph indentation.
* @code{@@indent}:: Forcing paragraph indentation.
* @code{@@cartouche}:: Drawing rounded rectangles around text.
Lists and Tables
* Introducing Lists:: Texinfo formats lists for you.
* @code{@@itemize}:: How to construct a simple list.
* @code{@@enumerate}:: How to construct a numbered list.
* Two-column Tables:: How to construct a two-column table.
* Multi-column Tables:: How to construct generalized tables.
Making a Two-column Table
* @code{@@table}:: How to construct a two-column table.
* @code{@@ftable @@vtable}:: Automatic indexing for two-column tables.
* @code{@@itemx}:: How to put more entries in the first column.
@code{@@multitable}: Multi-column Tables
* Multitable Column Widths:: Defining multitable column widths.
* Multitable Rows:: Defining multitable rows, with examples.
Special Displays
* Floats:: Figures, tables, and the like.
* Images:: Including graphics and images.
* Footnotes:: Writing footnotes.
Floats
* @code{@@float}:: Producing floating material.
* @code{@@caption @@shortcaption}:: Specifying descriptions for floats.
* @code{@@listoffloats}:: A table of contents for floats.
Inserting Images
* Image Syntax::
* Image Scaling::
Footnotes
* Footnote Commands:: How to write a footnote in Texinfo.
* Footnote Styles:: Controlling how footnotes appear in Info.
Indices
* Index Entries:: Choose different words for index entries.
* Predefined Indices:: Use different indices for different kinds
of entries.
* Indexing Commands:: How to make an index entry.
* Printing Indices & Menus:: How to print an index in hardcopy and
generate index menus in Info.
* Combining Indices:: How to combine indices.
* New Indices:: How to define your own indices.
Combining Indices
* @code{@@syncodeindex}:: How to merge two indices, using @code{@@code}
font for the merged-from index.
* @code{@@synindex}:: How to merge two indices, using the
roman font for the merged-from index.
Special Insertions
* Special Characters:: Inserting @@ @{@} , \ #
* Inserting Quote Characters:: Inserting left and right quotes, in code.
* Inserting Space:: Inserting the right amount of whitespace.
* Inserting Accents:: Inserting accents and special characters.
* Inserting Quotation Marks:: Inserting quotation marks.
* Inserting Subscripts and Superscripts:: Inserting sub/superscripts.
* Inserting Math:: Formatting mathematical expressions.
* Glyphs for Text:: Inserting dots, bullets, currencies, etc.
* Glyphs for Programming:: Indicating results of evaluation,
expansion of macros, errors, etc.
* Inserting Unicode:: Inserting a Unicode character by code point.
Special Characters: Inserting @@ @{@} , \ #
* Inserting an Atsign:: @code{@@@@}, @code{@@atchar@{@}}.
* Inserting Braces:: @code{@@@{ @@@}}, @code{@@l rbracechar@{@}}.
* Inserting a Comma:: , and @code{@@comma@{@}}.
* Inserting a Backslash:: \ and @code{@@backslashchar@{@}}.
* Inserting a Hashsign:: # and @code{@@hashchar@{@}}.
Inserting Space
* Multiple Spaces:: Inserting multiple spaces.
* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
* Ending a Sentence:: Sometimes it does.
* @code{@@frenchspacing}:: Specifying end-of-sentence spacing.
* @code{@@dmn}:: Formatting a dimension.
Glyphs for Text
* @code{@@TeX @@LaTeX}:: The @TeX{} logos.
* @code{@@copyright}:: The copyright symbol (c in a circle).
* @code{@@registeredsymbol}:: The registered symbol (R in a circle).
* @code{@@dots}:: How to insert ellipses: @dots{} and @enddots{}
* @code{@@bullet}:: How to insert a bullet: @bullet{}
* @code{@@euro}:: How to insert the euro currency symbol.
* @code{@@pounds}:: How to insert the pounds currency symbol.
* @code{@@textdegree}:: How to insert the degrees symbol.
* @code{@@minus}:: How to insert a minus sign.
* @code{@@geq @@leq}:: How to insert greater/less-than-or-equal signs.
Glyphs for Programming
* Glyphs Summary::
* @code{@@result}:: How to show the result of expression.
* @code{@@expansion}:: How to indicate an expansion.
* @code{@@print}:: How to indicate generated output.
* @code{@@error}:: How to indicate an error message.
* @code{@@equiv}:: How to indicate equivalence.
* @code{@@point}:: How to indicate the location of point.
* Click Sequences:: Inserting GUI usage sequences.
Forcing and Preventing Breaks
* Break Commands:: Summary of break-related commands.
* Line Breaks:: Forcing line breaks.
* @code{@@- @@hyphenation}:: Helping @TeX{} with hyphenation points.
* @code{@@allowcodebreaks}:: Controlling line breaks within @@code text.
* @code{@@w}:: Preventing unwanted line breaks in text.
* @code{@@tie}:: Inserting an unbreakable but varying space.
* @code{@@sp}:: Inserting blank lines.
* @code{@@page}:: Forcing the start of a new page.
* @code{@@group}:: Preventing unwanted page breaks.
* @code{@@need}:: Another way to prevent unwanted page breaks.
Definition Commands
* Def Cmd Template:: Writing descriptions using definition commands.
* Def Cmd Continuation Lines:: Continuing the heading over source lines.
* Optional Arguments:: Handling optional and repeated arguments.
* @code{@@deffnx}:: Group two or more `first' lines.
* Def Cmds in Detail:: Reference for all the definition commands.
* Def Cmd Conventions:: Conventions for writing definitions.
* Sample Function Definition:: An example.
The Definition Commands
* Functions Commands:: Commands for functions and similar entities.
* Variables Commands:: Commands for variables and similar entities.
* Typed Functions:: Commands for functions in typed languages.
* Typed Variables:: Commands for variables in typed languages.
* Data Types:: The definition command for data types.
* Abstract Objects:: Commands for object-oriented programming.
Object-Oriented Programming
* Variables: Object-Oriented Variables.
* Methods: Object-Oriented Methods.
Internationalization
* @code{@@documentlanguage}:: Declaring the current language.
* @code{@@documentencoding}:: Declaring the input encoding.
Conditionally Visible Text
* Conditional Commands:: Text for a given format.
* Conditional Not Commands:: Text for any format other than a given one.
* Raw Formatter Commands:: Using raw formatter commands.
* Inline Conditionals:: Brace-delimited conditional text.
* @code{@@set @@clear @@value}:: Variable tests and substitutions.
* Testing for Texinfo Commands:: Testing if a Texinfo command is available.
* Conditional Nesting:: Using conditionals inside conditionals.
Flags: @code{@@set}, @code{@@clear}, conditionals, and @code{@@value}
* @code{@@set @@value}:: Expand a flag variable to a string.
* @code{@@ifset @@ifclear}:: Format a region if a flag is set.
* @code{@@inlineifset @@inlineifclear}:: Brace-delimited flag conditionals.
* @code{@@value} Example:: An easy way to update edition information.
Defining New Texinfo Commands
* Defining Macros:: Defining and undefining new commands.
* Invoking Macros:: Using a macro, once you've defined it.
* Macro Details:: Limitations of Texinfo macros.
* @code{@@alias}:: Command aliases.
* @code{@@definfoenclose}:: Customized highlighting.
* External Macro Processors:: @code{#line} directives.
External Macro Processors: Line Directives
* @samp{#line} Directive::
* TeX: @samp{#line} and @TeX{}.
* Syntax: @samp{#line} Syntax Details.
Include Files
* Using Include Files:: How to use the @code{@@include} command.
* @code{texinfo-multiple-files-update}:: How to create and update nodes and
menus when using included files.
* Include Files Requirements:: @code{texinfo-multiple-files-update} needs.
* Sample Include File:: A sample outer file with included files
within it; and a sample included file.
* Include Files Evolution:: How use of the @code{@@include} command
has changed over time.
Formatting and Printing Hardcopy
* Use @TeX{}:: Use @TeX{} to format for hardcopy.
* Format with @command{texi2dvi}:: The simplest way to format.
* Format with @command{tex}/@command{texindex}:: Formatting with explicit shell commands.
* Print with @command{lpr}:: How to print.
* Within Emacs:: How to format and print from an Emacs shell.
* Texinfo Mode Printing:: How to format and print in Texinfo mode.
* Compile-Command:: How to print using Emacs's compile command.
* Requirements Summary:: @TeX{} formatting requirements summary.
* Preparing for @TeX{}:: What to do before you use @TeX{}.
* Overfull hboxes:: What are and what to do with overfull hboxes.
* @code{@@smallbook}:: How to print small format books and manuals.
* A4 Paper:: How to print on A4 or A5 paper.
* @code{@@pagesizes}:: How to print with customized page sizes.
* Cropmarks and Magnification:: How to print marks to indicate the size
of pages and how to print scaled up output.
* PDF Output:: Portable Document Format output.
* Obtaining @TeX{}:: How to obtain @TeX{}.
Format with @command{tex}/@command{texindex}
* Formatting Partial Documents::
* Details of @command{texindex}::
@command{texi2any}: The Generic Translator for Texinfo
* Reference Implementation:: @command{texi2any}: the reference implementation.
* Invoking @command{texi2any}:: Running the translator from a shell.
* @command{texi2any} Printed Output:: Calling @command{texi2dvi}.
* Pointer Validation:: How to check that pointers point somewhere.
* Customization Variables:: Configuring @command{texi2any}.
* Internationalization of Document Strings:: Translating program-inserted text.
* Invoking @command{pod2texi}:: Translating Perl pod to Texinfo.
* @command{texi2html}:: An ancestor of @command{texi2any}.
Customization Variables
* Commands: Customization Variables for @@-Commands.
* Options: Customization Variables and Options.
* HTML: HTML Customization Variables.
* Other: Other Customization Variables.
Creating and Installing Info Files
* Creating an Info File::
* Installing an Info File::
Creating an Info File
* @command{makeinfo} Advantages:: @command{makeinfo} provides better error checking.
* @code{makeinfo} in Emacs:: How to run @code{makeinfo} from Emacs.
* @code{texinfo-format} commands:: Two Info formatting commands written
in Emacs Lisp are an alternative
to @code{makeinfo}.
* Batch Formatting:: How to format for Info in Emacs batch mode.
* Tag and Split Files:: How tagged and split files help Info
to run better.
Installing an Info File
* Directory File:: The top level menu for all Info files.
* New Info File:: Listing a new Info file.
* Other Info Directories:: How to specify Info files that are
located in other directories.
* Installing Dir Entries:: How to specify what menu entry to add
to the Info directory.
* Invoking @command{install-info}:: @code{install-info} options.
Generating HTML
* HTML Translation:: Details of the HTML output.
* HTML Splitting:: How HTML output is split.
* HTML CSS:: Influencing HTML output with Cascading Style Sheets.
* HTML Xref:: Cross-references in HTML output.
HTML Cross-references
* Link Basics: HTML Xref Link Basics.
* Node Expansion: HTML Xref Node Name Expansion.
* Command Expansion: HTML Xref Command Expansion.
* 8-bit Expansion: HTML Xref 8-bit Character Expansion.
* Mismatch: HTML Xref Mismatch.
* Configuration: HTML Xref Configuration. htmlxref.cnf.
* Preserving links: HTML Xref Link Preservation. MANUAL-noderename.cnf.
Sample Texinfo Files
* Short Sample Texinfo File::
* GNU Sample Texts::
* Verbatim Copying License::
* All-permissive Copying License::
Using Texinfo Mode
* Texinfo Mode Overview:: How Texinfo mode can help you.
* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
purpose editing features.
* Inserting:: How to insert frequently used @@-commands.
* Showing the Structure:: How to show the structure of a file.
* Updating Nodes and Menus:: How to update or create new nodes and menus.
* Info Formatting:: How to format for Info.
* Printing:: How to format and print part or all of a file.
* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
Updating Nodes and Menus
* Updating Commands:: Five major updating commands.
* Updating Requirements:: How to structure a Texinfo file for
using the updating command.
* Other Updating Commands:: How to indent descriptions, insert
missing nodes lines, and update
nodes in sequence.
Page Headings
* Headings Introduced:: Conventions for using page headings.
* Heading Format:: Standard page heading formats.
* Heading Choice:: How to specify the type of page heading.
* Custom Headings:: How to create your own headings and footings.
Catching Mistakes
* @command{makeinfo} Preferred:: @code{makeinfo} finds errors.
* Debugging with Info:: How to catch errors with Info formatting.
* Debugging with @TeX{}:: How to catch errors with @TeX{} formatting.
* Using @code{texinfo-show-structure}:: How to use @code{texinfo-show-structure}.
* Using @code{occur}:: How to list all lines containing a pattern.
* Running @code{Info-validate}:: How to find badly referenced nodes.
Finding Badly Referenced Nodes
* Using @code{Info-validate}:: How to run @code{Info-validate}.
* Unsplit:: How to create an unsplit file.
* Tagifying:: How to tagify a file.
* Splitting:: How to split a file manually.
Info Format Specification
* General: Info Format General Layout.
* Text: Info Format Text Constructs.
Info Format General Layout
* Whole: Info Format Whole Manual. Split vs.@: nonsplit manuals.
* Preamble: Info Format Preamble.
* Indirect: Info Format Indirect Table.
* Tag table: Info Format Tag Table.
* Local variables: Info Format Local Variables.
* Regular nodes: Info Format Regular Nodes.
Info Format Text Constructs
* Menu: Info Format Menu.
* Image: Info Format Image.
* Printindex: Info Format Printindex.
* Xref: Info Format Cross Reference.
@end detailmenu
@end menu
@c Reward readers for getting to the end of the menu :).
@c Contributed by Arnold Robbins.
@quotation
Documentation is like sex: when it is good, it is very, very good; and
when it is bad, it is better than nothing.
---Dick Brandon
@end quotation
@node Copying Conditions
@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
@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 or PostScript format, including chapters,
sections, cross-references, and indices. From the same Texinfo source
file, you can create an HTML output file suitable for use with a web
browser, you can create an Info file with special features to make
browsing documentation easy, and also create a Docbook file or a
transliteration to XML format.
@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.
You can edit a Texinfo file with any text editor, but it is especially
convenient to use GNU Emacs since that editor 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, it provides almost no commands for controlling
the final formatting. Texinfo is not intended to be a general-purpose
formatting program, so if you need to lay out a newspaper, devise a
glossy magazine ad, or follow the exact formatting requirements of
a publishing house, Texinfo may not be the simplest tool.
@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}.
@menu
* Reporting Bugs:: Submitting effective bug reports.
* Output Formats:: Overview of the supported output formats.
* Info Files:: What is an Info file?
* Printed Books:: Characteristics of a printed book or manual.
* Adding Output Formats:: Man pages and implementing new formats.
* History:: Acknowledgements, contributors and genesis.
@end menu
@node Reporting Bugs
@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. What's not critical is to ``narrow down'' the example to the
smallest possible input---the actual input with which you discovered
the bug will suffice. (Of course, if you do do experiments, the
smaller the input file, the better.)
@cindex Patches, contributing
Patches are most welcome; if possible, please make them with
@samp{@w{diff -c}} (@pxref{Top,,, diffutils, Comparing and Merging
Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,,
emacs, The GNU Emacs Manual}), and follow the existing coding style.
@node Output Formats
@section Output Formats
@cindex Output formats
@cindex Back-end output formats
Here is a brief overview of the output formats currently supported by
Texinfo.
@table @asis
@item Info
@cindex Info output, overview
(Generated via @command{makeinfo}.) 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}.
@item Plain text
@cindex Plain text output, overview
(Generated via @command{makeinfo --plaintext}.) This is almost the
same as Info output with the navigational control characters are
omitted.
@item HTML
@cindex HTML output, overview
@cindex W3 consortium
@cindex Mozilla
@cindex Lynx
@cindex Emacs-W3
(Generated via @command{makeinfo --html}.) HTML, standing for Hyper
Text Markup Language, has become the most commonly used language for
writing documents on the World Wide Web. Web browsers, 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{makeinfo} tries to use 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. For details of the HTML language and
much related information, see @uref{http://www.w3.org/MarkUp/}.
@xref{Generating HTML}.
@item DVI
@cindex DVI output, overview
@pindex dvips
@pindex xdvi
(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}.
(Be aware that the Texinfo language is very different from and much
stricter than @TeX{}'s usual languages: plain @TeX{}, @LaTeX{},
Con@TeX{}t, etc.)
@item PostScript
@cindex PostScript output, overview
(Generated via @command{texi2dvi --ps}.) PostScript is a page
description language that became widely used around 1985 and is still
used today. @uref{http://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}.
@item PDF
@cindex PDF output, overview
@cindex Beebe, Nelson
(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{http://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}.
@item Docbook
@cindex Docbook output, overview
@cindex XML Docbook output, overview
(Generated via @command{makeinfo --docbook}.) This is an XML-based
format developed some years ago, 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.
@item XML
@cindex XML Texinfo output, overview
@cindex Texinfo XML output, overview
@cindex DTD, for Texinfo XML
@pindex texinfo.dtd
@pindex txixml2texi
(Generated via @command{makeinfo --xml}.) XML is a generic syntax
specification usable for any sort of content (a reference is at
@uref{http://www.w3.org/XML}). The @command{makeinfo} XML output,
unlike all the other output formats, is a transliteration of the
Texinfo source rather than processed output. That is, it translates
the Texinfo markup commands into XML syntax, for further processing by
XML tools. The details of the output are defined in an XML DTD as
usual, which is contained in a file @file{texinfo.dtd} included in the
Texinfo source distribution and available via the Texinfo web pages.
The XML contains enough information to recreate the original content,
except for syntactic constructs such as Texinfo macros and
conditionals. The Texinfo source distribution includes a utility script
@file{txixml2texi} to do that backward transformation.
@end table
@node Info Files
@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