texinfo.texinfo

早期freebsd实现

\input texinfo    @c -*-texinfo-*-
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename ../info/texinfo
@settitle Texinfo 1.1
@comment %**end of header (This is for running Texinfo on a region.)

@iftex
@finalout
@end iftex

@ifinfo
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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
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.
@end ifinfo

@setchapternewpage odd
@titlepage
@sp 11
@center @titlefont{Texinfo}
@sp 2
@center The GNU Documentation Format
@sp 2
@center by Richard M. Stallman and Robert J. Chassell
@sp 2
@center Edition 1.1
@sp 2
@center May 1988

@comment   Include the Distribution inside the titlepage environment so
@c that headings are turned off. 

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1988 Free Software Foundation, Inc.

@sp 2
This is version 1.1 of the Texinfo documentation, and is for @*
the Texinfo that is distributed as part of Version 18 of GNU Emacs.
@sp 2

Published by the Free Software Foundation @*
675 Massachusetts Avenue, @*
Cambridge, MA 02139 USA @*
Printed copies are available for $10 each.

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.

@end titlepage


@node Top, License, (dir), (dir)

@menu
* License::			Licensing information.
* Overview::			What is Texinfo?
* Texinfo Mode::		Special features in GNU Emacs.
* Beginning a File::	 	What to put at the beginning of a Texinfo file.
* Ending a File::	 	What to put at the end of a Texinfo file.
* Structuring::	 		How to make nodes and chapters.
* Quotations and Examples::	How to insert quotations and examples.
* Lists and Tables::	 	How to make lists and tables.
* Cross References::	 	How to make cross references.
* Formatting Paragraphs::	How to format paragraphs.
* Marking Text::	 	How to mark code, definitions, variables etc.
* Conditionals::	 	Putting text in only Info or the printed work.
* Printing Hardcopy::	 	How to print a hardcopy of the manual.
* Creating an Info File::	How to create an on-line Info file.
* Catching Mistakes::		How to find problems.

Indices, nodes containing large menus

* Command Index:: 		An item for each @@-command.
* Concept Index::  		An item for each concept.

A detailed node listing

Overview
* Info File::			Characteristics of the Info file.
* Printed Manual::		Characteristics of the printed manual.
* Conventions::			General syntactic conventions.
* Short Sample::	        A short sample Texinfo file.

Using Texinfo Mode
* Info on a Region::		Formatting a region for Info.
* Showing the Structure::	Showing the structure of a file.
* Inserting::			Inserting frequently used commands.

Beginning a Texinfo File.
* First Line::			The first line of a Texinfo file.
* Start-of-Header::		Identifying the start of the header.
* Setfilename::			Specifying the name of the Info file.
* Settitle::			Specifying the title used by the headings.
* Setchapternewpage::		Starting chapters on odd numbered pages.
* Titlepage::			The title and copyright page.
* Center::			Centering a line.
* Copyright & Printed Permissions:: Ensuring free distributability.
* Top Node::			The master menu.  
* License and Distribution::	Your are free to copy and distribute this.

Ending a Texinfo File
* Contents::			Generating tables of contents.
* Indices::			Generating indices.
* Index Entries::		Defining the entries of an index.
* Combining Indices::		Putting two or more indices together.
* Printing Indices & Menus::	Printing an index and generating menus.

Node and Chapter Structuring
* Chapter::			Creating a chapter.
* Unnumbered and Appendix::	Chapter-like parts.
* Section::			Creating sections
* Subsection::			Creating subsections.
* Subsubsection::		Creating subsubsections.

* Node::			Creating nodes.
* Menu::			Creating menus.


Making quotations and examples
* Quotation::			Inserting long quotations.
* Example::			Inserting examples of code and the like.
* Display::			Inserting displayed text.

Making lists and two column tables
* Itemize::			Creating itemized lists.
* Enumerate::			Creating enumerated lists.
* Table::			Creating two column tables.
* Itemx::			Putting an extra item in the 
				first column of a table.

Making Cross References
* Xref::			Making a regular cross reference.
* Pxref::			Making a parenthetical cross reference.
* Inforef::			Making a cross reference to an Info file.


Formatting Paragraphs
* Refilling & Noindent::	Refilling paragraphs 
				and preventing indentation
* Refill::			Using the @code{@@refill} command.
* Noindent::			Using the @code{@@noindent} command.


Breaks, Blank Lines and Groups
* Line Breaks::			Inserting line breaks in @TeX{}.
* Sp::				Inserting blank lines.
* Br::				Inserting paragraph breaks.
* W::				Preventing line breaks.
* Page::			Starting new pages.
* Group::			Holding text together on one page.
* Need::			Keeping text together.

Marking Text Within a Paragraph
* 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.

