texinfo.texinfo

早期freebsd实现

headings.  Usually, you will use the same words for the title on the title
page and for the title specified by this command for the headings, but the
two could be different.  For example, the title on the title page may be
longer than the title specified by the @code{settitle} command.

The @code{@@settitle} command should precede everything that generates
actual output.

@node Setchapternewpage, End-of-Header, Settitle, Header
@comment  node-name,  next,  previous,  up
@subsection @@setchapternewpage
@cindex Starting chapters
@cindex Pages, starting odd
@findex setchapternewpage

Conventionally, chapters start on the page on the right hand side of a
book; and the right hand page has an odd number.  To make sure that Texinfo
does this, you can use the command @code{@@setchapternewpage}.  For
example, to cause each chapter to start on a fresh odd-numbered page:

@example
@@setchapternewpage odd
@end example

Page numbering is turned on by the @code{@@end titlepage} command, so the
@code{@@setchapternewpage} should come before it.  Although it can occur
anywhere in the beginning of the file, it is most convenient to put it in
this location.


@node End-of-Header, , Setchapternewpage, Header
@comment  node-name,  next,  previous,  up
@subsection  @samp{end-of-header}
@cindex end-of-header

The end-of-header line should follow the line containing the
@code{@@setchapternewpage} command.

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

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

