texinfo.texinfo

早期freebsd实现

@menu
* Info on a Region::		Formatting part of a file for Info.
* Showing the Structure::	Showing the structure of a file.
* Inserting::			Inserting frequently used commands. 
@end menu

@node Info on a Region, Showing the Structure, Texinfo Mode, Texinfo Mode
@comment  node-name,  next,  previous,  up
@section Formatting a Region for Info
@cindex  Running Info on a region
@cindex  Info, formatting on a region
@findex texinfo-format-region

To see what part of a Texinfo file will look like after it has been
transformed into an Info file, use the command @kbd{C-c C-f}
(@code{texinfo-format-region}).  This command formats the current region of
the Texinfo file for Info and writes it to a temporary buffer called
@samp{*Info Region*}.@refill

For @code{texinfo-format-region} to work, the file @strong{must} include a
line that has @code{@@setfilename} in its header.@refill

The command is:

@table @kbd
@item  C-c C-f 
texinfo-format-region
@end table

@node Showing the Structure, Inserting, Info on a Region, Texinfo Mode     
@comment  node-name,  next,  previous,  up
@section Showing the Structure of a File
@cindex  Showing the structure of a file
@cindex Structure of a file, showing it
@cindex File structure, showing it
@cindex Texinfo file structure, showing it

You can show the structure of a Texinfo file by using the @kbd{C-c C-s}
command (@code{texinfo-show-structure}).  This command shows the structure
of a Texinfo file by listing the lines with the @@-commands for
@code{@@node}, @code{@@chapter}, @code{@@section} and the like.  These
lines are displayed in another window called the @samp{*Occur*} window.  In
that window, you can position the cursor over one of the lines and use the
@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to the
corresponding spot in the Texinfo file.@refill

The two commands are:

@table @kbd
@item  C-c C-s 
texinfo-show-structure

@item  C-c C-c
occur-mode-goto-occurrence
@end table

Often, when you are working on a manual, you will be interested only in the
structure of the current chapter.  In this case, you can mark off the
region of the buffer that you are interested in with the @kbd{C-x n}
(@code{narrow-to-region}) command and @code{texinfo-show-structure} will
work on only that region.  (To see the whole buffer again, use @kbd{C-x w}
(@code{widen}).)@refill

@node     Inserting, , Showing the Structure, Texinfo Mode
@comment  node-name,  next,  previous,  up
@section Inserting Frequently Used Commands
@cindex Inserting frequently used commands
@cindex Frequently used commands, inserting them
@cindex Commands, inserting them

Texinfo mode provides commands that insert various frequently used
@@-commands into the buffer.  You can use these commands to save
keystrokes.  And you can insert balanced curly braces with the @kbd{M-@{}
command, (@code{texinfo-insert-braces}) and later use the @kbd{M-@}}
command (@code{up-list}) to move forward past the closing brace.@refill

The special commands are invoked by typing @kbd{C-c} twice and then the
first letter of the @@-command.

@table @kbd
@item  C-c C-c c
texinfo-insert-@@code

@item  C-c C-c d 
texinfo-insert-@@dfn

@item  C-c C-c e 
texinfo-insert-@@end

@item  C-c C-c i 
texinfo-insert-@@item

@item  C-c C-c n 
texinfo-insert-@@node

@item  C-c C-c s
texinfo-insert-@@samp

@item  C-c C-c v
texinfo-insert-@@var

@item M-@{ 
texinfo-insert-braces

@item M-@} 
up-list
@end table

This list was generated by analyzing the frequency with which commands were
used in the @cite{GNU Emacs Manual} and the @cite{GDB Manual}.  If you wish
to add your own insert commands, you can bind a keyboard macro to a key, use
abbreviations or extend the code in @file{texinfo.el}.

@node Beginning a File, Ending a File, Texinfo Mode, Top
@comment  node-name,  next,  previous,  up
@chapter Beginning a Texinfo File
@cindex Beginning a Texinfo file
@cindex Texinfo file beginning
@cindex File beginning

Various pieces of information have to be provided to Texinfo at the
beginning of a Texinfo file, such as the name of the file, the title
of the document and the like.  Generally, the beginning of a Texinfo file
has four parts:

@enumerate
@item 
The header, marked by start-of-header and end-of-header lines, that
includes the commands for naming the Texinfo file and telling @TeX{} what
definitions' file to use when processing the file.

@item 
A section, marked by the @code{@@ifinfo} and @code{@@end ifinfo} commands,
that contains a short statement of what the file is about, the copyright
notice and copying permissions. This section appears only in the Info file.

@item 
A section, marked by the @code{@@titlepage} and @code{@@end titlepage}
commands, that contains the title page, the copyright page and copying
permissions.  This section appears only in the printed manual.

@item
The @samp{Top} node that contains an extensive menu for the whole Info
file.  The contents of this node only appear in the Info file.
@end enumerate

If the Texinfo file has a section containing licensing information and a
warranty disclaimer, that section usually follows the @samp{Top} node.  The
licensing section will be followed by a preface or else by the first
chapter of the manual.

Since the copyright notice and the copying permissions are in sections that
appear only in the Info file or only in the printed manual, this
information has to be repeated twice.

The following sample shows what is needed.