Inserting Braces, @samp{@@} and Periods
* Braces Atsigns Periods::	Inserting braces, @samp{@@} and periods.
* Dots Bullets Tex::		Inserting dots, bullets and the @TeX{} logo
* Emphasis::			Emphasizing text.

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

Creating an Info File
* Installing an Info File::	Putting the Info file in the 
				@file{info} directory.

Catching Mistakes
* Debugging with Info::    	    Catching errors with info formatting.
* Using the Emacs Lisp Debugger::   Using the Emacs Lisp Debugger
* Debugging with Tex::		    Catching errors with @TeX{} formatting.
* Using texinfo-show-structure::    Using @code{texinfo-show-structure}
				    to catch mistakes.
* Using Occur::			    Using @code{occur} to catch mistakes.
* Running Info-Validate::	    Checking for unreferenced nodes.

Finding badly referenced nodes
* Info-Validating a Large File::     Running @code{Info-validate} 
				     on a large file.
* Splitting::                        Splitting a file manually.

Appendices
* Command Syntax::		Details about the syntax.
* Include Files::		Making one printed file out of 
				several Info files.
* TeX Input::			Where @TeX{} finds its @samp{\input} file.
* Sample Permissions::		You may copy GNU Software.
* Ifinfo Permissions::		What to put in the `ifinfo' section.
* Titlepage Permissions::	What to put in the `@@titlepage' section.
@end menu

@node     License,   Overview,  Top, Top 
@comment  node-name, next, previous,  up
@unnumbered Licensing Information

  The programs currently being distributed that relate to Texinfo
include two portions of GNU Emacs, plus two other separate programs
(@code{texindex} and @code{texinfo.tex}).  These programs are
@dfn{free}; this means that everyone is free to use them and free to
redistribute them on a free basis.  The Texinfo related programs are not
in the public domain; they are copyrighted and there are restrictions on
their 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 these programs 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.  The programs that are part of GNU Emacs
are covered by the GNU Emacs copying terms (@pxref{License, , , emacs,
The GNU Emacs Manual}), and other programs are covered by licenses that
are contained in their source files.

@node Overview, Texinfo Mode, License, Top
@comment  node-name,  next,  previous,  up
@chapter Overview of Texinfo
@cindex Overview of Texinfo
@cindex Texinfo overview

Texinfo is a documentation system that uses a single source file for both
on-line help and a printed manual.  This means that instead of writing two
different documents, one for the on-line help and the other for the printed
manual, only one document needs to be written.  When the system is revised,
only one file has to be revised.@refill

Using Texinfo, you can create a document with the normal features of a book
such as chapters, sections, cross references and indices.  The chapters and
sections of the printed manual can be made to correspond to the nodes of
the on-line help.  The cross references and indices can be used in both the
on-line help and in the printed document.  Indices are generated
semi-automatically.  The @cite{GNU Emacs Manual} is a good example of a
Texinfo file.@refill

To make the printed manual, the Texinfo source file is processed by the
@TeX{} typesetting program; the resulting DVI file can be typeset and
printed as a book.  To make the on-line help, the Texinfo source file is by
processed the @kbd{M-x texinfo-format-buffer} command; the resulting Info
file is installed in the @file{info} directory.@refill

Since the Texinfo source file is used for a dual task---to create both the
on-line help and the printed manual---it must be written in a special
format that uses @@-commands (words preceded by an @samp{@@}) to indicate
chapters, sections, nodes, examples, index entries and the like.@refill

Before writing a Texinfo source file, you should be familiar with the
on-line Info documentation reading program.  (@inforef{Info, info, info},
for more information.)  If you are writing a document that will be both
on-line and printed, you will need both Info and @TeX{}.

To make an Info file, you use the @kbd{M-x texinfo-format-buffer} command
in GNU Emacs.@refill

To make a printed manual, you need to use @TeX{}, a powerful,
sophisticated typesetting program written by Donald Knuth.  @TeX{} is
freely distributable. It is written in a dialect of Pascal called WEB and
can be compiled either in Pascal or (by using a conversion program that
comes with the @TeX{} distribution) in C.  (For information about getting
@TeX{}, @pxref{TeX Mode, , , emacs, The GNU Emacs Manual})

When @TeX{} processes a Texinfo source file, @TeX{} makes use of a macro
definitions file called @file{texinfo.tex} that comes with the GNU Emacs
distribution in the @file{emacs/man} sources directory.  (The first line of
every Texinfo file has a command that says @code{\input texinfo}; this
tells @TeX{} to use the @file{texinfo.tex} file.)@refill

If the @file{texinfo.tex} file has not already been copied to the directory
which contains the other @TeX{} macro definition files when Emacs was
installed, you will probably want to copy it to that directory.  Usually,
this is the @file{/usr/lib/tex/macros} directory.  For more information,
@pxref{TeX Input, , @TeX{} Input Initialization}

Documentation for GNU utilities and libraries should be written in Texinfo
format.