C.2 GNU Sample Texts

Following is a sample Texinfo document with the full texts that should be used in GNU manuals.

As well as the legal texts, it also serves as a practical example of how many elements in a GNU system can affect the manual. If you're not familiar with all these different elements, don't worry. They're not required and a perfectly good manual can be written without them. They're included here nonetheless because many manuals do (or could) benefit from them.

See Short Sample, for a minimal example of a Texinfo file. See Beginning a File, for a full explanation of that minimal example.

Here are some notes on the example:

• The `$Id:' comment is for the CVS (see Overview) or RCS (see rcsintro(1)) version control systems, which expand it into a string such as:

            $Id: GNU-Sample-Texts.html,v 1.1 2005/04/06 05:39:38 Bronger Exp $
       

  (This is useful in all sources that use version control, not just manuals.) You may wish to include the `$Id:' comment in the @copying text, if you want a completely unambiguous reference to the documentation version.

  If you want to literally write $Id$, use @w: @w{$}Id$.

• The version.texi in the @include command is maintained automatically by Automake (see Introduction). It sets the `VERSION' and `UPDATED' values used elsewhere. If your distribution doesn't use Automake, but you do use Emacs, you may find the time-stamp.el package helpful (see Time Stamps).
• The @syncodeindex command reflects the recommendation to use only one index where possible, to make it easier for readers to look up index entries.
• The @dircategory is for constructing the Info directory. See Installing Dir Entries, which includes a variety of recommended category names.
• The `Invoking' node is a GNU standard to help users find the basic information about command-line usage of a given program. See Manual Structure Details.
• It is best to include the entire GNU Free Documentation License in a GNU manual, unless the manual is only a few pages long. Of course this sample is even shorter than that, but it includes the FDL anyway in order to show one conventional way to do so. The fdl.texi file is available on the GNU machines and in the Texinfo and other GNU source distributions.

  The FDL provides for omitting itself under certain conditions, but in that case the sample texts given here have to be modified. See GNU Free Documentation License.

• If your manual has invariant sections (again, see the license itself for details), then don't forget to change the text here accordingly.
• For documents that express your personal views, feelings or experiences, it is more appropriate to use a license permitting only verbatim copying, rather than the FDL. See Verbatim Copying License.

Here is the sample document:

\input texinfo   @c -*-texinfo-*-
@comment $Id: GNU-Sample-Texts.html,v 1.1 2005/04/06 05:39:38 Bronger Exp $
@comment %**start of header
@setfilename sample.info
@include version.texi
@settitle GNU Sample @value{VERSION}
@syncodeindex pg cp
@comment %**end of header
@copying
This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}),
which is an example in the Texinfo documentation.

Copyright @copyright{} 2005 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.1 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 freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end quotation
@end copying

@dircategory Texinfo documentation system
@direntry
* sample: (sample)Invoking sample.
@end direntry

@titlepage
@title GNU Sample
@subtitle for version @value{VERSION}, @value{UPDATED}
@author A.U. Thor (@email{bug-texinfo@@gnu.org})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top GNU Sample

This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}).
@end ifnottex

@menu
* Invoking sample::
* Copying This Manual::
* Index::
@end menu


@node Invoking sample
@chapter Invoking sample

@pindex sample
@cindex invoking @command{sample}

This is a sample manual.  There is no sample program to
invoke, but if there was, you could see its basic usage
and command line options here.


@node Copying This Manual
@appendix Copying This Manual

@menu
* GNU Free Documentation License::  License for copying this manual.
@end menu

@include fdl.texi


@node Index
@unnumbered Index

@printindex cp

@bye