@example
\input texinfo   @@c -*-texinfo-*-
@@comment %**start of header (This is for running Texinfo on a region.)
@@setfilename name-of-texinfo-file
@@settitle Name of Manual
@@setchapternewpage odd
@@comment %**end of header (This is for running Texinfo on a region.)

@@ifinfo
This file documents @dots{}

Copyright @@copyright@{@} year  copyright-owner

Permission is granted to @dots{}
@@end ifinfo

@@titlepage
@@sp 10
@@center @@titlefont@{Name of Manual When Printed@}
@@sp 2
@@center Subtitle, If Any
@@sp 2
@@center Author

@@comment  The following two commands start the copyright page.
@@page
@@vskip 0pt plus 1filll
Copyright @@copyright@{@} year copyright-owner

Published by @dots{}

Permission is granted to @dots{}
@@end titlepage


@@node Top, Overview, (dir), (dir)

@@menu
* First Chapter::		The first chapter is usually an overview.
* Second Chapter::		@dots{}
  <many more menu items here>
@@end menu

@@node    First Chapter, Second Chapter, top,      top
@@comment node-name,     next,           previous, up
@@chapter First Chapter
@@cindex Reference to First Chapter
@end example

@menu
* Header::			Necessary first lines.
* Permissions for Info::	Copyright notice and copying permissions.
* Titlepage & Copyright Page::	Printed title and copyright pages.
* Top Node::			The top node and master menu.
* License and Distribution:: 	The importance of the license. 
@end menu

@node Header, Permissions for Info , Beginning a File, Beginning a File
@comment  node-name,  next,  previous,  up
@section The Texinfo File Header
@cindex Header for Texinfo files
@cindex Texinfo file header

Texinfo files start with at least three lines that provide Info and @TeX{}
with necessary information.  If you want to run @TeX{} on just a part of
the Texinfo File, you also have to mark these heading lines with
start-of-header and end-of-header lines.@refill

@menu
* 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.
* End-of-Header::		Identifying the end of the header.
@end menu

@node     First Line, Start-of-Header, Header, Header
@comment  node-name,  next,  previous,  up
@subsection The First Line of a Texinfo File
@cindex First line of a Texinfo file
@cindex Beginning line of a Texinfo file


Every Texinfo file that is to be the top-level input to @TeX{} must begin
with a line that looks like this:

@example
\input texinfo   @@c -*-texinfo-*-
@end example

@noindent
The line serves two functions:

@enumerate
@item 
When the file is processed by @TeX{}, it loads the macros needed for
processing a Texinfo file.  These are in a file called @file{texinfo.tex}
which is usually located in the @file{/usr/lib/tex/macros} directory.@refill

@item 
When the file is edited in GNU Emacs, it causes Texinfo mode to be used.@refill
@end enumerate

The @samp{\input texinfo} line should be followed by the start-of-header
line.  This makes it possible for the command for running @TeX{} on a part
of the Texinfo file (@code{texinfo-hardcopy-region}) to operate.  The
reason for this is that the @code{texinfo-hardcopy-region} command will
look on the line preceding the start-of-header line for the @samp{\input
texinfo} line.

@node Start-of-Header, Setfilename, First Line, Header
@comment  node-name,  next,  previous,  up
@subsection @samp{start-of-header}
@cindex start-of-header
@findex start-of-header

The start-of-header line should immediately follow the first line of the
Texinfo file.  

@ifinfo
The @code{texinfo-hardcopy-region} command will look at the
line preceding the start-of-header line to find the @samp{\input
texinfo} line.
@end ifinfo

Usually, the start-of-header line looks like this:

@example
@@comment %**start of header (This is for running Texinfo on a region.)
@end example

The reason for the odd string of characters (@samp{%**}) is so that the
@code{texinfo-hardcopy-region} command does not accidently find something
that it shouldn't when it is looking for the header.

In the default configuration, the phrase @samp{(This is for running Texinfo
on a region.)} is not needed and is just included to make it easier for
someone reading the Texinfo file.

The start-of-header line and the end-of-header line are Texinfo mode
variables that you can change.

@node     Setfilename, Settitle, Start-of-Header, Header
@comment  node-name,  next,  previous,  up
@subsection @@setfilename
@cindex Setfilename command
@cindex Info file requirement for @@setfilename
@findex setfilename

In order to be made into an Info file, a Texinfo file must contain a line
that looks like this:
@example
@@setfilename @var{info-file-name}
@end example

@noindent
This line specifies the name of the Info file to be generated.  In fact, there
can be other things in the file before this line, but they are ignored in
the generation of an Info file.  The @code{@@setfilename} line is ignored
when a printed manual is generated.
 
@node Settitle, Setchapternewpage, Setfilename, Header
@comment  node-name,  next,  previous,  up
@subsection @@settitle
@findex settitle

In order to be made into a printed manual file, a Texinfo file must contain
a line that specifies the title of the manual.  Texinfo uses this
information during printing to put the title on every other page as a
heading; Texinfo puts the current chapter title on the other pages.
Texinfo can find the name of the chapter title from the information
provided by the @code{@@chapter} command, but you must tell it the manual
title with @code{@@settitle}:

@example
@@settitle @var{Title}
@end example

@noindent
This command, on a line by itself, causes @var{title} to be used for the