@ifinfo
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 reason for the odd string of characters (`%**') 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.

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

@iftex
Also, @pxref{Start-of-Header}
@end iftex

@node Permissions for Info,  Titlepage & Copyright Page, Header, Beginning a File
@comment  node-name,  next,  previous,  up
@section Copying Permissions for Info

Since the title page and the copyright page appear only in the printed copy
of the manual, the same information has to inserted in a section that
appears only in the Info file.  This section usually contains a brief
description of the contents of the Info file, a copyright notice and
copying permissions.

The copyright notice should read:

@example
Copyright @var{year} @var{copyright-owner}
@end example

@noindent
and be put on a line by itself.

Standard text for the copyright permissions is contained in the appendix.
@xref{Ifinfo Permissions}, for the complete text.

@node Titlepage & Copyright Page, Top Node, Permissions for Info, Beginning a File
@comment  node-name,  next,  previous,  up
@section The Title and Copyright Pages
@cindex Titlepage
@cindex Copyright page

The title and copyright pages appear in the printed manual, but not in the
Info file.  Because of this, it is possible to use a couple of slightly
obscure @TeX{} typesetting commands that could not be used in an Info file.
In addition, this part of the beginning of a Texinfo file contains the text
of the copying permissions that will appear in the printed manual.

@menu
* Titlepage::			Creating a title page for the printed manual.
* Center::			Centering a line.
* Copyright & Printed Permissions:: 	Inserting the copyright notice 
					and printed permissions.
@end menu

@node     Titlepage, Center , Titlepage & Copyright Page, Titlepage & Copyright Page
@comment  node-name,  next,  previous,  up
@subsection @@titlepage
@cindex Titlepage
@findex titlepage

Start the material for the title page and following copyright page with
@code{@@titlepage} on a line by itself and end it with @code{@@end
titlepage} on a line by itself.  The title page and copyright page material
appears only in the printed manual, not in the Info file.  

Also, the @code{@@end titlepage} command starts a new page and turns on
page numbering (generation of headings).  Therefore, all the material that
you want to appear on unnumbered pages should be put between the
@code{@@titlepage} and @code{@@end titlepage} commands.  By using the
@code{@@page} command you can force a page break within the region
delineated by the @code{@@titlepage} and @code{@@end titlepage} commands
and create more than one unnumbered page.  This is how the copyright page
is produced.@refill

@findex titlefont
To select a large font suitable for the title itself, you can use the
command @code{@@titlefont}.  For example:

@example
@@center @@titlefont@{Texinfo@}
@end example

Also, you can use @code{@@sp} commands to adjust vertical spacing.  
For example:

@example
@@sp 2
@end example

@noindent
In the sample, the spacing was chosen to fit an 8 1/2 by 11 inch manual.

@node Center, Copyright & Printed Permissions, Titlepage, Titlepage & Copyright Page
@comment  node-name,  next,  previous,  up
@subsection @@center
@cindex Centering a line
@findex center

A line containing @code{@@center @var{text}} produces a line of output
containing @var{text}, centered between the margins.@refill



@node     Copyright & Printed Permissions,, Center, Titlepage & Copyright Page
@comment  node-name,  next,  previous,  up
@subsection The Copyright Page and Printed Permissions
@cindex Copyright
@cindex Printed permissions
@cindex Permissions, printed

By international treaty, the copyright notice for a book should either be
on the title page or on the back of the title page.  Other locations in a
book are not official and do not provide copyright protection.  The
copyright notice should include the year followed by the name of the person
or organization who has the copyright.

When the copyright notice is on the back of the title page, the page is not
numbered.  Therefore, in Texinfo, the information on the copyright page
should be within the region delineated by the @code{@@titlepage} and
@code{@@end titlepage} commands.@refill

@findex vskip
@findex filll
To cause a page break, the @code{@@page} command is used.  In the sample,
the @code{@@page} command is followed by the somewhat mysterious line that
reads: @samp{@@vskip 0pt plus 1filll}.  This is a line that uses @TeX{}
commands to push the copyright notice and the other text on the copyright
page towards the bottom of the page.  The @code{@@vskip} command means to
skip lines and put in white space.  The @samp{0pt plus 1filll} means to put
in zero points of mandatory white space, and as much optional white space
as needed.  Note the use of three @samp{l}s in the word @samp{filll}; this
is the correct use in @TeX{}.@refill

@findex copyright
The @code{@@copyright@{@}} command generates a @samp{c} inside a circle.
The copyright notice itself has the following legally defined sequence: 

@example
Copyright @copyright{} @var{year} @var{copyright-owner}
@end example

It is customary to put information on how to get a manual after the
copyright notice (the address of the Free Software Foundation, for example)
and the permissions.  

Note that the permissions have to be repeated here as well as in the
`ifinfo' section that immediately follows the header since this section
appears only in the printed manual and the `ifinfo' section appears only in
the Info file.

Standard text for the permissions appears in the appendix.  
@xref{Sample Permissions}.

@node Top Node, License and Distribution, Titlepage & Copyright Page, Beginning a File    
@comment  node-name,  next,  previous,  up
@section The Top Node and Master Menu
@cindex Top node
@cindex Master menu

The @samp{Top} node contains an extensive, master menu for the whole Info
file.  The contents of this node appear only in the Info file.  Nothing in
this node should appear in the printed file.  Since a node line by itself
and a menu by itself are not printed, the contents of this node do not have
to be within a region delineated by @code{@@ifinfo} and @code{@@end ifinfo}
commands.  However, any text within the node should be marked off in that
manner.  You may want to put a short summary before the master menu inside
a region delineated by @code{@@ifinfo} and @code{@@end ifinfo} commands.
Usually, the `Previous' and `Up' nodes refer to the top level directory of
the whole Info system, with pointers to @samp{(dir)}.@refill

Generally, the top menu is divided into parts.  

@itemize @bullet

@item
The first part contains the major nodes in the Texinfo file: the nodes for
the chapters, chapter-like sections and the major appendices.

@item
The second part contains entries for the indices.  In an Info file, it is
very useful to have indices here at the beginning of the file in the top
node rather than at the end, as in a printed book.

@item
The third and subsequent parts contain a listing of the other, lower level
nodes, often ordered by chapter.  This way, an inquirer can go directly to
a particular node if he or she is searching for specific information.
(These nodes are not required; use them if you think they are a
convenience.)
@end itemize

Each section in the menu can be introduced a descriptive line.  So long as
the line does not begin with an asterisk, it will not be treated as a menu
item.  (@xref{Menu, , Making Menus}, for more information.)

For example, the Top node of this manual looks like this (but with many
more entries):

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

@@menu
* Overview::                    What is Texinfo?
* Texinfo Mode::                Special features in GNU Emacs.
@dots{}

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.

Using Texinfo Mode
* Info on a Region::            Formatting a region for Info.
* Showing the Structure::       Showing the structure of a file.
@dots{}
@dots{}
@end example


@node License and Distribution, , Top Node, Beginning a File
@comment  node-name,  next,  previous,  up
@section Licensing and Distribution Information
@cindex Distribution
@cindex License agreement

If the Texinfo file has a section containing the ``General Public License''
and the distribution information and a warranty disclaimer, this section
usually follows the @samp{Top} node.  The licensing and distribution
information and the disclaimer are followed by a preface or else by the
first chapter of the manual.

The licensing agreement is very important to Project GNU documentation and
software.  Without it, you may find that you can no longer get the software
or its documentation.  This sounds paradoxical, but the state of the world
is such that documentation and software that does not have a
``restrictive'' license to make them freely distributable may be lost to
the public.  This has happened.@refill

For a good example of the text that could be used for the Distribution,
General Public License and NO WARRANTY sections of your document, see the
latest version of the @cite{GNU Emacs Manual}.

@cindex Preface
Although a preface is not a required part of a Texinfo file, it is very
helpful.  Ideally, it should state clearly and concisely what the file is
about and who would be interested in reading it.  In general, the preface
would follow the licensing and distribution information, although sometimes
people put it earlier in the document.  Usually, a preface is put in an
@code{@@unnumbered} section.  (@xref{Unnumbered and Appendix}.)

@node     Ending a File, Structuring, Beginning a File, Top
@comment  node-name,  next,  previous,  up
@chapter Ending a Texinfo File
@cindex Ending a Texinfo file
@cindex Texinfo file ending
@cindex File ending
@findex bye

The end of a Texinfo file should include the indices, the commands to
generate detailed and summary tables of contents and the @@-command
that tells @TeX{} that it has reached the end of the file.

For example, a Texinfo file might be ended as follows:

@example
@@node    Concept Index,     , Previous Node, Top
@@comment node-name,     next, previous,      up
@@unnumbered Concept Index

@@printindex cp

@@contents
@@bye
@end example

The @code{@@bye} command should be on a line by itself and every Texinfo
file must end with such a line.  This command terminates @TeX{} processing
and forces out unfinished pages.@refill

@menu
* Contents::		Generating a table of contents
* Indices::		Generating, sorting and printing indices
@end menu

@node     Contents, Indices , , Ending a File